@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 +42 -0
- package/README.md +50 -4
- package/dist/index.cjs +37 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +93 -16
- package/dist/index.d.ts +93 -16
- package/dist/index.js +35 -7
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
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)
|
|
376
|
-
`402 free_number_cap`
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|