@botozap/sdk 0.16.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.18.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 48db398: Link de setup com canal: cada link conecta um canal só, `whatsapp` (padrão) ou
8
+ `instagram`. No Instagram, o Cliente confirma que a conta é profissional e que as
9
+ mensagens estão liberadas e entra com o Instagram; `allowed_connection_types` não
10
+ vale (a API responde `422 invalid_connection_types`) e o link volta com
11
+ `allowed_connection_types: []` e `url` em `/instagram/setup/<token>`. Canal fora
12
+ desses dois responde `422 invalid_channel`. `whatsapp_setup_status` mantém o nome
13
+ e vale para os dois canais.
14
+
15
+ SDK: `channel?: "whatsapp" | "instagram"` em `CreateSetupLinkParams` e
16
+ `channel: "whatsapp" | "instagram"` em `SetupLink`. CLI: `setup-links create
17
+ --channel <whatsapp|instagram>` e coluna CANAL no `setup-links list`. MCP:
18
+ `create_setup_link` aceita `channel` opcional (padrão `whatsapp`) e o schema de
19
+ saída dos links de setup passa a trazer `channel`.
20
+
21
+ Requer a API com o campo `channel` nos links de setup (app BotoZap, branch
22
+ `feat/setup-link-instagram`): publique o MCP só depois desse deploy, porque o
23
+ schema de saída exige `channel`.
24
+
25
+ ## 0.17.0
26
+
27
+ ### Minor Changes
28
+
29
+ - ed98a15: Plano e slots adicionais (só chave de API, scopes `billing:read` e
30
+ `billing:write`). O plano pago inclui 1 negócio; cada negócio a mais ocupa um
31
+ slot de R$ 47/mês. SDK ganha `billing.get()`, `billing.slots.create({ idempotencyKey })`
32
+ e `billing.slots.cancel(id)`, os tipos `Billing`, `BillingPlan`, `BusinessSlot`,
33
+ `ConnectionBilling`, `ConnectionBillingOutcome`, `ConnectionBillingRefusal` e
34
+ `CustomerBusinessSlot`, `connection_billing` no link de setup, `business_slot` no
35
+ Cliente e `isBusinessPaymentRequired` para o 402 `business_payment_required` do
36
+ envio (negócio pausado por fatura vencida há mais de 7 dias). CLI ganha
37
+ `billing`, `billing slots create [--idempotency-key]` e `billing slots cancel <id>`.
38
+ MCP ganha `get_billing`, `create_business_slot` e `cancel_business_slot`, só no
39
+ catálogo de chave de API, com `readOnlyHint`, `destructiveHint`, `openWorldHint` e
40
+ `idempotentHint` explícitos; os links de setup passam a trazer `connection_billing`.
41
+
3
42
  ## 0.16.1
4
43
 
5
44
  ### Patch Changes
package/README.md CHANGED
@@ -386,6 +386,47 @@ catch (err) {
386
386
  }
387
387
  ```
388
388
 
389
+ ### Plano e slots adicionais
390
+
391
+ O plano pago inclui 1 negócio. Cada negócio a mais ocupa um slot adicional de
392
+ R$ 47/mês, com assinatura própria. Estas rotas aceitam só chave de API, com os
393
+ scopes `billing:read` e `billing:write` (OAuth não tem acesso).
394
+
395
+ ```ts
396
+ const { plan, can_add_slot, slots } = await boto.billing.get();
397
+
398
+ // Compra um slot vazio (gera cobrança de R$ 47/mês). A mesma idempotencyKey
399
+ // devolve o mesmo slot em vez de comprar outro.
400
+ const slot = await boto.billing.slots.create({ idempotencyKey: "compra-2026-10-17" });
401
+
402
+ // Cancela um slot vazio, sem reembolso.
403
+ await boto.billing.slots.cancel(slot.id);
404
+ ```
405
+
406
+ Recusas da compra: `402 plan_required` (Free ou teste: assine o plano),
407
+ `402 slot_limit` (já há 2 slots com fatura em aberto: pague uma) e
408
+ `402 billing_customer_required` (conta sem cadastro de cobrança: fale com o
409
+ suporte). Cancelar slot ocupado responde `409 slot_in_use`: desconecte o negócio
410
+ antes. `invoice_url` pode vir `null` logo depois da compra; leia de novo em
411
+ `billing.get()`.
412
+
413
+ Cada link de setup traz `connection_billing`, que diz o que acontece quando o
414
+ Cliente conectar (`included`, `occupies_slot`, `creates_slot` ou `refused`, com
415
+ `message` pronta para mostrar). Cada Cliente traz `business_slot` (`null` quando
416
+ está no que o plano inclui).
417
+
418
+ Quando a fatura de um slot vence há mais de 7 dias, o negócio fica pausado e o
419
+ envio responde `402 business_payment_required`. Pagar libera na hora; não é
420
+ recusa de plano (`isPlanError` é `false`).
421
+
422
+ ```ts
423
+ import { isBusinessPaymentRequired } from "@botozap/sdk";
424
+
425
+ catch (err) {
426
+ if (isBusinessPaymentRequired(err)) avisarFaturaVencida();
427
+ }
428
+ ```
429
+
389
430
  ### Webhooks
390
431
 
391
432
  `WEBHOOK_CATEGORIES` lista as categorias de `webhooks.create({ events })`:
@@ -432,7 +473,7 @@ new BotoZap({
432
473
  O SDK cobre os recursos da API `/v1`:
433
474
 
434
475
  - `messages` — enviar texto (com `quick_replies` no Instagram), template e mídia por link, **listar** e buscar por id
435
- - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
476
+ - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar; `channel` `whatsapp` ou `instagram`, um canal por link)
436
477
  - `templates` — listar, buscar, **criar**
437
478
  - `broadcasts` — criar, destinatários, agendar, enviar, cancelar
438
479
  - `contacts` — listar, buscar, criar, atualizar, remover; `display_name` é o nome que a empresa dá ao Contato (1–200 caracteres; `null` limpa), separado do `profile_name` que vem do canal
@@ -443,6 +484,7 @@ O SDK cobre os recursos da API `/v1`:
443
484
  - `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
444
485
  - `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
445
486
  - `usage` — `metaCosts`: custo aproximado da Meta por dia, categoria e moeda (Pricing Analytics), com estimativa por tarifa publicada onde a Meta não devolveu custo
487
+ - `billing` — `get`: plano e slots adicionais; `slots.create` (compra, com `idempotencyKey`) e `slots.cancel` (slot vazio, sem reembolso). Só chave de API
446
488
  - `me` — `get`: Conta, ambiente (`live` ou `sandbox`) e scopes efetivos da chave autenticada; não retorna a chave nem uma identidade pessoal
447
489
  - `users`, `apiLogs`, `webhookDeliveries` — leitura
448
490
 
@@ -531,6 +573,20 @@ const link = await boto.customers.createSetupLink(customerId, {
531
573
  // Envie link.url ao Cliente. No sucesso, confirme o número em phoneNumbers.list:
532
574
  // uma conexão concluída ainda pode ter pendência de registro.
533
575
 
576
+ // Cada link conecta um canal só: channel "whatsapp" (padrão) ou "instagram"
577
+ // (outro valor → 422 invalid_channel). No Instagram, o Cliente confirma que a
578
+ // conta é profissional e que as mensagens estão liberadas e entra com o
579
+ // Instagram. allowed_connection_types não vale (enviar → 422
580
+ // invalid_connection_types); o link volta com allowed_connection_types: [] e
581
+ // url em /instagram/setup/<token>. whatsapp_setup_status vale para os dois
582
+ // canais e passa a completed quando a conta do Instagram conecta.
583
+ const linkIg = await boto.customers.createSetupLink(customerId, {
584
+ channel: "instagram",
585
+ success_redirect_url: "https://seu-app.com/instagram/ok", // status=completed
586
+ failure_redirect_url: "https://seu-app.com/instagram/erro", // status=cancelled
587
+ });
588
+ // linkIg.channel === "instagram"
589
+
534
590
  await boto.webhooks.create({
535
591
  url: "https://seu-app.com/hooks",
536
592
  events: ["messages", "statuses"], // categorias aceitas pela API (a rota rejeita nomes finos)
package/dist/index.cjs CHANGED
@@ -63,6 +63,7 @@ __export(index_exports, {
63
63
  Radar: () => Radar,
64
64
  SavedReplies: () => SavedReplies,
65
65
  WEBHOOK_CATEGORIES: () => WEBHOOK_CATEGORIES,
66
+ isBusinessPaymentRequired: () => isBusinessPaymentRequired,
66
67
  isPlanError: () => isPlanError
67
68
  });
68
69
  module.exports = __toCommonJS(index_exports);
@@ -130,6 +131,9 @@ var PLAN_ERROR_CODES = [
130
131
  function isPlanError(error) {
131
132
  return error instanceof BotoZapError && PLAN_ERROR_CODES.includes(error.code);
132
133
  }
134
+ function isBusinessPaymentRequired(error) {
135
+ return error instanceof BotoZapError && error.code === "business_payment_required";
136
+ }
133
137
 
134
138
  // src/resources/ai/upload.ts
135
139
  var receipts = /* @__PURE__ */ new WeakMap();
@@ -5347,7 +5351,8 @@ var Customers = class {
5347
5351
  * Cria um link de setup sob um cliente (expira em 30 dias). Envie a `url`
5348
5352
  * devolvida ao Cliente; veja em {@link CreateSetupLinkParams} como funcionam
5349
5353
  * os redirecionamentos. URL de redirecionamento inválida lança
5350
- * `BotoZapError` com `code: "invalid_redirect_url"` (422).
5354
+ * `BotoZapError` com `code: "invalid_redirect_url"` (422); canal inválido,
5355
+ * `code: "invalid_channel"` (422).
5351
5356
  */
5352
5357
  createSetupLink(customerId, params = {}) {
5353
5358
  return this.client.requestItem(
@@ -6002,6 +6007,50 @@ var Usage = class {
6002
6007
  }
6003
6008
  };
6004
6009
 
6010
+ // src/resources/billing.ts
6011
+ function enc8(id) {
6012
+ return encodeURIComponent(id);
6013
+ }
6014
+ var BillingSlots = class {
6015
+ constructor(client) {
6016
+ this.client = client;
6017
+ }
6018
+ client;
6019
+ /**
6020
+ * Compra um slot vazio: gera cobrança de R$ 47/mês. Scope `billing:write`.
6021
+ * `invoice_url` pode vir `null`; a fatura chega em instantes em
6022
+ * {@link BillingResource.get}. Recusas: 402 `plan_required` (Free ou teste: assine o
6023
+ * plano), 402 `slot_limit` (já há 2 slots com fatura em aberto: pague uma),
6024
+ * 402 `billing_customer_required` (conta sem cadastro de cobrança: fale com o
6025
+ * suporte), 422 `invalid_idempotency_key`.
6026
+ */
6027
+ create(options = {}) {
6028
+ return this.client.requestItem("POST", "/billing/slots", {
6029
+ idempotencyKey: options.idempotencyKey
6030
+ });
6031
+ }
6032
+ /**
6033
+ * Cancela um slot vazio, sem reembolso. Responde 204, também quando o slot
6034
+ * já estava cancelado. Slot ocupado responde 409 `slot_in_use`: desconecte o
6035
+ * negócio antes. Scope `billing:write`.
6036
+ */
6037
+ cancel(id) {
6038
+ return this.client.request("DELETE", `/billing/slots/${enc8(id)}`);
6039
+ }
6040
+ };
6041
+ var BillingResource = class {
6042
+ constructor(client) {
6043
+ this.client = client;
6044
+ this.slots = new BillingSlots(client);
6045
+ }
6046
+ client;
6047
+ slots;
6048
+ /** Plano, negócios incluídos e slots ativos. Scope `billing:read`. */
6049
+ get() {
6050
+ return this.client.requestItem("GET", "/billing");
6051
+ }
6052
+ };
6053
+
6005
6054
  // src/resources/read-only.ts
6006
6055
  var Users = class {
6007
6056
  constructor(client) {
@@ -6095,6 +6144,8 @@ var BotoZap = class {
6095
6144
  media;
6096
6145
  events;
6097
6146
  usage;
6147
+ /** Plano da Conta e slots adicionais (só chave de API). */
6148
+ billing;
6098
6149
  users;
6099
6150
  apiLogs;
6100
6151
  webhookDeliveries;
@@ -6138,6 +6189,7 @@ var BotoZap = class {
6138
6189
  this.media = new Media(this);
6139
6190
  this.events = new Events(this);
6140
6191
  this.usage = new Usage(this);
6192
+ this.billing = new BillingResource(this);
6141
6193
  this.users = new Users(this);
6142
6194
  this.apiLogs = new ApiLogs(this);
6143
6195
  this.webhookDeliveries = new WebhookDeliveries(this);
@@ -6355,6 +6407,7 @@ var WEBHOOK_CATEGORIES = [
6355
6407
  Radar,
6356
6408
  SavedReplies,
6357
6409
  WEBHOOK_CATEGORIES,
6410
+ isBusinessPaymentRequired,
6358
6411
  isPlanError
6359
6412
  });
6360
6413
  //# sourceMappingURL=index.cjs.map