@zernio/node 0.2.78 → 0.2.80

package/dist/index.d.mts

@@ -928,6 +928,20 @@ type AdMetrics = {
     actions?: {
         [key: string]: (number);
     };
+    /**
+     * Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Same keying — values are the revenue attributed to each action_type, in ad-account native currency (same unit as `spend`; see the campaign node's `currency` field). Use this to compute revenue-per-event (e.g. avg purchase value). Meta-only; other platforms return {}.
+     */
+    actionValues?: {
+        [key: string]: (number);
+    };
+    /**
+     * Convenience sum of purchase-type action values — picked from `actionValues` via the same priority list as `conversions` so both fields describe the same events. In ad-account native currency. 0 when the campaign has no purchase event configured. Meta-only.
+     */
+    purchaseValue?: number;
+    /**
+     * Return on ad spend — derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. At ad-set and campaign levels this is recomputed from summed purchaseValue + spend (NOT averaged across children) so it's mathematically correct at every rollup level.
+     */
+    roas?: number;
     /**
      * Present on individual ads only, not on campaign aggregations
      */
@@ -12152,14 +12166,20 @@ type CreateStandaloneAdData = {
         adAccountId: string;
         name: string;
         /**
-         * Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views.
+         * Required on legacy + multi-creative shapes. Inherited from the ad set on the attach shape. Available goals vary by platform.
          */
-        goal: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
-        budgetAmount: number;
-        budgetType: 'daily' | 'lifetime';
+        goal?: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetAmount?: number;
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetType?: 'daily' | 'lifetime';
         currency?: string;
         /**
-         * Required for most platforms. Max: Meta=255, Google=30, Pinterest=100
+         * Required on legacy + attach shapes (skip for multi-creative — use `creatives[].headline`). Max: Meta=255, Google=30, Pinterest=100
          */
         headline?: string;
         /**
@@ -12167,18 +12187,43 @@ type CreateStandaloneAdData = {
          */
         longHeadline?: string;
         /**
-         * Max: Google=90, Pinterest=500
+         * Required on legacy + attach shapes. Max: Google=90, Pinterest=500
          */
-        body: string;
+        body?: string;
         /**
-         * Meta only
+         * Required on legacy + attach shapes. Meta only.
          */
         callToAction?: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        /**
+         * Required on legacy + attach shapes. Skip for multi-creative.
+         */
         linkUrl?: string;
         /**
-         * Image URL (or video URL for TikTok). Not required for Google Search campaigns.
+         * Required on legacy + attach shapes. Not required for Google Search campaigns.
          */
         imageUrl?: string;
+        /**
+         * Meta-only. When present, switches to the multi-creative shape:
+         * creates 1 campaign + 1 ad set + N ads (one per entry here).
+         * Top-level `headline` / `body` / `imageUrl` / `linkUrl` /
+         * `callToAction` are ignored in this mode. Mutually exclusive with `adSetId`.
+         *
+         */
+        creatives?: Array<{
+            headline: string;
+            body: string;
+            imageUrl: string;
+            linkUrl: string;
+            callToAction: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        }>;
+        /**
+         * Meta-only. When present, switches to the attach shape: adds
+         * one new ad to this existing ad set without creating a new
+         * campaign. Budget, targeting, goal, and schedule are inherited
+         * from the ad set on Meta. Mutually exclusive with `creatives[]`.
+         *
+         */
+        adSetId?: string;
         /**
          * Google Display only
          */
@@ -12227,10 +12272,15 @@ type CreateStandaloneAdData = {
         advantageAudience?: 0 | 1;
     };
 };
-type CreateStandaloneAdResponse = ({
+type CreateStandaloneAdResponse = (({
     ad?: Ad;
     message?: string;
-});
+} | {
+    ads?: Array<Ad>;
+    platformCampaignId?: string;
+    platformAdSetId?: string;
+    message?: string;
+}));
 type CreateStandaloneAdError = (unknown | {
     error?: string;
 });

package/dist/index.d.ts

@@ -928,6 +928,20 @@ type AdMetrics = {
     actions?: {
         [key: string]: (number);
     };
+    /**
+     * Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Same keying — values are the revenue attributed to each action_type, in ad-account native currency (same unit as `spend`; see the campaign node's `currency` field). Use this to compute revenue-per-event (e.g. avg purchase value). Meta-only; other platforms return {}.
+     */
+    actionValues?: {
+        [key: string]: (number);
+    };
+    /**
+     * Convenience sum of purchase-type action values — picked from `actionValues` via the same priority list as `conversions` so both fields describe the same events. In ad-account native currency. 0 when the campaign has no purchase event configured. Meta-only.
+     */
+    purchaseValue?: number;
+    /**
+     * Return on ad spend — derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. At ad-set and campaign levels this is recomputed from summed purchaseValue + spend (NOT averaged across children) so it's mathematically correct at every rollup level.
+     */
+    roas?: number;
     /**
      * Present on individual ads only, not on campaign aggregations
      */
@@ -12152,14 +12166,20 @@ type CreateStandaloneAdData = {
         adAccountId: string;
         name: string;
         /**
-         * Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views.
+         * Required on legacy + multi-creative shapes. Inherited from the ad set on the attach shape. Available goals vary by platform.
          */
-        goal: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
-        budgetAmount: number;
-        budgetType: 'daily' | 'lifetime';
+        goal?: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetAmount?: number;
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetType?: 'daily' | 'lifetime';
         currency?: string;
         /**
-         * Required for most platforms. Max: Meta=255, Google=30, Pinterest=100
+         * Required on legacy + attach shapes (skip for multi-creative — use `creatives[].headline`). Max: Meta=255, Google=30, Pinterest=100
          */
         headline?: string;
         /**
@@ -12167,18 +12187,43 @@ type CreateStandaloneAdData = {
          */
         longHeadline?: string;
         /**
-         * Max: Google=90, Pinterest=500
+         * Required on legacy + attach shapes. Max: Google=90, Pinterest=500
          */
-        body: string;
+        body?: string;
         /**
-         * Meta only
+         * Required on legacy + attach shapes. Meta only.
          */
         callToAction?: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        /**
+         * Required on legacy + attach shapes. Skip for multi-creative.
+         */
         linkUrl?: string;
         /**
-         * Image URL (or video URL for TikTok). Not required for Google Search campaigns.
+         * Required on legacy + attach shapes. Not required for Google Search campaigns.
          */
         imageUrl?: string;
+        /**
+         * Meta-only. When present, switches to the multi-creative shape:
+         * creates 1 campaign + 1 ad set + N ads (one per entry here).
+         * Top-level `headline` / `body` / `imageUrl` / `linkUrl` /
+         * `callToAction` are ignored in this mode. Mutually exclusive with `adSetId`.
+         *
+         */
+        creatives?: Array<{
+            headline: string;
+            body: string;
+            imageUrl: string;
+            linkUrl: string;
+            callToAction: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        }>;
+        /**
+         * Meta-only. When present, switches to the attach shape: adds
+         * one new ad to this existing ad set without creating a new
+         * campaign. Budget, targeting, goal, and schedule are inherited
+         * from the ad set on Meta. Mutually exclusive with `creatives[]`.
+         *
+         */
+        adSetId?: string;
         /**
          * Google Display only
          */
@@ -12227,10 +12272,15 @@ type CreateStandaloneAdData = {
         advantageAudience?: 0 | 1;
     };
 };
-type CreateStandaloneAdResponse = ({
+type CreateStandaloneAdResponse = (({
     ad?: Ad;
     message?: string;
-});
+} | {
+    ads?: Array<Ad>;
+    platformCampaignId?: string;
+    platformAdSetId?: string;
+    message?: string;
+}));
 type CreateStandaloneAdError = (unknown | {
     error?: string;
 });

package/package.json

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

package/src/generated/sdk.gen.ts

@@ -3158,7 +3158,14 @@ export const boostPost = <ThrowOnError extends boolean = false>(options: Options
 
 /**
  * Create standalone ad
- * Creates a paid ad with custom creative (headline, body, image/video, link). Creates the full platform campaign hierarchy.
+ * Creates a paid ad with custom creative. The request body supports three mutually-exclusive shapes:
+ *
+ * 1. **Legacy single-creative** (all platforms). Top-level `headline` + `body` + `imageUrl` + `linkUrl` + `callToAction` create 1 campaign + 1 ad set + 1 ad.
+ * 2. **Multi-creative** (Meta only — use `creatives[]` array). Creates 1 campaign + 1 ad set + N ads sharing the same budget / targeting / schedule. This is the standard performance-marketing creative-testing flow — Meta's delivery algorithm A/B tests the creatives inside a single ad set so budget isn't fragmented across N parallel campaigns.
+ * 3. **Attach to existing ad set** (Meta only — pass `adSetId` + a single creative). Adds one new ad to an existing ad set without creating a new campaign. Budget, targeting, goal are inherited from the ad set on Meta.
+ *
+ * `creatives[]` and `adSetId` are mutually exclusive; specifying both returns 400.
+ *
  */
 export const createStandaloneAd = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<CreateStandaloneAdData, ThrowOnError>) => {
     return (options?.client ?? client).post<CreateStandaloneAdResponse, CreateStandaloneAdError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -343,6 +343,20 @@ export type AdMetrics = {
     actions?: {
         [key: string]: (number);
     };
+    /**
+     * Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Same keying — values are the revenue attributed to each action_type, in ad-account native currency (same unit as `spend`; see the campaign node's `currency` field). Use this to compute revenue-per-event (e.g. avg purchase value). Meta-only; other platforms return {}.
+     */
+    actionValues?: {
+        [key: string]: (number);
+    };
+    /**
+     * Convenience sum of purchase-type action values — picked from `actionValues` via the same priority list as `conversions` so both fields describe the same events. In ad-account native currency. 0 when the campaign has no purchase event configured. Meta-only.
+     */
+    purchaseValue?: number;
+    /**
+     * Return on ad spend — derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. At ad-set and campaign levels this is recomputed from summed purchaseValue + spend (NOT averaged across children) so it's mathematically correct at every rollup level.
+     */
+    roas?: number;
     /**
      * Present on individual ads only, not on campaign aggregations
      */
@@ -12462,14 +12476,20 @@ export type CreateStandaloneAdData = {
         adAccountId: string;
         name: string;
         /**
-         * Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views.
+         * Required on legacy + multi-creative shapes. Inherited from the ad set on the attach shape. Available goals vary by platform.
          */
-        goal: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
-        budgetAmount: number;
-        budgetType: 'daily' | 'lifetime';
+        goal?: 'engagement' | 'traffic' | 'awareness' | 'video_views' | 'lead_generation' | 'conversions' | 'app_promotion';
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetAmount?: number;
+        /**
+         * Required on legacy + multi-creative shapes. Inherited on attach.
+         */
+        budgetType?: 'daily' | 'lifetime';
         currency?: string;
         /**
-         * Required for most platforms. Max: Meta=255, Google=30, Pinterest=100
+         * Required on legacy + attach shapes (skip for multi-creative — use `creatives[].headline`). Max: Meta=255, Google=30, Pinterest=100
          */
         headline?: string;
         /**
@@ -12477,18 +12497,43 @@ export type CreateStandaloneAdData = {
          */
         longHeadline?: string;
         /**
-         * Max: Google=90, Pinterest=500
+         * Required on legacy + attach shapes. Max: Google=90, Pinterest=500
          */
-        body: string;
+        body?: string;
         /**
-         * Meta only
+         * Required on legacy + attach shapes. Meta only.
          */
         callToAction?: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        /**
+         * Required on legacy + attach shapes. Skip for multi-creative.
+         */
         linkUrl?: string;
         /**
-         * Image URL (or video URL for TikTok). Not required for Google Search campaigns.
+         * Required on legacy + attach shapes. Not required for Google Search campaigns.
          */
         imageUrl?: string;
+        /**
+         * Meta-only. When present, switches to the multi-creative shape:
+         * creates 1 campaign + 1 ad set + N ads (one per entry here).
+         * Top-level `headline` / `body` / `imageUrl` / `linkUrl` /
+         * `callToAction` are ignored in this mode. Mutually exclusive with `adSetId`.
+         *
+         */
+        creatives?: Array<{
+            headline: string;
+            body: string;
+            imageUrl: string;
+            linkUrl: string;
+            callToAction: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        }>;
+        /**
+         * Meta-only. When present, switches to the attach shape: adds
+         * one new ad to this existing ad set without creating a new
+         * campaign. Budget, targeting, goal, and schedule are inherited
+         * from the ad set on Meta. Mutually exclusive with `creatives[]`.
+         *
+         */
+        adSetId?: string;
         /**
          * Google Display only
          */
@@ -12538,10 +12583,15 @@ export type CreateStandaloneAdData = {
     };
 };
 
-export type CreateStandaloneAdResponse = ({
+export type CreateStandaloneAdResponse = (({
     ad?: Ad;
     message?: string;
-});
+} | {
+    ads?: Array<Ad>;
+    platformCampaignId?: string;
+    platformAdSetId?: string;
+    message?: string;
+}));
 
 export type CreateStandaloneAdError = (unknown | {
     error?: string;