@zernio/node 0.2.901 → 0.2.903

package/dist/index.d.mts

@@ -16842,7 +16842,36 @@ type GetConnectUrlData = {
          *
          * 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`,
-         * `dashboard_url` and `missing_scopes` are conditional and must be treated as optional.
+         * `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are
+         * conditional and must be treated as optional. Your own query params are kept on every
+         * redirect, but ours overwrite a param of yours with the same name. On an error redirect the
+         * internal `headless`, `adsConnect` and `adsScope` markers we add during the flow are removed.
+         *
+         * Correlation (every redirect from an OAuth callback, success and failure, and the
+         * `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page):
+         * - `request_id`: the id we log that request under. Quote it when reporting a problem.
+         * - `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an
+         * error or denial instead of a code. `callback` = we processed the returned code (success,
+         * a selection step, or a failure). `select_page` = the destination-selection endpoint
+         * (page, account, organization, board, location, profile or phone number) completed it.
+         *
+         * `oauth_denied` carries `error_message` and, when the platform sent them, its own values as
+         * `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and
+         * `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` is set when
+         * the platform reported that the user cancelled or declined.
+         *
+         * `no_facebook_pages` comes with `is_user_fixable=true`, an `error_message` telling the user to
+         * click "Edit previous settings" in Meta's dialog and tick the Page (or create one), and, when
+         * Meta's token debug answered, `error_reason`:
+         * - `pages_permission_declined`: the user declined the pages_show_list permission.
+         * - `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who
+         * manages no Page the same way, so this covers both.
+         * - `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage.
+         *
+         * Headless Facebook success (`step=select_page`): `userProfile` is JSON that was
+         * percent-encoded once before being set as a query param, so it is encoded twice on the wire.
+         * After your framework decodes the query string once, run one more decodeURIComponent (or
+         * equivalent) and then JSON.parse it. `tempToken` and `connect_token` are plain values.
          *
          * `missing_google_permissions` (YouTube and Google Business) means the user unchecked one or more
          * permissions on Google's consent screen. It always comes with `is_user_fixable=true`. When Google
@@ -16890,8 +16919,8 @@ type GetConnectUrlData = {
          * 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
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`, with the
+         * provider's own values in the `platform_error*` params described above. 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`.
          *
@@ -17150,6 +17179,11 @@ type ConnectAdsData = {
          * Set `force=true` to bypass that and always receivean `authUrl`.
          * Completing the returned OAuth refreshes the stored token
          * on the existing posting and ads accounts in place.
+         * An `alreadyConnected` response re-runs ad discovery and webhook
+         * subscriptions in the background at most once every 15 minutes per ads
+         * account (always when the call changes the ad-account scope), so it is not
+         * a sync trigger. To check the connection's health, read
+         * GET /v1/ads/accounts?accountId=<ads account ID>.
          *
          */
         force?: boolean;
@@ -17688,9 +17722,13 @@ type SelectFacebookPageData = {
 type SelectFacebookPageResponse = ({
     message?: string;
     /**
-     * Redirect URL when a custom redirect_url was provided or a business Page was selected.
+     * Redirect URL when a custom redirect_url was provided or a business Page was selected. On an ads connect it also carries `adsAccountId`.
      */
     redirect_url?: string;
+    /**
+     * Ads connect only (the redirect_url carries adsConnect=true, as it does after GET /v1/connect/{platform}/ads). The metaads SocialAccount ID to use with the /v1/ads endpoints. `account.accountId` is the Facebook posting account. Absent when the ads account could not be created.
+     */
+    adsAccountId?: string;
     account?: {
         /**
          * ID of the created SocialAccount
@@ -17706,10 +17744,7 @@ type SelectFacebookPageResponse = ({
 });
 type SelectFacebookPageError = (unknown | {
     error?: string;
-} | {
-    error?: string;
-    code?: 'RECONNECT_ACCOUNT_MISMATCH';
-});
+} | ErrorResponse);
 type ListInstagramPagesData = {
     query: {
         /**

package/dist/index.d.ts

@@ -16842,7 +16842,36 @@ type GetConnectUrlData = {
          *
          * 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`,
-         * `dashboard_url` and `missing_scopes` are conditional and must be treated as optional.
+         * `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are
+         * conditional and must be treated as optional. Your own query params are kept on every
+         * redirect, but ours overwrite a param of yours with the same name. On an error redirect the
+         * internal `headless`, `adsConnect` and `adsScope` markers we add during the flow are removed.
+         *
+         * Correlation (every redirect from an OAuth callback, success and failure, and the
+         * `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page):
+         * - `request_id`: the id we log that request under. Quote it when reporting a problem.
+         * - `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an
+         * error or denial instead of a code. `callback` = we processed the returned code (success,
+         * a selection step, or a failure). `select_page` = the destination-selection endpoint
+         * (page, account, organization, board, location, profile or phone number) completed it.
+         *
+         * `oauth_denied` carries `error_message` and, when the platform sent them, its own values as
+         * `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and
+         * `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` is set when
+         * the platform reported that the user cancelled or declined.
+         *
+         * `no_facebook_pages` comes with `is_user_fixable=true`, an `error_message` telling the user to
+         * click "Edit previous settings" in Meta's dialog and tick the Page (or create one), and, when
+         * Meta's token debug answered, `error_reason`:
+         * - `pages_permission_declined`: the user declined the pages_show_list permission.
+         * - `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who
+         * manages no Page the same way, so this covers both.
+         * - `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage.
+         *
+         * Headless Facebook success (`step=select_page`): `userProfile` is JSON that was
+         * percent-encoded once before being set as a query param, so it is encoded twice on the wire.
+         * After your framework decodes the query string once, run one more decodeURIComponent (or
+         * equivalent) and then JSON.parse it. `tempToken` and `connect_token` are plain values.
          *
          * `missing_google_permissions` (YouTube and Google Business) means the user unchecked one or more
          * permissions on Google's consent screen. It always comes with `is_user_fixable=true`. When Google
@@ -16890,8 +16919,8 @@ type GetConnectUrlData = {
          * 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
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`, with the
+         * provider's own values in the `platform_error*` params described above. 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`.
          *
@@ -17150,6 +17179,11 @@ type ConnectAdsData = {
          * Set `force=true` to bypass that and always receivean `authUrl`.
          * Completing the returned OAuth refreshes the stored token
          * on the existing posting and ads accounts in place.
+         * An `alreadyConnected` response re-runs ad discovery and webhook
+         * subscriptions in the background at most once every 15 minutes per ads
+         * account (always when the call changes the ad-account scope), so it is not
+         * a sync trigger. To check the connection's health, read
+         * GET /v1/ads/accounts?accountId=<ads account ID>.
          *
          */
         force?: boolean;
@@ -17688,9 +17722,13 @@ type SelectFacebookPageData = {
 type SelectFacebookPageResponse = ({
     message?: string;
     /**
-     * Redirect URL when a custom redirect_url was provided or a business Page was selected.
+     * Redirect URL when a custom redirect_url was provided or a business Page was selected. On an ads connect it also carries `adsAccountId`.
      */
     redirect_url?: string;
+    /**
+     * Ads connect only (the redirect_url carries adsConnect=true, as it does after GET /v1/connect/{platform}/ads). The metaads SocialAccount ID to use with the /v1/ads endpoints. `account.accountId` is the Facebook posting account. Absent when the ads account could not be created.
+     */
+    adsAccountId?: string;
     account?: {
         /**
          * ID of the created SocialAccount
@@ -17706,10 +17744,7 @@ type SelectFacebookPageResponse = ({
 });
 type SelectFacebookPageError = (unknown | {
     error?: string;
-} | {
-    error?: string;
-    code?: 'RECONNECT_ACCOUNT_MISMATCH';
-});
+} | ErrorResponse);
 type ListInstagramPagesData = {
     query: {
         /**

package/dist/index.js

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

package/src/generated/sdk.gen.ts

@@ -1651,9 +1651,20 @@ export const handleOAuthCallback = <ThrowOnError extends boolean = false>(option
  * return 400 with available Page IDs for API integrations; restart with pageId.
  * Dashboard session logins use the sole current grant automatically or open the existing
  * Facebook Page picker for several grants, including reconnects. Selection completes
- * the Meta Ads connection. With no Pages granted the callback returns
- * 400 with instructions to connect again and grant a Page.
+ * the Meta Ads connection.
  * Success redirects with connected=metaads, profileId and accountId.
+ * Every failure after Meta's dialog redirects to redirect_url (or the dashboard) with
+ * `error`, `platform=metaads`, `error_message`, `request_id` and `stage`, plus
+ * `is_user_fixable` and `error_reason` when known. `error` is the API error code:
+ * `invalid_field_value` with `error_reason` `no_pages_granted` (no Page ticked),
+ * `page_not_granted` (pageId not in the grant), `ad_accounts_not_granted` or
+ * `reconnect_mismatch` (the grant shares no ad account with the existing connection);
+ * `reconnect_required`, `ads_addon_required`, `payment_required` and the profile gates of
+ * GET /v1/connect/{platform}; `invalid_state` with `error_reason=state_expired` after the
+ * 30-minute window; `connection_failed` when Meta refuses the code (e.g. a replayed callback).
+ * A denial in the dialog is `meta_ads_authorization_denied` with the `platform_error*` params.
+ * Only a state that cannot be decrypted at all still answers 400 JSON, since it names no
+ * redirect_url.
  * Business login reports metadata.tokenType=system-user in GET /v1/accounts. An absent
  * Meta expires_in leaves tokenExpiresAt absent; no personal-token re-exchange occurs.
  * Subsequent classic requests can change the ad-account scope using the business token;

package/src/generated/types.gen.ts

@@ -15882,7 +15882,36 @@ export type GetConnectUrlData = {
          *
          * 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`,
-         * `dashboard_url` and `missing_scopes` are conditional and must be treated as optional.
+         * `dashboard_url`, `missing_scopes`, `error_reason` and the `platform_error*` params are
+         * conditional and must be treated as optional. Your own query params are kept on every
+         * redirect, but ours overwrite a param of yours with the same name. On an error redirect the
+         * internal `headless`, `adsConnect` and `adsScope` markers we add during the flow are removed.
+         *
+         * Correlation (every redirect from an OAuth callback, success and failure, and the
+         * `redirect_url` returned by the selection endpoints such as POST /v1/connect/facebook/select-page):
+         * - `request_id`: the id we log that request under. Quote it when reporting a problem.
+         * - `stage`: where the flow ended. `authorize` = the platform's consent dialog returned an
+         * error or denial instead of a code. `callback` = we processed the returned code (success,
+         * a selection step, or a failure). `select_page` = the destination-selection endpoint
+         * (page, account, organization, board, location, profile or phone number) completed it.
+         *
+         * `oauth_denied` carries `error_message` and, when the platform sent them, its own values as
+         * `platform_error` (e.g. `access_denied`), `platform_error_reason` (e.g. `user_denied`) and
+         * `platform_error_description` (truncated to 500 characters). `is_user_fixable=true` is set when
+         * the platform reported that the user cancelled or declined.
+         *
+         * `no_facebook_pages` comes with `is_user_fixable=true`, an `error_message` telling the user to
+         * click "Edit previous settings" in Meta's dialog and tick the Page (or create one), and, when
+         * Meta's token debug answered, `error_reason`:
+         * - `pages_permission_declined`: the user declined the pages_show_list permission.
+         * - `no_pages_granted`: the permission was granted with no Page ticked. Meta reports a user who
+         * manages no Page the same way, so this covers both.
+         * - `granted_pages_not_listed`: Pages were ticked but Meta listed none the user can manage.
+         *
+         * Headless Facebook success (`step=select_page`): `userProfile` is JSON that was
+         * percent-encoded once before being set as a query param, so it is encoded twice on the wire.
+         * After your framework decodes the query string once, run one more decodeURIComponent (or
+         * equivalent) and then JSON.parse it. `tempToken` and `connect_token` are plain values.
          *
          * `missing_google_permissions` (YouTube and Google Business) means the user unchecked one or more
          * permissions on Google's consent screen. It always comes with `is_user_fixable=true`. When Google
@@ -15930,8 +15959,8 @@ export type GetConnectUrlData = {
          * 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
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`, with the
+         * provider's own values in the `platform_error*` params described above. 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`.
          *
@@ -16196,6 +16225,11 @@ export type ConnectAdsData = {
          * Set `force=true` to bypass that and always receivean `authUrl`.
          * Completing the returned OAuth refreshes the stored token
          * on the existing posting and ads accounts in place.
+         * An `alreadyConnected` response re-runs ad discovery and webhook
+         * subscriptions in the background at most once every 15 minutes per ads
+         * account (always when the call changes the ad-account scope), so it is not
+         * a sync trigger. To check the connection's health, read
+         * GET /v1/ads/accounts?accountId=<ads account ID>.
          *
          */
         force?: boolean;
@@ -16757,9 +16791,13 @@ export type SelectFacebookPageData = {
 export type SelectFacebookPageResponse = ({
     message?: string;
     /**
-     * Redirect URL when a custom redirect_url was provided or a business Page was selected.
+     * Redirect URL when a custom redirect_url was provided or a business Page was selected. On an ads connect it also carries `adsAccountId`.
      */
     redirect_url?: string;
+    /**
+     * Ads connect only (the redirect_url carries adsConnect=true, as it does after GET /v1/connect/{platform}/ads). The metaads SocialAccount ID to use with the /v1/ads endpoints. `account.accountId` is the Facebook posting account. Absent when the ads account could not be created.
+     */
+    adsAccountId?: string;
     account?: {
         /**
          * ID of the created SocialAccount
@@ -16776,10 +16814,7 @@ export type SelectFacebookPageResponse = ({
 
 export type SelectFacebookPageError = (unknown | {
     error?: string;
-} | {
-    error?: string;
-    code?: 'RECONNECT_ACCOUNT_MISMATCH';
-});
+} | ErrorResponse);
 
 export type ListInstagramPagesData = {
     query: {