@zernio/node 0.2.111 → 0.2.113

package/src/generated/types.gen.ts

@@ -918,6 +918,54 @@ export type ConversionEvent = {
  */
 export type actionSource = 'web' | 'app' | 'offline' | 'crm' | 'phone_call' | 'system_generated';
 
+export type CreateLeadFormBody = {
+    /**
+     * Facebook social account ID (Late SocialAccount _id).
+     */
+    accountId: string;
+    name: string;
+    questions: Array<LeadGenFormQuestion>;
+    /**
+     * Required by Meta. Must be reachable from Meta's crawler.
+     */
+    privacyPolicyUrl: string;
+    privacyPolicyLinkText?: string;
+    followUpActionUrl?: string;
+    locale?: string;
+    thankYouTitle?: string;
+    thankYouBody?: string;
+    thankYouButtonText?: string;
+    /**
+     * Meta enum (e.g. VIEW_WEBSITE, CALL_BUSINESS, DOWNLOAD)
+     */
+    thankYouButtonType?: string;
+    thankYouWebsiteUrl?: string;
+    isOptimizedForQuality?: boolean;
+    contextCard?: {
+        title?: string;
+        style?: 'LIST_STYLE' | 'PARAGRAPH_STYLE';
+        content?: Array<(string)>;
+        buttonText?: string;
+    };
+    legalContent?: {
+        customDisclaimer?: {
+            title?: string;
+            body?: string;
+        };
+    };
+    /**
+     * Up to 20 key/value pairs surfaced on every lead for attribution.
+     */
+    trackingParameters?: {
+        [key: string]: (string);
+    };
+    questionPageCustomHeadline?: string;
+    allowOrganicLead?: boolean;
+    blockDisplayForNonTargetedViewer?: boolean;
+};
+
+export type style = 'LIST_STYLE' | 'PARAGRAPH_STYLE';
+
 /**
  * Discord message settings. Supports plain text (2,000 chars), rich embeds (up to 10), native polls, forum posts, threads, and announcement crossposts. Media attachments support images (JPEG, PNG, GIF, WebP), videos (MP4), and documents (up to 10 files, 25 MB each). Webhook identity (username + avatar) can be customized per-account via PATCH /v1/connect/discord or per-post via webhookUsername/webhookAvatarUrl.
  *
@@ -1617,6 +1665,111 @@ export type contentType2 = 'story';
  */
 export type graduationStrategy = 'MANUAL' | 'SS_PERFORMANCE';
 
+/**
+ * A single lead submission returned by the leads endpoint and the lead.received webhook.
+ */
+export type Lead = {
+    /**
+     * Meta `leadgen_id`.
+     */
+    id?: string;
+    createdTime?: string;
+    /**
+     * Meta ad ID that surfaced the form. Organic leads omit this.
+     */
+    adId?: (string) | null;
+    formId?: string;
+    /**
+     * Flattened key→value map of answers (multi-value fields joined with ", ").
+     */
+    fields?: {
+        [key: string]: (string);
+    };
+    /**
+     * Raw `field_data` from Meta (one entry per question).
+     */
+    fieldData?: Array<{
+        name?: string;
+        values?: Array<(string)>;
+    }>;
+};
+
+/**
+ * Common meta-block returned alongside lead-form responses for traceability.
+ */
+export type LeadFormResponseMeta = {
+    platform?: string;
+    accountId?: string;
+    formId?: (string) | null;
+    leadId?: (string) | null;
+    pageId?: (string) | null;
+    lastUpdated?: string;
+};
+
+/**
+ * A Meta Lead Gen (Instant) Form definition.
+ */
+export type LeadGenForm = {
+    id?: string;
+    name?: string;
+    status?: 'ACTIVE' | 'ARCHIVED' | 'DELETED' | 'DRAFT';
+    locale?: string;
+    created_time?: string;
+    /**
+     * Total leads (real + organic).
+     */
+    leads_count?: number;
+    organic_leads_count?: (number) | null;
+    expired_leads_count?: (number) | null;
+    questions?: Array<LeadGenFormQuestion>;
+    privacy_policy_url?: (string) | null;
+    follow_up_action_url?: (string) | null;
+    thank_you_page?: {
+        [key: string]: unknown;
+    } | null;
+    context_card?: {
+        [key: string]: unknown;
+    } | null;
+    question_page_custom_headline?: (string) | null;
+    is_optimized_for_quality?: (boolean) | null;
+    page_id?: (string) | null;
+};
+
+export type status3 = 'ACTIVE' | 'ARCHIVED' | 'DELETED' | 'DRAFT';
+
+/**
+ * A single question on a Meta Instant Form. The `type` enum spans Meta's
+ * prefill set (FULL_NAME, EMAIL, PHONE, STREET_ADDRESS, CITY, STATE,
+ * COUNTRY, POST_CODE, DOB, GENDER, JOB_TITLE, COMPANY_NAME, etc.) plus
+ * custom types (CUSTOM, MULTIPLE_CHOICE, CONDITIONAL, STORE_LOOKUP,
+ * APPOINTMENT_REQUEST). See Meta's Lead Ads docs for the full list —
+ * we forward whatever string the caller sends so new types work without
+ * a Zernio release.
+ *
+ */
+export type LeadGenFormQuestion = {
+    /**
+     * Stable key returned in `field_data` on each lead. If omitted, Meta auto-derives one from `label`.
+     */
+    key?: string;
+    /**
+     * Display text shown above the input.
+     */
+    label?: string;
+    type: string;
+    /**
+     * Required for MULTIPLE_CHOICE / CONDITIONAL questions.
+     */
+    options?: Array<{
+        key?: string;
+        value?: string;
+    }>;
+    /**
+     * Help text rendered below the field.
+     */
+    inline_context?: string;
+};
+
 /**
  * Response for DAILY aggregation (time series breakdown)
  */
@@ -1867,7 +2020,7 @@ export type PlatformAnalytics = {
     errorMessage?: (string) | null;
 };
 
-export type status3 = 'published' | 'failed';
+export type status4 = 'published' | 'failed';
 
 /**
  * Sync state of analytics for this platform
@@ -1977,7 +2130,7 @@ export type Post = {
     updatedAt?: string;
 };
 
-export type status4 = 'draft' | 'scheduled' | 'publishing' | 'published' | 'failed' | 'partial';
+export type status5 = 'draft' | 'scheduled' | 'publishing' | 'published' | 'failed' | 'partial';
 
 export type visibility = 'public' | 'private' | 'unlisted';
 
@@ -2644,7 +2797,7 @@ export type UploadTokenResponse = {
     status?: 'pending' | 'completed' | 'expired';
 };
 
-export type status5 = 'pending' | 'completed' | 'expired';
+export type status6 = 'pending' | 'completed' | 'expired';
 
 export type UploadTokenStatusResponse = {
     token?: string;
@@ -2715,7 +2868,7 @@ export type Webhook = {
     /**
      * Events subscribed to
      */
-    events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'message.received' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.failed' | 'comment.received' | 'review.new' | 'review.updated')>;
+    events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'message.received' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.failed' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received')>;
     /**
      * Whether webhook delivery is enabled
      */
@@ -2768,6 +2921,20 @@ export type WebhookPayloadAccountAdsInitialSyncCompleted = {
          * URL of the account's profile picture, when available.
          */
         profilePicture?: string;
+        /**
+         * When the consumer scoped the connect call to a single ad account, this echoes
+         * that ID back so the webhook can be correlated to the originating connect
+         * request without consulting the consumer's DB. Meta uses the `act_*` shape.
+         *
+         */
+        platformAdAccountId?: string;
+        /**
+         * Every ad-account ID that the connected token could see at discovery time.
+         * Useful for "we synced ads from these accounts" UX without a follow-up API call.
+         * Empty array when the token had no ad-account visibility.
+         *
+         */
+        platformAdAccountIds?: Array<(string)>;
     };
     /**
      * Summary of the initial ads sync backfill results.
@@ -2789,6 +2956,37 @@ export type WebhookPayloadAccountAdsInitialSyncCompleted = {
          * Number of ads that failed to sync.
          */
         failed: number;
+        /**
+         * Free-form error message from the platform (typically Meta's Marketing API).
+         * Truncated to ~2KB. Present when `status` is `failure` (and sometimes on `success`
+         * when discovery saw zero ad accounts). For UX branching prefer `errorCategory`;
+         * this field is for human display and debugging.
+         *
+         */
+        error?: string;
+        /**
+         * Platform-native error code if parsed (e.g. Meta `190`, `10`, `200`).
+         */
+        errorCode?: string;
+        /**
+         * Platform-native error subcode if parsed.
+         */
+        errorSubcode?: string;
+        /**
+         * Stable category for UX branching. New values may be added; existing ones are
+         * stable. Mapping:
+         * - `token_invalid`: access token is expired or revoked. Reconnect.
+         * - `permission_denied`: token lacks required scope, or the user has no role
+         * on the Business Manager that owns the ad account. Reconnect with full
+         * permissions, or have an admin grant access.
+         * - `no_ad_accounts`: token is valid but sees zero ad accounts. The user
+         * needs to connect a Business Manager that owns ad accounts.
+         * - `rate_limited`: platform throttled us. Sync will retry automatically.
+         * - `discovery_failed`: any other platform-side failure. Inspect `error`.
+         * - `unknown`: classifier could not categorize the failure.
+         *
+         */
+        errorCategory?: 'token_invalid' | 'permission_denied' | 'no_ad_accounts' | 'rate_limited' | 'discovery_failed' | 'unknown';
     };
     timestamp: string;
 };
@@ -2798,7 +2996,23 @@ export type event = 'account.ads.initial_sync_completed';
 /**
  * Overall outcome of the initial sync.
  */
-export type status6 = 'success' | 'failure';
+export type status7 = 'success' | 'failure';
+
+/**
+ * Stable category for UX branching. New values may be added; existing ones are
+ * stable. Mapping:
+ * - `token_invalid`: access token is expired or revoked. Reconnect.
+ * - `permission_denied`: token lacks required scope, or the user has no role
+ * on the Business Manager that owns the ad account. Reconnect with full
+ * permissions, or have an admin grant access.
+ * - `no_ad_accounts`: token is valid but sees zero ad accounts. The user
+ * needs to connect a Business Manager that owns ad accounts.
+ * - `rate_limited`: platform throttled us. Sync will retry automatically.
+ * - `discovery_failed`: any other platform-side failure. Inspect `error`.
+ * - `unknown`: classifier could not categorize the failure.
+ *
+ */
+export type errorCategory2 = 'token_invalid' | 'permission_denied' | 'no_ad_accounts' | 'rate_limited' | 'discovery_failed' | 'unknown';
 
 /**
  * Webhook payload for account connected events
@@ -2962,6 +3176,34 @@ export type event4 = 'comment.received';
 
 export type platform6 = 'instagram' | 'facebook' | 'twitter' | 'youtube' | 'linkedin' | 'bluesky' | 'reddit';
 
+/**
+ * Webhook payload for the lead.received event. Fired when a Meta Lead Gen
+ * Form receives a new submission. Real-time delivery requires the page to
+ * be subscribed to the `leadgen` webhook field — Zernio subscribes
+ * on connect; existing accounts get backfilled by
+ * `scripts/backfill-fb-webhook-subscriptions.ts`.
+ *
+ * Requires the Ads add-on. Subscribers without the add-on are filtered at
+ * delivery time.
+ *
+ */
+export type WebhookPayloadLeadReceived = {
+    /**
+     * Stable webhook event ID
+     */
+    id: string;
+    event: 'lead.received';
+    lead: Lead;
+    account: {
+        id: string;
+        platform: string;
+        username: string;
+    };
+    timestamp: string;
+};
+
+export type event5 = 'lead.received';
+
 /**
  * Webhook payload for message received events
  */
@@ -3177,7 +3419,7 @@ export type WebhookPayloadMessage = {
     timestamp: string;
 };
 
-export type event5 = 'message.received';
+export type event6 = 'message.received';
 
 /**
  * WhatsApp only. Which kind of interactive reply the user sent:
@@ -3209,7 +3451,7 @@ export type WebhookPayloadMessageDeleted = {
     timestamp: string;
 };
 
-export type event6 = 'message.deleted';
+export type event7 = 'message.deleted';
 
 /**
  * Shared payload for message.delivered, message.read, and
@@ -3244,7 +3486,7 @@ export type WebhookPayloadMessageDeliveryStatus = {
     timestamp: string;
 };
 
-export type event7 = 'message.delivered' | 'message.read' | 'message.failed';
+export type event8 = 'message.delivered' | 'message.read' | 'message.failed';
 
 /**
  * Webhook payload for message.edited events. Fires when the sender
@@ -3286,7 +3528,7 @@ export type WebhookPayloadMessageEdited = {
     timestamp: string;
 };
 
-export type event8 = 'message.edited';
+export type event9 = 'message.edited';
 
 /**
  * Webhook payload for message sent events (fired when a message is sent via the API)
@@ -3362,7 +3604,7 @@ export type WebhookPayloadMessageSent = {
     timestamp: string;
 };
 
-export type event9 = 'message.sent';
+export type event10 = 'message.sent';
 
 /**
  * Webhook payload for post events
@@ -3390,7 +3632,7 @@ export type WebhookPayloadPost = {
     timestamp: string;
 };
 
-export type event10 = 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled';
+export type event11 = 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled';
 
 /**
  * Webhook payload for the review.new event (new review posted on a connected account).
@@ -3410,7 +3652,7 @@ export type WebhookPayloadReviewNew = {
     timestamp: string;
 };
 
-export type event11 = 'review.new';
+export type event12 = 'review.new';
 
 /**
  * Webhook payload for the review.updated event. Fired when the reviewer edits
@@ -3434,7 +3676,7 @@ export type WebhookPayloadReviewUpdated = {
     timestamp: string;
 };
 
-export type event12 = 'review.updated';
+export type event13 = 'review.updated';
 
 /**
  * Webhook payload for test deliveries
@@ -3452,7 +3694,7 @@ export type WebhookPayloadTest = {
     timestamp: string;
 };
 
-export type event13 = 'webhook.test';
+export type event14 = 'webhook.test';
 
 export type WhatsAppBodyComponent = {
     type: 'body';
@@ -4676,6 +4918,13 @@ export type ListAccountGroupsResponse = ({
         _id?: string;
         name?: string;
         accountIds?: Array<(string)>;
+        createdBy?: string;
+        /**
+         * Legacy field. Present only on groups created before
+         * cross-profile groups were supported. New groups omit it.
+         *
+         */
+        profileId?: string;
     }>;
 });
 
@@ -4687,6 +4936,13 @@ export type CreateAccountGroupData = {
     body: {
         name: string;
         accountIds: Array<(string)>;
+        /**
+         * Deprecated. Accepted for backward compatibility but ignored.
+         * Groups are no longer scoped to a single profile.
+         *
+         * @deprecated
+         */
+        profileId?: string;
     };
 };
 
@@ -5772,6 +6028,25 @@ export type ConnectAdsData = {
          *
          */
         accountId?: string;
+        /**
+         * (metaads only) Scope ad sync to a single Meta ad account. Without this
+         * param, sync covers every `act_*` the connected token can see. Pass this
+         * to limit `sync.totalAds` / `synced` and the resulting ads to one ad
+         * account. Format: `act_<digits>` (matches what `/me/adaccounts` returns).
+         * Validated against the connected token; unreachable IDs return 400.
+         * For multiple accounts use `adAccountIds` instead.
+         *
+         */
+        adAccountId?: string;
+        /**
+         * (metaads only) Scope ad sync to multiple Meta ad accounts. Repeat the
+         * param (`?adAccountIds=act_1&adAccountIds=act_2`) or comma-separate
+         * (`?adAccountIds=act_1,act_2`). Validated against the connected token.
+         * Persisted server-side; latest call wins. Omitting both `adAccountId`
+         * and `adAccountIds` keeps any previously persisted scope unchanged.
+         *
+         */
+        adAccountIds?: Array<(string)>;
         /**
          * Enable headless mode (same-token platforms only)
          */
@@ -5793,6 +6068,12 @@ export type ConnectAdsResponse = (({
     platform?: string;
     username?: string;
     displayName?: string;
+    /**
+     * Echo of the persisted ad-account scope when the caller passed
+     * `adAccountId` / `adAccountIds`. Omitted when no scope is set.
+     *
+     */
+    scopedAdAccountIds?: Array<(string)>;
 } | {
     authUrl?: string;
     state?: string;
@@ -13443,9 +13724,13 @@ export type CreateStandaloneAdData = {
          */
         body?: string;
         /**
-         * Required on legacy + attach shapes for Meta. Honoured on TikTok too — passes through to the Spark Ad creative's `call_to_action`. Ignored by other platforms.
+         * Required on legacy + attach shapes for Meta. Honoured on TikTok too — passes through to the Spark Ad creative's `call_to_action`. Ignored by other platforms. Ignored on Meta when `leadGenFormId` is set — lead ads force CTA type to SIGN_UP.
          */
         callToAction?: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+        /**
+         * Meta-only. Attaches a Lead Gen (Instant) Form to the creative. Required when `goal="lead_generation"`. Force-overrides the CTA to SIGN_UP. Create a form first via POST /v1/ads/lead-forms. On the multi-creative shape this can also be set per `creatives[i]` to A/B different forms inside one ad set.
+         */
+        leadGenFormId?: string;
         /**
          * Required on legacy + attach shapes. Skip for multi-creative.
          */
@@ -13503,6 +13788,10 @@ export type CreateStandaloneAdData = {
             };
             linkUrl: string;
             callToAction: 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'BOOK_TRAVEL' | 'CONTACT_US' | 'DOWNLOAD' | 'GET_OFFER' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_MORE';
+            /**
+             * Per-creative Lead Gen Form ID. Wins over the top-level `leadGenFormId` so each ad in a campaign can A/B a different form. Forces CTA to SIGN_UP.
+             */
+            leadGenFormId?: string;
         }>;
         /**
          * Meta-only. When present, switches to the attach shape: adds
@@ -13967,6 +14256,189 @@ export type AddUsersToAdAudienceError = (unknown | {
     error?: string;
 });
 
+export type ListLeadFormsData = {
+    query: {
+        /**
+         * Facebook social account ID (Late SocialAccount _id)
+         */
+        accountId: string;
+        /**
+         * Meta `paging.cursors.after` from a prior page
+         */
+        cursor?: string;
+        limit?: number;
+    };
+};
+
+export type ListLeadFormsResponse = ({
+    status?: string;
+    forms?: Array<LeadGenForm>;
+    pagination?: {
+        hasMore?: boolean;
+        cursor?: (string) | null;
+    };
+    meta?: LeadFormResponseMeta;
+});
+
+export type ListLeadFormsError = ({
+    error?: string;
+} | unknown);
+
+export type CreateLeadFormData = {
+    body: CreateLeadFormBody;
+};
+
+export type CreateLeadFormResponse = ({
+    status?: string;
+    form?: {
+        id?: string;
+        name?: string;
+    };
+    meta?: LeadFormResponseMeta;
+});
+
+export type CreateLeadFormError = (unknown | {
+    error?: string;
+});
+
+export type GetLeadFormData = {
+    path: {
+        /**
+         * Meta lead form ID (numeric string)
+         */
+        formId: string;
+    };
+    query: {
+        accountId: string;
+    };
+};
+
+export type GetLeadFormResponse = ({
+    status?: string;
+    form?: LeadGenForm;
+    meta?: LeadFormResponseMeta;
+});
+
+export type GetLeadFormError = ({
+    error?: string;
+} | unknown);
+
+export type UpdateLeadFormData = {
+    body: {
+        accountId: string;
+        status: 'ACTIVE' | 'ARCHIVED' | 'DRAFT';
+    };
+    path: {
+        formId: string;
+    };
+};
+
+export type UpdateLeadFormResponse = ({
+    status?: string;
+    success?: boolean;
+    meta?: LeadFormResponseMeta;
+});
+
+export type UpdateLeadFormError = (unknown | {
+    error?: string;
+});
+
+export type DeleteLeadFormData = {
+    path: {
+        formId: string;
+    };
+    query: {
+        accountId: string;
+    };
+};
+
+export type DeleteLeadFormResponse = ({
+    status?: string;
+    success?: boolean;
+    meta?: LeadFormResponseMeta;
+});
+
+export type DeleteLeadFormError = ({
+    error?: string;
+} | unknown);
+
+export type ListLeadFormLeadsData = {
+    path: {
+        formId: string;
+    };
+    query: {
+        accountId: string;
+        cursor?: string;
+        limit?: number;
+        /**
+         * Unix timestamp; only return leads created strictly after this.
+         */
+        since?: number;
+    };
+};
+
+export type ListLeadFormLeadsResponse = ({
+    status?: string;
+    leads?: Array<Lead>;
+    pagination?: {
+        hasMore?: boolean;
+        cursor?: (string) | null;
+    };
+    meta?: LeadFormResponseMeta;
+});
+
+export type ListLeadFormLeadsError = ({
+    error?: string;
+} | unknown);
+
+export type CreateLeadFormTestLeadData = {
+    body: {
+        accountId: string;
+        fieldData: Array<{
+            /**
+             * Question key (matches `key` from form definition)
+             */
+            name: string;
+            values: Array<(string)>;
+        }>;
+    };
+    path: {
+        formId: string;
+    };
+};
+
+export type CreateLeadFormTestLeadResponse = ({
+    status?: string;
+    testLead?: {
+        id?: string;
+    };
+    meta?: LeadFormResponseMeta;
+});
+
+export type CreateLeadFormTestLeadError = ({
+    error?: string;
+} | unknown);
+
+export type DeleteLeadFormTestLeadData = {
+    path: {
+        formId: string;
+        leadId: string;
+    };
+    query: {
+        accountId: string;
+    };
+};
+
+export type DeleteLeadFormTestLeadResponse = ({
+    status?: string;
+    success?: boolean;
+    meta?: LeadFormResponseMeta;
+});
+
+export type DeleteLeadFormTestLeadError = ({
+    error?: string;
+} | unknown);
+
 export type SendConversionsData = {
     body: {
         /**