@getlatedev/node 0.2.485 → 0.2.487

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;
     /**
@@ -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>;
 };
@@ -15553,7 +15558,7 @@ type ListInboxConversationsData = {
         /**
          * Filter by platform
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram' | 'whatsapp';
         /**
          * Filter by profile ID
          */
@@ -15620,6 +15625,108 @@ type ListInboxConversationsResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured from the referral Meta attaches to the first inbound message
+         * after the click, which is the only message that carries it. If the same
+         * person later clicks a different ad, the original values are kept, so the
+         * first ad wins. One exception on WhatsApp: when Meta omits `ctwa_clid`
+         * from that referral, a later Meta automatic event can supply it and
+         * refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time
+         * Zernio stored the value, not the time of the click.
+         *
+         * Two families of keys, one per surface. They never appear together:
+         *
+         * - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
+         * `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
+         * - `meta_ad_*` is Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. The ad ID is `meta_ad_id`. `ctwa_clid` never
+         * appears on these platforms.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none
+         * is exposed here. More keys may be added over time. Treat any key you
+         * do not recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
+             */
+            ctwa_clid?: string;
+            /**
+             * WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
+             */
+            ctwa_source_id?: string;
+            /**
+             * WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
+             */
+            ctwa_source_type?: string;
+            /**
+             * WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
+             */
+            ctwa_source_url?: string;
+            /**
+             * WhatsApp only. Headline of the ad creative at click time.
+             */
+            ctwa_headline?: string;
+            /**
+             * WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
+             */
+            ctwa_captured_at?: string;
+            /**
+             * Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * Instagram and Facebook only. The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Instagram and Facebook only. Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Instagram and Facebook only. Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Instagram and Facebook only. Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * Instagram and Facebook only. The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -15893,6 +16000,79 @@ type GetInboxConversationResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured once, on the first inbound message after the click, and never
+         * overwritten. If the same person later clicks a different ad, the
+         * original values are kept. Meta only sends the referral on that first
+         * message.
+         *
+         * This operation currently returns only the `meta_ad_*` family, which
+         * covers Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. WhatsApp Click-to-WhatsApp attribution (the `ctwa_*`
+         * keys, where the ad ID is `ctwa_source_id`) is returned by
+         * `GET /v1/inbox/conversations` instead.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none is
+         * exposed here. More keys may be added over time. Treat any key you do not
+         * recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * The Meta ad ID the user clicked. Always present when a referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * When Zernio stored this referral. Always present when a referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     };
 });
 type GetInboxConversationError = ({
@@ -25332,7 +25512,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 +25564,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;

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;
     /**
@@ -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>;
 };
@@ -15553,7 +15558,7 @@ type ListInboxConversationsData = {
         /**
          * Filter by platform
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram' | 'whatsapp';
         /**
          * Filter by profile ID
          */
@@ -15620,6 +15625,108 @@ type ListInboxConversationsResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured from the referral Meta attaches to the first inbound message
+         * after the click, which is the only message that carries it. If the same
+         * person later clicks a different ad, the original values are kept, so the
+         * first ad wins. One exception on WhatsApp: when Meta omits `ctwa_clid`
+         * from that referral, a later Meta automatic event can supply it and
+         * refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time
+         * Zernio stored the value, not the time of the click.
+         *
+         * Two families of keys, one per surface. They never appear together:
+         *
+         * - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
+         * `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
+         * - `meta_ad_*` is Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. The ad ID is `meta_ad_id`. `ctwa_clid` never
+         * appears on these platforms.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none
+         * is exposed here. More keys may be added over time. Treat any key you
+         * do not recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
+             */
+            ctwa_clid?: string;
+            /**
+             * WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
+             */
+            ctwa_source_id?: string;
+            /**
+             * WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
+             */
+            ctwa_source_type?: string;
+            /**
+             * WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
+             */
+            ctwa_source_url?: string;
+            /**
+             * WhatsApp only. Headline of the ad creative at click time.
+             */
+            ctwa_headline?: string;
+            /**
+             * WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
+             */
+            ctwa_captured_at?: string;
+            /**
+             * Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * Instagram and Facebook only. The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Instagram and Facebook only. Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Instagram and Facebook only. Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Instagram and Facebook only. Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * Instagram and Facebook only. The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -15893,6 +16000,79 @@ type GetInboxConversationResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured once, on the first inbound message after the click, and never
+         * overwritten. If the same person later clicks a different ad, the
+         * original values are kept. Meta only sends the referral on that first
+         * message.
+         *
+         * This operation currently returns only the `meta_ad_*` family, which
+         * covers Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. WhatsApp Click-to-WhatsApp attribution (the `ctwa_*`
+         * keys, where the ad ID is `ctwa_source_id`) is returned by
+         * `GET /v1/inbox/conversations` instead.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none is
+         * exposed here. More keys may be added over time. Treat any key you do not
+         * recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * The Meta ad ID the user clicked. Always present when a referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * When Zernio stored this referral. Always present when a referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     };
 });
 type GetInboxConversationError = ({
@@ -25332,7 +25512,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 +25564,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;

package/dist/index.js

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

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;
     /**
@@ -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>;
 };
@@ -15210,7 +15215,7 @@ export type ListInboxConversationsData = {
         /**
          * Filter by platform
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram' | 'whatsapp';
         /**
          * Filter by profile ID
          */
@@ -15278,6 +15283,108 @@ export type ListInboxConversationsResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured from the referral Meta attaches to the first inbound message
+         * after the click, which is the only message that carries it. If the same
+         * person later clicks a different ad, the original values are kept, so the
+         * first ad wins. One exception on WhatsApp: when Meta omits `ctwa_clid`
+         * from that referral, a later Meta automatic event can supply it and
+         * refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time
+         * Zernio stored the value, not the time of the click.
+         *
+         * Two families of keys, one per surface. They never appear together:
+         *
+         * - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
+         * `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
+         * - `meta_ad_*` is Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. The ad ID is `meta_ad_id`. `ctwa_clid` never
+         * appears on these platforms.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none
+         * is exposed here. More keys may be added over time. Treat any key you
+         * do not recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
+             */
+            ctwa_clid?: string;
+            /**
+             * WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
+             */
+            ctwa_source_id?: string;
+            /**
+             * WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
+             */
+            ctwa_source_type?: string;
+            /**
+             * WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
+             */
+            ctwa_source_url?: string;
+            /**
+             * WhatsApp only. Headline of the ad creative at click time.
+             */
+            ctwa_headline?: string;
+            /**
+             * WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
+             */
+            ctwa_captured_at?: string;
+            /**
+             * Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * Instagram and Facebook only. The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Instagram and Facebook only. Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Instagram and Facebook only. Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Instagram and Facebook only. Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * Instagram and Facebook only. The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -15560,6 +15667,79 @@ export type GetInboxConversationResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
+        /**
+         * Ad-click attribution for a conversation that started from a Meta ad.
+         * Absent when the conversation did not originate from an ad click.
+         *
+         * Captured once, on the first inbound message after the click, and never
+         * overwritten. If the same person later clicks a different ad, the
+         * original values are kept. Meta only sends the referral on that first
+         * message.
+         *
+         * This operation currently returns only the `meta_ad_*` family, which
+         * covers Instagram Click-to-Direct and Facebook Messenger
+         * Click-to-Message. WhatsApp Click-to-WhatsApp attribution (the `ctwa_*`
+         * keys, where the ad ID is `ctwa_source_id`) is returned by
+         * `GET /v1/inbox/conversations` instead.
+         *
+         * Every key is optional and only the keys Meta supplied are returned, so
+         * read defensively. Meta does not send a campaign or ad set ID, so none is
+         * exposed here. More keys may be added over time. Treat any key you do not
+         * recognise as an opaque string.
+         *
+         * Key names differ from the `message.received` webhook on purpose. The
+         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+         * while the stored conversation record uses the prefixed names below.
+         * Renaming either side would break existing integrations, so both
+         * spellings are kept.
+         *
+         */
+        metadata?: {
+            /**
+             * The Meta ad ID the user clicked. Always present when a referral was captured.
+             */
+            meta_ad_id?: string;
+            /**
+             * Meta-supplied source identifier, for example ADS.
+             */
+            meta_ad_source?: string;
+            /**
+             * Meta-supplied referral type, for example OPEN_THREAD.
+             */
+            meta_ad_type?: string;
+            /**
+             * The ref parameter passed through from the ad creative.
+             */
+            meta_ad_ref?: string;
+            /**
+             * Title of the ad creative at click time.
+             */
+            meta_ad_title?: string;
+            /**
+             * Image of the ad creative at click time.
+             */
+            meta_ad_photo_url?: string;
+            /**
+             * Video of the ad creative at click time.
+             */
+            meta_ad_video_url?: string;
+            /**
+             * The organic post the ad promoted, when the ad was a boosted post.
+             */
+            meta_ad_post_id?: string;
+            /**
+             * The catalogue product the user clicked, for product ads.
+             */
+            meta_ad_product_id?: string;
+            /**
+             * The Meta flow the ad launched, for flow ads.
+             */
+            meta_ad_flow_id?: string;
+            /**
+             * When Zernio stored this referral. Always present when a referral was captured.
+             */
+            meta_ad_captured_at?: string;
+        } | null;
     };
 });
 
@@ -25745,7 +25925,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 +25981,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;