@zernio/node 0.2.471 → 0.2.473

package/src/generated/types.gen.ts

@@ -450,7 +450,7 @@ export type AdMetrics = {
     cpm?: number;
     engagement?: number;
     /**
-     * Count of conversion events over the requested date range. Meta: events matching the campaign's promoted_object.custom_event_type (PURCHASE, LEAD, etc.). Google: the account's tracked conversions. X and LinkedIn: their reported website/lead conversions (added 2026-07). 0 for non-conversion campaigns or when no events have fired.
+     * Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google additionally reports modeled conversions, so values like 0.347 are normal. Meta: events matching the campaign's promoted_object.custom_event_type (PURCHASE, LEAD, etc.). Google: the account's tracked conversions. X and LinkedIn: their reported website/lead conversions (added 2026-07). 0 for non-conversion campaigns or when no events have fired.
      */
     conversions?: number;
     /**
@@ -2258,14 +2258,10 @@ export type ExternalPostWebhookPost = {
 export type source = 'external';
 
 /**
- * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
+ * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories. Draft, carousel, and colored-background text options live under facebookSettings, see FacebookSettings.
  *
  */
 export type FacebookPlatformData = {
-    /**
-     * When true, creates the post as a draft in Facebook Publishing Tools instead of publishing immediately. Supported for feed posts (text, link, image, video) and reels. Not supported for stories. Drafts expire after ~30 days.
-     */
-    draft?: boolean;
     /**
      * Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted.
      */
@@ -2275,7 +2271,7 @@ export type FacebookPlatformData = {
      */
     title?: string;
     /**
-     * Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
+     * Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when facebookSettings.draft is true.
      */
     firstComment?: string;
     /**
@@ -2283,34 +2279,7 @@ export type FacebookPlatformData = {
      */
     pageId?: string;
     geoRestriction?: GeoRestriction;
-    /**
-     * Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.
-     *
-     */
-    carouselCards?: Array<{
-        /**
-         * Per-card click destination (required).
-         */
-        link: string;
-        /**
-         * Per-card headline (optional, ~35-char display).
-         */
-        name?: string;
-        /**
-         * Per-card subhead (optional, ~30-char display).
-         */
-        description?: string;
-    }>;
-    /**
-     * Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards.
-     *
-     */
-    carouselLink?: string;
-    /**
-     * Facebook-defined preset ID that renders the post as large text on a colored background (Graph `text_format_preset_id`). Supply the raw numeric ID from Meta; we do not publish a catalog of presets and Facebook may change the available set. Pages only (ignored on personal profiles and groups) and text-only feed posts only: the request is rejected with 400 when mediaItems or carouselCards are present, when contentType is story or reel, or when content is empty. An attachment makes Facebook drop the background silently, so those are rejected up front. Length is NOT rejected: Facebook's composer stops offering a background at around 130 characters, but Meta documents no API limit, so longer content publishes and returns a warning instead. A URL detected in the content is NOT attached as a link preview while a preset is set, because a link attachment also makes Facebook drop the background.
-     *
-     */
-    textFormatPresetId?: string;
+    facebookSettings?: FacebookSettings;
 };
 
 /**
@@ -2408,6 +2377,45 @@ export type FacebookPostEarningsResponse = {
  */
 export type period = 'lifetime';
 
+/**
+ * Facebook options that must be nested under platformSpecificData.facebookSettings, or sent at the request root as facebookSettings. The remaining Facebook options sit directly on platformSpecificData, see FacebookPlatformData.
+ *
+ */
+export type FacebookSettings = {
+    /**
+     * When true, creates the post as a draft in Facebook Publishing Tools instead of publishing immediately. Supported for feed posts (text, link, image, video) and reels. Not supported for stories. Drafts expire after ~30 days.
+     */
+    draft?: boolean;
+    /**
+     * Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.
+     *
+     */
+    carouselCards?: Array<{
+        /**
+         * Per-card click destination (required).
+         */
+        link: string;
+        /**
+         * Per-card headline (optional, ~35-char display).
+         */
+        name?: string;
+        /**
+         * Per-card subhead (optional, ~30-char display).
+         */
+        description?: string;
+    }>;
+    /**
+     * Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards.
+     *
+     */
+    carouselLink?: string;
+    /**
+     * Facebook-defined preset ID that renders the post as large text on a colored background (Graph `text_format_preset_id`). Supply the raw numeric ID from Meta; we do not publish a catalog of presets and Facebook may change the available set. Pages only (ignored on personal profiles and groups) and text-only feed posts only: the request is rejected with 400 when mediaItems or carouselCards are present, when contentType is story or reel, or when content is empty. An attachment makes Facebook drop the background silently, so those are rejected up front. Length is NOT rejected: Facebook's composer stops offering a background at around 130 characters, but Meta documents no API limit, so longer content publishes and returns a warning instead. A URL detected in the content is NOT attached as a link preview while a preset is set, because a link attachment also makes Facebook drop the background.
+     *
+     */
+    textFormatPresetId?: string;
+};
+
 export type FollowerStatsResponse = {
     accounts?: Array<AccountWithFollowerStats>;
     stats?: {
@@ -9400,9 +9408,9 @@ export type CreatePostData = {
          */
         tiktokSettings?: TikTokPlatformData;
         /**
-         * Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
+         * Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData.facebookSettings, with platform-specific settings taking precedence.
          */
-        facebookSettings?: FacebookPlatformData;
+        facebookSettings?: FacebookSettings;
         recycling?: RecyclingConfig;
         /**
          * Profile ID to schedule via queue. When provided without scheduledFor, the post is auto-assigned to the next available slot. Do not call /v1/queue/next-slot and use that time in scheduledFor, as that bypasses queue locking.
@@ -9564,11 +9572,11 @@ export type UpdatePostData = {
          */
         tiktokSettings?: TikTokPlatformData;
         /**
-         * Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
+         * Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData.facebookSettings, with platform-specific settings taking precedence.
          */
-        facebookSettings?: FacebookPlatformData;
+        facebookSettings?: FacebookSettings;
         recycling?: RecyclingConfig;
-        [key: string]: unknown | string | MediaItem | boolean | TikTokPlatformData | FacebookPlatformData | RecyclingConfig;
+        [key: string]: unknown | string | MediaItem | boolean | TikTokPlatformData | FacebookSettings | RecyclingConfig;
     };
     path: {
         postId: string;
@@ -25068,6 +25076,24 @@ export type CreateAdCampaignData = {
         budgetAmount?: number;
         budgetType?: 'daily' | 'lifetime';
         status?: 'ACTIVE' | 'PAUSED';
+        /**
+         * Campaign bid strategy. Meta puts `bid_strategy` where the budget lives, so this applies only alongside a campaign budget (CBO). Previously settable only via `PUT /v1/ads/campaigns/{campaignId}`.
+         */
+        bidStrategy?: 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS';
+        /**
+         * Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise.
+         */
+        bidAmount?: number;
+        /**
+         * Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.
+         */
+        roasAverageFloor?: number;
+    };
+    headers?: {
+        /**
+         * Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
+         */
+        'Idempotency-Key'?: string;
     };
 };
 
@@ -25253,6 +25279,12 @@ export type DuplicateAdCampaignData = {
          */
         syncAfter?: boolean;
     };
+    headers?: {
+        /**
+         * Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
+         */
+        'Idempotency-Key'?: string;
+    };
     path: {
         /**
          * Source platform campaign ID
@@ -25301,6 +25333,12 @@ export type DuplicateAdSetData = {
         renameSuffix?: string;
         syncAfter?: boolean;
     };
+    headers?: {
+        /**
+         * Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
+         */
+        'Idempotency-Key'?: string;
+    };
     path: {
         /**
          * Source platform ad set ID
@@ -25339,6 +25377,12 @@ export type DuplicateAdData = {
         renameSuffix?: string;
         syncAfter?: boolean;
     };
+    headers?: {
+        /**
+         * Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
+         */
+        'Idempotency-Key'?: string;
+    };
     path: {
         /**
          * Zernio ad ID or platform ad ID
@@ -25649,7 +25693,7 @@ export type GetAdsTimelineResponse = ({
          */
         cpm?: number;
         /**
-         * Sum of conversion events over the range. Meta: events matching the campaign optimization goal. Google: tracked conversions. X / LinkedIn: reported website/lead conversions (added 2026-07).
+         * Sum of conversion events over the range. Fractional values are normal (attribution splitting + Google modeled conversions). Meta: events matching the campaign optimization goal. Google: tracked conversions. X / LinkedIn: reported website/lead conversions (added 2026-07).
          */
         conversions?: number;
         costPerConversion?: number;
@@ -27614,9 +27658,13 @@ export type CreateStandaloneAdData = {
          */
         video?: {
             /**
-             * Public URL of the video. Meta: uploaded via chunked transfer on /act_X/advideos, then the request blocks on Meta's transcoding until status.video_status === 'ready'. LinkedIn: uploaded via the Videos API (multipart), then the request blocks until LinkedIn finishes transcoding (status AVAILABLE) — short clips take ~10-30s.
+             * Public URL of the video. Meta: uploaded via chunked transfer on /act_X/advideos, then the request blocks on Meta's transcoding until status.video_status === 'ready'. LinkedIn: uploaded via the Videos API (multipart), then the request blocks until LinkedIn finishes transcoding (status AVAILABLE) — short clips take ~10-30s. Provide either `url` or `id`.
              */
-            url: string;
+            url?: string;
+            /**
+             * Meta only. Reuse a video ALREADY uploaded to this ad account instead of re-uploading the file: pass the `videoId` returned by a previous create. Wins over `url`, so N ads that differ only in copy share one upload (`existingCreativeId` only covers the identical-copy case). Provide either `url` or `id`.
+             */
+            id?: string;
             /**
              * Public URL of a still-image thumbnail for the video. OPTIONAL: when omitted on Meta, the poster is auto-generated from Meta's own preferred video thumbnail (the same candidates Ads Manager shows), so video ads publish without supplying one. Provide it to control the poster frame exactly (uploaded as an ad image and referenced in object_story_spec.video_data). Ignored by LinkedIn (auto-generated poster frame).
              */
@@ -27973,6 +28021,54 @@ export type CreateStandaloneAdData = {
              */
             callToAction?: string;
         }>;
+        /**
+         * Meta only. Language the top-level copy is written in (e.g. `en`, `pt_BR`), used by the `translations` default rule. Defaults to `en`. Meta rejects a language asset feed whose default rule carries no locales of its own.
+         */
+        defaultLocale?: string;
+        /**
+         * Meta only. Multi-language ads (Dynamic Language Optimization): ONE ad carrying
+         * per-locale copy and, optionally, per-locale media — the "Languages" toggle in Ads
+         * Manager. Keeps social proof (likes/comments/shares) on a SINGLE post instead of
+         * splitting it across one ad per language.
+         *
+         * The ad's top-level copy and media are the DEFAULT every unlisted locale falls back
+         * to, and a variant inherits any field it omits, so send only what differs per
+         * language. Media shared across languages is uploaded once.
+         *
+         * Mutually exclusive with `dynamicCreative`, `placementAssets`, `carouselCards` and
+         * `existingCreativeId` — Meta allows one `asset_feed_spec` shape per creative.
+         *
+         */
+        translations?: Array<{
+            /**
+             * Language code, resolved to Meta's numeric locale id. Bare codes target the '(All)' umbrella (`es` = every Spanish variant); region-qualified codes target the variant (`pt_BR`, `en_GB`).
+             */
+            locale: string;
+            /**
+             * Headline for this language. Inherits the top-level `headline` when omitted.
+             */
+            headline?: string;
+            /**
+             * Primary text for this language. Inherits the top-level `body` when omitted.
+             */
+            body?: string;
+            /**
+             * Link description for this language. Inherits the top-level `description` when omitted.
+             */
+            description?: string;
+            /**
+             * Image for this language. Inherits the ad's `imageUrl` when omitted. The feed is all-image OR all-video.
+             */
+            imageUrl?: string;
+            /**
+             * Video for this language. Inherits the ad's `video.url` when omitted. The feed is all-image OR all-video.
+             */
+            videoUrl?: string;
+            /**
+             * Poster frame for this language's video.
+             */
+            thumbnailUrl?: string;
+        }>;
         /**
          * Meta only. Placement asset customization: pin a SPECIFIC asset (image OR video) to
          * each placement group on a SINGLE ad (e.g. a 9:16 on Stories/Reels and a 4:5 on Feed).