@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 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` e `GET /messages/:id` — as demais rotas respondem
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
- from: "phone_number_id_aqui",
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 template, **listar** e buscar por id
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 e obter um media_id
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
- if (!res.ok) {
717
- const envelope = data;
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;