@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 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 20.19 ou superior.
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
- - `users`, `apiLogs`, `webhookDeliveries` — leitura
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 `retry` da API. Resultados concluídos
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 20.19+ ou passe a op\xE7\xE3o `fetch`."
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
  }