@botozap/sdk 0.17.0 → 0.19.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,47 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.19.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 8d6d00f: Limites do Free: 1 Cliente e 1 número. Quem passa do teto (por exemplo, depois do
8
+ teste grátis) fica suspenso, sem exclusão: continua recebendo, mas não envia, e
9
+ volta sozinho ao assinar. SDK: `plan_suspended?: boolean` em `Customer` e
10
+ `PhoneNumber`; `isFreeCap` (402 `free_cap`: 2º Cliente no Free ou envio por
11
+ Cliente suspenso) e `isFreeNumberCap` (402 `free_number_cap`: envio por Número
12
+ suspenso ou setup além do teto); `free_cap` entra em `PLAN_ERROR_CODES`, então
13
+ `isPlanError` passa a reconhecê-lo. Docs de `customers.create`, Regras de
14
+ mensagem e Perguntas e menu citam o 403 `plan_restricted` do Free. CLI: coluna
15
+ SUSPENSO em `customers list` e `numbers list`. MCP, só no catálogo completo:
16
+ `plan_suspended` na saída de `list_customers`, `get_customer`, `create_customer`,
17
+ `update_customer`, `list_phone_numbers`, `get_phone_number` e
18
+ `update_phone_number`, e descrições com as recusas do Free (`free_cap`,
19
+ `free_number_cap`, `plan_restricted`) em leituras, envios, `create_customer`,
20
+ Regras de mensagem e Perguntas e menu. O perfil `assistant` (OAuth) não muda:
21
+ mesmas tools, anotações, descrições e saída.
22
+
23
+ ## 0.18.0
24
+
25
+ ### Minor Changes
26
+
27
+ - 48db398: Link de setup com canal: cada link conecta um canal só, `whatsapp` (padrão) ou
28
+ `instagram`. No Instagram, o Cliente confirma que a conta é profissional e que as
29
+ mensagens estão liberadas e entra com o Instagram; `allowed_connection_types` não
30
+ vale (a API responde `422 invalid_connection_types`) e o link volta com
31
+ `allowed_connection_types: []` e `url` em `/instagram/setup/<token>`. Canal fora
32
+ desses dois responde `422 invalid_channel`. `whatsapp_setup_status` mantém o nome
33
+ e vale para os dois canais.
34
+
35
+ SDK: `channel?: "whatsapp" | "instagram"` em `CreateSetupLinkParams` e
36
+ `channel: "whatsapp" | "instagram"` em `SetupLink`. CLI: `setup-links create
37
+ --channel <whatsapp|instagram>` e coluna CANAL no `setup-links list`. MCP:
38
+ `create_setup_link` aceita `channel` opcional (padrão `whatsapp`) e o schema de
39
+ saída dos links de setup passa a trazer `channel`.
40
+
41
+ Requer a API com o campo `channel` nos links de setup (app BotoZap, branch
42
+ `feat/setup-link-instagram`): publique o MCP só depois desse deploy, porque o
43
+ schema de saída exige `channel`.
44
+
3
45
  ## 0.17.0
4
46
 
5
47
  ### Minor Changes
package/README.md CHANGED
@@ -254,6 +254,9 @@ http/https: 2000. Os quatro métodos retornam o snapshot com
254
254
  explicitamente o desejado. Falhas de aplicação conservam a configuração para
255
255
  retry; `profile_busy` e `profile_sync_unconfirmed` pedem reconciliar após um
256
256
  minuto. Sync sem configuração salva retorna `profile_not_configured`.
257
+ Perguntas e menu são do plano pago e do teste: no Free, salvar conteúdo
258
+ (PATCH) ou reaplicar uma configuração com conteúdo (sync) responde
259
+ `403 plan_restricted`; remover seções e DELETE seguem livres.
257
260
 
258
261
  ## Clientes e templates
259
262
 
@@ -370,10 +373,13 @@ catch (err) {
370
373
  ### Recusas de plano
371
374
 
372
375
  `isPlanError(err)` reconhece recusas que só um upgrade resolve (retry não):
373
- `403 plan_restricted` nas escritas de IA, Agenda, Calendário, Jornadas e execuções
376
+ `403 plan_restricted` nas escritas de IA, Agenda, Calendário, Jornadas, execuções,
377
+ Regras de mensagem do Direct e Perguntas e menu do Instagram
374
378
  (`422 plan_restricted` em funil, aquecimento e regras de comentário),
375
- `429 free_form_limit_reached` (limite de mensagens 1:1 do Free) e
376
- `402 free_number_cap` no setup além do teto de Números do Free. Credencial de IA
379
+ `429 free_form_limit_reached` (limite de mensagens 1:1 do Free),
380
+ `402 free_number_cap` (setup além do teto de Números do Free ou envio por um
381
+ Número suspenso) e `402 free_cap` (2º Cliente no Free ou envio por um Cliente
382
+ suspenso). Credencial de IA
377
383
  nova só para `openai`/`anthropic` (`AI_CREDENTIAL_PROVIDERS`; os demais respondem
378
384
  `422 provider_not_enabled`); `ai.providers.get()` traz `accepts_new_credentials`
379
385
  por provedor.
@@ -386,6 +392,30 @@ catch (err) {
386
392
  }
387
393
  ```
388
394
 
395
+ ### Acima dos limites do Free
396
+
397
+ O Free permite 1 Cliente (com canal conectado ou não) e 1 número de WhatsApp.
398
+ Quem passa disso, por exemplo depois do teste grátis, não é apagado nem
399
+ desconectado: fica suspenso. As leituras de `customers` e `phoneNumbers`
400
+ (`list`, `get` e o `update` do número) trazem `plan_suspended: true`. O recurso
401
+ suspenso continua recebendo mensagens, mas não envia: o envio responde
402
+ `402 free_cap` (Cliente suspenso) ou `402 free_number_cap` (Número suspenso; o
403
+ Número de um Cliente suspenso também vem com `plan_suspended: true`). Criar o 2º
404
+ Cliente no Free responde `402 free_cap`. Assinar libera tudo na hora; para
405
+ seguir no Free, desconecte o outro número ou apague o Cliente que não usa.
406
+
407
+ ```ts
408
+ import { isFreeCap, isFreeNumberCap } from "@botozap/sdk";
409
+
410
+ const numeros = await boto.phoneNumbers.list();
411
+ const ativos = numeros.data.filter((n) => !n.plan_suspended);
412
+
413
+ catch (err) {
414
+ if (isFreeNumberCap(err)) avisar("Número suspenso no Free: assine ou desconecte o outro número.");
415
+ else if (isFreeCap(err)) avisar("Negócio suspenso no Free: assine ou apague o outro Cliente.");
416
+ }
417
+ ```
418
+
389
419
  ### Plano e slots adicionais
390
420
 
391
421
  O plano pago inclui 1 negócio. Cada negócio a mais ocupa um slot adicional de
@@ -473,7 +503,7 @@ new BotoZap({
473
503
  O SDK cobre os recursos da API `/v1`:
474
504
 
475
505
  - `messages` — enviar texto (com `quick_replies` no Instagram), template e mídia por link, **listar** e buscar por id
476
- - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
506
+ - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar; `channel` `whatsapp` ou `instagram`, um canal por link)
477
507
  - `templates` — listar, buscar, **criar**
478
508
  - `broadcasts` — criar, destinatários, agendar, enviar, cancelar
479
509
  - `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
@@ -573,6 +603,20 @@ const link = await boto.customers.createSetupLink(customerId, {
573
603
  // Envie link.url ao Cliente. No sucesso, confirme o número em phoneNumbers.list:
574
604
  // uma conexão concluída ainda pode ter pendência de registro.
575
605
 
606
+ // Cada link conecta um canal só: channel "whatsapp" (padrão) ou "instagram"
607
+ // (outro valor → 422 invalid_channel). No Instagram, o Cliente confirma que a
608
+ // conta é profissional e que as mensagens estão liberadas e entra com o
609
+ // Instagram. allowed_connection_types não vale (enviar → 422
610
+ // invalid_connection_types); o link volta com allowed_connection_types: [] e
611
+ // url em /instagram/setup/<token>. whatsapp_setup_status vale para os dois
612
+ // canais e passa a completed quando a conta do Instagram conecta.
613
+ const linkIg = await boto.customers.createSetupLink(customerId, {
614
+ channel: "instagram",
615
+ success_redirect_url: "https://seu-app.com/instagram/ok", // status=completed
616
+ failure_redirect_url: "https://seu-app.com/instagram/erro", // status=cancelled
617
+ });
618
+ // linkIg.channel === "instagram"
619
+
576
620
  await boto.webhooks.create({
577
621
  url: "https://seu-app.com/hooks",
578
622
  events: ["messages", "statuses"], // categorias aceitas pela API (a rota rejeita nomes finos)
@@ -686,6 +730,8 @@ por tempo, conforme o runbook `botozap/docs/ops/message-send-receipts.md`.
686
730
 
687
731
  Regras de comentário incluem `dm_button_title`, `delivery_text` e `delivery_media`.
688
732
  Regras de mensagem têm CRUD com gatilhos e ações tipados (`message-rules:read/write`);
733
+ no Free, criar ou editar responde `403 plan_restricted` (pausar com
734
+ `{ is_active: false }` e excluir seguem livres);
689
735
  métricas de comentário recebem `from`/`to` (`comment-rules:read`).
690
736
  [Contrato e exemplos de SDK, CLI e MCP](../../docs/instagram-wave-two.md).
691
737
 
package/dist/index.cjs CHANGED
@@ -64,6 +64,8 @@ __export(index_exports, {
64
64
  SavedReplies: () => SavedReplies,
65
65
  WEBHOOK_CATEGORIES: () => WEBHOOK_CATEGORIES,
66
66
  isBusinessPaymentRequired: () => isBusinessPaymentRequired,
67
+ isFreeCap: () => isFreeCap,
68
+ isFreeNumberCap: () => isFreeNumberCap,
67
69
  isPlanError: () => isPlanError
68
70
  });
69
71
  module.exports = __toCommonJS(index_exports);
@@ -126,7 +128,8 @@ var BotoZapError = class extends Error {
126
128
  var PLAN_ERROR_CODES = [
127
129
  "plan_restricted",
128
130
  "free_form_limit_reached",
129
- "free_number_cap"
131
+ "free_number_cap",
132
+ "free_cap"
130
133
  ];
131
134
  function isPlanError(error) {
132
135
  return error instanceof BotoZapError && PLAN_ERROR_CODES.includes(error.code);
@@ -134,6 +137,12 @@ function isPlanError(error) {
134
137
  function isBusinessPaymentRequired(error) {
135
138
  return error instanceof BotoZapError && error.code === "business_payment_required";
136
139
  }
140
+ function isFreeCap(error) {
141
+ return error instanceof BotoZapError && error.code === "free_cap";
142
+ }
143
+ function isFreeNumberCap(error) {
144
+ return error instanceof BotoZapError && error.code === "free_number_cap";
145
+ }
137
146
 
138
147
  // src/resources/ai/upload.ts
139
148
  var receipts = /* @__PURE__ */ new WeakMap();
@@ -5323,7 +5332,10 @@ var Customers = class {
5323
5332
  get(id) {
5324
5333
  return this.client.requestItem("GET", `/customers/${enc(id)}`);
5325
5334
  }
5326
- /** Cria um cliente. */
5335
+ /**
5336
+ * Cria um cliente. No plano Free, que permite 1 Cliente (com canal ou não), o
5337
+ * segundo responde 402 `free_cap` (veja `isFreeCap`).
5338
+ */
5327
5339
  create(params) {
5328
5340
  return this.client.requestItem("POST", "/customers", {
5329
5341
  body: params
@@ -5351,7 +5363,8 @@ var Customers = class {
5351
5363
  * Cria um link de setup sob um cliente (expira em 30 dias). Envie a `url`
5352
5364
  * devolvida ao Cliente; veja em {@link CreateSetupLinkParams} como funcionam
5353
5365
  * os redirecionamentos. URL de redirecionamento inválida lança
5354
- * `BotoZapError` com `code: "invalid_redirect_url"` (422).
5366
+ * `BotoZapError` com `code: "invalid_redirect_url"` (422); canal inválido,
5367
+ * `code: "invalid_channel"` (422).
5355
5368
  */
5356
5369
  createSetupLink(customerId, params = {}) {
5357
5370
  return this.client.requestItem(
@@ -5886,11 +5899,18 @@ var ChannelAccounts = class {
5886
5899
  getMessageRule(channelAccountId, ruleId) {
5887
5900
  return this.client.requestItem("GET", messageRulesPath(channelAccountId, ruleId));
5888
5901
  }
5889
- /** Cria uma Regra de mensagem. message-rules:write. */
5902
+ /**
5903
+ * Cria uma Regra de mensagem. message-rules:write. Fora do plano (Free)
5904
+ * responde 403 `plan_restricted`.
5905
+ */
5890
5906
  createMessageRule(channelAccountId, params) {
5891
5907
  return this.client.requestItem("POST", messageRulesPath(channelAccountId), { body: params });
5892
5908
  }
5893
- /** PATCH parcial; a API valida o estado final. message-rules:write. */
5909
+ /**
5910
+ * PATCH parcial; a API valida o estado final. message-rules:write. No Free,
5911
+ * só `{ is_active: false }` (pausar) passa; o resto responde 403
5912
+ * `plan_restricted`.
5913
+ */
5894
5914
  updateMessageRule(channelAccountId, ruleId, params) {
5895
5915
  return this.client.requestItem("PATCH", messageRulesPath(channelAccountId, ruleId), { body: params });
5896
5916
  }
@@ -5902,7 +5922,11 @@ var ChannelAccounts = class {
5902
5922
  getMessengerProfile(channelAccountId) {
5903
5923
  return this.client.requestItem("GET", profilePath(channelAccountId));
5904
5924
  }
5905
- /** Salva/aplica apenas as seções enviadas. messenger-profile:write; sem sandbox. */
5925
+ /**
5926
+ * Salva/aplica apenas as seções enviadas. messenger-profile:write; sem
5927
+ * sandbox. No Free, só remover seções passa; salvar conteúdo responde 403
5928
+ * `plan_restricted`.
5929
+ */
5906
5930
  updateMessengerProfile(channelAccountId, params) {
5907
5931
  return this.client.requestItem("PATCH", profilePath(channelAccountId), { body: params });
5908
5932
  }
@@ -5910,7 +5934,11 @@ var ChannelAccounts = class {
5910
5934
  deleteMessengerProfile(channelAccountId) {
5911
5935
  return this.client.requestItem("DELETE", profilePath(channelAccountId));
5912
5936
  }
5913
- /** Verifica/reaplica explicitamente o desejado salvo. messenger-profile:write. */
5937
+ /**
5938
+ * Verifica/reaplica explicitamente o desejado salvo. messenger-profile:write.
5939
+ * No Free, reaplicar uma configuração com conteúdo responde 403
5940
+ * `plan_restricted`.
5941
+ */
5914
5942
  syncMessengerProfile(channelAccountId) {
5915
5943
  return this.client.requestItem("POST", `${profilePath(channelAccountId)}/sync`);
5916
5944
  }
@@ -6407,6 +6435,8 @@ var WEBHOOK_CATEGORIES = [
6407
6435
  SavedReplies,
6408
6436
  WEBHOOK_CATEGORIES,
6409
6437
  isBusinessPaymentRequired,
6438
+ isFreeCap,
6439
+ isFreeNumberCap,
6410
6440
  isPlanError
6411
6441
  });
6412
6442
  //# sourceMappingURL=index.cjs.map