@botozap/sdk 0.23.0 → 0.25.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 +27 -0
- package/README.md +31 -3
- package/dist/index.cjs +19 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +34 -3
- package/dist/index.d.ts +34 -3
- package/dist/index.js +19 -2
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# @botozap/sdk
|
|
2
2
|
|
|
3
|
+
## 0.25.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 259b5db: Código da Meta nas recusas e reenvio de entrega de webhook.
|
|
8
|
+
|
|
9
|
+
- `BotoZapError.metaCode` (e `SendFailureDetails.metaCode`) traz o código
|
|
10
|
+
numérico da Meta (`error.meta_code`, ex.: `131026`) quando ela recusa um envio
|
|
11
|
+
ou um pedido de consentimento; só vem quando é inteiro. A CLI mostra
|
|
12
|
+
`— código da Meta: N` no erro e `meta_code` no `-o json`. No MCP o texto do
|
|
13
|
+
erro ganha `Código da Meta: N.` e, no catálogo completo, o erro estruturado
|
|
14
|
+
ganha `meta_code`; o perfil `assistant` (OAuth) segue anunciando e devolvendo
|
|
15
|
+
o erro revisado, com o código só no texto.
|
|
16
|
+
- `webhookDeliveries.replay(id)` (`POST /v1/webhook_deliveries/{id}/replay`,
|
|
17
|
+
tipo `WebhookDeliveryReplay`) reenvia uma entrega `exhausted` ou `limited`,
|
|
18
|
+
como o Reenviar do painel, com a mesma `X-Idempotency-Key`; erros
|
|
19
|
+
`delivery_not_replayable` e `forward_limit_reached` (409) e
|
|
20
|
+
`replay_rate_limited` (429). CLI `deliveries replay <id>`; tool
|
|
21
|
+
`replay_webhook_delivery` (`webhooks:write`, idempotente, `openWorldHint`),
|
|
22
|
+
só no catálogo completo: o perfil `assistant` (OAuth) não muda.
|
|
23
|
+
|
|
24
|
+
## 0.24.0
|
|
25
|
+
|
|
26
|
+
### Minor Changes
|
|
27
|
+
|
|
28
|
+
- c56cd71: **Quebra de compatibilidade:** o Node mínimo passa a ser o 22.12. O Node 20 saiu de suporte em abril de 2026 e deixa de ser testado. Quem ainda roda Node 20 deve atualizar o Node antes de instalar esta versão; as versões anteriores dos pacotes continuam funcionando no 20.19.
|
|
29
|
+
|
|
3
30
|
## 0.23.0
|
|
4
31
|
|
|
5
32
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -44,7 +44,7 @@ Espelha [a documentação de confiabilidade](https://botozap.com.br/docs):
|
|
|
44
44
|
pnpm add @botozap/sdk
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
-
Requer Node
|
|
47
|
+
Requer Node 22.12 ou superior.
|
|
48
48
|
|
|
49
49
|
## Início rápido
|
|
50
50
|
|
|
@@ -370,6 +370,19 @@ catch (err) {
|
|
|
370
370
|
|
|
371
371
|
`err.headers` traz só os headers da resposta — nenhuma credencial de request entra nele.
|
|
372
372
|
|
|
373
|
+
Quando a Meta recusa um envio (`messages.send` e afins, `conversations.reply` e
|
|
374
|
+
`conversations.requestConsent`), o erro chega como `meta_error` e
|
|
375
|
+
`err.metaCode` traz o código numérico da Meta (por exemplo, `131026`), se ela
|
|
376
|
+
informou um. Use-o para consultar a causa na documentação de erros da Meta.
|
|
377
|
+
|
|
378
|
+
```ts
|
|
379
|
+
catch (err) {
|
|
380
|
+
if (err instanceof BotoZapError && err.metaCode !== undefined) {
|
|
381
|
+
console.error(`Meta recusou com o código ${err.metaCode}: ${err.message}`);
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
|
|
373
386
|
### Recusas de plano
|
|
374
387
|
|
|
375
388
|
`isPlanError(err)` reconhece recusas que só um upgrade resolve (retry não):
|
|
@@ -596,6 +609,20 @@ e `app_messages`, opt-in, com `whatsapp.message.echo`, `.edited` e `.revoked` do
|
|
|
596
609
|
app WhatsApp Business em coexistência. Em `webhookDeliveries.list`, o status
|
|
597
610
|
`limited` marca a entrega cortada pelo limite de repasse do Free (sem retry).
|
|
598
611
|
|
|
612
|
+
`webhookDeliveries.replay(id)` reenvia uma entrega `exhausted` (esgotada) ou
|
|
613
|
+
`limited`, como o botão Reenviar do painel: ela volta para a fila
|
|
614
|
+
(`{ id, status: "pending", replayed: true }`) e o evento sai de novo com a mesma
|
|
615
|
+
`X-Idempotency-Key`. Repetir não duplica: a entrega que já voltou para a fila
|
|
616
|
+
responde `409 delivery_not_replayable`. Outras recusas: `404 not_found`,
|
|
617
|
+
`409 forward_limit_reached` (entrega `limited` e o limite de repasse do mês
|
|
618
|
+
acabou) e `429 replay_rate_limited` (headers de rate limit em `err.headers`).
|
|
619
|
+
Exige o escopo `webhooks:write`.
|
|
620
|
+
|
|
621
|
+
```ts
|
|
622
|
+
const { data } = await boto.webhookDeliveries.list({ status: "exhausted", limit: 1 });
|
|
623
|
+
if (data[0]) await boto.webhookDeliveries.replay(data[0].id);
|
|
624
|
+
```
|
|
625
|
+
|
|
599
626
|
`channel_account_ids` limita um Endpoint a alguns canais (ids de
|
|
600
627
|
`channelAccounts.list`, os mesmos de `channel_account.id` nos payloads; 1 a
|
|
601
628
|
100). No create, omitido ou `null` = todos os canais. No update, omitido não
|
|
@@ -649,7 +676,8 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
649
676
|
- `exports` — `create`, `list`, `get` (exportação de dados da Conta; `exports:read`/`exports:write`)
|
|
650
677
|
- `teamEvents` — `list`: registro de atividades da equipe, com filtros (`team:read`, só Administrador)
|
|
651
678
|
- `me` — `get`: Conta, ambiente (`live` ou `sandbox`) e scopes efetivos da chave autenticada; não retorna a chave nem uma identidade pessoal
|
|
652
|
-
- `
|
|
679
|
+
- `webhookDeliveries` — histórico de Entregas de webhook e reenvio das esgotadas (`replay`)
|
|
680
|
+
- `users`, `apiLogs` — leitura
|
|
653
681
|
|
|
654
682
|
`me.get()` é útil para conferir a identidade configurada antes de executar
|
|
655
683
|
operações em uma integração:
|
|
@@ -863,7 +891,7 @@ Requer a API com suporte a `Idempotency-Key` em `POST /v1/messages`.
|
|
|
863
891
|
Recusas confirmadas (`outcome: rejected`) liberam a chave. Aguarde o backoff ou
|
|
864
892
|
corrija a causa e repita com a mesma chave; após liberação, outro payload é uma
|
|
865
893
|
nova intenção. `unknown` ou `accepted` exigem conciliação antes de considerar
|
|
866
|
-
outro envio. SDK e MCP preservam `outcome` e `
|
|
894
|
+
outro envio. SDK e MCP preservam `outcome`, `retry` e o código da Meta (`metaCode`) da API. Resultados concluídos
|
|
867
895
|
vencidos são removidos pelo cron a cada minuto; claims incertas não são removidas
|
|
868
896
|
por tempo, conforme o runbook `botozap/docs/ops/message-send-receipts.md`.
|
|
869
897
|
|
package/dist/index.cjs
CHANGED
|
@@ -116,6 +116,7 @@ var BotoZapError = class extends Error {
|
|
|
116
116
|
status;
|
|
117
117
|
outcome;
|
|
118
118
|
retry;
|
|
119
|
+
metaCode;
|
|
119
120
|
/** Headers da resposta HTTP. Ausente em erros sem resposta (status 0). */
|
|
120
121
|
headers;
|
|
121
122
|
constructor(code, message, status, headers, details) {
|
|
@@ -126,6 +127,7 @@ var BotoZapError = class extends Error {
|
|
|
126
127
|
this.headers = headers;
|
|
127
128
|
this.outcome = details?.outcome;
|
|
128
129
|
this.retry = details?.retry;
|
|
130
|
+
this.metaCode = details?.metaCode;
|
|
129
131
|
}
|
|
130
132
|
};
|
|
131
133
|
var PLAN_ERROR_CODES = [
|
|
@@ -6594,6 +6596,20 @@ var WebhookDeliveries = class {
|
|
|
6594
6596
|
}
|
|
6595
6597
|
);
|
|
6596
6598
|
}
|
|
6599
|
+
/**
|
|
6600
|
+
* Reenvia uma entrega esgotada (`exhausted`) ou cortada pelo limite de repasse
|
|
6601
|
+
* (`limited`): ela volta para a fila e o evento sai de novo com a mesma
|
|
6602
|
+
* `X-Idempotency-Key`, como o botão Reenviar do painel. Repetir não duplica: a
|
|
6603
|
+
* entrega já na fila responde 409 `delivery_not_replayable`. Outras recusas:
|
|
6604
|
+
* 404 `not_found`, 409 `forward_limit_reached` (limite de repasse do mês
|
|
6605
|
+
* acabou) e 429 `replay_rate_limited`. Exige o escopo `webhooks:write`.
|
|
6606
|
+
*/
|
|
6607
|
+
replay(id) {
|
|
6608
|
+
return this.client.requestItem(
|
|
6609
|
+
"POST",
|
|
6610
|
+
`/webhook_deliveries/${encodeURIComponent(id)}/replay`
|
|
6611
|
+
);
|
|
6612
|
+
}
|
|
6597
6613
|
};
|
|
6598
6614
|
|
|
6599
6615
|
// src/resources/me.ts
|
|
@@ -6657,7 +6673,7 @@ var BotoZap = class {
|
|
|
6657
6673
|
const resolvedFetch = options.fetch ?? globalThis.fetch;
|
|
6658
6674
|
if (typeof resolvedFetch !== "function") {
|
|
6659
6675
|
throw new Error(
|
|
6660
|
-
"BotoZap: fetch global n\xE3o encontrado. Use Node
|
|
6676
|
+
"BotoZap: fetch global n\xE3o encontrado. Use Node 22.12+ ou passe a op\xE7\xE3o `fetch`."
|
|
6661
6677
|
);
|
|
6662
6678
|
}
|
|
6663
6679
|
this.fetchImpl = resolvedFetch;
|
|
@@ -6784,7 +6800,8 @@ var BotoZap = class {
|
|
|
6784
6800
|
headers,
|
|
6785
6801
|
{
|
|
6786
6802
|
outcome: envelope?.error?.outcome === "rejected" || envelope?.error?.outcome === "accepted" || envelope?.error?.outcome === "unknown" ? envelope.error.outcome : void 0,
|
|
6787
|
-
retry: envelope?.error?.retry === "backoff" || envelope?.error?.retry === "after_correction" || envelope?.error?.retry === "reconcile_first" || envelope?.error?.retry === "unknown" ? envelope.error.retry : void 0
|
|
6803
|
+
retry: envelope?.error?.retry === "backoff" || envelope?.error?.retry === "after_correction" || envelope?.error?.retry === "reconcile_first" || envelope?.error?.retry === "unknown" ? envelope.error.retry : void 0,
|
|
6804
|
+
metaCode: Number.isSafeInteger(envelope?.error?.meta_code) ? envelope?.error?.meta_code : void 0
|
|
6788
6805
|
}
|
|
6789
6806
|
);
|
|
6790
6807
|
}
|