@zernio/node 0.2.580 → 0.2.582

package/dist/index.d.mts

@@ -4051,6 +4051,9 @@ type ExternalPostSummary = {
         views?: number;
         reach?: number;
         impressions?: number;
+        /**
+         * Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted.
+         */
         engagementRate?: number;
         /**
          * When these metrics were last refreshed
@@ -5329,7 +5332,7 @@ type LinkedInAggregateAnalyticsTotalResponse = {
          */
         sends?: number;
         /**
-         * Overall engagement rate as percentage
+         * Overall engagement rate, as a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100. Clicks are not counted, and there is no fallback denominator, so this is 0 whenever impressions is 0. This is NOT the same formula as PostAnalytics.engagementRate on GET /v1/analytics.
          */
         engagementRate?: number;
     };
@@ -5669,6 +5672,9 @@ type PostAnalytics = {
      * Video length in seconds. Currently Instagram Reels only; combine with igReelsAvgWatchTime (ms) to estimate retention. Null when unknown (other platforms, non-video media, or when Instagram does not expose the media URL, e.g. reels with copyrighted audio).
      */
     videoDurationSeconds?: (number) | null;
+    /**
+     * Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so it is not the same basis on every post: a post with impressions divides by impressions, one without falls back to reach, then to views. If you need a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. The engagementRate on the LinkedIn account endpoints is a different formula.
+     */
     engagementRate?: number;
     lastUpdated?: string;
 };
@@ -15236,7 +15242,7 @@ type GetLinkedInPostAnalyticsResponse = ({
          */
         views?: number;
         /**
-         * Engagement rate as percentage
+         * Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100. Unlike PostAnalytics.engagementRate on GET /v1/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0. For organization accounts the value is the rate LinkedIn returns, not one computed here.
          */
         engagementRate?: number;
     };
@@ -27453,18 +27459,21 @@ type UpdateAdCampaignStatusData = {
 };
 type UpdateAdCampaignStatusResponse = ({
     /**
-     * Number of ads updated
+     * The status written to the campaign
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
      */
     updated?: number;
     /**
-     * Number of ads skipped
+     * Number of ads whose own status was left as it was
      */
     skipped?: number;
-    skippedReasons?: Array<(string)>;
     /**
-     * Human-readable summary (present when no ads were actionable)
+     * Why each group of ads was skipped
      */
-    message?: string;
+    skippedReasons?: Array<(string)>;
 });
 type UpdateAdCampaignStatusError = (unknown | {
     error?: string;
@@ -27774,7 +27783,7 @@ type UpdateAdSetData = {
             type?: 'daily' | 'lifetime';
         };
         /**
-         * Omit if not toggling delivery state
+         * Writes the ad set's own on/off switch (Meta: `configured_status`) on Meta and LinkedIn, whatever delivery status its ads report. Omit if not toggling delivery state.
          */
         status?: 'active' | 'paused';
         /**
@@ -27879,9 +27888,26 @@ type UpdateAdSetData = {
 type UpdateAdSetResponse = ({
     budget?: AdBudget;
     budgetLevel?: 'adset';
+    /**
+     * The status written to the ad set. Absent when nothing was written (see statusMessage).
+     */
     status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed alongside the ad set switch
+     */
     statusUpdated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     statusSkipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    statusSkippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable; `status` is then absent because nothing was written
+     */
+    statusMessage?: string;
     bidStrategy?: BidStrategy;
     bidAmount?: (number) | null;
     roasAverageFloor?: (number) | null;
@@ -27905,8 +27931,26 @@ type UpdateAdSetStatusData = {
     };
 };
 type UpdateAdSetStatusResponse = ({
+    /**
+     * The status written to the ad set. Absent when nothing was written (see message).
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
+     */
     updated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     skipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    skippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable
+     */
+    message?: string;
 });
 type UpdateAdSetStatusError = (unknown | {
     error?: string;
@@ -30031,7 +30075,7 @@ type CreateStandaloneAdData = {
          */
         budgetType?: 'daily' | 'lifetime';
         /**
-         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused and skips activation, so you can review before they spend. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
+         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused so you can review before they spend. On Meta the pause is held on the campaign this call creates, leaving the ad set and ad switched on, so a single PUT /v1/ads/campaigns/{campaignId}/status with `active` brings the whole thing live. It is held at every level instead when the pause cannot rely on the campaign: `existingCampaignId` (that campaign may be running and is never touched) or `campaignStatus: ACTIVE`. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
          */
         status?: 'ACTIVE' | 'PAUSED';
         /**

package/dist/index.d.ts

@@ -4051,6 +4051,9 @@ type ExternalPostSummary = {
         views?: number;
         reach?: number;
         impressions?: number;
+        /**
+         * Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted.
+         */
         engagementRate?: number;
         /**
          * When these metrics were last refreshed
@@ -5329,7 +5332,7 @@ type LinkedInAggregateAnalyticsTotalResponse = {
          */
         sends?: number;
         /**
-         * Overall engagement rate as percentage
+         * Overall engagement rate, as a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100. Clicks are not counted, and there is no fallback denominator, so this is 0 whenever impressions is 0. This is NOT the same formula as PostAnalytics.engagementRate on GET /v1/analytics.
          */
         engagementRate?: number;
     };
@@ -5669,6 +5672,9 @@ type PostAnalytics = {
      * Video length in seconds. Currently Instagram Reels only; combine with igReelsAvgWatchTime (ms) to estimate retention. Null when unknown (other platforms, non-video media, or when Instagram does not expose the media URL, e.g. reels with copyrighted audio).
      */
     videoDurationSeconds?: (number) | null;
+    /**
+     * Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so it is not the same basis on every post: a post with impressions divides by impressions, one without falls back to reach, then to views. If you need a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. The engagementRate on the LinkedIn account endpoints is a different formula.
+     */
     engagementRate?: number;
     lastUpdated?: string;
 };
@@ -15236,7 +15242,7 @@ type GetLinkedInPostAnalyticsResponse = ({
          */
         views?: number;
         /**
-         * Engagement rate as percentage
+         * Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100. Unlike PostAnalytics.engagementRate on GET /v1/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0. For organization accounts the value is the rate LinkedIn returns, not one computed here.
          */
         engagementRate?: number;
     };
@@ -27453,18 +27459,21 @@ type UpdateAdCampaignStatusData = {
 };
 type UpdateAdCampaignStatusResponse = ({
     /**
-     * Number of ads updated
+     * The status written to the campaign
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
      */
     updated?: number;
     /**
-     * Number of ads skipped
+     * Number of ads whose own status was left as it was
      */
     skipped?: number;
-    skippedReasons?: Array<(string)>;
     /**
-     * Human-readable summary (present when no ads were actionable)
+     * Why each group of ads was skipped
      */
-    message?: string;
+    skippedReasons?: Array<(string)>;
 });
 type UpdateAdCampaignStatusError = (unknown | {
     error?: string;
@@ -27774,7 +27783,7 @@ type UpdateAdSetData = {
             type?: 'daily' | 'lifetime';
         };
         /**
-         * Omit if not toggling delivery state
+         * Writes the ad set's own on/off switch (Meta: `configured_status`) on Meta and LinkedIn, whatever delivery status its ads report. Omit if not toggling delivery state.
          */
         status?: 'active' | 'paused';
         /**
@@ -27879,9 +27888,26 @@ type UpdateAdSetData = {
 type UpdateAdSetResponse = ({
     budget?: AdBudget;
     budgetLevel?: 'adset';
+    /**
+     * The status written to the ad set. Absent when nothing was written (see statusMessage).
+     */
     status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed alongside the ad set switch
+     */
     statusUpdated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     statusSkipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    statusSkippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable; `status` is then absent because nothing was written
+     */
+    statusMessage?: string;
     bidStrategy?: BidStrategy;
     bidAmount?: (number) | null;
     roasAverageFloor?: (number) | null;
@@ -27905,8 +27931,26 @@ type UpdateAdSetStatusData = {
     };
 };
 type UpdateAdSetStatusResponse = ({
+    /**
+     * The status written to the ad set. Absent when nothing was written (see message).
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
+     */
     updated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     skipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    skippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable
+     */
+    message?: string;
 });
 type UpdateAdSetStatusError = (unknown | {
     error?: string;
@@ -30031,7 +30075,7 @@ type CreateStandaloneAdData = {
          */
         budgetType?: 'daily' | 'lifetime';
         /**
-         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused and skips activation, so you can review before they spend. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
+         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused so you can review before they spend. On Meta the pause is held on the campaign this call creates, leaving the ad set and ad switched on, so a single PUT /v1/ads/campaigns/{campaignId}/status with `active` brings the whole thing live. It is held at every level instead when the pause cannot rely on the campaign: `existingCampaignId` (that campaign may be running and is never touched) or `campaignStatus: ACTIVE`. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
          */
         status?: 'ACTIVE' | 'PAUSED';
         /**

package/dist/index.js

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

package/src/generated/sdk.gen.ts

@@ -7109,8 +7109,20 @@ export const createAdCampaign = <ThrowOnError extends boolean = false>(options:
 
 /**
  * Pause or resume a campaign
- * Updates the status of all ads in a campaign. Makes one platform API call (not per-ad) since status cascades through the campaign hierarchy.
- * Ads in terminal statuses (rejected, completed, cancelled) are automatically skipped.
+ * Writes the campaign's own on/off switch, then lets the platform cascade delivery to its ad sets and ads.
+ * Makes one platform API call, not one per ad.
+ *
+ * The switch is always written, whatever delivery status the ads underneath report: an ad still in review
+ * does not block resuming its campaign. The echoed `status` is the confirmation that it landed.
+ *
+ * `updated` / `skipped` describe only the ads whose own stored status CHANGED alongside it, so
+ * `updated: 0` is a normal successful response, not a no-op. Ads are skipped when they are in a terminal
+ * status (rejected, completed, cancelled), already in the target state, or switched on but not yet
+ * delivering — the last group keeps its `pending_review` / `error` status until the platform reports what
+ * it became. `skippedReasons` names which case applies.
+ *
+ * On Meta this flips the campaign only. An ad set paused in its own right stays paused, so pair this with
+ * PUT /v1/ads/ad-sets/{adSetId}/status when you also need the ad set switched back on.
  *
  */
 export const updateAdCampaignStatus = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<UpdateAdCampaignStatusData, ThrowOnError>) => {
@@ -7328,6 +7340,23 @@ export const updateAdSet = <ThrowOnError extends boolean = false>(options: Optio
  * status toggle and prefer a symmetric URL to
  * /v1/ads/campaigns/{campaignId}/status.
  *
+ * On Meta and LinkedIn this writes the ad set's own on/off switch
+ * (Meta: `configured_status`), whatever delivery status its ads report —
+ * an ad still in review does not block resuming its ad set. The echoed
+ * `status` is the confirmation that it landed. Where the platform has no
+ * ad-set switch (TikTok and others) the toggle is emulated by flipping the
+ * child ads; a call with no actionable ad then writes nothing and returns a
+ * `message` with no `status`.
+ *
+ * `updated` / `skipped` describe only the ads whose own stored status
+ * CHANGED alongside the switch, so `updated: 0` is a normal successful
+ * response. See `skippedReasons` for which of the three cases applies
+ * (terminal, already in the target state, or switched on but not yet
+ * delivering).
+ *
+ * A campaign created paused needs its campaign resumed as well: pair this
+ * with PUT /v1/ads/campaigns/{campaignId}/status.
+ *
  */
 export const updateAdSetStatus = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<UpdateAdSetStatusData, ThrowOnError>) => {
     return (options?.client ?? client).put<UpdateAdSetStatusResponse, UpdateAdSetStatusError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -2852,6 +2852,9 @@ export type ExternalPostSummary = {
         views?: number;
         reach?: number;
         impressions?: number;
+        /**
+         * Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted.
+         */
         engagementRate?: number;
         /**
          * When these metrics were last refreshed
@@ -4174,7 +4177,7 @@ export type LinkedInAggregateAnalyticsTotalResponse = {
          */
         sends?: number;
         /**
-         * Overall engagement rate as percentage
+         * Overall engagement rate, as a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100. Clicks are not counted, and there is no fallback denominator, so this is 0 whenever impressions is 0. This is NOT the same formula as PostAnalytics.engagementRate on GET /v1/analytics.
          */
         engagementRate?: number;
     };
@@ -4538,6 +4541,9 @@ export type PostAnalytics = {
      * Video length in seconds. Currently Instagram Reels only; combine with igReelsAvgWatchTime (ms) to estimate retention. Null when unknown (other platforms, non-video media, or when Instagram does not expose the media URL, e.g. reels with copyrighted audio).
      */
     videoDurationSeconds?: (number) | null;
+    /**
+     * Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so it is not the same basis on every post: a post with impressions divides by impressions, one without falls back to reach, then to views. If you need a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. The engagementRate on the LinkedIn account endpoints is a different formula.
+     */
     engagementRate?: number;
     lastUpdated?: string;
 };
@@ -14668,7 +14674,7 @@ export type GetLinkedInPostAnalyticsResponse = ({
          */
         views?: number;
         /**
-         * Engagement rate as percentage
+         * Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100. Unlike PostAnalytics.engagementRate on GET /v1/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0. For organization accounts the value is the rate LinkedIn returns, not one computed here.
          */
         engagementRate?: number;
     };
@@ -27826,18 +27832,21 @@ export type UpdateAdCampaignStatusData = {
 
 export type UpdateAdCampaignStatusResponse = ({
     /**
-     * Number of ads updated
+     * The status written to the campaign
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
      */
     updated?: number;
     /**
-     * Number of ads skipped
+     * Number of ads whose own status was left as it was
      */
     skipped?: number;
-    skippedReasons?: Array<(string)>;
     /**
-     * Human-readable summary (present when no ads were actionable)
+     * Why each group of ads was skipped
      */
-    message?: string;
+    skippedReasons?: Array<(string)>;
 });
 
 export type UpdateAdCampaignStatusError = (unknown | {
@@ -28170,7 +28179,7 @@ export type UpdateAdSetData = {
             type?: 'daily' | 'lifetime';
         };
         /**
-         * Omit if not toggling delivery state
+         * Writes the ad set's own on/off switch (Meta: `configured_status`) on Meta and LinkedIn, whatever delivery status its ads report. Omit if not toggling delivery state.
          */
         status?: 'active' | 'paused';
         /**
@@ -28276,9 +28285,26 @@ export type UpdateAdSetData = {
 export type UpdateAdSetResponse = ({
     budget?: AdBudget;
     budgetLevel?: 'adset';
+    /**
+     * The status written to the ad set. Absent when nothing was written (see statusMessage).
+     */
     status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed alongside the ad set switch
+     */
     statusUpdated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     statusSkipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    statusSkippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable; `status` is then absent because nothing was written
+     */
+    statusMessage?: string;
     bidStrategy?: BidStrategy;
     bidAmount?: (number) | null;
     roasAverageFloor?: (number) | null;
@@ -28305,8 +28331,26 @@ export type UpdateAdSetStatusData = {
 };
 
 export type UpdateAdSetStatusResponse = ({
+    /**
+     * The status written to the ad set. Absent when nothing was written (see message).
+     */
+    status?: 'active' | 'paused';
+    /**
+     * Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.
+     */
     updated?: number;
+    /**
+     * Number of ads whose own status was left as it was
+     */
     skipped?: number;
+    /**
+     * Why each group of ads was skipped
+     */
+    skippedReasons?: Array<(string)>;
+    /**
+     * Present only where the platform has no ad-set switch and no child ad was actionable
+     */
+    message?: string;
 });
 
 export type UpdateAdSetStatusError = (unknown | {
@@ -30568,7 +30612,7 @@ export type CreateStandaloneAdData = {
          */
         budgetType?: 'daily' | 'lifetime';
         /**
-         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused and skips activation, so you can review before they spend. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
+         * Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused so you can review before they spend. On Meta the pause is held on the campaign this call creates, leaving the ad set and ad switched on, so a single PUT /v1/ads/campaigns/{campaignId}/status with `active` brings the whole thing live. It is held at every level instead when the pause cannot rely on the campaign: `existingCampaignId` (that campaign may be running and is never touched) or `campaignStatus: ACTIVE`. On TikTok the whole campaign > ad group > ad hierarchy stays paused.
          */
         status?: 'ACTIVE' | 'PAUSED';
         /**