@botozap/sdk 0.24.0 → 0.26.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,40 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.26.0
4
+
5
+ ### Minor Changes
6
+
7
+ - e131e97: Declaração do dono em follow-up de Marketing.
8
+
9
+ - `AiFlowSettings.marketing_consent` (`required` | `declared`, só em
10
+ `marketing`): com `declared`, quem publica declara que os contatos do fluxo
11
+ autorizaram marketing. No envio, contato sem registro ganha `granted` com a
12
+ origem nova `owner_declaration`; `revoked` sempre bloqueia. O MCP aceita o
13
+ campo nas configurações do fluxo.
14
+ - `ConsentOrigin` ganha `owner_declaration`, e as descrições do MCP e os READMEs
15
+ citam a origem.
16
+
17
+ ## 0.25.0
18
+
19
+ ### Minor Changes
20
+
21
+ - 259b5db: Código da Meta nas recusas e reenvio de entrega de webhook.
22
+
23
+ - `BotoZapError.metaCode` (e `SendFailureDetails.metaCode`) traz o código
24
+ numérico da Meta (`error.meta_code`, ex.: `131026`) quando ela recusa um envio
25
+ ou um pedido de consentimento; só vem quando é inteiro. A CLI mostra
26
+ `— código da Meta: N` no erro e `meta_code` no `-o json`. No MCP o texto do
27
+ erro ganha `Código da Meta: N.` e, no catálogo completo, o erro estruturado
28
+ ganha `meta_code`; o perfil `assistant` (OAuth) segue anunciando e devolvendo
29
+ o erro revisado, com o código só no texto.
30
+ - `webhookDeliveries.replay(id)` (`POST /v1/webhook_deliveries/{id}/replay`,
31
+ tipo `WebhookDeliveryReplay`) reenvia uma entrega `exhausted` ou `limited`,
32
+ como o Reenviar do painel, com a mesma `X-Idempotency-Key`; erros
33
+ `delivery_not_replayable` e `forward_limit_reached` (409) e
34
+ `replay_rate_limited` (429). CLI `deliveries replay <id>`; tool
35
+ `replay_webhook_delivery` (`webhooks:write`, idempotente, `openWorldHint`),
36
+ só no catálogo completo: o perfil `assistant` (OAuth) não muda.
37
+
3
38
  ## 0.24.0
4
39
 
5
40
  ### Minor Changes
package/README.md CHANGED
@@ -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):
@@ -467,7 +480,8 @@ Cada contato tem um consentimento por canal (`whatsapp` ou `instagram`) e
467
480
  finalidade (`marketing` ou `utility`), com a origem de cada registro: `manual`,
468
481
  `import`, `api`, `keyword` (Palavra de saída), `conversation_button` (botão do
469
482
  pedido de consentimento), `contact_keyword` (Palavra de volta), `template_button`
470
- (botão de saída do template) e `meta_opt_out` (recusa informada pela Meta). Só o
483
+ (botão de saída do template), `meta_opt_out` (recusa informada pela Meta) e
484
+ `owner_declaration` (declaração do dono num follow-up de Marketing). Só o
471
485
  próprio contato volta a aceitar depois de recusar.
472
486
 
473
487
  ```ts
@@ -596,6 +610,20 @@ e `app_messages`, opt-in, com `whatsapp.message.echo`, `.edited` e `.revoked` do
596
610
  app WhatsApp Business em coexistência. Em `webhookDeliveries.list`, o status
597
611
  `limited` marca a entrega cortada pelo limite de repasse do Free (sem retry).
598
612
 
613
+ `webhookDeliveries.replay(id)` reenvia uma entrega `exhausted` (esgotada) ou
614
+ `limited`, como o botão Reenviar do painel: ela volta para a fila
615
+ (`{ id, status: "pending", replayed: true }`) e o evento sai de novo com a mesma
616
+ `X-Idempotency-Key`. Repetir não duplica: a entrega que já voltou para a fila
617
+ responde `409 delivery_not_replayable`. Outras recusas: `404 not_found`,
618
+ `409 forward_limit_reached` (entrega `limited` e o limite de repasse do mês
619
+ acabou) e `429 replay_rate_limited` (headers de rate limit em `err.headers`).
620
+ Exige o escopo `webhooks:write`.
621
+
622
+ ```ts
623
+ const { data } = await boto.webhookDeliveries.list({ status: "exhausted", limit: 1 });
624
+ if (data[0]) await boto.webhookDeliveries.replay(data[0].id);
625
+ ```
626
+
599
627
  `channel_account_ids` limita um Endpoint a alguns canais (ids de
600
628
  `channelAccounts.list`, os mesmos de `channel_account.id` nos payloads; 1 a
601
629
  100). No create, omitido ou `null` = todos os canais. No update, omitido não
@@ -649,7 +677,8 @@ O SDK cobre os recursos da API `/v1`:
649
677
  - `exports` — `create`, `list`, `get` (exportação de dados da Conta; `exports:read`/`exports:write`)
650
678
  - `teamEvents` — `list`: registro de atividades da equipe, com filtros (`team:read`, só Administrador)
651
679
  - `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
680
+ - `webhookDeliveries` — histórico de Entregas de webhook e reenvio das esgotadas (`replay`)
681
+ - `users`, `apiLogs` — leitura
653
682
 
654
683
  `me.get()` é útil para conferir a identidade configurada antes de executar
655
684
  operações em uma integração:
@@ -863,7 +892,7 @@ Requer a API com suporte a `Idempotency-Key` em `POST /v1/messages`.
863
892
  Recusas confirmadas (`outcome: rejected`) liberam a chave. Aguarde o backoff ou
864
893
  corrija a causa e repita com a mesma chave; após liberação, outro payload é uma
865
894
  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
895
+ outro envio. SDK e MCP preservam `outcome`, `retry` e o código da Meta (`metaCode`) da API. Resultados concluídos
867
896
  vencidos são removidos pelo cron a cada minuto; claims incertas não são removidas
868
897
  por tempo, conforme o runbook `botozap/docs/ops/message-send-receipts.md`.
869
898
 
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
@@ -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
  }