@zernio/node 0.2.130 → 0.2.132

package/dist/index.d.mts

@@ -845,6 +845,26 @@ type Ad = {
          * Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available.
          */
         objectType?: string;
+        /**
+         * Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
+         */
+        objectStoryId?: (string) | null;
+        /**
+         * Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
+         */
+        effectiveObjectStoryId?: (string) | null;
+        /**
+         * Meta `effective_instagram_media_id` — the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad.
+         */
+        effectiveInstagramMediaId?: (string) | null;
+        /**
+         * Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
+         */
+        instagramUserId?: (string) | null;
+        /**
+         * Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
+         */
+        instagramPermalinkUrl?: (string) | null;
         /**
          * All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts).
          */
@@ -10391,9 +10411,9 @@ type ListInboxCommentsData = {
          */
         minComments?: number;
         /**
-         * Filter by platform
+         * Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only.
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit' | 'metaads';
         /**
          * Filter by profile ID
          */
@@ -10432,6 +10452,14 @@ type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the comment platform (facebook or instagram), `id` equals `adId`, and the thread is at GET /v1/ads/{adId}/comments.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows (same value as `id`).
+         */
+        adId?: string;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10569,11 +10597,24 @@ type GetInboxPostCommentsResponse = ({
          */
         subreddit?: (string) | null;
         lastUpdated?: string;
+        /**
+         * (Facebook/Instagram only) Present when this post has no organic comments but is a boosted post — the engagement lives on the ad. Use the ad-comments endpoint instead.
+         */
+        adComments?: {
+            /**
+             * Internal Zernio ad ID
+             */
+            adId?: string;
+            /**
+             * Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)
+             */
+            adCommentsUrl?: string;
+        } | null;
     };
 });
-type GetInboxPostCommentsError = ({
+type GetInboxPostCommentsError = (unknown | {
     error?: string;
-} | unknown);
+});
 type ReplyToInboxPostData = {
     body: {
         accountId: string;
@@ -13279,6 +13320,14 @@ type ListAdsData = {
          * Platform campaign ID (filter ads within a campaign)
          */
         campaignId?: string;
+        /**
+         * Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad.
+         */
+        effectiveInstagramMediaId?: string;
+        /**
+         * Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad.
+         */
+        effectiveObjectStoryId?: string;
         /**
          * Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
          */
@@ -13289,6 +13338,10 @@ type ListAdsData = {
          */
         page?: number;
         platform?: 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter';
+        /**
+         * Meta ad ID. Returns the ad with this platform-side ad ID.
+         */
+        platformAdId?: string;
         /**
          * Profile ID
          */
@@ -13791,6 +13844,18 @@ type GetAdCommentsResponse = ({
          * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
          */
         effectiveStoryId: string;
+        /**
+         * Instagram-only. The Instagram-scoped business ID that owns the boosted media (creative.instagram_user_id).
+         */
+        instagramUserId?: string;
+        /**
+         * Instagram-only. Public permalink of the boosted IG post (creative.instagram_permalink_url).
+         */
+        instagramPermalink?: string;
+        /**
+         * Instagram-only. The connected Instagram SocialAccount these comments were read through — use it for reply/hide actions via /v1/inbox/comments.
+         */
+        instagramAccountId?: string;
         /**
          * Social account ID (ads SocialAccount).
          */

package/dist/index.d.ts

@@ -845,6 +845,26 @@ type Ad = {
          * Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available.
          */
         objectType?: string;
+        /**
+         * Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
+         */
+        objectStoryId?: (string) | null;
+        /**
+         * Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
+         */
+        effectiveObjectStoryId?: (string) | null;
+        /**
+         * Meta `effective_instagram_media_id` — the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad.
+         */
+        effectiveInstagramMediaId?: (string) | null;
+        /**
+         * Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
+         */
+        instagramUserId?: (string) | null;
+        /**
+         * Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
+         */
+        instagramPermalinkUrl?: (string) | null;
         /**
          * All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts).
          */
@@ -10391,9 +10411,9 @@ type ListInboxCommentsData = {
          */
         minComments?: number;
         /**
-         * Filter by platform
+         * Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only.
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit' | 'metaads';
         /**
          * Filter by profile ID
          */
@@ -10432,6 +10452,14 @@ type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the comment platform (facebook or instagram), `id` equals `adId`, and the thread is at GET /v1/ads/{adId}/comments.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows (same value as `id`).
+         */
+        adId?: string;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10569,11 +10597,24 @@ type GetInboxPostCommentsResponse = ({
          */
         subreddit?: (string) | null;
         lastUpdated?: string;
+        /**
+         * (Facebook/Instagram only) Present when this post has no organic comments but is a boosted post — the engagement lives on the ad. Use the ad-comments endpoint instead.
+         */
+        adComments?: {
+            /**
+             * Internal Zernio ad ID
+             */
+            adId?: string;
+            /**
+             * Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)
+             */
+            adCommentsUrl?: string;
+        } | null;
     };
 });
-type GetInboxPostCommentsError = ({
+type GetInboxPostCommentsError = (unknown | {
     error?: string;
-} | unknown);
+});
 type ReplyToInboxPostData = {
     body: {
         accountId: string;
@@ -13279,6 +13320,14 @@ type ListAdsData = {
          * Platform campaign ID (filter ads within a campaign)
          */
         campaignId?: string;
+        /**
+         * Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad.
+         */
+        effectiveInstagramMediaId?: string;
+        /**
+         * Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad.
+         */
+        effectiveObjectStoryId?: string;
         /**
          * Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
          */
@@ -13289,6 +13338,10 @@ type ListAdsData = {
          */
         page?: number;
         platform?: 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter';
+        /**
+         * Meta ad ID. Returns the ad with this platform-side ad ID.
+         */
+        platformAdId?: string;
         /**
          * Profile ID
          */
@@ -13791,6 +13844,18 @@ type GetAdCommentsResponse = ({
          * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
          */
         effectiveStoryId: string;
+        /**
+         * Instagram-only. The Instagram-scoped business ID that owns the boosted media (creative.instagram_user_id).
+         */
+        instagramUserId?: string;
+        /**
+         * Instagram-only. Public permalink of the boosted IG post (creative.instagram_permalink_url).
+         */
+        instagramPermalink?: string;
+        /**
+         * Instagram-only. The connected Instagram SocialAccount these comments were read through — use it for reply/hide actions via /v1/inbox/comments.
+         */
+        instagramAccountId?: string;
         /**
          * Social account ID (ads SocialAccount).
          */

package/package.json

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

package/src/generated/sdk.gen.ts

@@ -2080,6 +2080,15 @@ export const deleteTelegramCommands = <ThrowOnError extends boolean = false>(opt
 /**
  * List commented posts
  * Returns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.
+ *
+ * For users with the Ads add-on (Metronome plans always qualify), the user's Meta ads
+ * (boosted/dark posts) are included too, flagged with `isAd: true` and an `adId`. Use
+ * `?platform=metaads` to return *only* ad rows; passing `facebook`/`instagram` returns
+ * *organic* posts only (no ads); omitting `platform` returns both. Fetch an ad row's
+ * thread from GET /v1/ads/{adId}/comments. Ad comment counts are read with the Marketing
+ * API token (Facebook) or the connected Instagram account's token (Instagram); an ad
+ * whose count can't be read is omitted.
+ *
  */
 export const listInboxComments = <ThrowOnError extends boolean = false>(options?: OptionsLegacyParser<ListInboxCommentsData, ThrowOnError>) => {
     return (options?.client ?? client).get<ListInboxCommentsResponse, ListInboxCommentsError, ThrowOnError>({
@@ -3237,6 +3246,12 @@ export const listCommentAutomationLogs = <ThrowOnError extends boolean = false>(
  * Use source=all to include externally-synced ads from platform ad managers.
  * If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.
  *
+ * To find the Zernio ad behind a comment you see in Meta Business Manager, filter by
+ * platformAdId (the Meta ad ID), effectiveObjectStoryId (Facebook), or
+ * effectiveInstagramMediaId (Instagram) — those are the post/media the ad's engagement
+ * lives on, and are also returned on each ad's `creative` object. Then call
+ * GET /v1/ads/{adId}/comments with the returned ad id.
+ *
  */
 export const listAds = <ThrowOnError extends boolean = false>(options?: OptionsLegacyParser<ListAdsData, ThrowOnError>) => {
     return (options?.client ?? client).get<ListAdsResponse, ListAdsError, ThrowOnError>({
@@ -3474,6 +3489,11 @@ export const getAdAnalytics = <ThrowOnError extends boolean = false>(options: Op
  * effective_instagram_media_id (Instagram) via the Marketing API on each call
  * (cached in-process by the platform client), then fetches comments from the Graph API.
  *
+ * For Instagram-placed ads, the Instagram account that runs the ad must be connected
+ * to Zernio — comments are read through that account's token. If none of the connected
+ * Instagram accounts on the profile can read the ad's media, the call returns
+ * ads_connection_required.
+ *
  * Meta-only. Other ad platforms (TikTok, LinkedIn, Pinterest, Google, X) do not
  * expose a public per-ad comments API and return feature_not_available.
  *

package/src/generated/types.gen.ts

@@ -216,6 +216,26 @@ export type Ad = {
          * Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available.
          */
         objectType?: string;
+        /**
+         * Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
+         */
+        objectStoryId?: (string) | null;
+        /**
+         * Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
+         */
+        effectiveObjectStoryId?: (string) | null;
+        /**
+         * Meta `effective_instagram_media_id` — the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad.
+         */
+        effectiveInstagramMediaId?: (string) | null;
+        /**
+         * Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
+         */
+        instagramUserId?: (string) | null;
+        /**
+         * Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
+         */
+        instagramPermalinkUrl?: (string) | null;
         /**
          * All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts).
          */
@@ -10392,9 +10412,9 @@ export type ListInboxCommentsData = {
          */
         minComments?: number;
         /**
-         * Filter by platform
+         * Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only.
          */
-        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit';
+        platform?: 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'threads' | 'youtube' | 'linkedin' | 'reddit' | 'metaads';
         /**
          * Filter by profile ID
          */
@@ -10434,6 +10454,14 @@ export type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the comment platform (facebook or instagram), `id` equals `adId`, and the thread is at GET /v1/ads/{adId}/comments.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows (same value as `id`).
+         */
+        adId?: string;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10574,12 +10602,25 @@ export type GetInboxPostCommentsResponse = ({
          */
         subreddit?: (string) | null;
         lastUpdated?: string;
+        /**
+         * (Facebook/Instagram only) Present when this post has no organic comments but is a boosted post — the engagement lives on the ad. Use the ad-comments endpoint instead.
+         */
+        adComments?: {
+            /**
+             * Internal Zernio ad ID
+             */
+            adId?: string;
+            /**
+             * Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)
+             */
+            adCommentsUrl?: string;
+        } | null;
     };
 });
 
-export type GetInboxPostCommentsError = ({
+export type GetInboxPostCommentsError = (unknown | {
     error?: string;
-} | unknown);
+});
 
 export type ReplyToInboxPostData = {
     body: {
@@ -13556,6 +13597,14 @@ export type ListAdsData = {
          * Platform campaign ID (filter ads within a campaign)
          */
         campaignId?: string;
+        /**
+         * Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad.
+         */
+        effectiveInstagramMediaId?: string;
+        /**
+         * Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad.
+         */
+        effectiveObjectStoryId?: string;
         /**
          * Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
          */
@@ -13566,6 +13615,10 @@ export type ListAdsData = {
          */
         page?: number;
         platform?: 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter';
+        /**
+         * Meta ad ID. Returns the ad with this platform-side ad ID.
+         */
+        platformAdId?: string;
         /**
          * Profile ID
          */
@@ -14111,6 +14164,18 @@ export type GetAdCommentsResponse = ({
          * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
          */
         effectiveStoryId: string;
+        /**
+         * Instagram-only. The Instagram-scoped business ID that owns the boosted media (creative.instagram_user_id).
+         */
+        instagramUserId?: string;
+        /**
+         * Instagram-only. Public permalink of the boosted IG post (creative.instagram_permalink_url).
+         */
+        instagramPermalink?: string;
+        /**
+         * Instagram-only. The connected Instagram SocialAccount these comments were read through — use it for reply/hide actions via /v1/inbox/comments.
+         */
+        instagramAccountId?: string;
         /**
          * Social account ID (ads SocialAccount).
          */