@zernio/node 0.2.678 → 0.2.680

package/dist/index.d.mts

@@ -8439,9 +8439,23 @@ type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -8456,6 +8470,18 @@ type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -9013,9 +9039,13 @@ type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -9024,6 +9054,11 @@ type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -9033,14 +9068,37 @@ type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -13440,6 +13498,60 @@ type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -13580,6 +13692,11 @@ type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -13643,8 +13760,12 @@ type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -18893,7 +19014,7 @@ type CreateInboxConversationData = {
          */
         templateLanguage?: string;
         /**
-         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
+         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. For positional templates the list must cover every slot: supplying fewer values than the template's header + body + dynamic URL-button count is rejected with a 400 (code INVALID_TEMPLATE_PARAMS) naming the expected split, rather than delivering a template whose button URL was filled from the wrong value. A dynamic URL button covered by templateButtonParams needs no value here unless another uncovered dynamic URL button follows it, since the override applies after slot numbering. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
          */
         templateParams?: Array<(string)>;
         /**
@@ -19320,6 +19441,10 @@ type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20460,7 +20585,7 @@ type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: string;
         /**

package/dist/index.d.ts

@@ -8439,9 +8439,23 @@ type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -8456,6 +8470,18 @@ type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -9013,9 +9039,13 @@ type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -9024,6 +9054,11 @@ type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -9033,14 +9068,37 @@ type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -13440,6 +13498,60 @@ type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -13580,6 +13692,11 @@ type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -13643,8 +13760,12 @@ type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -18893,7 +19014,7 @@ type CreateInboxConversationData = {
          */
         templateLanguage?: string;
         /**
-         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
+         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. For positional templates the list must cover every slot: supplying fewer values than the template's header + body + dynamic URL-button count is rejected with a 400 (code INVALID_TEMPLATE_PARAMS) naming the expected split, rather than delivering a template whose button URL was filled from the wrong value. A dynamic URL button covered by templateButtonParams needs no value here unless another uncovered dynamic URL button follows it, since the override applies after slot numbering. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
          */
         templateParams?: Array<(string)>;
         /**
@@ -19320,6 +19441,10 @@ type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20460,7 +20585,7 @@ type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: 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.678",
+  version: "0.2.680",
   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.678",
+  version: "0.2.680",
   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.678",
+  "version": "0.2.680",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -1467,7 +1467,24 @@ export const handleOAuthCallback = <ThrowOnError extends boolean = false>(option
  * Connect ads for a platform
  * Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.
  *
- * Same-token platforms (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (metaads, linkedinads, pinterestads) with a copied OAuth token from the parent posting account. If the ads account already exists, returns alreadyConnected: true. No extra OAuth needed.
+ * Same-token platforms (facebook, instagram, linkedin, pinterest): the ads SocialAccount
+ * (metaads, linkedinads, pinterestads) reuses the OAuth token of the parent posting account,
+ * but only when an active parent exists and, for facebook and instagram, its stored token
+ * carries ads_management and ads_read (linkedin and pinterest need no extra scope). In that
+ * case no extra OAuth happens and the response is alreadyConnected: true. When no such parent
+ * exists, or the scopes are missing, the endpoint returns an authUrl and a full OAuth round
+ * trip is required. When a parent exists but carries no token usable for ad accounts, the call
+ * fails with 400 RECONNECT_REQUIRED. Independently of the branch, the call can return 403
+ * ADS_ADDON_REQUIRED without the ads add-on and 402 PAYMENT_REQUIRED when the billing gate is
+ * closed.
+ *
+ * Meta Ads prerequisite: connecting Meta Ads (via facebook or instagram) requires a Facebook
+ * Page. Not because the ad account is read through a Page, but because both parent posting
+ * accounts are: the facebook flow only offers Pages you manage, and the instagram flow with
+ * loginMethod=facebook_login only offers Instagram accounts linked to one of those Pages.
+ * Without a Page there is no parent account to inherit a token from. A user who manages no
+ * Facebook Page cannot complete this connection, and the facebook flow ends with
+ * error=no_facebook_pages.
  *
  * Separate-token platforms (tiktok, twitter): Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (tiktokads, xads) with its own token. If the ads account already exists, returns alreadyConnected: true.
  * - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set) — Spark Ads + standalone ads using the posting TT_USER identity become available. Without accountId, ads-only mode kicks in: the new tiktokads account has parentAccountId=null and standalone ads use a synthetic CUSTOMIZED_USER ("Brand Identity"); Spark Ads are unavailable because TikTok requires a posting account for them. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).
@@ -3769,7 +3786,16 @@ export const deleteTelegramCommands = <ThrowOnError extends boolean = false>(opt
  * and stops working later. This endpoint checks the stored url and, when it
  * has gone stale, re-mints the message's media from Meta and persists it
  * before answering. The message id never expires, so this URL is the one to
- * store — it is returned on each attachment as `refreshUrl`.
+ * store. It is returned ready-made on each attachment as `refreshUrl` when
+ * you read a message over REST.
+ *
+ * **Webhook payloads do not carry `refreshUrl`**, so a webhook-driven
+ * integration builds this URL itself. Every piece is in the event:
+ * `message.conversationId`, `message.platformMessageId`, the attachment's
+ * zero-based position, and `account.accountId`. Note that **`accountId` is a
+ * required query parameter**; omitting it returns `400`
+ * `missing_required_field`, which is the same requirement
+ * `GET /v1/whatsapp/media/{mediaId}` has.
  *
  * By default it responds `302` to the live media url, so it can be used
  * directly as an `<img src>` on a browser session. API-key integrators

package/src/generated/types.gen.ts

@@ -7378,9 +7378,23 @@ export type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -7395,6 +7409,18 @@ export type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -7963,9 +7989,13 @@ export type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -7974,6 +8004,11 @@ export type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -7983,14 +8018,37 @@ export type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -12695,6 +12753,60 @@ export type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -12841,6 +12953,11 @@ export type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -12904,8 +13021,12 @@ export type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -18531,7 +18652,7 @@ export type CreateInboxConversationData = {
          */
         templateLanguage?: string;
         /**
-         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
+         * WhatsApp only. Template variable values as one flat array, in the order the variables appear across the whole template: text-header variables first, then body variables, then one value per dynamic URL button (in button order). Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance. Example - a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix]. For positional templates the list must cover every slot: supplying fewer values than the template's header + body + dynamic URL-button count is rejected with a 400 (code INVALID_TEMPLATE_PARAMS) naming the expected split, rather than delivering a template whose button URL was filled from the wrong value. A dynamic URL button covered by templateButtonParams needs no value here unless another uncovered dynamic URL button follows it, since the override applies after slot numbering. Media headers (image, video, document) are filled automatically from the approved template and take no value here (use headerMedia to override the header asset per send). Buttons that are not dynamic-URL buttons (copy-code, flow) take no value here either; use templateButtonParams.
          */
         templateParams?: Array<(string)>;
         /**
@@ -18971,6 +19092,10 @@ export type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20167,7 +20292,7 @@ export type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: string;
         /**