@zernio/node 0.2.131 → 0.2.133

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,18 @@ type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the placement (facebook = the Page dark post / instagram = the IG media), `id` is `{adId}:{placement}`, and the thread is at GET /v1/ads/{adId}/comments?placement={placement}.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows.
+         */
+        adId?: string;
+        /**
+         * Which side of the ad this row's comments are on — only on ad rows.
+         */
+        placement?: 'facebook' | 'instagram';
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10569,11 +10601,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 +13324,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 +13342,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
          */
@@ -13766,6 +13823,10 @@ type GetAdCommentsData = {
          */
         cursor?: string;
         limit?: number;
+        /**
+         * Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement.
+         */
+        placement?: 'facebook' | 'instagram';
     };
 };
 type GetAdCommentsResponse = ({
@@ -13778,7 +13839,14 @@ type GetAdCommentsResponse = ({
         cursor?: string;
     };
     meta: {
+        /**
+         * Which side these comments are on (same as `placement`).
+         */
         platform: 'facebook' | 'instagram';
+        /**
+         * The placement these comments are for — useful when you didn't pass ?placement= and want to know which one you got.
+         */
+        placement: 'facebook' | 'instagram';
         /**
          * Internal Zernio ad ID.
          */
@@ -13788,7 +13856,7 @@ type GetAdCommentsResponse = ({
          */
         platformAdId: string;
         /**
-         * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
+         * Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side.
          */
         effectiveStoryId: string;
         /**

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,18 @@ type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the placement (facebook = the Page dark post / instagram = the IG media), `id` is `{adId}:{placement}`, and the thread is at GET /v1/ads/{adId}/comments?placement={placement}.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows.
+         */
+        adId?: string;
+        /**
+         * Which side of the ad this row's comments are on — only on ad rows.
+         */
+        placement?: 'facebook' | 'instagram';
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10569,11 +10601,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 +13324,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 +13342,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
          */
@@ -13766,6 +13823,10 @@ type GetAdCommentsData = {
          */
         cursor?: string;
         limit?: number;
+        /**
+         * Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement.
+         */
+        placement?: 'facebook' | 'instagram';
     };
 };
 type GetAdCommentsResponse = ({
@@ -13778,7 +13839,14 @@ type GetAdCommentsResponse = ({
         cursor?: string;
     };
     meta: {
+        /**
+         * Which side these comments are on (same as `placement`).
+         */
         platform: 'facebook' | 'instagram';
+        /**
+         * The placement these comments are for — useful when you didn't pass ?placement= and want to know which one you got.
+         */
+        placement: 'facebook' | 'instagram';
         /**
          * Internal Zernio ad ID.
          */
@@ -13788,7 +13856,7 @@ type GetAdCommentsResponse = ({
          */
         platformAdId: string;
         /**
-         * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
+         * Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side.
          */
         effectiveStoryId: string;
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zernio/node",
-  "version": "0.2.131",
+  "version": "0.2.133",
   "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,18 @@ 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. There's one row per (ad, placement-with-comments):
+ * an ad that runs on both Facebook feed and Instagram feed produces up to two rows (the
+ * Page dark post and the IG media have separate comment threads), each flagged
+ * `isAd: true` with `adId` and `placement` (`id` is `{adId}:{placement}`). Use
+ * `?platform=metaads` to return *only* ad rows; passing `facebook`/`instagram` returns
+ * *organic* posts only (no ads); omitting `platform` returns both. Fetch a row's thread
+ * from GET /v1/ads/{adId}/comments?placement={placement}. Ad comment counts are read with
+ * the Marketing API token (Facebook side) or the connected Instagram account's token
+ * (Instagram side); a row 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 +3249,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>({
@@ -3470,14 +3488,17 @@ export const getAdAnalytics = <ThrowOnError extends boolean = false>(options: Op
  * regular GET /v1/inbox/comments/{postId} endpoint cannot serve because dark posts are
  * not in Zernio's post database.
  *
- * Resolves the ad's creative effective_object_story_id (Facebook) or
- * 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.
+ * An ad that runs on both Facebook feed and Instagram feed has two separate underlying
+ * posts with separate comment threads (the creative's effective_object_story_id and
+ * effective_instagram_media_id). Use the `placement` query param to pick one; with no
+ * param the Instagram side is returned when it exists, otherwise Facebook. The
+ * identifiers are read from the ad record (persisted during sync) with a Marketing-API
+ * fallback for ads that predate the field.
+ *
+ * For Instagram-placed comments, the Instagram account that runs the ad must be connected
+ * to Zernio — those comments are read through that account's token. If no connected
+ * Instagram account on the profile can read the ad's media, the call returns
+ * ads_connection_required (the Facebook side, if any, is still readable via ?placement=facebook).
  *
  * 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,18 @@ export type ListInboxCommentsResponse = ({
          * Reddit subreddit name
          */
         subreddit?: (string) | null;
+        /**
+         * True when this row is an ad (boosted/dark post). `platform` is then the placement (facebook = the Page dark post / instagram = the IG media), `id` is `{adId}:{placement}`, and the thread is at GET /v1/ads/{adId}/comments?placement={placement}.
+         */
+        isAd?: boolean;
+        /**
+         * Internal Zernio ad id — only on ad rows.
+         */
+        adId?: string;
+        /**
+         * Which side of the ad this row's comments are on — only on ad rows.
+         */
+        placement?: 'facebook' | 'instagram';
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -10574,12 +10606,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 +13601,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 +13619,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
          */
@@ -14085,6 +14142,10 @@ export type GetAdCommentsData = {
          */
         cursor?: string;
         limit?: number;
+        /**
+         * Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement.
+         */
+        placement?: 'facebook' | 'instagram';
     };
 };
 
@@ -14098,7 +14159,14 @@ export type GetAdCommentsResponse = ({
         cursor?: string;
     };
     meta: {
+        /**
+         * Which side these comments are on (same as `placement`).
+         */
         platform: 'facebook' | 'instagram';
+        /**
+         * The placement these comments are for — useful when you didn't pass ?placement= and want to know which one you got.
+         */
+        placement: 'facebook' | 'instagram';
         /**
          * Internal Zernio ad ID.
          */
@@ -14108,7 +14176,7 @@ export type GetAdCommentsResponse = ({
          */
         platformAdId: string;
         /**
-         * Underlying post ID the comments belong to. effective_object_story_id for Facebook, effective_instagram_media_id for Instagram.
+         * Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side.
          */
         effectiveStoryId: string;
         /**