@botozap/sdk 0.1.0 → 0.3.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 +51 -0
- package/README.md +87 -6
- package/dist/index.cjs +98 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +146 -2
- package/dist/index.d.ts +146 -2
- package/dist/index.js +98 -3
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# @botozap/sdk
|
|
2
|
+
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 05733ec: Adiciona o stream durável `events.list` ao SDK e um resource MCP assinável por
|
|
8
|
+
cursor. O servidor stdio anuncia subscriptions, envia
|
|
9
|
+
`notifications/resources/updated` enquanto a assinatura está ativa e preserva
|
|
10
|
+
as tools e o fallback de replay após reconexão.
|
|
11
|
+
- da01362: Adiciona `conversations.reply` ao SDK e a tool MCP
|
|
12
|
+
`reply_to_conversation`, que resolvem Contato e Número pela Conversa e
|
|
13
|
+
delegam ao endpoint canônico de mensagens, preservando janela, quota, billing
|
|
14
|
+
e isolamento multi-tenant no servidor.
|
|
15
|
+
- 42c65ef: Adiciona envio tipado de image, video, audio e document pelo SDK e pela tool MCP `send_media_message`, com limites e campos específicos por tipo.
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- de26959: Adiciona output schemas e structured content às tools centrais de Mensagens,
|
|
20
|
+
Números e Templates, preservando o fallback textual e expondo erros estruturados.
|
|
21
|
+
Sincroniza também o tipo `SendResult` do SDK com o campo aditivo `sent_to` da API.
|
|
22
|
+
- e923a96: Torna o push remoto resiliente a queda ou indisponibilidade inicial do event
|
|
23
|
+
bus, sinais concorrentes, restart e clientes abandonados. Adiciona heartbeat de
|
|
24
|
+
reconciliação por cursor, limites de sessão/assinatura, cleanup por cancelamento
|
|
25
|
+
ou expiração e testes de carga e isolamento entre Conta e ambiente. Leituras de
|
|
26
|
+
Eventos do SDK agora aceitam `AbortSignal`, permitindo cancelar I/O em voo.
|
|
27
|
+
|
|
28
|
+
## 0.2.0 (2026-08-13)
|
|
29
|
+
|
|
30
|
+
### Novidades
|
|
31
|
+
|
|
32
|
+
- **`media.get(id)`** — busca os metadados de uma mídia RECEBIDA pelo `media_id`
|
|
33
|
+
da Cloud API (`GET /v1/media/:id`), incluindo `download_url` (URL assinada e
|
|
34
|
+
efêmera, válida até `expires_at`). Novo tipo exportado: `MediaAsset`.
|
|
35
|
+
- **Erro distinguível em 2xx** — um corpo `{ error }` agora lança `BotoZapError`
|
|
36
|
+
mesmo com status 2xx. Caso concreto: o 202 `media_not_ready` de `media.get`
|
|
37
|
+
(mídia ainda sendo espelhada) vira um erro com `code: "media_not_ready"` e o
|
|
38
|
+
segundo que falta em `err.headers["retry-after"]`, em vez de passar como
|
|
39
|
+
sucesso malformado.
|
|
40
|
+
|
|
41
|
+
### Notas
|
|
42
|
+
|
|
43
|
+
- `GET /v1/media/:id/download` (302 para a mesma URL assinada) não ganha método
|
|
44
|
+
dedicado de propósito: `download_url` já entrega a URL sem o hop de redirect.
|
|
45
|
+
|
|
46
|
+
## 0.1.0 (2026-07-15)
|
|
47
|
+
|
|
48
|
+
Primeira versão pública: `messages`, `customers`, `templates`, `broadcasts`,
|
|
49
|
+
`contacts`, `conversations`, `webhooks`, `phoneNumbers`, `flows`, `media.upload`,
|
|
50
|
+
`users`, `apiLogs`, `webhookDeliveries`; desempacote de `{ data }`, paginação por
|
|
51
|
+
cursor/offset e `BotoZapError` com headers da resposta.
|
package/README.md
CHANGED
|
@@ -4,8 +4,6 @@ SDK oficial da [BotoZap](https://botozap.com.br) para Node.js. Envie mensagens e
|
|
|
4
4
|
|
|
5
5
|
O core da plataforma é fechado. Este cliente é a camada pública sobre a API HTTP: um envelope fino, tipado, sem dependências de runtime.
|
|
6
6
|
|
|
7
|
-
> **Ainda não publicado no npm — em preparação.** O pacote está em migração para o monorepo `botozap-js`; o comando de instalação abaixo passará a funcionar quando a primeira versão for publicada.
|
|
8
|
-
|
|
9
7
|
## Status: preview `0.x`
|
|
10
8
|
|
|
11
9
|
- Versão `0.x`, **sem promessa de estabilidade de API**: métodos e tipos podem
|
|
@@ -25,7 +23,7 @@ simulados percorrem o pipeline real (webhook assinado com retry). Números
|
|
|
25
23
|
mágicos: `+5500000000001` (sent→delivered→read, janela de 24h sempre aberta),
|
|
26
24
|
`+5500000000002` (falha `131026`), `+5500000000003` (delivered + resposta
|
|
27
25
|
inbound que abre a janela real). A chave sandbox só acessa `POST /messages`,
|
|
28
|
-
`GET /messages
|
|
26
|
+
`GET /messages`, `GET /messages/:id` e `GET /events` — as demais rotas respondem
|
|
29
27
|
`403 sandbox_forbidden`.
|
|
30
28
|
|
|
31
29
|
## Garantias de entrega (leia antes de ir a produção)
|
|
@@ -77,11 +75,25 @@ await boto.messages.sendTemplate({
|
|
|
77
75
|
template: { name: "boas_vindas", language: { code: "pt_BR" } },
|
|
78
76
|
});
|
|
79
77
|
|
|
78
|
+
// Mídia por link (image, video, audio ou document)
|
|
79
|
+
await boto.messages.sendMedia({
|
|
80
|
+
to: "+5531988887777",
|
|
81
|
+
type: "image",
|
|
82
|
+
link: "https://cdn.exemplo.com/pedido.jpg",
|
|
83
|
+
caption: "Seu pedido ficou pronto",
|
|
84
|
+
});
|
|
85
|
+
|
|
80
86
|
// De um número específico (obrigatório se a conta tem mais de um)
|
|
81
87
|
await boto.messages.send({
|
|
82
88
|
to: "+5531988887777",
|
|
83
89
|
text: "Olá!",
|
|
84
|
-
|
|
90
|
+
// Aceita o phone_number_id Meta ou o UUID interno retornado pelo SDK.
|
|
91
|
+
from: "uuid-ou-phone_number_id",
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
// Responder sem combinar manualmente Contato e Número
|
|
95
|
+
await boto.conversations.reply("uuid-da-conversa", {
|
|
96
|
+
text: "Resposta do agente",
|
|
85
97
|
});
|
|
86
98
|
```
|
|
87
99
|
|
|
@@ -94,6 +106,52 @@ const customer = await boto.customers.get("uuid-do-cliente");
|
|
|
94
106
|
const { data: templates } = await boto.templates.list();
|
|
95
107
|
```
|
|
96
108
|
|
|
109
|
+
## Mídia
|
|
110
|
+
|
|
111
|
+
Para enviar por link, use `messages.sendMedia`. O SDK só envia o contrato ao
|
|
112
|
+
endpoint canônico; não baixa o arquivo no processo do cliente:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
await boto.messages.sendMedia({
|
|
116
|
+
to: "+5531988887777",
|
|
117
|
+
type: "document",
|
|
118
|
+
link: "https://cdn.exemplo.com/fatura.pdf",
|
|
119
|
+
caption: "Fatura de agosto",
|
|
120
|
+
filename: "fatura-agosto.pdf",
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`caption` é aceito em `image`, `video` e `document`; `audio` aceita apenas o
|
|
125
|
+
link; `filename` é exclusivo de `document`.
|
|
126
|
+
|
|
127
|
+
Para fazer ingest de um arquivo, a BotoZap baixa da URL com guard SSRF e envia
|
|
128
|
+
à Cloud API:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
const up = await boto.media.upload({
|
|
132
|
+
source: "https://exemplo.com/foto.png",
|
|
133
|
+
phone_number_id,
|
|
134
|
+
});
|
|
135
|
+
// up.target.media_id → usável no envio
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Para uma mídia **recebida**, busque metadados e a URL de download pelo `media_id`
|
|
139
|
+
da Cloud API. A mídia é espelhada de forma assíncrona: se ainda não terminou, o
|
|
140
|
+
método lança `BotoZapError` com `code: "media_not_ready"` (202) e você retenta,
|
|
141
|
+
respeitando o `Retry-After`:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
try {
|
|
145
|
+
const media = await boto.media.get(mediaId);
|
|
146
|
+
// media.download_url é uma URL assinada e efêmera — baixe direto (GET).
|
|
147
|
+
} catch (err) {
|
|
148
|
+
if (err instanceof BotoZapError && err.code === "media_not_ready") {
|
|
149
|
+
const wait = Number(err.headers?.["retry-after"] ?? 5);
|
|
150
|
+
// aguarde `wait` segundos e tente de novo
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
97
155
|
## Retornos e paginação
|
|
98
156
|
|
|
99
157
|
O SDK **desempacota o envelope `{ data }`** da API pra você:
|
|
@@ -169,7 +227,7 @@ new BotoZap({
|
|
|
169
227
|
|
|
170
228
|
O SDK cobre os recursos da API `/v1`:
|
|
171
229
|
|
|
172
|
-
- `messages` — enviar texto e
|
|
230
|
+
- `messages` — enviar texto, template e mídia por link, **listar** e buscar por id
|
|
173
231
|
- `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
|
|
174
232
|
- `templates` — listar, buscar, **criar**
|
|
175
233
|
- `broadcasts` — criar, destinatários, agendar, enviar, cancelar
|
|
@@ -178,9 +236,32 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
178
236
|
- `webhooks` — CRUD e teste
|
|
179
237
|
- `phoneNumbers` — listar, buscar, remover, saúde (a rota de update não expõe campos editáveis, então o SDK não tem `phoneNumbers.update`)
|
|
180
238
|
- `flows` — criar, versionar, publicar, data endpoint (as operações por flow exigem `phone_number_id`, que amarra o flow à sua WABA)
|
|
181
|
-
- `media` — subir arquivo
|
|
239
|
+
- `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
|
|
240
|
+
- `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
|
|
182
241
|
- `users`, `apiLogs`, `webhookDeliveries` — leitura
|
|
183
242
|
|
|
243
|
+
Inbound e mudanças de status compartilham um stream crescente. Guarde
|
|
244
|
+
`paging.cursor` e use-o como `after` na leitura seguinte; após uma desconexão,
|
|
245
|
+
isso recupera o intervalo persistido sem depender de memória do processo:
|
|
246
|
+
|
|
247
|
+
```ts
|
|
248
|
+
const page = await boto.events.list({ after: ultimoCursor, limit: 100 });
|
|
249
|
+
|
|
250
|
+
for (const event of page.data) {
|
|
251
|
+
console.log(event.cursor, event.type, event.data);
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
ultimoCursor = page.paging.cursor;
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Passe um `AbortSignal` quando a leitura fizer parte de um tail cancelável:
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
const controller = new AbortController();
|
|
261
|
+
const page = await boto.events.list({ after: ultimoCursor, signal: controller.signal });
|
|
262
|
+
controller.abort(); // interrompe o I/O se a assinatura deixou de existir
|
|
263
|
+
```
|
|
264
|
+
|
|
184
265
|
```ts
|
|
185
266
|
// Transmissão: template_name + template_language são obrigatórios.
|
|
186
267
|
await boto.broadcasts.create({
|
package/dist/index.cjs
CHANGED
|
@@ -70,6 +70,25 @@ var Messages = class {
|
|
|
70
70
|
});
|
|
71
71
|
return assertSendResult(result);
|
|
72
72
|
}
|
|
73
|
+
/** Envia mídia por URL pública. */
|
|
74
|
+
async sendMedia(params) {
|
|
75
|
+
const media = { link: params.link };
|
|
76
|
+
if ("caption" in params && params.caption !== void 0) {
|
|
77
|
+
media.caption = params.caption;
|
|
78
|
+
}
|
|
79
|
+
if ("filename" in params && params.filename !== void 0) {
|
|
80
|
+
media.filename = params.filename;
|
|
81
|
+
}
|
|
82
|
+
const result = await this.client.requestObject("POST", "/messages", {
|
|
83
|
+
body: {
|
|
84
|
+
to: params.to,
|
|
85
|
+
from: params.from,
|
|
86
|
+
type: params.type,
|
|
87
|
+
[params.type]: media
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
return assertSendResult(result);
|
|
91
|
+
}
|
|
73
92
|
/** Lista as mensagens da conta (paginação por cursor). */
|
|
74
93
|
list(params = {}) {
|
|
75
94
|
return this.client.requestCursorList("GET", "/messages", {
|
|
@@ -361,6 +380,32 @@ var Conversations = class {
|
|
|
361
380
|
`/conversations/${enc4(id)}`
|
|
362
381
|
);
|
|
363
382
|
}
|
|
383
|
+
/**
|
|
384
|
+
* Responde uma Conversa sem o chamador precisar combinar Contato e Número.
|
|
385
|
+
* A leitura e o envio usam a mesma chave; o POST /messages revalida Conta,
|
|
386
|
+
* ambiente, identidade, janela, quota e billing antes de chamar a Meta.
|
|
387
|
+
*/
|
|
388
|
+
async reply(id, params) {
|
|
389
|
+
const conversation = await this.get(id);
|
|
390
|
+
const from = conversation.phone_number_id;
|
|
391
|
+
if (typeof from !== "string" || !from.trim()) {
|
|
392
|
+
throw new BotoZapError(
|
|
393
|
+
"malformed_response",
|
|
394
|
+
"Conversa sem UUID interno do N\xFAmero de origem.",
|
|
395
|
+
0
|
|
396
|
+
);
|
|
397
|
+
}
|
|
398
|
+
const contact = conversation.contact;
|
|
399
|
+
const to = typeof contact?.wa_id === "string" && contact.wa_id.trim() ? contact.wa_id : typeof contact?.phone === "string" && contact.phone.trim() ? contact.phone : null;
|
|
400
|
+
if (!to) {
|
|
401
|
+
throw new BotoZapError(
|
|
402
|
+
"conversation_recipient_unavailable",
|
|
403
|
+
"Conversa sem destinat\xE1rio utiliz\xE1vel no Contato.",
|
|
404
|
+
422
|
|
405
|
+
);
|
|
406
|
+
}
|
|
407
|
+
return this.client.messages.send({ to, text: params.text, from });
|
|
408
|
+
}
|
|
364
409
|
update(id, params) {
|
|
365
410
|
return this.client.requestItem(
|
|
366
411
|
"PATCH",
|
|
@@ -582,6 +627,52 @@ var Media = class {
|
|
|
582
627
|
body: params
|
|
583
628
|
});
|
|
584
629
|
}
|
|
630
|
+
/**
|
|
631
|
+
* Busca os metadados de uma mídia RECEBIDA pelo `media_id` da Cloud API,
|
|
632
|
+
* incluindo `download_url` — uma URL assinada e efêmera que você pode baixar
|
|
633
|
+
* direto (GET), válida até `expires_at`.
|
|
634
|
+
*
|
|
635
|
+
* A mídia é espelhada de forma assíncrona; se você consultar antes de terminar,
|
|
636
|
+
* a rota responde 202 e este método lança `BotoZapError` com
|
|
637
|
+
* `code: "media_not_ready"`. Nesse caso, aguarde e retente — o segundo que faltar
|
|
638
|
+
* está em `err.headers?.["retry-after"]`:
|
|
639
|
+
*
|
|
640
|
+
* ```ts
|
|
641
|
+
* try {
|
|
642
|
+
* const media = await boto.media.get("wamid_media_id");
|
|
643
|
+
* // baixe media.download_url direto
|
|
644
|
+
* } catch (err) {
|
|
645
|
+
* if (err instanceof BotoZapError && err.code === "media_not_ready") {
|
|
646
|
+
* const wait = Number(err.headers?.["retry-after"] ?? 5);
|
|
647
|
+
* // retente após `wait` segundos
|
|
648
|
+
* }
|
|
649
|
+
* }
|
|
650
|
+
* ```
|
|
651
|
+
*
|
|
652
|
+
* Existe também `GET /v1/media/:id/download`, que responde 302 redirecionando
|
|
653
|
+
* para a mesma URL assinada; não há método SDK dedicado porque `download_url`
|
|
654
|
+
* (acima) já entrega essa URL sem o hop de redirect.
|
|
655
|
+
*/
|
|
656
|
+
get(id) {
|
|
657
|
+
return this.client.requestItem(
|
|
658
|
+
"GET",
|
|
659
|
+
`/media/${encodeURIComponent(id)}`
|
|
660
|
+
);
|
|
661
|
+
}
|
|
662
|
+
};
|
|
663
|
+
|
|
664
|
+
// src/resources/events.ts
|
|
665
|
+
var Events = class {
|
|
666
|
+
constructor(client) {
|
|
667
|
+
this.client = client;
|
|
668
|
+
}
|
|
669
|
+
client;
|
|
670
|
+
list(params = {}) {
|
|
671
|
+
return this.client.requestCursorList("GET", "/events", {
|
|
672
|
+
query: { after: params.after, limit: params.limit },
|
|
673
|
+
signal: params.signal
|
|
674
|
+
});
|
|
675
|
+
}
|
|
585
676
|
};
|
|
586
677
|
|
|
587
678
|
// src/resources/read-only.ts
|
|
@@ -651,6 +742,7 @@ var BotoZap = class {
|
|
|
651
742
|
phoneNumbers;
|
|
652
743
|
flows;
|
|
653
744
|
media;
|
|
745
|
+
events;
|
|
654
746
|
users;
|
|
655
747
|
apiLogs;
|
|
656
748
|
webhookDeliveries;
|
|
@@ -680,6 +772,7 @@ var BotoZap = class {
|
|
|
680
772
|
this.phoneNumbers = new PhoneNumbers(this);
|
|
681
773
|
this.flows = new Flows(this);
|
|
682
774
|
this.media = new Media(this);
|
|
775
|
+
this.events = new Events(this);
|
|
683
776
|
this.users = new Users(this);
|
|
684
777
|
this.apiLogs = new ApiLogs(this);
|
|
685
778
|
this.webhookDeliveries = new WebhookDeliveries(this);
|
|
@@ -701,7 +794,8 @@ var BotoZap = class {
|
|
|
701
794
|
"Content-Type": "application/json",
|
|
702
795
|
Accept: "application/json"
|
|
703
796
|
},
|
|
704
|
-
body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body)
|
|
797
|
+
body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
|
|
798
|
+
signal: opts.signal
|
|
705
799
|
});
|
|
706
800
|
} catch (cause) {
|
|
707
801
|
const detail = cause instanceof Error ? cause.message : String(cause);
|
|
@@ -713,8 +807,9 @@ var BotoZap = class {
|
|
|
713
807
|
}
|
|
714
808
|
const raw = await res.text();
|
|
715
809
|
const data = raw ? safeJson(raw) : void 0;
|
|
716
|
-
|
|
717
|
-
|
|
810
|
+
const envelope = data;
|
|
811
|
+
const hasErrorEnvelope = typeof envelope === "object" && envelope !== null && typeof envelope.error === "object" && envelope.error !== null;
|
|
812
|
+
if (!res.ok || hasErrorEnvelope) {
|
|
718
813
|
const headers = {};
|
|
719
814
|
res.headers.forEach((value, key) => {
|
|
720
815
|
headers[key] = value;
|