@zernio/node 0.2.1519 → 0.2.1521

package/dist/index.d.mts

@@ -18874,13 +18874,17 @@ type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -61939,7 +61943,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".
@@ -62045,6 +62049,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.
          */

package/dist/index.d.ts

@@ -18874,13 +18874,17 @@ type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -61939,7 +61943,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".
@@ -62045,6 +62049,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.
          */

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.1519",
+  version: "0.2.1521",
   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.1519",
+  version: "0.2.1521",
   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.1519",
+  "version": "0.2.1521",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/types.gen.ts

@@ -17288,13 +17288,17 @@ export type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -63297,7 +63301,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".
@@ -63403,6 +63407,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.
          */