@botozap/sdk 0.11.0 → 0.12.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,12 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.12.0
4
+
5
+ ### Minor Changes
6
+
7
+ - ab0ddbc: Add Instagram interactive button/card/gallery sends with human_agent and channel receipts, extended comment-rule fields and deletion, and messenger-profile read/update/delete/sync across SDK, CLI and MCP. Preserve WhatsApp interactive formats and partial PATCH semantics, and expose messenger-profile scopes and structured results.
8
+ - df51d96: Add Instagram comment-rule button and delivery fields, message-rule CRUD with trigger/action types and message-rules scopes, and comment-rule metrics by period across SDK, CLI and MCP. Preserve nullable fields and partial PATCH bodies, advertise typed MCP results, and support JSON input for comment and message rules in the CLI.
9
+
3
10
  ## 0.11.0
4
11
 
5
12
  ### Minor Changes
package/README.md CHANGED
@@ -163,6 +163,36 @@ no WhatsApp a API recusa com `channel_not_supported`; acima de 13 opções,
163
163
  `quick_reply_title_too_long`; fora da janela, `quick_replies_window_closed`.
164
164
  No Instagram não existe `caption` em mídia (`unsupported_caption`).
165
165
 
166
+ ### Botões e cards no Instagram
167
+
168
+ ```ts
169
+ await boto.messages.sendInteractive({
170
+ to: "17841400000000123", from: contaInstagramId,
171
+ interactive: { type: "button", body: { text: "Como posso ajudar?" }, action: { buttons: [
172
+ { type: "web_url", title: "Ver loja", url: "https://exemplo.com" },
173
+ { type: "postback", title: "Horários", payload: "horarios" },
174
+ ] } },
175
+ }, { idempotencyKey: chaveDaIntencao });
176
+ await boto.messages.sendInteractive({
177
+ to: "17841400000000123", from: contaInstagramId,
178
+ interactive: { type: "generic", elements: [{
179
+ title: "Produto", subtitle: "Disponível na loja",
180
+ image_url: "https://exemplo.com/foto.jpg",
181
+ default_action: { type: "web_url", url: "https://exemplo.com/produto" },
182
+ buttons: [{ type: "postback", title: "Quero saber mais", payload: "produto" }],
183
+ }] },
184
+ });
185
+ ```
186
+
187
+ `button` aceita 1–3 botões e texto até 640 caracteres; `generic` aceita 1–10
188
+ cards com título (até 80 caracteres) e ao menos uma propriedade adicional.
189
+ Subtítulo: até 80 caracteres; até 3 botões por card. Botões usam título de até
190
+ 20 caracteres e postback de até 1000 caracteres; links são HTTPS. A API valida
191
+ os limites (`422`). `tag: "human_agent"` é opcional e depende da flag e da
192
+ janela autorizada pela API. O recibo traz `wamid: null`, `external_id`,
193
+ `channel: "instagram"` e `type: "interactive"`. Os formatos WhatsApp
194
+ `button` com `reply`, `list` e `cta_url` continuam disponíveis.
195
+
166
196
  ## Contas de canal e Regras de comentário
167
197
 
168
198
  ```ts
@@ -188,7 +218,12 @@ await boto.channelAccounts.updateCommentRule(conta.id, regra.id, { is_active: fa
188
218
  `keyword` vazia vale para qualquer comentário e `media_id` vazio para todos os
189
219
  posts. Criar ou ativar exige plano com Regras de comentário (`422
190
220
  plan_restricted`); a mesma palavra-chave no mesmo alvo é `409 duplicate_rule`.
191
- Não há exclusão pela API: desative com `is_active: false`.
221
+ `deleteCommentRule(conta.id, regra.id)` exclui e retorna `{ id, deleted: true }`.
222
+ `keywords` (até 20 expressões), `excluded_keywords` (até 20 exclusões),
223
+ `reply_variations` (até 10 respostas públicas) e `next_post` estão disponíveis
224
+ na criação, leitura e atualização. `keywords` prevalece sobre `keyword`, e
225
+ `reply_variations` sobre `reply_text`; `[]` limpa a lista. `next_post: true`
226
+ aguarda o próximo post e não deve ser combinado com `media_id` explícito.
192
227
 
193
228
  Com `token_status` `expired`, `invalid` ou `revoked`, os envios pela conta
194
229
  falham até reconectá-la em Canais. Mensagens do Instagram editadas pelo contato
@@ -196,6 +231,30 @@ trazem o conteúdo atualizado com `content.edited` (`{ count, at }`); as apagada
196
231
  `revoked_at`. Os Eventos `instagram.message.edited` e `instagram.message.revoked`
197
232
  chegam pelo webhook e por `events.list`.
198
233
 
234
+ ### Perguntas e menu do Instagram
235
+
236
+ ```ts
237
+ const perfil = await boto.channelAccounts.getMessengerProfile(conta.id);
238
+ await boto.channelAccounts.updateMessengerProfile(conta.id, {
239
+ ice_breakers: [{ question: "Quais os horários?", payload: "horarios" }],
240
+ persistent_menu: [{ type: "web_url", title: "Ver loja", url: "https://exemplo.com" }],
241
+ });
242
+ await boto.channelAccounts.updateMessengerProfile(conta.id, { ice_breakers: null });
243
+ await boto.channelAccounts.syncMessengerProfile(conta.id);
244
+ await boto.channelAccounts.deleteMessengerProfile(conta.id);
245
+ ```
246
+
247
+ GET usa `messenger-profile:read`; PATCH, DELETE e sync usam
248
+ `messenger-profile:write`. Sem sandbox. PATCH preserva seções ausentes;
249
+ `null` ou `[]` remove a seção. Até 4 perguntas e 5 itens de menu (`postback`
250
+ ou `web_url`). Perguntas: 80 caracteres; títulos: 20; payloads: 1000; URLs
251
+ http/https: 2000. Os quatro métodos retornam o snapshot com
252
+ `channel_account_id`, `config`, `revision`, `sync_status`, `synced_at`,
253
+ `last_error_code` e `updated_at`. GET lê o espelho salvo; sync verifica/reaplica
254
+ explicitamente o desejado. Falhas de aplicação conservam a configuração para
255
+ retry; `profile_busy` e `profile_sync_unconfirmed` pedem reconciliar após um
256
+ minuto. Sync sem configuração salva retorna `profile_not_configured`.
257
+
199
258
  ## Clientes e templates
200
259
 
201
260
  ```ts
@@ -360,7 +419,7 @@ O SDK cobre os recursos da API `/v1`:
360
419
  - `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
361
420
  - `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)
362
421
  - `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro)
363
- - `channelAccounts` — listar e buscar Contas de canal (WhatsApp e Instagram); **Regras de comentário** do Instagram (listar, buscar, criar, atualizar)
422
+ - `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)
364
423
  - `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
365
424
  - `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
366
425
  - `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
@@ -561,3 +620,10 @@ nova intenção. `unknown` ou `accepted` exigem conciliação antes de considera
561
620
  outro envio. SDK e MCP preservam `outcome` e `retry` da API. Resultados concluídos
562
621
  vencidos são removidos pelo cron a cada minuto; claims incertas não são removidas
563
622
  por tempo, conforme o runbook `botozap/docs/ops/message-send-receipts.md`.
623
+
624
+ ## Instagram — onda 2
625
+
626
+ Regras de comentário incluem `dm_button_title`, `delivery_text` e `delivery_media`.
627
+ Regras de mensagem têm CRUD com gatilhos e ações tipados (`message-rules:read/write`);
628
+ métricas de comentário recebem `from`/`to` (`comment-rules:read`).
629
+ [Contrato e exemplos de SDK, CLI e MCP](../../docs/instagram-wave-two.md).
package/dist/index.cjs CHANGED
@@ -5209,13 +5209,19 @@ var Messages = class {
5209
5209
  return assertSendResult(result);
5210
5210
  }
5211
5211
  /**
5212
- * Envia botões de resposta, lista ou botão de link (WhatsApp; mensagem livre,
5213
- * exige janela de 24h aberta).
5212
+ * Envia button/list/cta_url no WhatsApp ou button/generic no Instagram.
5213
+ * Mensagem livre sujeita à janela do canal.
5214
5214
  */
5215
5215
  async sendInteractive(params, options = {}) {
5216
5216
  return postMessage(
5217
5217
  this.client,
5218
- { to: params.to, from: params.from, type: "interactive", interactive: params.interactive },
5218
+ {
5219
+ to: params.to,
5220
+ from: params.from,
5221
+ type: "interactive",
5222
+ interactive: params.interactive,
5223
+ ...params.tag !== void 0 ? { tag: params.tag } : {}
5224
+ },
5219
5225
  options
5220
5226
  );
5221
5227
  }
@@ -5802,7 +5808,7 @@ var ChannelAccounts = class {
5802
5808
  }
5803
5809
  /**
5804
5810
  * Altera uma Regra de comentário (só os campos enviados). comment-rules:write.
5805
- * `is_active: false` desliga a regra; não há exclusão pela API.
5811
+ * `is_active: false` desliga a regra.
5806
5812
  */
5807
5813
  updateCommentRule(channelAccountId, ruleId, params) {
5808
5814
  return this.client.requestItem(
@@ -5811,10 +5817,71 @@ var ChannelAccounts = class {
5811
5817
  { body: params }
5812
5818
  );
5813
5819
  }
5820
+ /** Exclui uma Regra de comentário. comment-rules:write. */
5821
+ deleteCommentRule(channelAccountId, ruleId) {
5822
+ return this.client.requestItem(
5823
+ "DELETE",
5824
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}`
5825
+ );
5826
+ }
5827
+ /** Resultados da Regra por período e post. comment-rules:read. */
5828
+ getCommentRuleMetrics(channelAccountId, ruleId, params) {
5829
+ return this.client.requestItem(
5830
+ "GET",
5831
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}/metrics`,
5832
+ { query: { from: params.from, to: params.to } }
5833
+ );
5834
+ }
5835
+ /** Lista Regras de mensagem com paginação offset. message-rules:read. */
5836
+ listMessageRules(channelAccountId, params = {}) {
5837
+ return this.client.requestOffsetList(
5838
+ "GET",
5839
+ messageRulesPath(channelAccountId),
5840
+ { query: { page: params.page, per_page: params.per_page } }
5841
+ );
5842
+ }
5843
+ /** Busca uma Regra de mensagem. message-rules:read. */
5844
+ getMessageRule(channelAccountId, ruleId) {
5845
+ return this.client.requestItem("GET", messageRulesPath(channelAccountId, ruleId));
5846
+ }
5847
+ /** Cria uma Regra de mensagem. message-rules:write. */
5848
+ createMessageRule(channelAccountId, params) {
5849
+ return this.client.requestItem("POST", messageRulesPath(channelAccountId), { body: params });
5850
+ }
5851
+ /** PATCH parcial; a API valida o estado final. message-rules:write. */
5852
+ updateMessageRule(channelAccountId, ruleId, params) {
5853
+ return this.client.requestItem("PATCH", messageRulesPath(channelAccountId, ruleId), { body: params });
5854
+ }
5855
+ /** Exclui a Regra preservando Disparos e Eventos. message-rules:write. */
5856
+ deleteMessageRule(channelAccountId, ruleId) {
5857
+ return this.client.requestItem("DELETE", messageRulesPath(channelAccountId, ruleId));
5858
+ }
5859
+ /** Lê o espelho salvo (sem consultar a Meta). messenger-profile:read; sem sandbox. */
5860
+ getMessengerProfile(channelAccountId) {
5861
+ return this.client.requestItem("GET", profilePath(channelAccountId));
5862
+ }
5863
+ /** Salva/aplica apenas as seções enviadas. messenger-profile:write; sem sandbox. */
5864
+ updateMessengerProfile(channelAccountId, params) {
5865
+ return this.client.requestItem("PATCH", profilePath(channelAccountId), { body: params });
5866
+ }
5867
+ /** Remove perguntas e menu, conservando configuração vazia. messenger-profile:write. */
5868
+ deleteMessengerProfile(channelAccountId) {
5869
+ return this.client.requestItem("DELETE", profilePath(channelAccountId));
5870
+ }
5871
+ /** Verifica/reaplica explicitamente o desejado salvo. messenger-profile:write. */
5872
+ syncMessengerProfile(channelAccountId) {
5873
+ return this.client.requestItem("POST", `${profilePath(channelAccountId)}/sync`);
5874
+ }
5814
5875
  };
5876
+ function profilePath(id) {
5877
+ return `/channel_accounts/${enc7(id)}/messenger-profile`;
5878
+ }
5815
5879
  function enc7(id) {
5816
5880
  return encodeURIComponent(id);
5817
5881
  }
5882
+ function messageRulesPath(id, ruleId) {
5883
+ return `/channel_accounts/${enc7(id)}/message-rules${ruleId === void 0 ? "" : `/${enc7(ruleId)}`}`;
5884
+ }
5818
5885
 
5819
5886
  // src/resources/media.ts
5820
5887
  var Media = class {