@funnelchat-hq/sdk 0.1.2 → 0.2.1

package/README.md

@@ -16,7 +16,7 @@ npm install @funnelchat-hq/sdk
 
 ## First call
 
-You need an API key (`<id>|fc_live_...`) created in the "Developers" section of the panel, with the permissions of what you are going to use. Keep it in an environment variable: the client reads `FUNNELCHAT_API_KEY` when you do not pass it.
+You need an API key (`<id>|fc_live_...`) created in the "Developers" section of the panel, with the permissions of what you are going to use. The panel groups them by area, with one checkbox per level: this README names each one as the panel shows it, with its literal in parentheses, such as **WhatsApp numbers → View** (`accounts:read`). The literal is what the panel shows as a tooltip and what the API names in its errors. In the panel, **Send** includes **View** and **Edit**, and **Edit** includes **View**. Keep it in an environment variable: the client reads `FUNNELCHAT_API_KEY` when you do not pass it.
 
 ```ts
 import { Funnelchat } from '@funnelchat-hq/sdk';
@@ -24,7 +24,7 @@ import { Funnelchat } from '@funnelchat-hq/sdk';
 
 const funnelchat = new Funnelchat({ apiKey: process.env.FUNNELCHAT_API_KEY });
 
-// Your WhatsApp numbers (permission accounts:read). The `id` of each one is the `device_id` you send with.
+// Your WhatsApp numbers. Permission: WhatsApp numbers → View (accounts:read). The `id` of each one is the `device_id` you send with.
 for await (const device of funnelchat.devices.list()) {
   console.log(device.id, device.number, device.capabilities.messages.templates);
 }
@@ -56,14 +56,15 @@ Every request sends `Authorization: Bearer <key>`, `Accept: application/json` an
 | `funnelchat.tags` | `list`, `create`, `retrieve`, `update`, `delete`, `listContacts`. |
 | `funnelchat.customFields` | `list`, `create`, `retrieve`, `update`, `delete`. |
 | `funnelchat.groups` | Read groups, participants, events and messages. |
-| `funnelchat.devices` | `list`, `retrieve` (with `capabilities`), `update`, `status`, `health`, `me`, `checkPhone`, connection history. |
+| `funnelchat.devices` | `list` (filter by `external_reference`), `create` (a QR number), `qr`, `retrieve` (with `capabilities`), `update`, `delete`, `status`, `health`, `me`, `checkPhone`, connection history. |
+| `funnelchat.connectLinks` | `create`, `get`, `list`, `revoke`: a page where your customer connects a number. See [Connect a number](#connect-a-number). |
 | `funnelchat.webhooks` | Subscriptions (`list`, `create`, `retrieve`, `update`, `delete`, `test`, `listDeliveries`), the catalog (`events`), `verify` and `constructEvent`. |
 
 Parameters, bodies and responses are typed from the spec. For any other route, see [Any route](#any-route).
 
 ## Send a message
 
-Sending with a key needs the `conversations:send` permission and follows the WhatsApp rules. **Every send answers right away with the registered message, `status: 'queued'`:** accepted is not delivered. What happens next arrives by the `message.status_changed` webhook, or is read with `messages.get`.
+Sending with a key needs **Contacts and conversations → Send** (`conversations:send`) and follows the WhatsApp rules. **Every send answers right away with the registered message, `status: 'queued'`:** accepted is not delivered. What happens next arrives by the `message.status_changed` webhook, or is read with `messages.get`.
 
 **Open window: free text.** With an official Meta number you can only send free text if the contact wrote to you in the last 24 hours. Check the window first:
 
@@ -132,7 +133,7 @@ const { message } = await funnelchat.templates.send(3, '45', {
 A WhatsApp form is built, published on one or more numbers and sent to a contact. There are two ids: `id` is one version; `family_id` is the form itself, the one you send it with and the one that comes back as `form.id` in `whatsapp_form.completed`.
 
 ```ts
-const { data: draft } = await funnelchat.forms.create({ device_id: 3, template_key: 'lead' }); // permission conversations:write
+const { data: draft } = await funnelchat.forms.create({ device_id: 3, template_key: 'lead' }); // Contacts and conversations → Edit (conversations:write)
 await funnelchat.forms.publish(draft.id);
 
 const { message } = await funnelchat.messages.sendForm(2001, {
@@ -145,6 +146,105 @@ const { message } = await funnelchat.messages.sendForm(2001, {
 
 The answers arrive by the `whatsapp_form.completed` webhook (`answers`: `key`, `label` and `value`) and are read with `forms.listResponses(familyId)`. `forms.templates()` lists the templates to start from; `forms.update(id, { definition, expected_updated_at })` saves a draft and answers `409 STALE` when someone saved it first.
 
+## Connect a number
+
+> **In production, except the official sign-up by link.** Creating QR numbers and connect links by QR work in production. Connect links with `type: 'meta'` are not available in production yet: they answer `503 meta_connect_disabled` until the Funnelchat domain is registered with Meta. The published spec does not describe these routes yet; see [Pending of the spec](#pending-of-the-spec).
+
+A number belongs to the account of the key and takes a slot of its plan, as in the panel. Creating numbers, showing their QR code and creating or revoking connect links needs **WhatsApp numbers → Create, connect and delete** (`accounts:operate`); reading links, **WhatsApp numbers → View** (`accounts:read`). Tag each number with your own `external_reference` (for example the id of your customer): it comes back in the number, in the links and in every `device.*` webhook.
+
+**A connect link** is a single-use page on the Funnelchat domain. Send your customer there: the number is created when they finish.
+
+```ts
+const { data: link } = await funnelchat.connectLinks.create(
+  {
+    type: 'qr',                                     // a number by QR code; or 'meta' (not in production yet)
+    country: 'br',                                  // the country of the phone that will scan the QR
+    external_reference: 'customer-81',
+    return_url: 'https://your-app.example/whatsapp/done',   // optional, https only
+    expires_in_minutes: 1440,                       // 30 to 10080; 24 hours by default
+  },
+  { idempotencyKey: 'connect-customer-81' },
+);
+console.log(link.url); // https://api.funnelchat.com/connect/… — it carries the token and is shown only now
+```
+
+- `country` (only `qr`, two letters, optional) is the country of the phone that will scan the QR: the WhatsApp session is opened from there, so send it when you know it. It does not go with `device_id` (a reconnection creates nothing), and the link returns it, lowercase.
+- `type: 'meta'` (an official WhatsApp Cloud number, **not in production yet**: `503 meta_connect_disabled`) takes `allowed_connection_types: ['coexistence', 'dedicated']`, one or both; with both, your customer chooses on the page.
+- `provision_us_number: true` (only `meta`) also offers a US number of the pool. A pool number is always dedicated: it needs `dedicated` in `allowed_connection_types` and does not go with `device_id`; otherwise the API answers `422 invalid_request` (the SDK does not check it for you).
+- `device_id` reconnects a number you already have, without taking a new slot; `same_number_as` (only `qr`) adds QR to a number in coexistence.
+- A Meta link tolerates retries: after a failure of Facebook or Meta it stays `pending`, so your customer can try again on the page; the fifth failed attempt turns it `failed` with `facebook_auth_failed` or `meta_error`. `quota_exceeded`, `trial_number_blocked` and `number_not_owned` close it at the first attempt.
+- You learn the result three ways: the `device.connected` webhook (with `connect_link_id` and `external_reference`), the `return_url` (`?connect_link_id=…&status=completed|failed&device_id=…&error_code=…`), or reading the link:
+
+```ts
+const { data } = await funnelchat.connectLinks.get(link.id);
+console.log(data.status, data.device_id, data.error_code); // 'completed', 9, null
+
+for await (const open of funnelchat.connectLinks.list({ status: 'pending', external_reference: 'customer-81' })) {
+  await funnelchat.connectLinks.revoke(open.id); // only a pending link; any other answers 409
+}
+```
+
+**A QR number, without a page.** Create it and show its QR yourself:
+
+```ts
+const { data: device } = await funnelchat.devices.create(
+  { connection: 'qr', alias: 'Sales', country: 'br', external_reference: 'customer-81' },
+  { idempotencyKey: 'qr-customer-81' },
+);
+
+const { data: qr } = await funnelchat.devices.qr(device.id);
+// qr.qr_code is a PNG data URI (null once connected); ask again after qr.expires_in seconds
+// (5 with a QR, 3 while the session starts, 0 once connected).
+
+for await (const number of funnelchat.devices.list({ external_reference: 'customer-81' })) {
+  console.log(number.id, number.connection, number.connected);
+}
+```
+
+- **Ask for the QR every 5 seconds and have it scanned right away.** WhatsApp changes the code every few seconds and an old one no longer links ("can't link the device now"): replace the image with the latest one on each call, and never store, cache or forward a QR.
+- `country` (two letters, optional) is the country of the phone that will scan the QR: the WhatsApp session is opened from there.
+- An account has at most one QR number waiting to be scanned: creating another answers `409 pending_number_exists`, with that number's `device_id` in `error.body`. Show its QR instead, or delete it.
+- `external_reference` changes with `devices.update(id, { external_reference })`.
+- `devices.delete(id)` deletes a number and frees its slot. It needs **WhatsApp numbers → Create, connect and delete** (`accounts:operate`) and is irreversible. An official number stops working through Funnelchat but stays registered with Meta; a QR one logs out. It sends `device.deleted`.
+- `devices.list(query, options)` takes the query first, like every list. The signature of 0.1.2, `devices.list(options)`, still works.
+
+**`idempotencyKey`** (both creates, 1 to 255 characters) is sent as `Idempotency-Key` and kept 24 hours. The same key with the same body answers the same response without creating another number or link, so after a timeout or a `5xx` you can repeat the call with it. Only a success is replayed, with the `Idempotent-Replayed: true` header (see it with `.withResponse()`); a rejection is evaluated again. On their own, creates follow the rule of writes (see [Retries](#retries)): they are retried only on a `429` or `503`, which guarantee nothing was created.
+
+**The webhooks of numbers:**
+
+| Event | `data` |
+|---|---|
+| `device.connected` | `device`, `connected_at`, `connect_link_id`. |
+| `device.disconnected` | `device`, `disconnected_at`, `connect_link_id`, `reason`: `qr_logged_out`, `meta_account_not_registered`, `shadow_ban_protection`, `provider_error`, `disconnected_by_user` or `unknown`. |
+| `device.deleted` | `device`, `deleted_at`, `connect_link_id`. |
+| `device.health_changed` | `device`, `previous_state`, `state` (`available`, `limited`, `blocked`, `unknown`), `changed_at`, `connect_link_id`. Official numbers, only when the state changes. |
+
+- `device` is `{ id, name, number, connection, external_reference }`, where `connection` is `qr`, `coexistence`, `dedicated` or `null`.
+- `connect_link_id`: in `device.connected`, the connect link of that connection; in the other three, the link that last connected the number. `null` when it did not come from a link.
+- What these events add to the ones production sends today (`connection`, `external_reference`, `connect_link_id` and `reason`) is optional in the types: it is missing until the API that serves it is deployed. Handle `undefined`.
+
+**When it is refused** (`NUMBER_ERROR_CODES` and `IDEMPOTENCY_ERROR_CODES`):
+
+| Error | What happened |
+|---|---|
+| `403 numbers_not_included` | The plan does not include numbers. |
+| `403 number_limit_reached` | Every number of the plan is in use (`limit`, `used`, `pending_device_ids` in the body). |
+| `409 pending_number_exists` | A QR number is already waiting to be scanned; the body brings its `device_id`. |
+| `422 qr_requires_coexistence` | QR can only be added to an official number in coexistence. |
+| `422 method_already_present` | The number already has that method; the body brings its `device_id`. |
+| `422 invalid_reference_device` | `same_number_as` or `device_id` is not a number of yours that can take it. |
+| `422 connection_type_mismatch` | A link with `device_id` of a number that connects another way than `type`. |
+| `429 too_many_open_links` | 20 connect links are open. Revoke some. |
+| `503 meta_connect_disabled` | Official numbers cannot be connected by link yet, as in production today. QR links work. |
+| `409 link_not_pending` | Revoking a link that already ended. |
+| `422 idempotency_key_mismatch` | The key was used with another body. |
+| `422 invalid_idempotency_key` | The key is not 1 to 255 characters. |
+| `409 operation_in_progress` | The first call with that key is still running. |
+| `422 provider_unsupported` | `devices.qr` on an official number. |
+| `409` on `devices.qr` | The number cannot connect now: `trial_number_blocked`, `number_suspended_by_plan`, `device_inactive`, `provisioning_quota_exceeded`. |
+
+`NUMBER_ERROR_CODES` lists the rest (`connect_not_allowed`, `payment_required`, `provider_error`…), with their status. `isNumberQuotaError(error.code)` tells you whether it was the quota of the plan (the first five). `too_many_open_links` and `meta_connect_disabled` are never retried automatically.
+
 ## Receive webhooks with Express
 
 Verify the signature over the **raw body**, exactly as it arrived. If you parse it and serialize it again, the signature changes: use `express.raw`, not `express.json`.
@@ -206,7 +306,7 @@ const subscription = await funnelchat.webhooks.create({
 // Store subscription.id and subscription.secret: the secret is shown only once.
 ```
 
-- Permissions: `webhooks:read` to read and `webhooks:write` for the rest. Also, a key can only subscribe to events of the areas it can read (`conversations:read`, `communities:read`, `accounts:read`): asking for others is a `422` on `events`.
+- Permissions: **Notifications (webhooks) → View** (`webhooks:read`) to read and **Notifications (webhooks) → Manage** (`webhooks:write`) for the rest. Also, a key can only subscribe 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`.
 - Subscriptions belong to the account: `list()` also brings the ones of other integrations. To change the URL use `update(id, …)` (the secret stays). `test(id)` sends a signed `webhook.test` right now and `listDeliveries(id)` is the history.
 - `rotateSecret(id)` is **not open to API keys** (`403 route_not_available`): rotate the secret from the panel.
 
@@ -267,7 +367,7 @@ The errors of the API entry and of access control apply to any route (`ACCESS_ER
 | Error | What happened |
 |---|---|
 | `401 unauthenticated` | The key is missing or not valid. |
-| `403 permission_denied` | The key lacks the permission of the route. |
+| `403 permission_denied` | The key lacks the permission of the route. `message` names it by its literal (such as `accounts:operate`), which the panel shows as the tooltip of each checkbox. |
 | `403 route_not_available` | The route is not open to API keys (or it is turned off). |
 | `404 route_not_found` | The route does not exist in the public API. |
 | `429 daily_cap_exceeded` | The daily call cap of the key was reached. It carries `Retry-After`. |
@@ -285,7 +385,7 @@ const { data, requestId, response } = await funnelchat.contacts.retrieve(2001).w
 
 - Reads and writes that give the same result when repeated (`GET`, `PUT`, `DELETE`) are retried on a `429`, a `5xx` or a network error (also when `timeoutMs` ran out), up to `maxRetries` times (2 by default).
 - Other writes (`POST`, `PATCH`) are retried **only when the API guarantees they were not applied**: `429` and `503`. A `500`, `502` or `504`, a timeout or a dropped connection can come after the write was applied, so the error is thrown right away: read the state before repeating it.
-- **A send is never retried automatically**: the `POST`s with the `conversations:send` permission (messages, forms, cards, forwards, templates). If a `429 rate_limited` sent nothing and you want the SDK to retry for you, ask for it in that call with `{ retrySend: true }`: it then follows the rule of writes. `mac_lockout_24h` and `mac_limit_reached` are never retried.
+- **A send is never retried automatically**: the `POST`s that need **Contacts and conversations → Send** (`conversations:send`): messages, forms, cards, forwards and templates. If a `429 rate_limited` sent nothing and you want the SDK to retry for you, ask for it in that call with `{ retrySend: true }`: it then follows the rule of writes. `mac_lockout_24h` and `mac_limit_reached` are never retried.
 - With `Retry-After`, the wait is exactly what it asks for. If it asks for more than 60 seconds, there is no wait: the error is thrown right away with its `retryAfter` and you decide. Without `Retry-After`, the wait is exponential: 0.5 s, 1 s, 2 s… up to 8 s, with some jitter.
 - Per call you can change `maxRetries`, `timeoutMs` and `signal`:
 
@@ -330,7 +430,8 @@ The published spec does not describe everything the API in production already ha
 - what sends answer (the queued message), `messages.get`, `client_reference`, `file_type` and `file_name`;
 - forms and `messages.sendForm`;
 - the `capabilities` of numbers;
-- webhook subscriptions and the events the spec does not bring (`message.status_changed` with its shape, `whatsapp_form.completed`, the group ones and the account ones).
+- webhook subscriptions and the events the spec does not bring (`message.status_changed` with its shape, `whatsapp_form.completed`, the group ones and the account ones);
+- creating and connecting numbers (`devices.create`, `devices.qr`, `country`, `external_reference`, `connectLinks`, `Idempotency-Key`) and the `device.*` events: in production (except `type: 'meta'` links), typed from the API of accounts until its spec is published.
 
 `src/pending/` has what is not OpenAPI (`device_id` in `message.received`) and `src/core/error-codes.ts` the error codes.
 
@@ -348,7 +449,7 @@ FUNNELCHAT_SANDBOX_URL=http://127.0.0.1:4010 npm run test:e2e   # against a runn
 
 The SDK runs on Node 18 or later; the development tools (vitest 4, eslint 9) need Node 20 or later.
 
-To release, push a `vX.Y.Z` tag on `main` matching the `version` in `package.json`; GitHub Actions (`.github/workflows/publish.yml`) publishes it to npm with provenance.
+To release, push a `vX.Y.Z` tag on `main` matching the `version` in `package.json`; GitHub Actions publishes it through npm Trusted Publishing (`.github/workflows/publish.yml`), with provenance.
 
 Everything generated comes from one script:
 
@@ -358,7 +459,7 @@ npm run generate                                    # with the one in spec/, for
 ```
 
 1. With `--spec`, it copies the spec to `spec/funnelchat.json` and writes `spec/procedencia.json`: repository, branch, commit, date and `sha256` of the file.
-2. It adds `spec/pending.json`, but only what the spec does not bring, and lists what it already brings so you can delete it from there.
+2. It adds `spec/pending.json`, but only what the spec does not bring, and lists what it already brings so you can delete it from there. An `operationPatches` entry without `while` adds body properties or `parameters` (such as a query filter) one by one, only while the operation lacks them.
 3. It writes `src/generated/openapi.ts` (with [openapi-typescript](https://openapi-ts.dev)), `src/generated/routes.ts` (every operation, with area and permission) and `src/generated/events.ts` (the event catalog and the shape of the `data` of each one).
 
 ```

package/dist/index.cjs

@@ -319,11 +319,72 @@ var SEND_ERROR_CODES = {
   /** 422: the number cannot send forms. */
   number_not_eligible: 422
 };
+var NUMBER_ERROR_CODES = {
+  /** 403: the plan of the account does not include numbers. */
+  numbers_not_included: 403,
+  /** 403: the account already uses every number of its plan (`limit`, `used`, `pending_device_ids` in the body). */
+  number_limit_reached: 403,
+  /** 403: the account cannot connect numbers now. */
+  connect_not_allowed: 403,
+  /** 403: `devices.qr` of a number whose payment is due. */
+  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.
+   */
+  pending_number_exists: 409,
+  /** 422 (409 on `devices.qr`): QR can only be added to an official number that is in coexistence. */
+  qr_requires_coexistence: 422,
+  /** 422: the number already has that connection method; the body brings its `device_id`. */
+  method_already_present: 422,
+  /** 422: `same_number_as` or `device_id` is not a number of the account that can take it. */
+  invalid_reference_device: 422,
+  /** 422: a connect link with `device_id` of a number that connects another way than `type`. */
+  connection_type_mismatch: 422,
+  /** 422 (409 on `devices.qr`): the number is suspended because the plan has fewer numbers than the account uses. */
+  number_suspended_by_plan: 422,
+  /** 422: the body is not valid; `errors` says which fields. */
+  invalid_request: 422,
+  /** 409: `devices.qr` of a trial number that is blocked. */
+  trial_number_blocked: 409,
+  /** 409: `devices.qr` of a number that is turned off. */
+  device_inactive: 409,
+  /** 409: `devices.qr` when no more QR sessions can be started now. */
+  provisioning_quota_exceeded: 409,
+  /** 409: revoking a connect link that is no longer `pending`. */
+  link_not_pending: 409,
+  /** 429: the account has 20 connect links open. Revoke some, or wait for them to end. Not worth retrying. */
+  too_many_open_links: 429,
+  /** 500 (502 on `devices.qr`): the WhatsApp provider failed. */
+  provider_error: 500,
+  /** 503: official numbers (`type: 'meta'`) cannot be connected by link yet. QR links work. Not worth retrying. */
+  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. */
+  credentials_not_allowed: 403
+};
+var IDEMPOTENCY_ERROR_CODES = {
+  /** 422: the key was already used with another body. Use a new key for a new resource. */
+  idempotency_key_mismatch: 422,
+  /** 422: the key is not 1 to 255 characters. */
+  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. */
+  operation_in_progress: 409
+};
 var has = (table, code) => code !== void 0 && Object.prototype.hasOwnProperty.call(table, code);
 function isSendRuleError(code) {
   return has(SEND_ERROR_CODES, code);
 }
-var NOT_RETRYABLE_CODES = /* @__PURE__ */ new Set(["mac_lockout_24h", "mac_limit_reached"]);
+var QUOTA_CODES = /* @__PURE__ */ new Set([
+  "numbers_not_included",
+  "number_limit_reached",
+  "pending_number_exists",
+  "qr_requires_coexistence",
+  "method_already_present"
+]);
+function isNumberQuotaError(code) {
+  return code !== void 0 && QUOTA_CODES.has(code);
+}
+var NOT_RETRYABLE_CODES = /* @__PURE__ */ new Set(["mac_lockout_24h", "mac_limit_reached", "too_many_open_links", "meta_connect_disabled"]);
 
 // src/generated/routes.ts
 var routes = [
@@ -376,6 +437,10 @@ var routes = [
   { "method": "GET", "path": "/api/v1/campaigns/{campaign}/pipelines/{pipeline}", "operationId": "campaign.showPipeline", "domain": "communities", "permission": "communities:read", "tag": "Grupos de una campa\xF1a y operaciones", "summary": "Ver un pipeline", "pending": false },
   { "method": "GET", "path": "/api/v1/campaigns/{campaign}/webhooks", "operationId": "campaignWebhook.index", "domain": "communities", "permission": "communities:read", "tag": "Webhooks de campa\xF1a (legado)", "summary": "Listar los webhooks de una campa\xF1a", "pending": false },
   { "method": "GET", "path": "/api/v1/campaigns/{campaign}/webhooks/logs", "operationId": "campaignWebhook.logs", "domain": "communities", "permission": "communities:read", "tag": "Webhooks de campa\xF1a (legado)", "summary": "Listar las entregas de los webhooks de una campa\xF1a", "pending": false },
+  { "method": "GET", "path": "/api/v1/connect-links", "operationId": "pendingConnectLink.index", "domain": "accounts", "permission": "accounts:read", "tag": "ConnectLink", "summary": "List connect links", "pending": true },
+  { "method": "POST", "path": "/api/v1/connect-links", "operationId": "pendingConnectLink.store", "domain": "accounts", "permission": "accounts:operate", "tag": "ConnectLink", "summary": "Create a connect link", "pending": true },
+  { "method": "DELETE", "path": "/api/v1/connect-links/{link}", "operationId": "pendingConnectLink.destroy", "domain": "accounts", "permission": "accounts:operate", "tag": "ConnectLink", "summary": "Revoke a connect link", "pending": true },
+  { "method": "GET", "path": "/api/v1/connect-links/{link}", "operationId": "pendingConnectLink.show", "domain": "accounts", "permission": "accounts:read", "tag": "ConnectLink", "summary": "Read a connect link", "pending": true },
   { "method": "PUT", "path": "/api/v1/contact-flows/{contactFlowId}/cancel", "operationId": "flow.cancelContactFlow", "domain": "conversations", "permission": "conversations:write", "tag": "Flow", "summary": "Cancelar un flujo en curso", "pending": false },
   { "method": "GET", "path": "/api/v1/contact-flows/{contactId}", "operationId": "flow.contactFlowHistory", "domain": "conversations", "permission": "conversations:read", "tag": "Flow", "summary": "Listar los flujos en curso de un contacto", "pending": false },
   { "method": "GET", "path": "/api/v1/contacts", "operationId": "contact.index", "domain": "conversations", "permission": "conversations:read", "tag": "Contact", "summary": "Listar contactos", "pending": false },
@@ -425,10 +490,11 @@ var routes = [
   { "method": "GET", "path": "/api/v1/custom-fields/{customField}", "operationId": "customField.show", "domain": "conversations", "permission": "conversations:read", "tag": "CustomField", "summary": "Ver un campo personalizado", "pending": false },
   { "method": "PUT", "path": "/api/v1/custom-fields/{customField}", "operationId": "customField.update", "domain": "conversations", "permission": "conversations:write", "tag": "CustomField", "summary": "Actualizar un campo personalizado", "pending": false },
   { "method": "POST", "path": "/api/v1/custom-fields/delete", "operationId": "customField.destroy", "domain": "conversations", "permission": "conversations:write", "tag": "CustomField", "summary": "Eliminar campos personalizados", "pending": false },
-  { "method": "GET", "path": "/api/v1/devices", "operationId": "device.index", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Listar n\xFAmeros", "pending": false },
+  { "method": "GET", "path": "/api/v1/devices", "operationId": "device.index", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Listar n\xFAmeros", "pending": true },
+  { "method": "POST", "path": "/api/v1/devices", "operationId": "pendingDevice.store", "domain": "accounts", "permission": "accounts:operate", "tag": "Device", "summary": "Create a number connected by QR code", "pending": true },
   { "method": "DELETE", "path": "/api/v1/devices/{device}", "operationId": "device.destroy", "domain": "accounts", "permission": "accounts:operate", "tag": "Device", "summary": "Eliminar un n\xFAmero", "pending": false },
   { "method": "GET", "path": "/api/v1/devices/{device}", "operationId": "device.show", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Ver un n\xFAmero", "pending": false },
-  { "method": "PUT", "path": "/api/v1/devices/{device}", "operationId": "device.update", "domain": "accounts", "permission": "accounts:write", "tag": "Device", "summary": "Actualizar un n\xFAmero", "pending": false },
+  { "method": "PUT", "path": "/api/v1/devices/{device}", "operationId": "device.update", "domain": "accounts", "permission": "accounts:write", "tag": "Device", "summary": "Actualizar un n\xFAmero", "pending": true },
   { "method": "GET", "path": "/api/v1/devices/{device}/ad-groups", "operationId": "group.adGroups", "domain": "communities", "permission": "communities:read", "tag": "Grupos", "summary": "Listar los grupos de anuncios de un n\xFAmero", "pending": false },
   { "method": "POST", "path": "/api/v1/devices/{device}/capi/dataset", "operationId": "capiConnection.dataset", "domain": "accounts", "permission": "accounts:write", "tag": "CapiConnection", "summary": "Configurar el dataset de Conversions API", "pending": false },
   { "method": "GET", "path": "/api/v1/devices/{device}/capi/test", "operationId": "capiConnection.test", "domain": "accounts", "permission": "accounts:read", "tag": "CapiConnection", "summary": "Probar la conexi\xF3n con Conversions API", "pending": false },
@@ -452,6 +518,7 @@ var routes = [
   { "method": "DELETE", "path": "/api/v1/devices/{device}/message-queue/all", "operationId": "device.clearQueue", "domain": "accounts", "permission": "accounts:operate", "tag": "Device", "summary": "Vaciar la cola de mensajes", "pending": false },
   { "method": "GET", "path": "/api/v1/devices/{device}/message-queue/count", "operationId": "device.getQueueCount", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Contar los mensajes en la cola", "pending": false },
   { "method": "GET", "path": "/api/v1/devices/{device}/open-conversations", "operationId": "device.openConversations", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Ver qu\xE9 tel\xE9fonos tienen conversaci\xF3n abierta", "pending": false },
+  { "method": "GET", "path": "/api/v1/devices/{device}/qr", "operationId": "pendingDevice.qr", "domain": "accounts", "permission": "accounts:operate", "tag": "Device", "summary": "The QR code to connect a number", "pending": true },
   { "method": "PUT", "path": "/api/v1/devices/{device}/reset", "operationId": "device.reset", "domain": "accounts", "permission": "accounts:operate", "tag": "Device", "summary": "Reiniciar la sesi\xF3n de un n\xFAmero", "pending": false },
   { "method": "GET", "path": "/api/v1/devices/{device}/status", "operationId": "device.status", "domain": "accounts", "permission": "accounts:read", "tag": "Device", "summary": "Ver el estado de conexi\xF3n", "pending": false },
   { "method": "DELETE", "path": "/api/v1/devices/{device}/templates/{template}", "operationId": "messageTemplate.delete", "domain": "conversations", "permission": "conversations:write", "tag": "MessageTemplate", "summary": "Eliminar una plantilla de un n\xFAmero", "pending": false },
@@ -676,6 +743,42 @@ var Resource = class {
   get client() {
     return this.#client;
   }
+  /** The options of a request with `idempotencyKey` turned into the `Idempotency-Key` header. */
+  idempotent({ idempotencyKey, ...options } = {}) {
+    if (idempotencyKey === void 0) return options;
+    return { ...options, headers: { ...options.headers, "Idempotency-Key": idempotencyKey } };
+  }
+};
+
+// src/resources/connect-links.ts
+var ConnectLinks = class 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, options) {
+    return this.client.request("POST", "/api/v1/connect-links", { ...this.idempotent(options), body });
+  }
+  /** `GET /api/v1/connect-links/{link}`: its `status`, and `device_id` and `error_code` once it ends. */
+  get(link, options) {
+    return this.client.request("GET", "/api/v1/connect-links/{link}", { ...options, path: { link } });
+  }
+  /** `GET /api/v1/connect-links`, paginated, newest first: filter by `status` or `external_reference`. */
+  list(query, options) {
+    return this.client.paginate("/api/v1/connect-links", { ...options, query });
+  }
+  /** `DELETE /api/v1/connect-links/{link}`: revokes a `pending` link (any other is `409 link_not_pending`). */
+  revoke(link, options) {
+    return this.client.request("DELETE", "/api/v1/connect-links/{link}", { ...options, path: { link } });
+  }
 };
 
 // src/resources/contacts.ts
@@ -806,10 +909,31 @@ var CustomFields = class extends Resource {
 };
 
 // src/resources/devices.ts
+var REQUEST_OPTION_KEYS = /* @__PURE__ */ new Set(["headers", "timeoutMs", "maxRetries", "retrySend", "signal"]);
+function isRequestOptions(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => REQUEST_OPTION_KEYS.has(key));
+}
 var Devices = class extends Resource {
-  /** `GET /api/v1/devices`. Iterate it with `for await`, or `await` it for the first page. */
-  list(options) {
-    return this.client.paginate("/api/v1/devices", { ...options });
+  list(queryOrOptions, options) {
+    if (options === void 0 && isRequestOptions(queryOrOptions)) return this.client.paginate("/api/v1/devices", { ...queryOrOptions });
+    return this.client.paginate("/api/v1/devices", { ...options, query: queryOrOptions });
+  }
+  /**
+   * `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, options) {
+    return this.client.request("POST", "/api/v1/devices", { ...this.idempotent(options), body });
   }
   /**
    * `GET /api/v1/devices/{device}`. `capabilities` says what the number can do by API: message
@@ -818,10 +942,32 @@ var Devices = class extends Resource {
   retrieve(device, options) {
     return this.client.request("GET", "/api/v1/devices/{device}", { ...options, path: { device } });
   }
-  /** `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, options) {
+    return this.client.request("DELETE", "/api/v1/devices/{device}", { ...options, path: { device } });
+  }
+  /** `PUT /api/v1/devices/{device}`: also changes `external_reference`. */
   update(device, body, options) {
     return this.client.request("PUT", "/api/v1/devices/{device}", { ...options, path: { device }, body });
   }
+  /**
+   * `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, options) {
+    return this.client.request("GET", "/api/v1/devices/{device}/qr", { ...options, path: { device } });
+  }
   /** `GET /api/v1/devices/{device}/status`: connection status. */
   status(device, options) {
     return this.client.request("GET", "/api/v1/devices/{device}/status", { ...options, path: { device } });
@@ -1241,7 +1387,7 @@ var Webhooks = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.2";
+var VERSION = "0.2.1";
 
 // src/client.ts
 var BASE_URLS = {
@@ -1268,6 +1414,8 @@ var Funnelchat = class {
   customFields;
   groups;
   devices;
+  /** Single-use pages where your customer connects a WhatsApp number to your account. */
+  connectLinks;
   /** Webhook subscriptions, plus `verify` and `constructEvent`. */
   webhooks;
   // Private fields: the key never shows up in `console.log(client)` or in JSON.
@@ -1302,6 +1450,7 @@ var Funnelchat = class {
     this.customFields = new CustomFields(this);
     this.groups = new Groups(this);
     this.devices = new Devices(this);
+    this.connectLinks = new ConnectLinks(this);
     this.webhooks = new Webhooks(this);
   }
   /** What `JSON.stringify(client)` shows: the configuration, never the key. */
@@ -1453,8 +1602,10 @@ var webhookEvents = [
   { "type": "conversation.assigned", "domains": ["conversations"], "status": "live", "pending": false, "description": "Una conversaci\xF3n qued\xF3 asignada a una persona del equipo o a un agente de IA.\n\nSe env\xEDa cuando una conversaci\xF3n queda asignada a una persona del equipo (`assignee.type` = `human`) o a un agente de IA (`assignee.type` = `ai`), por cualquier camino. `assignee` trae el tipo y el nombre, nunca un identificador. No se env\xEDa al desasignar, ni cuando se vuelve a enviar el mismo asignado." },
   { "type": "conversation.closed", "domains": ["conversations"], "status": "live", "pending": false, "description": "Una conversaci\xF3n pas\xF3 a cerrada.\n\nSe env\xEDa cuando una conversaci\xF3n pasa de abierta a cerrada. No se env\xEDa si la conversaci\xF3n ya estaba cerrada ni cuando se reabre." },
   { "type": "daily_report.generated", "domains": ["communities"], "status": "live", "pending": true, "description": "The daily report of the account was generated (clicks, joins and leaves)." },
-  { "type": "device.connected", "domains": ["accounts"], "status": "live", "pending": true, "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." },
-  { "type": "device.disconnected", "domains": ["accounts"], "status": "live", "pending": true, "description": "One of the numbers of the account disconnected and can no longer send or receive." },
+  { "type": "device.connected", "domains": ["accounts"], "status": "live", "pending": true, "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." },
+  { "type": "device.deleted", "domains": ["accounts"], "status": "planned", "pending": true, "description": "A number of the account was deleted: its slot of the plan is free again." },
+  { "type": "device.disconnected", "domains": ["accounts"], "status": "live", "pending": true, "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." },
+  { "type": "device.health_changed", "domains": ["accounts"], "status": "planned", "pending": true, "description": "The health of an official number changed (what Meta lets it do). Emitted only when the overall state changes." },
   { "type": "flow.completed", "domains": ["conversations"], "status": "live", "pending": false, "description": "Un contacto termin\xF3 un flujo de automatizaci\xF3n.\n\nSe env\xEDa una sola vez por cada ejecuci\xF3n de un flujo, cuando termina con \xE9xito. No se env\xEDa si la ejecuci\xF3n se cort\xF3, se cancel\xF3, qued\xF3 bloqueada o fall\xF3. `contact` es `null` si la ejecuci\xF3n no tiene un contacto asociado. Un flujo muy usado puede generar muchos eventos seguidos." },
   { "type": "flow.failed", "domains": ["conversations"], "status": "live", "pending": false, "description": "La ejecuci\xF3n de un flujo para un contacto termin\xF3 por un error.\n\nSe env\xEDa una sola vez por cada ejecuci\xF3n de un flujo que termina por un error, no porque lleg\xF3 al final. `reason` indica el motivo y toma uno de estos valores: `node_missing` (el paso a ejecutar ya no existe), `unknown_node_type` (el paso es de un tipo no reconocido), `missing_subflow` (el flujo que deb\xEDa ejecutarse dentro de otro ya no existe), `malformed_node` (el paso tiene una configuraci\xF3n da\xF1ada), `loop_detected` (la ejecuci\xF3n dio vueltas sin esperar nada) y `execution_error` (un error inesperado detuvo la ejecuci\xF3n). No se env\xEDa si la ejecuci\xF3n se cancel\xF3, qued\xF3 bloqueada o se cort\xF3 porque se edit\xF3 el flujo o se unieron contactos. `contact` es `null` si la ejecuci\xF3n no tiene un contacto asociado." },
   { "type": "group_action.failed", "domains": ["communities"], "status": "live", "pending": true, "description": "An action on a group of a campaign failed." },
@@ -1505,7 +1656,9 @@ exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
 exports.DEFAULT_TOLERANCE_SECONDS = DEFAULT_TOLERANCE_SECONDS;
 exports.Funnelchat = Funnelchat;
 exports.FunnelchatError = FunnelchatError;
+exports.IDEMPOTENCY_ERROR_CODES = IDEMPOTENCY_ERROR_CODES;
 exports.InternalServerError = InternalServerError;
+exports.NUMBER_ERROR_CODES = NUMBER_ERROR_CODES;
 exports.NotFoundError = NotFoundError;
 exports.Page = Page;
 exports.PagePromise = PagePromise;
@@ -1520,6 +1673,7 @@ exports.VERSION = VERSION;
 exports.WebhookVerificationError = WebhookVerificationError;
 exports.constructEvent = constructEvent;
 exports.default = Funnelchat;
+exports.isNumberQuotaError = isNumberQuotaError;
 exports.isSendRuleError = isSendRuleError;
 exports.routes = routes;
 exports.verify = verify;