@zernio/node 0.2.1518 → 0.2.1520

package/dist/index.d.mts

@@ -55345,7 +55345,10 @@ type CreateAdSetData = {
          * Reddit only. ISO 8601 end of the ad group. Defaults to the campaign end.
          */
         endDate?: string;
-        targeting?: TargetingSpec;
+        /**
+         * Reddit: the full targeting object. Google: locations and languages only, on a Demand Gen campaign.
+         */
+        targeting?: (TargetingSpec);
         /**
          * Reddit only. The pixel and the conversion event the ad group optimizes toward.
          */
@@ -61936,7 +61939,7 @@ type CreateStandaloneAdData = {
          * - `app_promotion`: requires `promotedObject.applicationId` and `promotedObject.objectStoreUrl`.
          * - `catalog_sales`: Advantage+ catalog ads (e.g. vehicle inventory). Requires `promotedObject.productSetId`, `promotedObject.pixelId` and `promotedObject.customEventType`. Builds a catalog TEMPLATE creative from the copy fields, which may carry template tags like {{product.name}} or {{vehicle.make}}.
          * - `catalog_sales` visuals: no imageUrl or video is sent; Meta renders them per catalog item (an imageUrl or video sent is ignored, not uploaded). Find catalogs via GET /v1/ads/catalogs and product sets via GET /v1/ads/catalogs/{catalogId}/product-sets.
-         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`.
+         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`, and open the carousel with `catalogIntroCards`.
          * - `traffic` with `promotedObject.productSetId`: a catalog ad without a pixel (OUTCOME_TRAFFIC, `optimizationGoal` LINK_CLICKS by default or LANDING_PAGE_VIEWS). The product set goes on the template creative only, never the ad set's promoted_object. No `pixelId` or `customEventType` needed. Same creative rules as `catalog_sales`.
          * - `page_likes`: Page Likes under OUTCOME_ENGAGEMENT (destination_type ON_PAGE, optimization PAGE_LIKES). `promotedObject.pageId` is optional and auto-filled. The CTA is fixed to LIKE_PAGE for that Page; headline / body / linkUrl / callToAction / imageUrl / video are all optional (Meta derives them from the Page).
          * - `page_visits`: "Page visits and followers" under OUTCOME_TRAFFIC (destination_type FACEBOOK_PAGE, optimization PROFILE_VISIT). `promotedObject.pageId` is optional and auto-filled; `linkUrl` defaults to the Page. Accounts Meta has not enabled are refused with "This account isn't eligible to use Profile Visit ads yet".
@@ -62042,6 +62045,34 @@ type CreateStandaloneAdData = {
          *
          */
         catalogFormat?: 'single_image' | 'carousel_images_multi_items' | 'carousel_images_single_item' | 'carousel_slideshows';
+        /**
+         * Meta only. Static cards shown before the catalog products in a catalog carousel, for example a brand or offer slide. Valid only with goal `catalog_sales` and `catalogFormat` omitted or `carousel_images_multi_items`; a 400 otherwise.
+         *
+         * Sent in order as `object_story_spec.template_data.child_attachments` with `static_card: true`, followed by one catalog card built from the top-level `headline`, `description` and `callToAction`.
+         *
+         */
+        catalogIntroCards?: Array<{
+            /**
+             * Card image; uploaded to the ad account and referenced by hash.
+             */
+            imageUrl: string;
+            /**
+             * Card headline. Meta does not show it on Instagram.
+             */
+            headline: string;
+            /**
+             * Card description. Meta does not show it on Instagram.
+             */
+            description?: string;
+            /**
+             * Card destination URL. Defaults to the top-level linkUrl.
+             */
+            linkUrl?: string;
+            /**
+             * Card CTA override. Defaults to the top-level callToAction; same enum.
+             */
+            callToAction?: string;
+        }>;
         /**
          * Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there.
          */
@@ -62160,12 +62191,14 @@ type CreateStandaloneAdData = {
         /**
          * Meta only. Where the budget lives, which selects the Meta budget model:
          *
-         * - `adset` (default): ABO (Ad-set Budget Optimization). The budget is set on the ad set. Back-compatible; omit this field to keep it.
+         * - `adset` (used when omitted): ABO (Ad-set Budget Optimization). The budget is set on the ad set.
          * - `campaign`: CBO (Campaign Budget Optimization / Advantage Campaign Budget). The budget AND `bidStrategy` are set on the CAMPAIGN, and Meta distributes spend across ad sets automatically.
          *
          * The returned ad stores the applied `budgetLevel`, and the budget in `campaignBudget` (CBO) or `adSetBudget` (ABO). Edit CBO budgets with `PUT /v1/ads/campaigns/{campaignId}` and ABO budgets with `PUT /v1/ads/ad-sets/{adSetId}`.
          *
-         * Meta requires the budget at exactly one level, never both. Non-Meta platforms ignore this field. Ignored on the attach shape (`adSetId`), which inherits the existing budget.
+         * Meta requires the budget at exactly one level, never both. Ignored on the Meta attach shape (`adSetId`), which inherits the existing budget.
+         *
+         * Google Demand Gen also reads it. A new Demand Gen campaign accepts only `campaign` or no value. With `existingCampaignId` or `adSetId`, omit it: the budget stays on the existing campaign. Other platforms ignore it.
          *
          */
         budgetLevel?: 'adset' | 'campaign';
@@ -62924,7 +62957,7 @@ type CreateStandaloneAdData = {
          */
         audienceId?: string;
         /**
-         * Google only. Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED. With `adSetId` it defaults to the ad group's own campaign type instead of display.
+         * Google only. Omitted, it is display on a new campaign, and the existing campaign's own type with `existingCampaignId` or `adSetId` (Search, Display or Demand Gen; other types return 422). Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED.
          */
         campaignType?: 'display' | 'search' | 'pmax' | 'demand_gen';
         /**

package/dist/index.d.ts

@@ -55345,7 +55345,10 @@ type CreateAdSetData = {
          * Reddit only. ISO 8601 end of the ad group. Defaults to the campaign end.
          */
         endDate?: string;
-        targeting?: TargetingSpec;
+        /**
+         * Reddit: the full targeting object. Google: locations and languages only, on a Demand Gen campaign.
+         */
+        targeting?: (TargetingSpec);
         /**
          * Reddit only. The pixel and the conversion event the ad group optimizes toward.
          */
@@ -61936,7 +61939,7 @@ type CreateStandaloneAdData = {
          * - `app_promotion`: requires `promotedObject.applicationId` and `promotedObject.objectStoreUrl`.
          * - `catalog_sales`: Advantage+ catalog ads (e.g. vehicle inventory). Requires `promotedObject.productSetId`, `promotedObject.pixelId` and `promotedObject.customEventType`. Builds a catalog TEMPLATE creative from the copy fields, which may carry template tags like {{product.name}} or {{vehicle.make}}.
          * - `catalog_sales` visuals: no imageUrl or video is sent; Meta renders them per catalog item (an imageUrl or video sent is ignored, not uploaded). Find catalogs via GET /v1/ads/catalogs and product sets via GET /v1/ads/catalogs/{catalogId}/product-sets.
-         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`.
+         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`, and open the carousel with `catalogIntroCards`.
          * - `traffic` with `promotedObject.productSetId`: a catalog ad without a pixel (OUTCOME_TRAFFIC, `optimizationGoal` LINK_CLICKS by default or LANDING_PAGE_VIEWS). The product set goes on the template creative only, never the ad set's promoted_object. No `pixelId` or `customEventType` needed. Same creative rules as `catalog_sales`.
          * - `page_likes`: Page Likes under OUTCOME_ENGAGEMENT (destination_type ON_PAGE, optimization PAGE_LIKES). `promotedObject.pageId` is optional and auto-filled. The CTA is fixed to LIKE_PAGE for that Page; headline / body / linkUrl / callToAction / imageUrl / video are all optional (Meta derives them from the Page).
          * - `page_visits`: "Page visits and followers" under OUTCOME_TRAFFIC (destination_type FACEBOOK_PAGE, optimization PROFILE_VISIT). `promotedObject.pageId` is optional and auto-filled; `linkUrl` defaults to the Page. Accounts Meta has not enabled are refused with "This account isn't eligible to use Profile Visit ads yet".
@@ -62042,6 +62045,34 @@ type CreateStandaloneAdData = {
          *
          */
         catalogFormat?: 'single_image' | 'carousel_images_multi_items' | 'carousel_images_single_item' | 'carousel_slideshows';
+        /**
+         * Meta only. Static cards shown before the catalog products in a catalog carousel, for example a brand or offer slide. Valid only with goal `catalog_sales` and `catalogFormat` omitted or `carousel_images_multi_items`; a 400 otherwise.
+         *
+         * Sent in order as `object_story_spec.template_data.child_attachments` with `static_card: true`, followed by one catalog card built from the top-level `headline`, `description` and `callToAction`.
+         *
+         */
+        catalogIntroCards?: Array<{
+            /**
+             * Card image; uploaded to the ad account and referenced by hash.
+             */
+            imageUrl: string;
+            /**
+             * Card headline. Meta does not show it on Instagram.
+             */
+            headline: string;
+            /**
+             * Card description. Meta does not show it on Instagram.
+             */
+            description?: string;
+            /**
+             * Card destination URL. Defaults to the top-level linkUrl.
+             */
+            linkUrl?: string;
+            /**
+             * Card CTA override. Defaults to the top-level callToAction; same enum.
+             */
+            callToAction?: string;
+        }>;
         /**
          * Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there.
          */
@@ -62160,12 +62191,14 @@ type CreateStandaloneAdData = {
         /**
          * Meta only. Where the budget lives, which selects the Meta budget model:
          *
-         * - `adset` (default): ABO (Ad-set Budget Optimization). The budget is set on the ad set. Back-compatible; omit this field to keep it.
+         * - `adset` (used when omitted): ABO (Ad-set Budget Optimization). The budget is set on the ad set.
          * - `campaign`: CBO (Campaign Budget Optimization / Advantage Campaign Budget). The budget AND `bidStrategy` are set on the CAMPAIGN, and Meta distributes spend across ad sets automatically.
          *
          * The returned ad stores the applied `budgetLevel`, and the budget in `campaignBudget` (CBO) or `adSetBudget` (ABO). Edit CBO budgets with `PUT /v1/ads/campaigns/{campaignId}` and ABO budgets with `PUT /v1/ads/ad-sets/{adSetId}`.
          *
-         * Meta requires the budget at exactly one level, never both. Non-Meta platforms ignore this field. Ignored on the attach shape (`adSetId`), which inherits the existing budget.
+         * Meta requires the budget at exactly one level, never both. Ignored on the Meta attach shape (`adSetId`), which inherits the existing budget.
+         *
+         * Google Demand Gen also reads it. A new Demand Gen campaign accepts only `campaign` or no value. With `existingCampaignId` or `adSetId`, omit it: the budget stays on the existing campaign. Other platforms ignore it.
          *
          */
         budgetLevel?: 'adset' | 'campaign';
@@ -62924,7 +62957,7 @@ type CreateStandaloneAdData = {
          */
         audienceId?: string;
         /**
-         * Google only. Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED. With `adSetId` it defaults to the ad group's own campaign type instead of display.
+         * Google only. Omitted, it is display on a new campaign, and the existing campaign's own type with `existingCampaignId` or `adSetId` (Search, Display or Demand Gen; other types return 422). Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED.
          */
         campaignType?: 'display' | 'search' | 'pmax' | 'demand_gen';
         /**

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.1518",
+  version: "0.2.1520",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -5,7 +5,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.1518",
+  version: "0.2.1520",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zernio/node",
-  "version": "0.2.1518",
+  "version": "0.2.1520",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -13797,6 +13797,15 @@ export const listAdSets = <ThrowOnError extends boolean = false>(options?: Optio
  *
  * The ad group is created WITHOUT an ad (Google Ads compliance row C.190). Ads join it later via `adSetId` on POST /v1/ads/create. Supports Google Ads and Reddit Ads; every other platform returns 501.
  *
+ * **Google Ads** (`platform: google`)
+ *
+ * - The ad group type follows the campaign: a standard ad group under a Search or Display campaign, a Demand Gen ad group under a Demand Gen campaign.
+ * - On a Demand Gen campaign the ad group is always created PAUSED, and `maxCpc` or `status: ACTIVE` returns 400 (Demand Gen bids at the campaign).
+ * - `targeting` sets a Demand Gen ad group's locations and languages (`countries`, `regions`, `cities`, `zips`, `metros`, `languages`), created atomically with the ad group. Without it the ad group serves worldwide.
+ * - `targeting` returns 400 for any other targeting field, and on campaigns that keep geo on the campaign: Search, Display, and Demand Gen campaigns migrated from Discovery. Edit those with PUT /v1/ads/campaigns/{campaignId}/targeting.
+ * - Any other campaign type returns 400 (Performance Max has asset groups instead of ad groups).
+ * - A campaign that is not in the ad account, or was removed, returns 404.
+ *
  * **Reddit Ads** (`platform: reddit`)
  *
  * - `adAccountId` (the Reddit ad account id) is required and must be a selected ad account of the connection (403 otherwise).
@@ -13807,7 +13816,7 @@ export const listAdSets = <ThrowOnError extends boolean = false>(options?: Optio
  * - The ad group must start no earlier than a future campaign start and end no later than the campaign end (400 otherwise).
  * - `targeting` takes the same targeting object as the other ad endpoints (no geo defaults to the US).
  * - A campaign of another ad account returns 404, a Reddit Max campaign 422.
- * - `maxCpc` and `customerId` are Google only (400 on Reddit), and the Reddit fields return 400 on Google.
+ * - `maxCpc` and `customerId` are Google only (400 on Reddit), and the other Reddit fields return 400 on Google.
  *
  * ### After creation
  *
@@ -17025,6 +17034,8 @@ export const listGoogleAssetGroups = <ThrowOnError extends boolean = false>(opti
  *
  * The group, any new assets, their links and an optional listing-group tree are created in one atomic request, so Google checks the asset minimums (for non-retail campaigns) against the whole set. Created PAUSED unless status is ENABLED. validateOnly: true runs Google's validation without creating anything.
  *
+ * A campaign that is not Performance Max returns 400 on campaignId (add an ad group with POST /v1/ads/ad-sets instead). A missing or removed campaign returns 404.
+ *
  */
 export const createGoogleAssetGroup = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<CreateGoogleAssetGroupData, ThrowOnError>) => {
     return (options?.client ?? client).post<CreateGoogleAssetGroupResponse, CreateGoogleAssetGroupError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -56316,7 +56316,10 @@ export type CreateAdSetData = {
          * Reddit only. ISO 8601 end of the ad group. Defaults to the campaign end.
          */
         endDate?: string;
-        targeting?: TargetingSpec;
+        /**
+         * Reddit: the full targeting object. Google: locations and languages only, on a Demand Gen campaign.
+         */
+        targeting?: (TargetingSpec);
         /**
          * Reddit only. The pixel and the conversion event the ad group optimizes toward.
          */
@@ -63294,7 +63297,7 @@ export type CreateStandaloneAdData = {
          * - `app_promotion`: requires `promotedObject.applicationId` and `promotedObject.objectStoreUrl`.
          * - `catalog_sales`: Advantage+ catalog ads (e.g. vehicle inventory). Requires `promotedObject.productSetId`, `promotedObject.pixelId` and `promotedObject.customEventType`. Builds a catalog TEMPLATE creative from the copy fields, which may carry template tags like {{product.name}} or {{vehicle.make}}.
          * - `catalog_sales` visuals: no imageUrl or video is sent; Meta renders them per catalog item (an imageUrl or video sent is ignored, not uploaded). Find catalogs via GET /v1/ads/catalogs and product sets via GET /v1/ads/catalogs/{catalogId}/product-sets.
-         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`.
+         * - `catalog_sales` shape: single shape only, no creatives[], dynamicCreative, placementAssets, existingCreativeId or carouselCards. Works with `existingCampaignId`, and with `adSetId` to add to an existing ad set (then only `promotedObject.productSetId` is required). Pick the format with `catalogFormat`, and open the carousel with `catalogIntroCards`.
          * - `traffic` with `promotedObject.productSetId`: a catalog ad without a pixel (OUTCOME_TRAFFIC, `optimizationGoal` LINK_CLICKS by default or LANDING_PAGE_VIEWS). The product set goes on the template creative only, never the ad set's promoted_object. No `pixelId` or `customEventType` needed. Same creative rules as `catalog_sales`.
          * - `page_likes`: Page Likes under OUTCOME_ENGAGEMENT (destination_type ON_PAGE, optimization PAGE_LIKES). `promotedObject.pageId` is optional and auto-filled. The CTA is fixed to LIKE_PAGE for that Page; headline / body / linkUrl / callToAction / imageUrl / video are all optional (Meta derives them from the Page).
          * - `page_visits`: "Page visits and followers" under OUTCOME_TRAFFIC (destination_type FACEBOOK_PAGE, optimization PROFILE_VISIT). `promotedObject.pageId` is optional and auto-filled; `linkUrl` defaults to the Page. Accounts Meta has not enabled are refused with "This account isn't eligible to use Profile Visit ads yet".
@@ -63400,6 +63403,34 @@ export type CreateStandaloneAdData = {
          *
          */
         catalogFormat?: 'single_image' | 'carousel_images_multi_items' | 'carousel_images_single_item' | 'carousel_slideshows';
+        /**
+         * Meta only. Static cards shown before the catalog products in a catalog carousel, for example a brand or offer slide. Valid only with goal `catalog_sales` and `catalogFormat` omitted or `carousel_images_multi_items`; a 400 otherwise.
+         *
+         * Sent in order as `object_story_spec.template_data.child_attachments` with `static_card: true`, followed by one catalog card built from the top-level `headline`, `description` and `callToAction`.
+         *
+         */
+        catalogIntroCards?: Array<{
+            /**
+             * Card image; uploaded to the ad account and referenced by hash.
+             */
+            imageUrl: string;
+            /**
+             * Card headline. Meta does not show it on Instagram.
+             */
+            headline: string;
+            /**
+             * Card description. Meta does not show it on Instagram.
+             */
+            description?: string;
+            /**
+             * Card destination URL. Defaults to the top-level linkUrl.
+             */
+            linkUrl?: string;
+            /**
+             * Card CTA override. Defaults to the top-level callToAction; same enum.
+             */
+            callToAction?: string;
+        }>;
         /**
          * Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there.
          */
@@ -63518,12 +63549,14 @@ export type CreateStandaloneAdData = {
         /**
          * Meta only. Where the budget lives, which selects the Meta budget model:
          *
-         * - `adset` (default): ABO (Ad-set Budget Optimization). The budget is set on the ad set. Back-compatible; omit this field to keep it.
+         * - `adset` (used when omitted): ABO (Ad-set Budget Optimization). The budget is set on the ad set.
          * - `campaign`: CBO (Campaign Budget Optimization / Advantage Campaign Budget). The budget AND `bidStrategy` are set on the CAMPAIGN, and Meta distributes spend across ad sets automatically.
          *
          * The returned ad stores the applied `budgetLevel`, and the budget in `campaignBudget` (CBO) or `adSetBudget` (ABO). Edit CBO budgets with `PUT /v1/ads/campaigns/{campaignId}` and ABO budgets with `PUT /v1/ads/ad-sets/{adSetId}`.
          *
-         * Meta requires the budget at exactly one level, never both. Non-Meta platforms ignore this field. Ignored on the attach shape (`adSetId`), which inherits the existing budget.
+         * Meta requires the budget at exactly one level, never both. Ignored on the Meta attach shape (`adSetId`), which inherits the existing budget.
+         *
+         * Google Demand Gen also reads it. A new Demand Gen campaign accepts only `campaign` or no value. With `existingCampaignId` or `adSetId`, omit it: the budget stays on the existing campaign. Other platforms ignore it.
          *
          */
         budgetLevel?: 'adset' | 'campaign';
@@ -64282,7 +64315,7 @@ export type CreateStandaloneAdData = {
          */
         audienceId?: string;
         /**
-         * Google only. Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED. With `adSetId` it defaults to the ad group's own campaign type instead of display.
+         * Google only. Omitted, it is display on a new campaign, and the existing campaign's own type with `existingCampaignId` or `adSetId` (Search, Display or Demand Gen; other types return 422). Performance Max requires assetGroup and Demand Gen requires demandGen; both are always created PAUSED.
          */
         campaignType?: 'display' | 'search' | 'pmax' | 'demand_gen';
         /**