@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 +35 -0
- package/README.md +32 -3
- package/dist/index.cjs +18 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +44 -6
- package/dist/index.d.ts +44 -6
- package/dist/index.js +18 -1
- package/dist/index.js.map +1 -1
- package/package.json +3 -1
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)
|
|
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
|
-
- `
|
|
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 `
|
|
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
|
}
|