@botozap/sdk 0.14.0 → 0.16.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,27 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.16.0
4
+
5
+ ### Minor Changes
6
+
7
+ - d51f908: Adiciona IA de comentários do Instagram (#740): configuração opt-in por Conta de canal, limite diário, prontidão e histórico paginado de decisões/envios.
8
+
9
+ SDK: channelAccounts.getCommentAi, updateCommentAi e listCommentAiRuns, com tipos de configuração, histórico, custo de execução e evento de resposta. CLI: channel-accounts comment-ai get|set|runs, com --enabled, --agent e --daily-limit no set.
10
+
11
+ MCP (catálogo completo): get_instagram_comment_ai, update_instagram_comment_ai e list_instagram_comment_ai_runs, com escopos agents:read/write, sem sandbox e anotações de efeito público. O perfil assistant permanece inalterado; PATCH via OAuth é exclusivo do painel.
12
+
13
+ ## 0.15.0
14
+
15
+ ### Minor Changes
16
+
17
+ - 45169ad: Webhooks por canal: `channel_account_ids` em create/update (ausente = todos no
18
+ create e sem mudança no update; `null` volta a todos) e, na leitura,
19
+ `channel_account_ids` e `channels_health` (saúde por canal, só dos canais em
20
+ falha). CLI ganha `--channel-account-id` (repetível) e `--all-channels`, e mostra
21
+ canais e saúde por canal em `webhooks get/list`. MCP aceita `channel_account_ids`
22
+ em `create_webhook`/`update_webhook` e devolve os campos novos na saída
23
+ estruturada.
24
+
3
25
  ## 0.14.0
4
26
 
5
27
  ### 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
@@ -644,3 +663,29 @@ const nonFollowers = await boto.conversations.list({ ig_follows_business: false
644
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`.
645
664
 
646
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.
666
+
667
+ ### IA de comentários do Instagram
668
+
669
+ ```ts
670
+ const config = await boto.channelAccounts.getCommentAi(channelAccountId);
671
+ await boto.channelAccounts.updateCommentAi(channelAccountId, {
672
+ enabled: true, agent_id: publishedAgentId, daily_limit: 50,
673
+ });
674
+ const runs = await boto.channelAccounts.listCommentAiRuns(channelAccountId, { page: 1, per_page: 30 });
675
+ await boto.channelAccounts.updateCommentAi(channelAccountId, { enabled: false });
676
+ ```
677
+
678
+ Leitura e histórico exigem `agents:read`; PATCH exige `agents:write` e capacidade
679
+ `ai` do plano, exceto o patch que somente desliga. Sem sandbox; no OAuth, PATCH
680
+ é exclusivo do painel. Ativar pode publicar respostas e enviar DMs automáticas.
681
+ Campos ausentes preservam a configuração; `agent_id: null` limpa o agente quando
682
+ desligada. `daily_limit` aceita inteiros de 1 a 200; o dia usa `America/Sao_Paulo`.
683
+ `answered_today` conta respostas públicas confirmadas e `reserved_today` inclui
684
+ tentativas incertas. `status`, `gate_mode` e `readiness` descrevem a prontidão.
685
+
686
+ `InstagramCommentAi` e `InstagramCommentAiRun` tipam os retornos. Execuções deste
687
+ recurso incluem `estimated_cost_usd?: number | null` e `finish_reason` com prefixo
688
+ `comment_ai_`; `source` continua `live`. `InstagramCommentAiRepliedEvent` tipa
689
+ `instagram.comment.replied` com `automation.kind = instagram_comment_ai`,
690
+ `execution_id` e `comment_id`. A Private Reply em `instagram.message.sent` traz
691
+ `source: agent`, `ai_execution_id` e `comment_id` no conteúdo da mensagem.
package/dist/index.cjs CHANGED
@@ -5793,6 +5793,26 @@ var ChannelAccounts = class {
5793
5793
  disconnect(id) {
5794
5794
  return this.client.requestItem("DELETE", `/channel_accounts/${enc7(id)}/connection`);
5795
5795
  }
5796
+ /** Configuração, uso diário e prontidão. agents:read; sem sandbox. */
5797
+ getCommentAi(channelAccountId) {
5798
+ return this.client.requestItem("GET", `/channel_accounts/${enc7(channelAccountId)}/comment-ai`);
5799
+ }
5800
+ /**
5801
+ * PATCH parcial. Ativar pode publicar respostas e enviar DMs automáticas.
5802
+ * agents:write e capacidade ai (desligar somente é livre); sem sandbox.
5803
+ * Chave de API; no OAuth a configuração é exclusiva do painel.
5804
+ */
5805
+ updateCommentAi(channelAccountId, params) {
5806
+ return this.client.requestItem("PATCH", `/channel_accounts/${enc7(channelAccountId)}/comment-ai`, { body: params });
5807
+ }
5808
+ /** Histórico, mais recente primeiro, com paginação offset. agents:read; sem sandbox. */
5809
+ listCommentAiRuns(channelAccountId, params = {}) {
5810
+ return this.client.requestOffsetList(
5811
+ "GET",
5812
+ `/channel_accounts/${enc7(channelAccountId)}/comment-ai/runs`,
5813
+ { query: { page: params.page, per_page: params.per_page } }
5814
+ );
5815
+ }
5796
5816
  /** QR do ref_link, PNG por padrão; 404 sem link. message-rules:read. */
5797
5817
  getMessageRuleQr(id, ruleId, params = {}) {
5798
5818
  return this.client.requestBinary("GET", `${messageRulesPath(id, ruleId)}/qr`, { query: { format: params.format } });