@funnelchat-hq/sdk 0.1.1 → 0.2.0

package/dist/index.js

@@ -315,11 +315,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 = [
@@ -372,6 +433,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 },
@@ -421,10 +486,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 },
@@ -448,6 +514,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 },
@@ -672,6 +739,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
@@ -802,10 +905,30 @@ 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 `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
@@ -814,10 +937,30 @@ 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 `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
+   * `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 } });
@@ -1237,7 +1380,7 @@ var Webhooks = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.2.0";
 
 // src/client.ts
 var BASE_URLS = {
@@ -1264,6 +1407,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.
@@ -1298,6 +1443,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. */
@@ -1449,8 +1595,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." },
@@ -1486,6 +1634,6 @@ var webhookEvents = [
   { "type": "whatsapp_form.completed", "domains": ["conversations"], "status": "live", "pending": true, "description": "A contact completed a form you sent them." }
 ];
 
-export { ACCESS_ERROR_CODES, APIConnectionError, APIConnectionTimeoutError, APIError, APIPromise, APIUserAbortError, AuthenticationError, BASE_URLS, BadRequestError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_TOLERANCE_SECONDS, Funnelchat, FunnelchatError, InternalServerError, NotFoundError, Page, PagePromise, PermissionDeniedError, REQUEST_ID_HEADER, RateLimitError, SEND_ERROR_CODES, SIGNATURE_HEADER, UnprocessableEntityError, UnsupportedMediaTypeError, VERSION, WebhookVerificationError, constructEvent, Funnelchat as default, isSendRuleError, routes, verify, webhookEvents };
+export { ACCESS_ERROR_CODES, APIConnectionError, APIConnectionTimeoutError, APIError, APIPromise, APIUserAbortError, AuthenticationError, BASE_URLS, BadRequestError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_TOLERANCE_SECONDS, Funnelchat, FunnelchatError, IDEMPOTENCY_ERROR_CODES, InternalServerError, NUMBER_ERROR_CODES, NotFoundError, Page, PagePromise, PermissionDeniedError, REQUEST_ID_HEADER, RateLimitError, SEND_ERROR_CODES, SIGNATURE_HEADER, UnprocessableEntityError, UnsupportedMediaTypeError, VERSION, WebhookVerificationError, constructEvent, Funnelchat as default, isNumberQuotaError, isSendRuleError, routes, verify, webhookEvents };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map