@botozap/sdk 0.13.0 → 0.15.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 +18 -0
- package/README.md +37 -1
- package/dist/index.cjs +30 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +107 -4
- package/dist/index.d.ts +107 -4
- package/dist/index.js +30 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# @botozap/sdk
|
|
2
2
|
|
|
3
|
+
## 0.15.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 45169ad: Webhooks por canal: `channel_account_ids` em create/update (ausente = todos no
|
|
8
|
+
create e sem mudança no update; `null` volta a todos) e, na leitura,
|
|
9
|
+
`channel_account_ids` e `channels_health` (saúde por canal, só dos canais em
|
|
10
|
+
falha). CLI ganha `--channel-account-id` (repetível) e `--all-channels`, e mostra
|
|
11
|
+
canais e saúde por canal em `webhooks get/list`. MCP aceita `channel_account_ids`
|
|
12
|
+
em `create_webhook`/`update_webhook` e devolve os campos novos na saída
|
|
13
|
+
estruturada.
|
|
14
|
+
|
|
15
|
+
## 0.14.0
|
|
16
|
+
|
|
17
|
+
### Minor Changes
|
|
18
|
+
|
|
19
|
+
- c75addc: Adiciona consulta, reassinatura e desconexão do Instagram e download binário do QR de Regras de mensagem no SDK, CLI e catálogo completo do MCP. Inclui ref_link, regras durante lives, condição de seguidor, perfil de seguidores nos contatos e filtros em contatos/conversas, preservando false, null e PATCH parcial. O MCP retorna link ig.me e imagem PNG; a desconexão é marcada como destrutiva. O catálogo assistant mantém sua composição, com os novos campos de contato expostos nas saídas de get_contact e list_contacts.
|
|
20
|
+
|
|
3
21
|
## 0.13.0
|
|
4
22
|
|
|
5
23
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -394,6 +394,25 @@ e `app_messages`, opt-in, com `whatsapp.message.echo`, `.edited` e `.revoked` do
|
|
|
394
394
|
app WhatsApp Business em coexistência. Em `webhookDeliveries.list`, o status
|
|
395
395
|
`limited` marca a entrega cortada pelo limite de repasse do Free (sem retry).
|
|
396
396
|
|
|
397
|
+
`channel_account_ids` limita um Endpoint a alguns canais (ids de
|
|
398
|
+
`channelAccounts.list`, os mesmos de `channel_account.id` nos payloads; 1 a
|
|
399
|
+
100). No create, omitido ou `null` = todos os canais. No update, omitido não
|
|
400
|
+
muda, `null` volta a todos e um array substitui a lista. A leitura devolve
|
|
401
|
+
`channel_account_ids` (`null` = todos; vazio quando os canais marcados foram
|
|
402
|
+
excluídos, e o Endpoint então não recebe eventos) e `channels_health`, só com
|
|
403
|
+
os canais em falha (`channel_account_id: null` = eventos sem canal). A espera,
|
|
404
|
+
as falhas seguidas e a pausa (na 15ª falha) contam por canal: um canal pausado
|
|
405
|
+
não para os outros. `health_status` e `failure_streak` do Endpoint resumem o
|
|
406
|
+
pior canal; `paused` só aparece quando todos os canais com falha estão
|
|
407
|
+
pausados. Erros: `422 invalid_channel_account_ids` e
|
|
408
|
+
`404 channel_account_not_found`.
|
|
409
|
+
|
|
410
|
+
```ts
|
|
411
|
+
await boto.webhooks.update(endpointId, { channel_account_ids: [canalId] });
|
|
412
|
+
await boto.webhooks.update(endpointId, { channel_account_ids: null }); // todos
|
|
413
|
+
const { channels_health } = await boto.webhooks.get(endpointId);
|
|
414
|
+
```
|
|
415
|
+
|
|
397
416
|
## Configuração
|
|
398
417
|
|
|
399
418
|
```ts
|
|
@@ -418,7 +437,7 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
418
437
|
- `broadcasts` — criar, destinatários, agendar, enviar, cancelar
|
|
419
438
|
- `contacts` — listar, buscar, criar, atualizar, remover; `display_name` é o nome que a empresa dá ao Contato (1–200 caracteres; `null` limpa), separado do `profile_name` que vem do canal
|
|
420
439
|
- `conversations` — listar (filtros `channel` e `channel_account_id`), buscar, atualizar, responder, atribuições; leituras trazem `entry_point` (`ctwa`/`organic`/`null`), `referral` do último clique em anúncio Click-to-WhatsApp, `fep_expires_at` (fim da janela grátis informado pela Meta) e `fep_reply_by` (estimativa do prazo para responder)
|
|
421
|
-
- `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro)
|
|
440
|
+
- `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro); `channel_account_ids` limita a alguns canais (`null` = todos) e `channels_health` traz a saúde por canal
|
|
422
441
|
- `channelAccounts` — listar e buscar Contas de canal (WhatsApp e Instagram); **Regras de comentário** do Instagram (listar, buscar, criar, atualizar, excluir) e **Perguntas e menu** (ler, salvar/aplicar, remover, verificar/reaplicar)
|
|
423
442
|
- `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
|
|
424
443
|
- `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
|
|
@@ -627,3 +646,20 @@ Regras de comentário incluem `dm_button_title`, `delivery_text` e `delivery_med
|
|
|
627
646
|
Regras de mensagem têm CRUD com gatilhos e ações tipados (`message-rules:read/write`);
|
|
628
647
|
métricas de comentário recebem `from`/`to` (`comment-rules:read`).
|
|
629
648
|
[Contrato e exemplos de SDK, CLI e MCP](../../docs/instagram-wave-two.md).
|
|
649
|
+
|
|
650
|
+
### Instagram: conexão, QR, lives e seguidores
|
|
651
|
+
|
|
652
|
+
```ts
|
|
653
|
+
const connection = await boto.channelAccounts.getConnection(channelAccountId);
|
|
654
|
+
await boto.channelAccounts.resubscribeConnection(channelAccountId);
|
|
655
|
+
// Chave de API; no OAuth, a desconexão é feita pelo painel.
|
|
656
|
+
await boto.channelAccounts.disconnect(channelAccountId);
|
|
657
|
+
const svg = await boto.channelAccounts.getMessageRuleQr(channelAccountId, ruleId, { format: "svg" });
|
|
658
|
+
// ArrayBuffer; formato padrão: png. Não contém envelope JSON.
|
|
659
|
+
const followers = await boto.contacts.list({ ig_follows_business: true });
|
|
660
|
+
const nonFollowers = await boto.conversations.list({ ig_follows_business: false });
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
As Regras de mensagem retornam `ref_link` (`https://ig.me/m/usuario?ref=...` ou `null`). Regras de comentário aceitam `live`; as métricas incluem `posts[].live`. Servidores sem lives habilitadas devolvem `422 feature_unavailable`. Não combine `live: true` com `media_id` ou `next_post`.
|
|
664
|
+
|
|
665
|
+
Ambos os tipos de regra aceitam `require_follow` e `non_follower_text`. Nas regras de comentário, a condição exige botão e texto para quem não segue (até 640 caracteres); nas de mensagem, esse texto é opcional e limitado a 1.000 bytes. `null` limpa o texto; campos ausentes no PATCH preservam o valor. Contatos expõem somente para leitura `ig_follows_business`, `ig_followed_by_business`, `ig_follower_count`, `ig_verified` e `ig_follow_checked_at`; valores desconhecidos são `null` e ficam fora dos filtros `true` e `false`. Eventos `instagram.message_rule.failed` podem ter `message_id: null` quando vêm de referral sem mensagem.
|
package/dist/index.cjs
CHANGED
|
@@ -5503,6 +5503,7 @@ var Contacts = class {
|
|
|
5503
5503
|
return this.client.requestCursorList("GET", "/contacts", {
|
|
5504
5504
|
query: {
|
|
5505
5505
|
limit: params.limit,
|
|
5506
|
+
ig_follows_business: params.ig_follows_business === void 0 ? void 0 : String(params.ig_follows_business),
|
|
5506
5507
|
after: params.after,
|
|
5507
5508
|
before: params.before,
|
|
5508
5509
|
customer_id: params.customer_id,
|
|
@@ -5558,6 +5559,7 @@ var Conversations = class {
|
|
|
5558
5559
|
{
|
|
5559
5560
|
query: {
|
|
5560
5561
|
limit: params.limit,
|
|
5562
|
+
ig_follows_business: params.ig_follows_business === void 0 ? void 0 : String(params.ig_follows_business),
|
|
5561
5563
|
customer_id: params.customer_id,
|
|
5562
5564
|
agent_paused: params.agent_paused === void 0 ? void 0 : String(params.agent_paused),
|
|
5563
5565
|
after: params.after,
|
|
@@ -5779,6 +5781,22 @@ var ChannelAccounts = class {
|
|
|
5779
5781
|
get(id) {
|
|
5780
5782
|
return this.client.requestItem("GET", `/channel_accounts/${enc7(id)}`);
|
|
5781
5783
|
}
|
|
5784
|
+
/** Estado e diagnóstico da conexão Instagram. numbers:read; sem sandbox. */
|
|
5785
|
+
getConnection(id) {
|
|
5786
|
+
return this.client.requestItem("GET", `/channel_accounts/${enc7(id)}/connection`);
|
|
5787
|
+
}
|
|
5788
|
+
/** Reassina webhooks usando a autorização existente. numbers:write; sem sandbox. */
|
|
5789
|
+
resubscribeConnection(id) {
|
|
5790
|
+
return this.client.requestItem("POST", `/channel_accounts/${enc7(id)}/connection/resubscribe`);
|
|
5791
|
+
}
|
|
5792
|
+
/** Desconecta a conta. numbers:write; por chave de API (OAuth: somente painel). */
|
|
5793
|
+
disconnect(id) {
|
|
5794
|
+
return this.client.requestItem("DELETE", `/channel_accounts/${enc7(id)}/connection`);
|
|
5795
|
+
}
|
|
5796
|
+
/** QR do ref_link, PNG por padrão; 404 sem link. message-rules:read. */
|
|
5797
|
+
getMessageRuleQr(id, ruleId, params = {}) {
|
|
5798
|
+
return this.client.requestBinary("GET", `${messageRulesPath(id, ruleId)}/qr`, { query: { format: params.format } });
|
|
5799
|
+
}
|
|
5782
5800
|
/** Lista as Regras de comentário de uma Conta do Instagram (UUID). comment-rules:read. */
|
|
5783
5801
|
listCommentRules(channelAccountId, params = {}) {
|
|
5784
5802
|
return this.client.requestOffsetList(
|
|
@@ -6139,6 +6157,13 @@ var BotoZap = class {
|
|
|
6139
6157
|
}
|
|
6140
6158
|
/** Faz uma requisição autenticada e devolve o corpo já parseado. */
|
|
6141
6159
|
async request(method, path, opts = {}) {
|
|
6160
|
+
return this.requestResponse(method, path, opts);
|
|
6161
|
+
}
|
|
6162
|
+
/** Baixa um arquivo autenticado, preservando os erros JSON e headers da API. */
|
|
6163
|
+
requestBinary(method, path, opts = {}) {
|
|
6164
|
+
return this.requestResponse(method, path, opts, true);
|
|
6165
|
+
}
|
|
6166
|
+
async requestResponse(method, path, opts, binary = false) {
|
|
6142
6167
|
const url = new URL(this.baseUrl + path);
|
|
6143
6168
|
if (opts.query) {
|
|
6144
6169
|
for (const [key, value] of Object.entries(opts.query)) {
|
|
@@ -6156,7 +6181,7 @@ var BotoZap = class {
|
|
|
6156
6181
|
headers: {
|
|
6157
6182
|
Authorization: `Bearer ${credential}`,
|
|
6158
6183
|
...opts.body instanceof FormData ? {} : { "Content-Type": "application/json" },
|
|
6159
|
-
Accept: "application/json",
|
|
6184
|
+
Accept: binary ? "image/png, image/svg+xml, application/json" : "application/json",
|
|
6160
6185
|
...opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {}
|
|
6161
6186
|
},
|
|
6162
6187
|
body: opts.body instanceof FormData ? opts.body : opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
|
|
@@ -6171,6 +6196,9 @@ var BotoZap = class {
|
|
|
6171
6196
|
0
|
|
6172
6197
|
);
|
|
6173
6198
|
}
|
|
6199
|
+
if (binary && res.ok && !res.headers.get("content-type")?.includes("json")) {
|
|
6200
|
+
return await res.arrayBuffer();
|
|
6201
|
+
}
|
|
6174
6202
|
const raw = await res.text();
|
|
6175
6203
|
const data = raw ? safeJson(raw) : void 0;
|
|
6176
6204
|
const envelope = data;
|
|
@@ -6191,6 +6219,7 @@ var BotoZap = class {
|
|
|
6191
6219
|
}
|
|
6192
6220
|
);
|
|
6193
6221
|
}
|
|
6222
|
+
if (binary) throw malformed("resposta JSON em endpoint de arquivo bin\xE1rio");
|
|
6194
6223
|
return data;
|
|
6195
6224
|
}
|
|
6196
6225
|
/**
|