@zernio/node 0.2.484 → 0.2.486

package/dist/index.d.mts

@@ -1654,7 +1654,9 @@ type budgetLevel = 'campaign' | 'adset';
  * called with `timeIncrement=1`. Rate metrics (ctr/cpc/cpm/costPerConversion/
  * roas/videoAvgTimeWatchedActions) are recomputed per day from that day's
  * sums, so summing the additive fields across a node's `daily[]` reproduces
- * its aggregated `metrics` total. Do NOT sum or plain-average
+ * its aggregated `metrics` total. `reach` is the exception: on Meta the
+ * aggregated total is de-duplicated across the range, so daily reach does
+ * not sum to it. Do NOT sum or plain-average
  * `videoAvgTimeWatchedActions` across days: the range value is the
  * play-weighted average of the daily values.
  *
@@ -1668,6 +1670,9 @@ type AdDailyMetrics = AdMetrics & {
 type AdMetrics = {
     spend?: number;
     impressions?: number;
+    /**
+     * Unique people reached in the requested date range. Meta (facebook/instagram): Meta's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery; on a transient Meta error the value temporarily falls back to a sum of per-day reach, which overcounts people reached on multiple days or by multiple child ads). Because it is de-duplicated, Meta reach is NOT additive: neither daily values nor child nodes sum to the range total. TikTok: sum of per-day reach, so multi-day ranges overcount vs TikTok Ads Manager. Google, LinkedIn, X, Pinterest and OpenAI report 0 (reach not synced). Only derive frequency (impressions / reach) for Meta.
+     */
     reach?: number;
     clicks?: number;
     /**
@@ -1816,7 +1821,7 @@ type AdTreeAdSet = {
         page_id?: string;
     } | null;
     /**
-     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation (core fields like _id, name, platform, status, budget, metrics, creative, goal are included; targeting and schedule may be absent). When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
+     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation: `_id`, `name`, `platform`, `status`, `configuredStatus`, `reviewStatus`, `budget`, `metrics`, `creative`, `goal` and the `platform*` ids are always included; `targeting` and `schedule` may be absent. `configuredStatus` (the ad's own on/off toggle) and `reviewStatus` (the platform's review verdict) are part of this contract, not incidental: a rejected ad is only distinguishable from a healthy one through `reviewStatus`. When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
      */
     ads?: Array<Ad>;
     /**
@@ -1928,7 +1933,7 @@ type AdTreeCampaign = {
     } | null;
     adSets?: Array<AdTreeAdSet>;
     /**
-     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total.
+     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total, except `reach`: on Meta the range total is de-duplicated, so daily reach does not sum to it.
      */
     daily?: Array<AdDailyMetrics>;
 };
@@ -25332,7 +25337,7 @@ type GetAdTreeData = {
          */
         status?: AdStatus;
         /**
-         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`. See `dailyLevel` to control which levels carry it.
+         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except Meta `reach`: the range total is Meta's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it.
          */
         timeIncrement?: 1;
         /**
@@ -25384,6 +25389,9 @@ type GetAdsTimelineResponse = ({
          */
         spend?: number;
         impressions?: number;
+        /**
+         * Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted).
+         */
         reach?: number;
         clicks?: number;
         engagement?: number;
@@ -27942,6 +27950,12 @@ type CreateStandaloneAdData = {
             /**
              * Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
              * **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
+             * To discover the pixels an ad account can use, call
+             * `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
+             * carries `kind` and `ownerAdAccountId`), or
+             * `GET /v1/accounts/{accountId}/conversion-destinations`. Note this is a
+             * different resource from `GET /v1/ads/{adId}/tracking-tags`, which reads an
+             * ad's click-URL params (`url_tags`), not pixels.
              *
              */
             pixelId?: string;

package/dist/index.d.ts

@@ -1654,7 +1654,9 @@ type budgetLevel = 'campaign' | 'adset';
  * called with `timeIncrement=1`. Rate metrics (ctr/cpc/cpm/costPerConversion/
  * roas/videoAvgTimeWatchedActions) are recomputed per day from that day's
  * sums, so summing the additive fields across a node's `daily[]` reproduces
- * its aggregated `metrics` total. Do NOT sum or plain-average
+ * its aggregated `metrics` total. `reach` is the exception: on Meta the
+ * aggregated total is de-duplicated across the range, so daily reach does
+ * not sum to it. Do NOT sum or plain-average
  * `videoAvgTimeWatchedActions` across days: the range value is the
  * play-weighted average of the daily values.
  *
@@ -1668,6 +1670,9 @@ type AdDailyMetrics = AdMetrics & {
 type AdMetrics = {
     spend?: number;
     impressions?: number;
+    /**
+     * Unique people reached in the requested date range. Meta (facebook/instagram): Meta's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery; on a transient Meta error the value temporarily falls back to a sum of per-day reach, which overcounts people reached on multiple days or by multiple child ads). Because it is de-duplicated, Meta reach is NOT additive: neither daily values nor child nodes sum to the range total. TikTok: sum of per-day reach, so multi-day ranges overcount vs TikTok Ads Manager. Google, LinkedIn, X, Pinterest and OpenAI report 0 (reach not synced). Only derive frequency (impressions / reach) for Meta.
+     */
     reach?: number;
     clicks?: number;
     /**
@@ -1816,7 +1821,7 @@ type AdTreeAdSet = {
         page_id?: string;
     } | null;
     /**
-     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation (core fields like _id, name, platform, status, budget, metrics, creative, goal are included; targeting and schedule may be absent). When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
+     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation: `_id`, `name`, `platform`, `status`, `configuredStatus`, `reviewStatus`, `budget`, `metrics`, `creative`, `goal` and the `platform*` ids are always included; `targeting` and `schedule` may be absent. `configuredStatus` (the ad's own on/off toggle) and `reviewStatus` (the platform's review verdict) are part of this contract, not incidental: a rejected ad is only distinguishable from a healthy one through `reviewStatus`. When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
      */
     ads?: Array<Ad>;
     /**
@@ -1928,7 +1933,7 @@ type AdTreeCampaign = {
     } | null;
     adSets?: Array<AdTreeAdSet>;
     /**
-     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total.
+     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total, except `reach`: on Meta the range total is de-duplicated, so daily reach does not sum to it.
      */
     daily?: Array<AdDailyMetrics>;
 };
@@ -25332,7 +25337,7 @@ type GetAdTreeData = {
          */
         status?: AdStatus;
         /**
-         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`. See `dailyLevel` to control which levels carry it.
+         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except Meta `reach`: the range total is Meta's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it.
          */
         timeIncrement?: 1;
         /**
@@ -25384,6 +25389,9 @@ type GetAdsTimelineResponse = ({
          */
         spend?: number;
         impressions?: number;
+        /**
+         * Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted).
+         */
         reach?: number;
         clicks?: number;
         engagement?: number;
@@ -27942,6 +27950,12 @@ type CreateStandaloneAdData = {
             /**
              * Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
              * **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
+             * To discover the pixels an ad account can use, call
+             * `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
+             * carries `kind` and `ownerAdAccountId`), or
+             * `GET /v1/accounts/{accountId}/conversion-destinations`. Note this is a
+             * different resource from `GET /v1/ads/{adId}/tracking-tags`, which reads an
+             * ad's click-URL params (`url_tags`), not pixels.
              *
              */
             pixelId?: string;

package/dist/index.js

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

package/src/generated/sdk.gen.ts

@@ -6908,6 +6908,12 @@ export const updateAdSetStatus = <ThrowOnError extends boolean = false>(options:
  * (`campaign` default, or `adset` / `ad`) to choose which levels carry the series. This replaces
  * calling the tree once per day for per-campaign daily trends.
  *
+ * **Deleted objects stay in the tree.** Deleting an ad or a campaign is a soft delete: the Ad
+ * documents move to `status: cancelled` and are kept indefinitely, so their historical spend
+ * still counts toward the metrics of any date range they fall in. There is no pruning job and
+ * no retention window. Filter on `status` if your view should hide them, but do that after
+ * reading the totals, not before.
+ *
  */
 export const getAdTree = <ThrowOnError extends boolean = false>(options?: OptionsLegacyParser<GetAdTreeData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdTreeResponse, GetAdTreeError, ThrowOnError>({
@@ -7167,6 +7173,11 @@ export const getAdAnalytics = <ThrowOnError extends boolean = false>(options: Op
  * - LinkedIn (linkedinads): the campaign's Dynamic UTM `dynamicValueParameters` + `customValueParameters`.
  * Returns 405 for platforms without a click-URL tracking surface (TikTok, X, Pinterest).
  *
+ * **Not pixels.** Despite the shared path segment, this endpoint has nothing to do with
+ * measurement tags. For an ad account's pixels use
+ * `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (Meta Pixels, with `kind`
+ * and `ownerAdAccountId`) or `GET /v1/accounts/{accountId}/conversion-destinations`.
+ *
  */
 export const getAdTrackingTags = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetAdTrackingTagsData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdTrackingTagsResponse, GetAdTrackingTagsError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -478,7 +478,9 @@ export type budgetLevel = 'campaign' | 'adset';
  * called with `timeIncrement=1`. Rate metrics (ctr/cpc/cpm/costPerConversion/
  * roas/videoAvgTimeWatchedActions) are recomputed per day from that day's
  * sums, so summing the additive fields across a node's `daily[]` reproduces
- * its aggregated `metrics` total. Do NOT sum or plain-average
+ * its aggregated `metrics` total. `reach` is the exception: on Meta the
+ * aggregated total is de-duplicated across the range, so daily reach does
+ * not sum to it. Do NOT sum or plain-average
  * `videoAvgTimeWatchedActions` across days: the range value is the
  * play-weighted average of the daily values.
  *
@@ -493,6 +495,9 @@ export type AdDailyMetrics = AdMetrics & {
 export type AdMetrics = {
     spend?: number;
     impressions?: number;
+    /**
+     * Unique people reached in the requested date range. Meta (facebook/instagram): Meta's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery; on a transient Meta error the value temporarily falls back to a sum of per-day reach, which overcounts people reached on multiple days or by multiple child ads). Because it is de-duplicated, Meta reach is NOT additive: neither daily values nor child nodes sum to the range total. TikTok: sum of per-day reach, so multi-day ranges overcount vs TikTok Ads Manager. Google, LinkedIn, X, Pinterest and OpenAI report 0 (reach not synced). Only derive frequency (impressions / reach) for Meta.
+     */
     reach?: number;
     clicks?: number;
     /**
@@ -644,7 +649,7 @@ export type AdTreeAdSet = {
         page_id?: string;
     } | null;
     /**
-     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation (core fields like _id, name, platform, status, budget, metrics, creative, goal are included; targeting and schedule may be absent). When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
+     * Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation: `_id`, `name`, `platform`, `status`, `configuredStatus`, `reviewStatus`, `budget`, `metrics`, `creative`, `goal` and the `platform*` ids are always included; `targeting` and `schedule` may be absent. `configuredStatus` (the ad's own on/off toggle) and `reviewStatus` (the platform's review verdict) are part of this contract, not incidental: a rejected ad is only distinguishable from a healthy one through `reviewStatus`. When `timeIncrement=1&dailyLevel=ad`, each entry also carries a `daily[]` array of `AdDailyMetrics`.
      */
     ads?: Array<Ad>;
     /**
@@ -757,7 +762,7 @@ export type AdTreeCampaign = {
     } | null;
     adSets?: Array<AdTreeAdSet>;
     /**
-     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total.
+     * Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total, except `reach`: on Meta the range total is de-duplicated, so daily reach does not sum to it.
      */
     daily?: Array<AdDailyMetrics>;
 };
@@ -25745,7 +25750,7 @@ export type GetAdTreeData = {
          */
         status?: AdStatus;
         /**
-         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`. See `dailyLevel` to control which levels carry it.
+         * Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except Meta `reach`: the range total is Meta's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it.
          */
         timeIncrement?: 1;
         /**
@@ -25801,6 +25806,9 @@ export type GetAdsTimelineResponse = ({
          */
         spend?: number;
         impressions?: number;
+        /**
+         * Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted).
+         */
         reach?: number;
         clicks?: number;
         engagement?: number;
@@ -28472,6 +28480,12 @@ export type CreateStandaloneAdData = {
             /**
              * Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
              * **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
+             * To discover the pixels an ad account can use, call
+             * `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
+             * carries `kind` and `ownerAdAccountId`), or
+             * `GET /v1/accounts/{accountId}/conversion-destinations`. Note this is a
+             * different resource from `GET /v1/ads/{adId}/tracking-tags`, which reads an
+             * ad's click-URL params (`url_tags`), not pixels.
              *
              */
             pixelId?: string;