@funnelchat-hq/sdk 0.1.2 → 0.2.1

package/dist/index.d.cts

@@ -3780,7 +3780,11 @@ interface paths {
          */
         get: operations["device.index"];
         put?: never;
-        post?: never;
+        /**
+         * Create a number connected by QR code
+         * @description Same path and same rejections as the panel: `403 numbers_not_included`, `403 number_limit_reached`, `409 pending_number_exists` (the account already has a QR number waiting to be scanned: its `device_id` comes in the body), `422 qr_requires_coexistence`, `422 method_already_present` (with `device_id`), `409 operation_in_progress`. The provider is chosen by the system. Then ask for the QR with `GET devices/{device}/qr`. `country` is the country of the phone that will scan the QR, where the WhatsApp session is opened from.
+         */
+        post: operations["pendingDevice.store"];
         delete?: never;
         options?: never;
         head?: never;
@@ -4887,6 +4891,71 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/devices/{device}/qr": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The QR code to connect a number
+         * @description Creates the WhatsApp instance when needed. Only for QR numbers: an official one answers `422 provider_unsupported`. Scanning the QR gives control of a WhatsApp, so it needs **WhatsApp numbers → Create, connect and delete** (`accounts:operate`). Every call brings the code of that moment: ask again every `expires_in` seconds (5 with a QR) and replace the image with the latest one; the answer carries `Cache-Control: no-store`.
+         */
+        get: operations["pendingDevice.qr"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/connect-links": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List connect links
+         * @description Without the token: `url` is not shown again. Newest first.
+         */
+        get: operations["pendingConnectLink.index"];
+        put?: never;
+        /**
+         * Create a connect link
+         * @description A single-use page where your customer connects a number: by QR code, or an official one through the Meta sign-up. The number is created when the page finishes. The quota is checked now (except on a reconnection) and again at the end, with the rejections of `POST devices`. `provision_us_number` needs `dedicated` in `allowed_connection_types` and no `device_id` (`422 invalid_request`). At most 20 open links per account (`429 too_many_open_links`); `type: "meta"` answers `503 meta_connect_disabled` while the official sign-up is off, as it is in production until the domain is registered with Meta. `country` (only `qr`, not with `device_id`) is the country of the phone that will scan the QR.
+         */
+        post: operations["pendingConnectLink.store"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/connect-links/{link}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read a connect link */
+        get: operations["pendingConnectLink.show"];
+        put?: never;
+        post?: never;
+        /**
+         * Revoke a connect link
+         * @description Only a `pending` link: any other answers `409 link_not_pending`.
+         */
+        delete: operations["pendingConnectLink.destroy"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface webhooks {
     "message.received": {
@@ -6136,7 +6205,7 @@ interface webhooks {
         put?: never;
         /**
          * device.connected
-         * @description One of the numbers of the account got connected: by scanning the QR code or by finishing the sign-up of a WhatsApp Cloud number.
+         * @description One of the numbers of the account got connected: by scanning the QR code, by finishing the sign-up of a WhatsApp Cloud number, or through a connect link.
          */
         post: {
             parameters: {
@@ -6149,14 +6218,11 @@ interface webhooks {
                 content: {
                     "application/json": {
                         data?: {
-                            device: {
-                                id: number;
-                                name: string | null;
-                                /** @description Digits only, without `+`. */
-                                number: string | null;
-                            };
+                            device: components["schemas"]["PendingWebhookDevice"];
                             /** Format: date-time */
                             connected_at: string;
+                            /** @description The connect link of this connection, or `null` when it did not come from a link. */
+                            connect_link_id?: number | null;
                         };
                     };
                 };
@@ -6180,7 +6246,7 @@ interface webhooks {
         put?: never;
         /**
          * device.disconnected
-         * @description One of the numbers of the account disconnected and can no longer send or receive.
+         * @description One of the numbers of the account disconnected and can no longer send or receive: a QR session that closed or was protected from a shadow ban, an official number that failed its re-registration, or one disconnected from the panel.
          */
         post: {
             parameters: {
@@ -6193,14 +6259,13 @@ interface webhooks {
                 content: {
                     "application/json": {
                         data?: {
-                            device: {
-                                id: number;
-                                name: string | null;
-                                /** @description Digits only, without `+`. */
-                                number: string | null;
-                            };
+                            device: components["schemas"]["PendingWebhookDevice"];
                             /** Format: date-time */
                             disconnected_at: string;
+                            /** @enum {string} */
+                            reason?: "qr_logged_out" | "meta_account_not_registered" | "shadow_ban_protection" | "provider_error" | "unknown" | "disconnected_by_user";
+                            /** @description The connect link that last connected the number, or `null`. */
+                            connect_link_id?: number | null;
                         };
                     };
                 };
@@ -7352,6 +7417,92 @@ interface webhooks {
         patch?: never;
         trace?: never;
     };
+    "device.deleted": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * device.deleted
+         * @description A number of the account was deleted: its slot of the plan is free again.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        data?: {
+                            device: components["schemas"]["PendingWebhookDevice"];
+                            /** Format: date-time */
+                            deleted_at: string;
+                            /** @description The connect link that last connected the number, or `null`. */
+                            connect_link_id?: number | null;
+                        };
+                    };
+                };
+            };
+            responses: never;
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "device.health_changed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * device.health_changed
+         * @description The health of an official number changed (what Meta lets it do). Emitted only when the overall state changes.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        data?: {
+                            device: components["schemas"]["PendingWebhookDevice"];
+                            /** @enum {string} */
+                            previous_state: "available" | "limited" | "blocked" | "unknown";
+                            /** @enum {string} */
+                            state: "available" | "limited" | "blocked" | "unknown";
+                            /** Format: date-time */
+                            changed_at: string;
+                            /** @description The connect link that last connected the number, or `null`. */
+                            connect_link_id?: number | null;
+                        };
+                    };
+                };
+            };
+            responses: never;
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
@@ -8422,6 +8573,8 @@ interface components {
                 /** @description The statuses `message.status_changed` reports for the messages of this number. */
                 statuses: ("sent" | "delivered" | "read" | "failed")[];
             };
+            connection?: components["schemas"]["PendingDeviceConnection"];
+            external_reference?: components["schemas"]["PendingExternalReference"];
         };
         /** DisconnectSurveyResource */
         DisconnectSurveyResource: {
@@ -9441,7 +9594,7 @@ interface components {
             /** @description `https`, public and without user or password. */
             url: string;
             description?: string | null;
-            /** @description Types of the catalog (`GET /api/v1/webhooks/events`). The key needs the `{area}:read` permission of the area of each type. */
+            /** @description Types of the catalog (`GET /api/v1/webhooks/events`). The key needs the **View** permission of the area of each type in the panel (`{area}:read`), such as **WhatsApp numbers → View** (`accounts:read`). */
             events: string[];
             filters?: components["schemas"]["PendingWebhookSubscriptionFilters"] | null;
         };
@@ -9587,6 +9740,115 @@ interface components {
             /** Format: date-time */
             updated_at?: string | null;
         };
+        /**
+         * @description `qr`: connected by scanning a QR code (not official). `coexistence`: WhatsApp Cloud API together with the WhatsApp Business app. `dedicated`: WhatsApp Cloud API only. `null` when it cannot be told yet.
+         * @enum {string|null}
+         */
+        PendingDeviceConnection: "qr" | "coexistence" | "dedicated" | null;
+        /** @description Your own reference for the number (for example the id of your customer). Free text, not unique. */
+        PendingExternalReference: string | null;
+        PendingDeviceCreate: {
+            /**
+             * @description How the number connects. Only `qr` for now: an official number is created through a connect link.
+             * @enum {string}
+             */
+            connection: "qr";
+            /** @description The name of the number in the panel. */
+            alias?: string;
+            external_reference?: components["schemas"]["PendingExternalReference"];
+            /** @description Adds QR to a number that already exists (in coexistence) instead of taking a new slot of the plan. */
+            same_number_as?: number;
+            country?: components["schemas"]["PendingCountry"];
+        };
+        PendingDeviceQr: {
+            connected: boolean;
+            /** @description A PNG image as a data URI, or `null` when the number is already connected. */
+            qr_code: string | null;
+            /** @description Seconds after which to ask for it again: 5 with a QR, 3 while the session starts, 0 once connected. WhatsApp changes the code every few seconds and an old one no longer links: show the latest one and have it scanned right away; do not store or forward a QR. */
+            expires_in: number;
+        };
+        /** @enum {string} */
+        PendingConnectLinkStatus: "pending" | "completed" | "failed" | "expired" | "revoked";
+        /**
+         * @description Why the link did not complete, or `null`.
+         * @enum {string|null}
+         */
+        PendingConnectLinkErrorCode: "link_expired" | "already_used" | "revoked" | "quota_exceeded" | "trial_number_blocked" | "facebook_auth_failed" | "meta_error" | "number_not_owned" | "qr_timeout" | "provider_error" | null;
+        /** @enum {string} */
+        PendingConnectLinkConnectionType: "coexistence" | "dedicated";
+        PendingConnectLink: {
+            id: number;
+            /** @enum {string} */
+            type: "meta" | "qr";
+            /** @description A Meta link stays `pending` after a failure of Facebook or Meta, so your customer can try again on the page; the fifth failed attempt turns it `failed` (`facebook_auth_failed` or `meta_error`). `quota_exceeded`, `trial_number_blocked` and `number_not_owned` close it at the first attempt. */
+            status: components["schemas"]["PendingConnectLinkStatus"];
+            /** @description The page to send your customer to. It carries the token, so it comes only in the response of `POST connect-links`. */
+            url?: string | null;
+            /** Format: date-time */
+            expires_at: string;
+            allowed_connection_types: components["schemas"]["PendingConnectLinkConnectionType"][] | null;
+            provision_us_number: boolean;
+            /** @description Only `type: qr`: the country the WhatsApp session is opened from, lowercase; `null` when it was not sent. */
+            country: string | null;
+            /** @description The number the link reconnects, or the one it created once `completed`; `null` otherwise. */
+            device_id: number | null;
+            external_reference: components["schemas"]["PendingExternalReference"];
+            return_url: string | null;
+            /** @description Why the link did not complete (`link_expired` when it expired, `revoked` when revoked), or `null`. */
+            error_code: components["schemas"]["PendingConnectLinkErrorCode"];
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at: string | null;
+        };
+        PendingConnectLinkWithUrl: components["schemas"]["PendingConnectLink"] & {
+            url: string;
+        };
+        PendingConnectLinkCreate: {
+            /** @enum {string} */
+            type: "meta";
+            /** @description With both, your customer chooses on the page. */
+            allowed_connection_types: components["schemas"]["PendingConnectLinkConnectionType"][];
+            /** @description Offers a US number of the pool (3 per account, 1 on trial accounts, held 15 minutes). `false` by default. A pool number is always dedicated: it needs `dedicated` in `allowed_connection_types` and does not go with `device_id`; otherwise `422 invalid_request`. */
+            provision_us_number?: boolean;
+            /** @description Reconnects this number instead of creating one; takes no new slot. `type` must match how the number connects. */
+            device_id?: number;
+            external_reference?: components["schemas"]["PendingExternalReference"];
+            /**
+             * Format: uri
+             * @description Only `https`. When the page finishes it redirects there with `connect_link_id`, `status`, `device_id` and `error_code`.
+             */
+            return_url?: string;
+            /** @description 1440 (24 hours) by default. */
+            expires_in_minutes?: number;
+        } | {
+            /** @enum {string} */
+            type: "qr";
+            /** @description Adds QR to a number in coexistence. */
+            same_number_as?: number;
+            /** @description The country of the phone that will scan the QR code (ISO 3166-1 alpha-2): the WhatsApp session is opened from there. Not with `device_id` (`422 invalid_request`): a reconnection creates nothing. */
+            country?: components["schemas"]["PendingCountry"];
+            /** @description Reconnects this number instead of creating one; takes no new slot. `type` must match how the number connects. */
+            device_id?: number;
+            external_reference?: components["schemas"]["PendingExternalReference"];
+            /**
+             * Format: uri
+             * @description Only `https`. When the page finishes it redirects there with `connect_link_id`, `status`, `device_id` and `error_code`.
+             */
+            return_url?: string;
+            /** @description 1440 (24 hours) by default. */
+            expires_in_minutes?: number;
+        };
+        PendingWebhookDevice: {
+            id: number;
+            name: string | null;
+            /** @description Digits only, without `+`. */
+            number: string | null;
+            connection?: components["schemas"]["PendingDeviceConnection"];
+            external_reference?: components["schemas"]["PendingExternalReference"];
+        };
+        /** @description The country of the phone that will scan the QR code (ISO 3166-1 alpha-2, two letters, any case): the WhatsApp session is opened from there. Without it, Funnelchat chooses one. */
+        PendingCountry: string | null;
     };
     responses: {
         /** @description Unauthenticated */
@@ -17432,7 +17694,10 @@ interface operations {
     };
     "device.index": {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Only the numbers with this reference (exact match). */
+                external_reference?: string;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -17483,6 +17748,35 @@ interface operations {
             403: components["responses"]["AccountsAuthorizationException"];
         };
     };
+    "pendingDevice.store": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Kept 24 hours per account and resource. Only a 2xx is replayed, with `Idempotent-Replayed: true`; a rejection is evaluated again. The same key with another body: `422 idempotency_key_mismatch`; while the first call runs: `409 operation_in_progress`; a malformed key: `422 invalid_idempotency_key`. */
+                "Idempotency-Key"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PendingDeviceCreate"];
+            };
+        };
+        responses: {
+            /** @description Created, with `connected: false` and `connection: "qr"`. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["DeviceResource"];
+                    };
+                };
+            };
+        };
+    };
     "device.me": {
         parameters: {
             query?: never;
@@ -17640,6 +17934,7 @@ interface operations {
                      *     account (defense in depth, see updateMetaDevice below).
                      */
                     capi_consent?: boolean;
+                    external_reference?: components["schemas"]["PendingExternalReference"];
                 };
             };
         };
@@ -19733,6 +20028,134 @@ interface operations {
             };
         };
     };
+    "pendingDevice.qr": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The device ID */
+                device: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PendingDeviceQr"];
+                    };
+                };
+            };
+        };
+    };
+    "pendingConnectLink.index": {
+        parameters: {
+            query?: {
+                status?: components["schemas"]["PendingConnectLinkStatus"];
+                /** @description Exact match. */
+                external_reference?: string;
+                perPage?: number;
+                page?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PendingConnectLink"][];
+                        links?: Record<string, unknown>;
+                        meta?: Record<string, unknown>;
+                    };
+                };
+            };
+        };
+    };
+    "pendingConnectLink.store": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Kept 24 hours per account. The same key with the same body answers the same response without creating another resource; with another body, `422 idempotency_key_mismatch`; while the first call runs, `409 operation_in_progress`. */
+                "Idempotency-Key"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PendingConnectLinkCreate"];
+            };
+        };
+        responses: {
+            /** @description Created. `url` carries the token and is shown only here. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PendingConnectLinkWithUrl"];
+                    };
+                };
+            };
+        };
+    };
+    "pendingConnectLink.show": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                link: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PendingConnectLink"];
+                    };
+                };
+            };
+        };
+    };
+    "pendingConnectLink.destroy": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                link: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description No Content */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     "webhook.group_created": {
         parameters: {
             query?: never;
@@ -20634,13 +21057,24 @@ interface RequestOptions {
     /** Overrides the client's `maxRetries` for this request. */
     maxRetries?: number;
     /**
-     * Allows automatic retries of a non-idempotent send (`POST` with `conversations:send`) for this
-     * request. Off by default: a retried send can deliver the same message twice.
+     * Allows automatic retries of a non-idempotent send for this request: a `POST` that needs
+     * **Contacts and conversations → Send** (`conversations:send`). Off by default: a retried send
+     * can deliver the same message twice.
      */
     retrySend?: boolean;
     /** Cancels the request. */
     signal?: AbortSignal;
 }
+/** Options of the creates that take an `Idempotency-Key` (`devices.create`, `connectLinks.create`). */
+interface IdempotentRequestOptions extends RequestOptions {
+    /**
+     * Sent as the `Idempotency-Key` header (up to 255 characters, kept 24 hours per account). The same
+     * key with the same body answers the same response without creating another resource, so after a
+     * timeout or a `5xx` you can repeat the call with it safely. With another body: `422
+     * idempotency_key_mismatch`; while the first call runs: `409 operation_in_progress`.
+     */
+    idempotencyKey?: string;
+}
 type PathPart<P extends ApiPath, M extends HttpMethod> = PathParams<P, M> extends undefined ? {
     path?: undefined;
 } : {
@@ -20688,6 +21122,67 @@ declare abstract class Resource {
     #private;
     constructor(client: Funnelchat);
     protected get client(): Funnelchat;
+    /** The options of a request with `idempotencyKey` turned into the `Idempotency-Key` header. */
+    protected idempotent({ idempotencyKey, ...options }?: IdempotentRequestOptions): RequestOptions;
+}
+
+type LinkId = PathParams<'/api/v1/connect-links/{link}', 'GET'>['link'];
+/**
+ * Connect links (accounts area): a single-use page, on the Funnelchat domain, where your customer
+ * connects a WhatsApp number to your account, by QR code (`type: 'qr'`) or as an official number
+ * through the Meta sign-up (`type: 'meta'`). The number is created when the page finishes; with
+ * `device_id` the link reconnects that number instead, without taking a new slot. The Meta sign-up
+ * is not available in production yet: `type: 'meta'` answers `503 meta_connect_disabled` until it is.
+ *
+ * Reading needs **WhatsApp numbers → View** (`accounts:read`); creating and revoking,
+ * **WhatsApp numbers → Create, connect and delete** (`accounts:operate`). The result arrives three
+ * ways: the `device.connected` webhook (with `connect_link_id` and `external_reference`), the
+ * `return_url`, or `get`. The other `device.*` events carry the link that last connected the number.
+ *
+ * Errors of their own (`APIError.code`): the rejections of `devices.create`, `429
+ * too_many_open_links` (20 open links per account), `503 meta_connect_disabled`, `422
+ * connection_type_mismatch` (`device_id` of a number that connects another way) and `409
+ * link_not_pending` (revoking a link that already ended).
+ */
+declare class ConnectLinks extends Resource {
+    /**
+     * `POST /api/v1/connect-links`. `url` is the page to send your customer to: it carries the token
+     * and comes only in this response.
+     *
+     * `provision_us_number` (a US number of the pool, always dedicated) needs `dedicated` in
+     * `allowed_connection_types` and does not go with `device_id`: otherwise `422 invalid_request`.
+     * A Meta link stays `pending` after a failure of Facebook or Meta, so your customer can try again;
+     * the fifth failed attempt turns it `failed`.
+     *
+     * `country` (only `qr`, not with `device_id`) is the country of the phone that will scan the QR, in
+     * two letters: the WhatsApp session is opened from there. The link returns it, lowercase.
+     */
+    create(body: Body<'/api/v1/connect-links', 'POST'>, options?: IdempotentRequestOptions): APIPromise<{
+        data: components["schemas"]["PendingConnectLinkWithUrl"];
+    }>;
+    /** `GET /api/v1/connect-links/{link}`: its `status`, and `device_id` and `error_code` once it ends. */
+    get(link: LinkId, options?: RequestOptions): APIPromise<{
+        data: components["schemas"]["PendingConnectLink"];
+    }>;
+    /** `GET /api/v1/connect-links`, paginated, newest first: filter by `status` or `external_reference`. */
+    list(query?: Query<'/api/v1/connect-links'>, options?: RequestOptions): PagePromise<{
+        id: number;
+        type: "meta" | "qr";
+        status: components["schemas"]["PendingConnectLinkStatus"];
+        url?: string | null;
+        expires_at: string;
+        allowed_connection_types: components["schemas"]["PendingConnectLinkConnectionType"][] | null;
+        provision_us_number: boolean;
+        country: string | null;
+        device_id: number | null;
+        external_reference: components["schemas"]["PendingExternalReference"];
+        return_url: string | null;
+        error_code: components["schemas"]["PendingConnectLinkErrorCode"];
+        created_at: string;
+        completed_at: string | null;
+    }>;
+    /** `DELETE /api/v1/connect-links/{link}`: revokes a `pending` link (any other is `409 link_not_pending`). */
+    revoke(link: LinkId, options?: RequestOptions): APIPromise<unknown>;
 }
 
 type ContactId$2 = PathParams<'/api/v1/contacts/{contact}', 'GET'>['contact'];
@@ -21080,50 +21575,30 @@ declare class CustomFields extends Resource {
 }
 
 type DeviceId$3 = PathParams<'/api/v1/devices/{device}', 'GET'>['device'];
+type Device = ListItem<'/api/v1/devices'>;
 /** WhatsApp numbers of the account (accounts area). The `id` of a number is the `device_id` used to send. */
 declare class Devices extends Resource {
-    /** `GET /api/v1/devices`. Iterate it with `for await`, or `await` it for the first page. */
-    list(options?: RequestOptions): PagePromise<{
-        id: number;
-        alias: string;
-        image: string;
-        color: string;
-        number: string;
-        normalized_number: string;
-        first_conecction_at: string;
-        user_id: number;
-        provider: components["schemas"]["WhatsAppProviderEnum"];
-        waba_id: string;
-        whatsapp_username: string | null;
-        is_business: number;
-        connected: number;
-        active: number | null;
-        health: string;
-        number_key?: string | null;
-        number_key_confirmed?: boolean;
-        is_coexistence?: boolean;
-        slot_state?: "free" | "reserved" | "pending" | "held";
-        pool_suspended?: boolean;
-        pool_suspension_reason?: "over_pool" | "payment_lapse" | null;
-        pool_keep?: boolean;
-        qr_allowed?: boolean;
-        can_change_to_meta?: boolean;
-        capabilities: {
-            messages: {
-                text: boolean;
-                media: boolean;
-                buttons: boolean;
-                lists: boolean;
-                templates: boolean;
-                location: boolean;
-                voice_note: boolean;
-                polls: boolean;
-                events: boolean;
-                contact_card: boolean;
-                reactions: boolean;
-            };
-            statuses: ("sent" | "delivered" | "read" | "failed")[];
-        };
+    /**
+     * `GET /api/v1/devices`. Iterate it with `for await`, or `await` it for the first page.
+     * `external_reference` keeps only the numbers with that reference (exact match).
+     */
+    list(query?: Query<'/api/v1/devices'>, options?: RequestOptions): PagePromise<Device>;
+    /** @deprecated The 0.1.2 signature, still supported: pass the options second, `list({}, options)`. */
+    list(options: RequestOptions): PagePromise<Device>;
+    /**
+     * `POST /api/v1/devices`: creates a number that connects by QR code (`connection: 'qr'`), with
+     * `connected: false`. Then show its QR with `qr`, or send your customer a connect link
+     * (`connectLinks.create`). Needs **WhatsApp numbers → Create, connect and delete**
+     * (`accounts:operate`). It takes a slot of the plan, with the panel's
+     * rejections: `403 numbers_not_included`, `403 number_limit_reached`, `422 qr_requires_coexistence`
+     * and `422 method_already_present` (`same_number_as` adds QR to a number in coexistence instead).
+     * An account has at most one QR number waiting to be scanned: another one is `409
+     * pending_number_exists`, with that number's `device_id` in `error.body`. `country` (two letters,
+     * such as `'br'`) is the country of the phone that will scan the QR: the WhatsApp session is opened
+     * from there.
+     */
+    create(body: Body<'/api/v1/devices', 'POST'>, options?: IdempotentRequestOptions): APIPromise<{
+        data: components["schemas"]["DeviceResource"];
     }>;
     /**
      * `GET /api/v1/devices/{device}`. `capabilities` says what the number can do by API: message
@@ -21170,8 +21645,17 @@ declare class Devices extends Resource {
             };
             statuses: ("sent" | "delivered" | "read" | "failed")[];
         };
+        connection?: components["schemas"]["PendingDeviceConnection"];
+        external_reference?: components["schemas"]["PendingExternalReference"];
     }>;
-    /** `PUT /api/v1/devices/{device}`. */
+    /**
+     * `DELETE /api/v1/devices/{device}`: deletes the number and frees its slot of the plan. An
+     * official number stops receiving through Funnelchat but stays registered with Meta; a QR one
+     * logs out. Irreversible; needs **WhatsApp numbers → Create, connect and delete**
+     * (`accounts:operate`). Sends `device.deleted`.
+     */
+    delete(device: DeviceId$3, options?: RequestOptions): APIPromise<Record<string, unknown>>;
+    /** `PUT /api/v1/devices/{device}`: also changes `external_reference`. */
     update(device: DeviceId$3, body: Body<'/api/v1/devices/{device}', 'PUT'>, options?: RequestOptions): APIPromise<{
         id: number;
         alias: string;
@@ -21213,6 +21697,21 @@ declare class Devices extends Resource {
             };
             statuses: ("sent" | "delivered" | "read" | "failed")[];
         };
+        connection?: components["schemas"]["PendingDeviceConnection"];
+        external_reference?: components["schemas"]["PendingExternalReference"];
+    }>;
+    /**
+     * `GET /api/v1/devices/{device}/qr`: the QR code to scan, as a PNG data URI (`qr_code`), or `null`
+     * once `connected`. Ask for it every `expires_in` seconds (5 with a QR, 3 while the session starts,
+     * 0 once connected) and have it scanned right away: WhatsApp changes the code every few seconds and
+     * an old one no longer links, so show the latest and never store or forward a QR. Only for QR
+     * numbers (an official one is `422 provider_unsupported`); needs
+     * **WhatsApp numbers → Create, connect and delete** (`accounts:operate`), since scanning it gives
+     * control of a WhatsApp. A number that cannot connect now
+     * answers `409` (`trial_number_blocked`, `number_suspended_by_plan`, `device_inactive`…).
+     */
+    qr(device: DeviceId$3, options?: RequestOptions): APIPromise<{
+        data: components["schemas"]["PendingDeviceQr"];
     }>;
     /** `GET /api/v1/devices/{device}/status`: connection status. */
     status(device: DeviceId$3, options?: RequestOptions): APIPromise<Record<string, unknown>>;
@@ -21250,7 +21749,8 @@ type RunId = PathParams<'/api/v1/forms/families/{familyId}/responses/{runId}', '
 type DeviceId$2 = PathParams<'/api/v1/forms/{id}/numbers/{deviceId}', 'DELETE'>['deviceId'];
 /**
  * WhatsApp forms (conversations area): build them, publish them on your numbers and read the
- * answers. Reading needs `conversations:read`; the rest, `conversations:write`.
+ * answers. Reading needs **Contacts and conversations → View** (`conversations:read`); the rest,
+ * **Contacts and conversations → Edit** (`conversations:write`).
  *
  * Two ids: `id` is one version of a form; `family_id` is the form itself (every version). You send
  * a form by its `family_id` with `messages.sendForm`, and `whatsapp_form.completed` brings it as
@@ -21407,7 +21907,7 @@ declare class Forms extends Resource {
 type GroupId = PathParams<'/api/v1/groups/{group}', 'GET'>['group'];
 type GroupUid = PathParams<'/api/v1/groups/{groupUid}/metadata', 'GET'>['groupUid'];
 type DeviceId$1 = PathParams<'/api/v1/devices/{device}/groups', 'GET'>['device'];
-/** WhatsApp groups (communities area): read them, their participants, events and messages. Permission `communities:read`. */
+/** WhatsApp groups (communities area): read them, their participants, events and messages. Permission: **Groups and campaigns → View** (`communities:read`). */
 declare class Groups extends Resource {
     /** `GET /api/v1/groups`, paginated. */
     list(query?: Query<'/api/v1/groups'>, options?: RequestOptions): PagePromise<{
@@ -21614,8 +22114,8 @@ type SendMessageParams = Omit<SendMessageBody, 'contact_id'> & {
  * delivered. The rest arrives by `message.status_changed` (with the same `id` as `message_id`) or
  * with {@link Messages.get}.
  *
- * Sending with an API key needs the `conversations:send` permission and is subject to the
- * WhatsApp rules: `422 window_closed`, `422 antiblock_*`, `422 recipient_*`,
+ * Sending with an API key needs **Contacts and conversations → Send** (`conversations:send`) and
+ * is subject to the WhatsApp rules: `422 window_closed`, `422 antiblock_*`, `422 recipient_*`,
  * `422 provider_unsupported`, `429 rate_limited` (with `retryAfter`) and `429 mac_lockout_24h`. A
  * rejected send stores nothing (see `SEND_ERROR_CODES`). Sends are never retried automatically
  * unless you pass `retrySend: true`.
@@ -21929,7 +22429,7 @@ interface WebhookEventInfo {
     readonly pending: boolean;
     readonly description: string | null;
 }
-/** Every webhook event type known to the spec (53). */
+/** Every webhook event type known to the spec (55). */
 declare const webhookEvents: readonly [{
     readonly type: "account.blocked";
     readonly domains: readonly ["accounts"];
@@ -22043,13 +22543,25 @@ declare const webhookEvents: readonly [{
     readonly domains: readonly ["accounts"];
     readonly status: "live";
     readonly pending: true;
-    readonly description: "One of the numbers of the account got connected: by scanning the QR code or by finishing the sign-up of a WhatsApp Cloud number.";
+    readonly description: "One of the numbers of the account got connected: by scanning the QR code, by finishing the sign-up of a WhatsApp Cloud number, or through a connect link.";
+}, {
+    readonly type: "device.deleted";
+    readonly domains: readonly ["accounts"];
+    readonly status: "planned";
+    readonly pending: true;
+    readonly description: "A number of the account was deleted: its slot of the plan is free again.";
 }, {
     readonly type: "device.disconnected";
     readonly domains: readonly ["accounts"];
     readonly status: "live";
     readonly pending: true;
-    readonly description: "One of the numbers of the account disconnected and can no longer send or receive.";
+    readonly description: "One of the numbers of the account disconnected and can no longer send or receive: a QR session that closed or was protected from a shadow ban, an official number that failed its re-registration, or one disconnected from the panel.";
+}, {
+    readonly type: "device.health_changed";
+    readonly domains: readonly ["accounts"];
+    readonly status: "planned";
+    readonly pending: true;
+    readonly description: "The health of an official number changed (what Meta lets it do). Emitted only when the overall state changes.";
 }, {
     readonly type: "flow.completed";
     readonly domains: readonly ["conversations"];
@@ -22411,25 +22923,36 @@ interface WebhookEventDataMap {
         leaves: number;
         conversion_rate: number;
     };
-    /** `device.connected` (live, pending of the spec; typed from: schema). One of the numbers of the account got connected: by scanning the QR code or by finishing the sign-up of a WhatsApp Cloud number. */
+    /** `device.connected` (live, pending of the spec; typed from: schema). One of the numbers of the account got connected: by scanning the QR code, by finishing the sign-up of a WhatsApp Cloud number, or through a connect link. */
     "device.connected": {
-        device: {
-            id: number;
-            name: string | null;
-            /** Digits only, without `+`. */
-            number: string | null;
-        };
+        device: components["schemas"]["PendingWebhookDevice"];
         connected_at: string;
+        /** The connect link of this connection, or `null` when it did not come from a link. */
+        connect_link_id?: number | null;
+    };
+    /** `device.deleted` (planned, pending of the spec; typed from: schema). A number of the account was deleted: its slot of the plan is free again. */
+    "device.deleted": {
+        device: components["schemas"]["PendingWebhookDevice"];
+        deleted_at: string;
+        /** The connect link that last connected the number, or `null`. */
+        connect_link_id?: number | null;
     };
-    /** `device.disconnected` (live, pending of the spec; typed from: schema). One of the numbers of the account disconnected and can no longer send or receive. */
+    /** `device.disconnected` (live, pending of the spec; typed from: schema). One of the numbers of the account disconnected and can no longer send or receive: a QR session that closed or was protected from a shadow ban, an official number that failed its re-registration, or one disconnected from the panel. */
     "device.disconnected": {
-        device: {
-            id: number;
-            name: string | null;
-            /** Digits only, without `+`. */
-            number: string | null;
-        };
+        device: components["schemas"]["PendingWebhookDevice"];
         disconnected_at: string;
+        reason?: "qr_logged_out" | "meta_account_not_registered" | "shadow_ban_protection" | "provider_error" | "unknown" | "disconnected_by_user";
+        /** The connect link that last connected the number, or `null`. */
+        connect_link_id?: number | null;
+    };
+    /** `device.health_changed` (planned, pending of the spec; typed from: schema). The health of an official number changed (what Meta lets it do). Emitted only when the overall state changes. */
+    "device.health_changed": {
+        device: components["schemas"]["PendingWebhookDevice"];
+        previous_state: "available" | "limited" | "blocked" | "unknown";
+        state: "available" | "limited" | "blocked" | "unknown";
+        changed_at: string;
+        /** The connect link that last connected the number, or `null`. */
+        connect_link_id?: number | null;
     };
     /** `flow.completed` (live; typed from: example). Un contacto terminó un flujo de automatización. Se envía una sola vez por cada ejecución de un flujo, cuando termina con éxito. No se envía si la ejecución se cortó, se canceló, quedó bloqueada o falló. `contact` es `null` si la ejecución no tiene un contacto asociado. Un flujo muy usado puede generar muchos eventos seguidos. */
     "flow.completed": {
@@ -22868,7 +23391,9 @@ interface PendingEventData {
  * Sources (production, 22-10): platform-gate v0.8.0 as pinned by accounts v1.4.24; api-edge v0.3.0
  * (src/index.ts); conversations v1.18.10 (Message/Services/ApiSendGuard.php,
  * Message/Support/ApiKeySendResponse.php, WhatsappForm/Support/FormSendPreflight.php). The spec
- * does not document most of them yet; when it does, this list can be generated.
+ * does not document most of them yet; when it does, this list can be generated. The codes of
+ * creating and connecting numbers come from contract 1022-alta-de-numeros v0.1 (23-10-2026, with
+ * its amendment from accounts feat/alta-de-numeros-api 52d49b319), not from production yet.
  */
 /** Errors of the API entry and of the key gate, on any route. */
 declare const ACCESS_ERROR_CODES: {
@@ -22931,13 +23456,75 @@ declare const SEND_ERROR_CODES: {
     /** 422: the number cannot send forms. */
     readonly number_not_eligible: 422;
 };
+/**
+ * Rejections of creating a number (`devices.create`), asking for its QR (`devices.qr`) or creating,
+ * reading or revoking a connect link: nothing was created. The quota of the plan is the same as in
+ * the panel. A code that comes with two statuses has the one of the create here; the other is noted.
+ */
+declare const NUMBER_ERROR_CODES: {
+    /** 403: the plan of the account does not include numbers. */
+    readonly numbers_not_included: 403;
+    /** 403: the account already uses every number of its plan (`limit`, `used`, `pending_device_ids` in the body). */
+    readonly number_limit_reached: 403;
+    /** 403: the account cannot connect numbers now. */
+    readonly connect_not_allowed: 403;
+    /** 403: `devices.qr` of a number whose payment is due. */
+    readonly payment_required: 403;
+    /**
+     * 409: the account already has a QR number waiting to be scanned (at most one): its `device_id`
+     * comes in the body. Show that one's QR, or delete it, instead of creating another.
+     */
+    readonly pending_number_exists: 409;
+    /** 422 (409 on `devices.qr`): QR can only be added to an official number that is in coexistence. */
+    readonly qr_requires_coexistence: 422;
+    /** 422: the number already has that connection method; the body brings its `device_id`. */
+    readonly method_already_present: 422;
+    /** 422: `same_number_as` or `device_id` is not a number of the account that can take it. */
+    readonly invalid_reference_device: 422;
+    /** 422: a connect link with `device_id` of a number that connects another way than `type`. */
+    readonly connection_type_mismatch: 422;
+    /** 422 (409 on `devices.qr`): the number is suspended because the plan has fewer numbers than the account uses. */
+    readonly number_suspended_by_plan: 422;
+    /** 422: the body is not valid; `errors` says which fields. */
+    readonly invalid_request: 422;
+    /** 409: `devices.qr` of a trial number that is blocked. */
+    readonly trial_number_blocked: 409;
+    /** 409: `devices.qr` of a number that is turned off. */
+    readonly device_inactive: 409;
+    /** 409: `devices.qr` when no more QR sessions can be started now. */
+    readonly provisioning_quota_exceeded: 409;
+    /** 409: revoking a connect link that is no longer `pending`. */
+    readonly link_not_pending: 409;
+    /** 429: the account has 20 connect links open. Revoke some, or wait for them to end. Not worth retrying. */
+    readonly too_many_open_links: 429;
+    /** 500 (502 on `devices.qr`): the WhatsApp provider failed. */
+    readonly provider_error: 500;
+    /** 503: official numbers (`type: 'meta'`) cannot be connected by link yet. QR links work. Not worth retrying. */
+    readonly meta_connect_disabled: 503;
+    /** 403: the connect page was opened with an API key or a session. The page is for your customer, without credentials. */
+    readonly credentials_not_allowed: 403;
+};
+/** Rejections of a create sent with `idempotencyKey`. */
+declare const IDEMPOTENCY_ERROR_CODES: {
+    /** 422: the key was already used with another body. Use a new key for a new resource. */
+    readonly idempotency_key_mismatch: 422;
+    /** 422: the key is not 1 to 255 characters. */
+    readonly invalid_idempotency_key: 422;
+    /** 409: the first call with that key, or another operation on the number, is still running. Read the state, or repeat it later. */
+    readonly operation_in_progress: 409;
+};
 type AccessErrorCode = keyof typeof ACCESS_ERROR_CODES;
 /** An error code of a send rejected by the WhatsApp rules (`APIError.code`). */
 type SendErrorCode = keyof typeof SEND_ERROR_CODES;
+/** An error code of creating a number or a connect link (`APIError.code`). */
+type NumberErrorCode = keyof typeof NUMBER_ERROR_CODES;
+type IdempotencyErrorCode = keyof typeof IDEMPOTENCY_ERROR_CODES;
 /** Every `error` code the SDK knows. The API can send others: treat `code` as a `string`. */
-type KnownErrorCode = AccessErrorCode | SendErrorCode;
+type KnownErrorCode = AccessErrorCode | SendErrorCode | NumberErrorCode | IdempotencyErrorCode;
 /** Whether an `APIError.code` is a rejection of a send: nothing was sent and nothing was stored. */
 declare function isSendRuleError(code: string | undefined): code is SendErrorCode;
+/** Whether an `APIError.code` is a rejection by the number quota of the plan (the same as the panel's). */
+declare function isNumberQuotaError(code: string | undefined): code is 'numbers_not_included' | 'number_limit_reached' | 'pending_number_exists' | 'qr_requires_coexistence' | 'method_already_present';
 
 /**
  * Errors thrown by the SDK.
@@ -23030,14 +23617,16 @@ declare class UnprocessableEntityError extends APIError {
 }
 /**
  * `429`: rate limit (`rate_limited`, `daily_cap_exceeded`; `retryAfter` says how many seconds to
- * wait) or the monthly active contacts (`mac_lockout_24h`, `mac_limit_reached`), which waiting
- * does not fix.
+ * wait), the monthly active contacts (`mac_lockout_24h`, `mac_limit_reached`) or the open connect
+ * links (`too_many_open_links`), which waiting does not fix.
  */
 declare class RateLimitError extends APIError {
 }
 /**
  * `5xx`. `502 origin_unreachable` and `500 edge_misconfigured` come from the API entry. After a
- * `5xx` on a write, read the state before repeating it: it may have been applied.
+ * `5xx` on a write, read the state before repeating it: it may have been applied (or repeat a create
+ * with the same `idempotencyKey`). `503 meta_connect_disabled`: official numbers cannot be connected
+ * by link yet.
  */
 declare class InternalServerError extends APIError {
 }
@@ -23124,10 +23713,13 @@ type SubscriptionId = PathParams<'/api/v1/webhooks/{id}', 'GET'>['id'];
 /**
  * Webhook subscriptions (accounts area) and the verification of deliveries.
  *
- * Reading needs `webhooks:read` and the rest `webhooks:write`; the catalog (`events()`) needs
- * `accounts:read`. A key only sees and manages subscriptions to events of the areas it can read
- * (`conversations:read`, `communities:read`, `accounts:read`): asking for others is a `422` on
- * `events`, and touching a subscription that has them is `403 permission_denied`.
+ * Reading needs **Notifications (webhooks) → View** (`webhooks:read`) and the rest
+ * **Notifications (webhooks) → Manage** (`webhooks:write`); the catalog (`events()`) needs
+ * **WhatsApp numbers → View** (`accounts:read`). A key only sees and manages subscriptions to
+ * events of the areas it can read: **Contacts and conversations → View** (`conversations:read`),
+ * **Groups and campaigns → View** (`communities:read`) and **WhatsApp numbers → View**
+ * (`accounts:read`). Asking for others is a `422` on `events`, and touching a subscription that
+ * has them is `403 permission_denied`.
  */
 declare class Webhooks extends Resource {
     /** Same as `Funnelchat.webhooks.verify`. */
@@ -23325,7 +23917,7 @@ declare class Funnelchat {
         readonly verify: typeof verify;
         readonly constructEvent: typeof constructEvent;
     };
-    static readonly VERSION = "0.1.2";
+    static readonly VERSION = "0.2.1";
     readonly baseUrl: string;
     readonly timeoutMs: number;
     readonly maxRetries: number;
@@ -23339,6 +23931,8 @@ declare class Funnelchat {
     readonly customFields: CustomFields;
     readonly groups: Groups;
     readonly devices: Devices;
+    /** Single-use pages where your customer connects a WhatsApp number to your account. */
+    readonly connectLinks: ConnectLinks;
     /** Webhook subscriptions, plus `verify` and `constructEvent`. */
     readonly webhooks: Webhooks;
     constructor(options?: ClientOptions);
@@ -23384,10 +23978,10 @@ interface RouteInfo {
     readonly summary: string | null;
     readonly pending: boolean;
 }
-/** Every operation of the spec (258), sorted by path. */
+/** Every operation of the spec (264), sorted by path. */
 declare const routes: readonly RouteInfo[];
 
 /** The SDK version, sent in the `User-Agent`. A test keeps it equal to package.json. */
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.2.1";
 
-export { ACCESS_ERROR_CODES, APIConnectionError, APIConnectionTimeoutError, APIError, APIPromise, type APIResponse, APIUserAbortError, type AccessErrorCode, type ApiPath, AuthenticationError, BASE_URLS, BadRequestError, type Body, type ClientOptions, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_TOLERANCE_SECONDS, type Environment, type FieldErrors, Funnelchat, FunnelchatError, type HttpMethod, InternalServerError, type KnownErrorCode, type ListItem, NotFoundError, Page, PagePromise, type PathParams, PermissionDeniedError, type Query, type QueryParams, REQUEST_ID_HEADER, RateLimitError, type RawBody, type RequestBody, type RequestOptions, type ResponseBody, type RouteInfo, SEND_ERROR_CODES, SIGNATURE_HEADER, type SendErrorCode, type SendMessageParams, type TypedRequestOptions, UnprocessableEntityError, UnsupportedMediaTypeError, type UntypedRequestOptions, VERSION, type VerifyOptions, type WebhookEvent, type WebhookEventData, type WebhookEventEnvelope, type WebhookEventInfo, type WebhookEventOf, type WebhookEventType, type webhooks as WebhookSchemas, WebhookVerificationError, type WebhookVerificationFailure, type components, constructEvent, Funnelchat as default, isSendRuleError, type operations, type paths, routes, verify, webhookEvents };
+export { ACCESS_ERROR_CODES, APIConnectionError, APIConnectionTimeoutError, APIError, APIPromise, type APIResponse, APIUserAbortError, type AccessErrorCode, type ApiPath, AuthenticationError, BASE_URLS, BadRequestError, type Body, type ClientOptions, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_TOLERANCE_SECONDS, type Environment, type FieldErrors, Funnelchat, FunnelchatError, type HttpMethod, IDEMPOTENCY_ERROR_CODES, type IdempotencyErrorCode, type IdempotentRequestOptions, InternalServerError, type KnownErrorCode, type ListItem, NUMBER_ERROR_CODES, NotFoundError, type NumberErrorCode, Page, PagePromise, type PathParams, PermissionDeniedError, type Query, type QueryParams, REQUEST_ID_HEADER, RateLimitError, type RawBody, type RequestBody, type RequestOptions, type ResponseBody, type RouteInfo, SEND_ERROR_CODES, SIGNATURE_HEADER, type SendErrorCode, type SendMessageParams, type TypedRequestOptions, UnprocessableEntityError, UnsupportedMediaTypeError, type UntypedRequestOptions, VERSION, type VerifyOptions, type WebhookEvent, type WebhookEventData, type WebhookEventEnvelope, type WebhookEventInfo, type WebhookEventOf, type WebhookEventType, type webhooks as WebhookSchemas, WebhookVerificationError, type WebhookVerificationFailure, type components, constructEvent, Funnelchat as default, isNumberQuotaError, isSendRuleError, type operations, type paths, routes, verify, webhookEvents };