facebook / facebook-business-sdk-codegen

Codegen project for our business SDKs

Facebook Business SDK Codegen

Introduction

This project contains all the code to auto generate Facebook Business SDKs (php, python, nodejs, ruby, java). There are three parts of this project :

• JSON schema representation of the Graph API endpoints.
• Mustache template for 5 languages.
• Codegen scripts.

Pre-requisites

Install Node.js

Install all dependencies by npm : npm install

Codegen SDK

npm run build && node lib/CodeGenerator.js <language>

Debug

During debug, if you want to compare with the generated SDK to our current SDK code, you can specific the output folder by using -o :

npm run build && node lib/CodeGenerator.js <language> -o outputDir

If you want to keep git config in outputDir, you can specific only cleanup source code by using -c , for example:

npm run build && node lib/CodeGenerator.js php -o ../facebook-php-business-sdk/ -c src/

License

Facebook Codegen for Business SDKs is licensed under the LICENSE file in the root directory of this source tree.

facebook-business-sdk-codegen's Issues

Creation of AdSet suffers from breaking changes

Checklist

• I've updated to the latest released version
• I've searched for existing GitHub issues
• I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• I've read the Code of Conduct
• This issue is not security related and can safely be disclosed publicly on GitHub

Environment

• Node Version: 16.15.0
• NPM Version: 8.5.5

Goals

Be able to use strongly-typed programming without type casting when creating API resources, as it was possible before v13

Expected Results

I expect existing code using facebook-java-business-sdk which creates AdSet in particular to compile without errors
There are no breaking changes introduced in v13 changelog related to AdSet creation
https://developers.facebook.com/docs/graph-api/changelog/version13.0

Actual Results

Compilation error due to:

before commit

public static class APIRequestCreateAdSet extends APIRequest<AdSet>

after

public static class APIRequestCreateAdSet extends APIRequest<APINode>

before commit

public APIRequestCreateAdSet setBillingEvent (AdSet.EnumBillingEvent billingEvent)

after

public APIRequestCreateAdSet setBillingEvent (EnumBillingEvent billingEvent)

There are more enums which suffered from additional enum definition copies added
There are more entities which lost strongly-typed api
One can observe the same in node.js sdk returning Promise<AbstractObject>

Steps to Reproduce

Try to compile examples

Steps to Fix

Restore return type back to "AdSet" in spec

Restore "node" property on "adaccountadsets_billing_event_enum_param" back to "AdSet" in spec

I'd be happy to create PR, but commit tells the spec was "Automitically generate from our internal API framework." which I don't have access to.

I can confirm java sdk is fully compilable after mentioned changes

I might be missing something, since I just joined a java project and learning java for 5 days and fb business api for 1.5 days, but it'd be so nice to leave the code as is without typecasting.

Ad Account Users Endpoints Removed

It looks like the methods for creating, updating, and deleting users assigned to ad accounts were removed in bbc4156, even though they are still listed in the documentation: https://developers.facebook.com/docs/marketing-api/reference/ad-account/users/

Will those be restored, or did I miss an announcement to deprecate those?

FacebookAds\Object\AdAccount -> createAdCreative() not handling the exception properly.

Checklist

• I've updated to the latest released version (facebook/php-ads-sdk": "5.0")
• I've searched for existing GitHub issues
• I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• This issue is not security related and can safely be disclosed publicly on GitHub

Environment

facebook/php-ads-sdk": "5.0.*

Goals

I want to create new Creative while creating a new ad. If it fails then returns specific message returned from FB API.

Expected Results

Speicifc errpr message return from FB API like "The image couldn't be downloaded. Please wait a few minutes and try again."
What do you expect to happen?

Actual Results

"array_key_exists() expects parameter 2 to be array, null given".

What actually happened? Can you provide a stack trace?
{ "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 100, "error_data": "null", "error_subcode": 1487833, "is_transient": true, "error_user_title": "Image wasn't downloaded", "error_user_msg": "Your image, https://someimage.png, couldn't be downloaded. Please wait a few minutes and try again.", "fbtrace_id": "AGIA_kW9Khu9XO05piwiXuw" } }

Steps to Reproduce

We can't provide token and other details for securoty reasons. You can just try to create a new creative by using following payload.

Code Samples & Details

Payload
{ "access_token": "XXX", "object_type": "SHARE", "object_story_spec": { "page_id": "XXX", "link_data": { "message": "Some message", "link": "https://fb.me/", "name": "test", "picture": "https://storage.googleapis.com/facebook-prod-f655/prod/Xes0M1599608679sC4Qj.png", "description": "Some descriotion", "call_to_action": { "type": "LEARN_MORE", "value": { "lead_gen_form_id": "XXX" } } } } }

Now, whenever a exception occurs getData(); method not handling that properly and not returning appropriate error message.

API call

$adAccount = new AdAccount('act_<ad_account_id>'');
$creative = $adAccount->createAdCreative([], $payload)->getData();

This function is calling createAdCreative() method in FacebookAds\Object\AdAccount class

public function createAdCreative(array $fields = array(), array $params = array(), $pending = false) {
	
	// Code stuff
}

Feature Request: Ads Library API

Checklist

• I've updated to the latest released version
• I've searched for existing feature requests on GitHub issues
• I've read the Code of Conduct
• I've given my issue the title: Feature Request: [name of my feature request]

Goals

Access the ads library API (https://www.facebook.com/ads/library/api) through the SDK so that my users can see ads from companies similar to theirs and build better ads.

How can I auto-generate types for a new API version?

Is there a way to update the JSON defs for a new API version? for example currently, this package only support v14 but v15 is available. I would like to generate Python SDK code using this package so I can submit it downstream to resolve hard blockers like this one. However, I'm not sure how to autogenerate. I looked around the repo and didn't find something which can achieve this. Could you help?

I guess more generally, as a consumer of this package, what are my options for staying up to date with API changes while still using an SDK generated by this package?

Cannot run CodeGenerator.js

Checklist

• I've updated to the latest released version
• I've searched for existing GitHub issues
• I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• I've read the Code of Conduct
• This issue is not security related and can safely be disclosed publicly on GitHub

Environment

Describe your dev environment here, giving as many details as possible. If you have them, make sure to include:

• Node Version: 15.14.0
• NPM Version: 7.7.6

Goals

What do you want to achieve?

I want to run CodeGenerator.js as the README.md described.
The command I used to run: npm run build && node lib/CodeGenerator.js python

Expected Results

What do you expect to happen?
CodeGenerator.js successfully executed.

Actual Results

Error: ENOENT: no such file or directory, open '/Users/james/Downloads/programmation/sdk/servers/python/release/setup.py'

What actually happened? Can you provide a stack trace?
It is not able to find the sdk folder. In fact, these are the folders named sdk: (find . -name "sdk" -type d)
./templates/java/examples/src/main/java/com/facebook/ads/sdk
./templates/java/src/main/java/com/facebook/ads/sdk

Also, it is trying to access the parent folder of the repo. (the cwd is: /Users/james/Downloads/programmation/facebook-business-sdk-codegen)

Taking a look at how this path is generated, the path is written inapi_specs/version_path.json, and src/common/Utils.js: loadDefaultSDKVersion went 3 directories back, but __dirname is facebook-business-sdk-codegen/lib/common.

Steps to Reproduce

What are the steps necessary to reproduce this issue?
npm install && npm run build && node lib/CodeGenerator.js python

Code Samples & Details

Please provide a code sample, as well as any additional details, to help us track down the issue. If you can provide a link to a test project that allows us to reproduce the issue, this helps us immensely in both the speed and quality of the fix.

Note: Remember to format your code for readability:

npm install && npm run build && node lib/CodeGenerator.js python

Feature Request: Add missing types for nested Objects (such as Ads/insights/filtering)

Checklist

• I've updated to the latest released version
• I've searched for existing feature requests on GitHub issues
• I've read the Code of Conduct
• I've given my issue the title: Feature Request: [name of my feature request]

Goals

Be able to fully validate and describe the API, align to official references documentation

Expected Results

I expect a field like filtering to contain list<FilterObject> or list<AdRuleFilter> and not list<Object>

Code Samples & Details

FilterObject:

{
    "apis": [],
    "fields": [
        {
            "name": "field",
            "type": "string"
        },
        {
            "name": "operator",
            "type": "Filters_operator"
        },
        {
            "name": "value",
            "type": "Object"
        }
    ]
}

Ads/insights/filtering:

                {
                    "name": "filtering",
                    "required": false,
                    "type": "list<FilterObject>"
                },

Thanks

targeting_optimization_types has wrong type

Checklist

• I've updated to the latest released version
• I've searched for existing GitHub issues
• I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• I've read the Code of Conduct
• This issue is not security related and can safely be disclosed publicly on GitHub

Environment

Describe your dev environment here, giving as many details as possible. If you have them, make sure to include:

• Node Version: 16.16.0
• NPM Version: 8.11.0

Goals

What do you want to achieve?

Get correct type for targeting_optimization_types

Expected Results

What do you expect to happen?

According to documentation, targeting_optimization_types has type listKeyValue:string,int32, so type in codegen specs should be list

There are 3 objects that uses this field:

1. AdSet https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/
2. AdAccountDeliveryEstimate (no documentation found)
3. AdCampaignDeliveryEstimate https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-delivery-estimate/

Actual Results

What actually happened?

Current type for targeting_optimization_types is map<string, int>

Because of that, targeting_optimization_types could not be mapped properly. For example, one issue was reported in python sdk project link

Code Samples & Details

Please provide a code sample, as well as any additional details, to help us track down the issue. If you can provide a link to a test project that allows us to reproduce the issue, this helps us immensely in both the speed and quality of the fix.

        {
            "name": "targeting_optimization_types",
            "type": "map<string, int>"
        }

should be changed to:

        {
            "name": "targeting_optimization_types",
            "type": "list<map>"
        }

CodeGenerator for python:v14 seems broken

Checklist

• I've updated to the latest released version
• I've searched for existing GitHub issues
• I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• I've read the Code of Conduct
• This issue is not security related and can safely be disclosed publicly on GitHub

Environment

• Node Version: 14.18.2
• NPM Version: 7.24.2

Goals

I want to generate the python SDK for v14

Expected Results

I would expect changes related to schema/fields in adobjects.

Actual Results

lots of files deleted and three of them modified. The three modifications are simply replacing 13.0.0 for 14.0.0. It doesn't seem that these changes are correct.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	deleted:    examples/AdAccountActivityNode.py
	deleted:    examples/AdAccountAdCreativesEdge.py
	deleted:    examples/AdAccountAdCreativesPost.py
	deleted:    examples/AdAccountAdCreativesPost2CreateAdCreativeLinkAd.py
	deleted:    examples/AdAccountAdCreativesPost2CreateLinkAdCallToActionAppInstall.py
	deleted:    examples/AdAccountAdCreativesPost2CreateLinkAdImageCrop.py
	deleted:    examples/AdAccountAdCreativesPost2CreateMAIDPA.py
	deleted:    examples/AdAccountAdCreativesPost2CreateVideoLeadAd.py
	deleted:    examples/AdAccountAdCreativesPost2CreateVideoPageLikeAd.py
	deleted:    examples/AdAccountAdCreativesPost3CreateAdCreativePageLike.py
	deleted:    examples/AdAccountAdCreativesPost3CreateAssetFeedSpec.py
	deleted:    examples/AdAccountAdCreativesPost3CreateCarouselCallToActionAppInstall.py
	deleted:    examples/AdAccountAdCreativesPost3CreateDynamicAdCustomization.py
	deleted:    examples/AdAccountAdCreativesPostCreateAdCreative.py
	deleted:    examples/AdAccountAdCreativesPostCreateAdCreativeCanvas.py
	deleted:    examples/AdAccountAdCreativesPostCreateAdCreativeCustomizationCanvasDV.py
	deleted:    examples/AdAccountAdCreativesPostCreateAdCreativeCustomizationCanvasImage.py
	deleted:    examples/AdAccountAdCreativesPostCreateAdCreativeCustomizationCanvasVideo.py
	deleted:    examples/AdAccountAdSetsPost2CreateMAIA.py
	deleted:    examples/AdAccountAdSetsPostAdSetCreateCpa.py
	deleted:    examples/AdAccountAdSetsPostAdSetCreateCpaAppEvents.py
	deleted:    examples/AdAccountAdSetsPostBehaviorTargeting.py
	deleted:    examples/AdAccountAdSetsPostBidMultiplier.py
	deleted:    examples/AdAccountAdSetsPostCreateAdSet.py
	deleted:    examples/AdAccountAdSetsPostCreateAudienceNetwork.py
	deleted:    examples/AdAccountAdSetsPostDailyBudget20.py
	deleted:    examples/AdAccountAdSetsPostDemographicTargeting.py
	deleted:    examples/AdAccountAdSetsPostInterestTargeting.py
	deleted:    examples/AdAccountAdSetsPostLifetimeBudget200Duration10Days.py
	deleted:    examples/AdAccountAdSetsPostOfferClaim.py
	deleted:    examples/AdAccountAdSetsPostOptimizePostEngagement.py
	deleted:    examples/AdAccountAdSetsPostPageLikes.py
	deleted:    examples/AdAccountAdSetsPostPlacementTargeting.py
	deleted:    examples/AdAccountAdSetsPostReach.py
	deleted:    examples/AdAccountAdVideosPost.py
	deleted:    examples/AdAccountAdsPixelEdgeGetPixelCode.py
	deleted:    examples/AdAccountAdsPixelsPost.py
	deleted:    examples/AdAccountAdsPost.py
	deleted:    examples/AdAccountAdsPostAdsRedownload.py
	deleted:    examples/AdAccountAdsPostOfferClaim.py
	deleted:    examples/AdAccountAdsPostTrackingPostEngagement.py
	deleted:    examples/AdAccountCampaignsEdge.py
	deleted:    examples/AdAccountCampaignsPostConversions.py
	deleted:    examples/AdAccountCampaignsPostEventResponses.py
	deleted:    examples/AdAccountCampaignsPostLeadGen.py
	deleted:    examples/AdAccountCampaignsPostLinkClicks.py
	deleted:    examples/AdAccountCampaignsPostLocalAwareness.py
	deleted:    examples/AdAccountCampaignsPostMAIA.py
	deleted:    examples/AdAccountCampaignsPostMAIDPA.py
	deleted:    examples/AdAccountCampaignsPostOfferClaims.py
	deleted:    examples/AdAccountCampaignsPostPageLikes.py
	deleted:    examples/AdAccountCampaignsPostPostEngagement.py
	deleted:    examples/AdAccountCampaignsPostStoreCampaign.py
	deleted:    examples/AdAccountCampaignsPostVideoViews.py
	deleted:    examples/AdAccountCustomAudiencesEdge.py
	deleted:    examples/AdAccountCustomAudiencesEdgeDataSourceSubtype.py
	deleted:    examples/AdAccountCustomAudiencesPostCreateCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostDynamicEventValueBasedLookalikeCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostDynamicValueBasedLookalikeCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformCustomAudienceMACARule.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformECAExclusions.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformECAMultiFilters.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformECAMultiPages.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformEngagementCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostPlatformWebsiteCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostValueBasedCustomAudience.py
	deleted:    examples/AdAccountCustomAudiencesPostValueBasedLookalikeCustomAudience.py
	deleted:    examples/AdAccountGeneratePreviewsEdge.py
	deleted:    examples/AdAccountGeneratePreviewsEdgeDesktopWithStoryId.py
	deleted:    examples/AdAccountGeneratePreviewsEdgeInstagramStandards.py
	deleted:    examples/AdAccountGeneratePreviewsEdgeMaiaWithObjectStorySpec.py
	deleted:    examples/AdAccountNode.py
	deleted:    examples/AdAccountProductAudiencesPostIphoneViewNoPurchase.py
	deleted:    examples/AdAccountProductAudiencesPostNoPurchase.py
	deleted:    examples/AdAccountReachEstimate.py
	deleted:    examples/AdCampaignActivityNode.py
	deleted:    examples/AdCampaignGroupActivityNode.py
	deleted:    examples/AdCampaignGroupAdsEdge.py
	deleted:    examples/AdCampaignGroupAdsEdgeAdgroupsWithStatusArchived.py
	deleted:    examples/AdCampaignGroupAdsetsEdge.py
	deleted:    examples/AdCampaignNode.py
	deleted:    examples/AdCampaignPost.py
	deleted:    examples/AdCampaignPostAdsetUpdateCpa.py
	deleted:    examples/AdCreativeCreativeInsightsEdge.py
	deleted:    examples/AdCreativeNode.py
	deleted:    examples/AdCreativeNodeRead.py
	deleted:    examples/AdCreativeNodeReadInstagramPermalinkUrl.py
	deleted:    examples/AdCreativePreviewsEdge.py
	deleted:    examples/AdCreativePreviewsEdgePreview.py
	deleted:    examples/AdCreativePreviewsEdgePreviewDynamicAds.py
	deleted:    examples/AdCreativePreviewsEdgePreviewDynamicAdsWithCustomizations.py
	deleted:    examples/AdgroupActivityNode.py
	deleted:    examples/AdgroupLeadsEdgeAdgroupLeads.py
	deleted:    examples/AdgroupLeadsEdgeAdgroupLeadsDPA.py
	deleted:    examples/AdgroupLeadsEdgeAdgroupLeadsFiltered.py
	deleted:    examples/AdgroupPost.py
	deleted:    examples/AdgroupPostUpdateStatus.py
	deleted:    examples/AdsInsightsEdgeAdCampaignInsights.py
	deleted:    examples/AdsInsightsEdgeStoreVisitsAdCampaignInsights.py
	deleted:    examples/AdsPixelEventsPost.py
	deleted:    examples/AdsPixelEventsPostCustom.py
	deleted:    examples/AdsPixelSharedAccountsEdge.py
	deleted:    examples/AdsPixelSharedAccountsPost.py
	deleted:    examples/AdsPixelSharedAgenciesEdge.py
	deleted:    examples/BusinessOwnedProductCatalogsPostDestinationCatalog.py
	deleted:    examples/BusinessOwnedProductCatalogsPostFlightCatalog.py
	deleted:    examples/BusinessOwnedProductCatalogsPostHotelCatalog.py
	deleted:    examples/BusinessOwnedProductCatalogsPostProductCatalog.py
	deleted:    examples/CustomAudienceDelete.py
	deleted:    examples/CustomAudienceNode.py
	deleted:    examples/CustomAudienceNodeReadRule.py
	deleted:    examples/CustomAudiencePost.py
	deleted:    examples/CustomAudienceUsersPost.py
	deleted:    examples/CustomAudienceUsersPostCrossPlatform.py
	deleted:    examples/MultiPageFeedCreateThenDelete.py
	deleted:    examples/MultiPromoteYourPage.py
	deleted:    examples/OfflineConversionsCreateOfflineSet.py
	deleted:    examples/PageFeedEdge.py
	deleted:    examples/PageFeedPost.py
	deleted:    examples/PageFeedPostFeedImageDeepLink.py
	deleted:    examples/PageNode.py
	deleted:    examples/PageNodePageSearch.py
	deleted:    examples/PagePhotosEdge.py
	deleted:    examples/PagePhotosPost.py
	deleted:    examples/PagePictureEdge.py
	deleted:    examples/PagePostCommentsEdge.py
	deleted:    examples/PagePostCommentsPost.py
	deleted:    examples/PagePostDelete.py
	deleted:    examples/PagePostNode.py
	deleted:    examples/PagePostPost.py
	deleted:    examples/PagePostsEdge.py
	deleted:    examples/PagePostsEdgePagePostCreateCarousel.py
	deleted:    examples/PageRolesEdge.py
	deleted:    examples/PageSubscribedAppsPost.py
	deleted:    examples/ProductCatalogEventStatsEdge.py
	deleted:    examples/ProductCatalogHotelsPost.py
	deleted:    examples/ProductCatalogHotelsPostUpdateHotelsCatalogSettings.py
	deleted:    examples/ProductCatalogProductFeedsPostProductFeed.py
	deleted:    examples/ProductCatalogProductSetsPostHotelSet.py
	deleted:    examples/ProductCatalogProductSetsPostProductSet.py
	deleted:    examples/UserAccountsEdge.py
	deleted:    examples/UserAdAccountsEdge.py
	deleted:    examples/UserLeadGenInfoNode.py
	deleted:    examples/UserNode.py
	deleted:    examples/VideoThumbnailsEdge.py
	modified:   facebook_business/__init__.py
	modified:   facebook_business/apiconfig.py
	deleted:    facebook_business/docs_runner/__init__.py
	deleted:    facebook_business/docs_runner/doc_runner.py
	deleted:    facebook_business/docs_runner/get_version.py
	modified:   setup.py

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	compiled.json

no changes added to commit (use "git add" and/or "git commit -a")

Steps to Reproduce

cloned facebook-python-business-sdk repository, changed 13.0.0 for 14.0.0 in setup.py
moved facebook-python-business-sdk to sdk/servers/python/release
cloned and this repository, installed dependencies with npm i and then built it with npm run build.
ran node lib/CodeGenerator.js python

I'm willing to dedicate more time working on this 💪, but would need some guidance from facebook team to get things right

Missing Call-to-Action enum CALL_NOW

Checklist

• [ x] I've updated to the latest released version
• [x ] I've searched for existing GitHub issues
• [ x] I've looked for existing answers on Stack Overflow and the Facebook Developers Group
• [x ] I've read the Code of Conduct
• [x ] This issue is not security related and can safely be disclosed publicly on GitHub

Environment

I'm using the Java Business sdk v10.0.1.

Goals

Use a call to action type of CALL_NOW, as shown in examples here:
https://developers.facebook.com/docs/marketing-api/guides/event-ads#create

Expected Results

SDKs contain an enum value of CALL_NOW in EnumType for AdCreativeLinkDataCallToAction

Code Samples & Details

The enum_types.json file in this project doesn't contain the CALL_NOW call-to-action enum value.

Related to this, the Java Business SDK method AdCreativeLinkDataCallToAction.setFieldType has only one implementation where the first argument is the EnumType. A different solution might be to include an overloaded method in the SDK with a String type argument instead.

Also reported here
facebook/facebook-java-business-sdk#338