@botozap/sdk 0.10.0 → 0.11.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,35 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.11.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 0df58da: Instagram nas ferramentas públicas.
8
+
9
+ SDK: `SendResult.wamid` passa a ser `string | null` e ganha `external_id` e
10
+ `channel` — no Instagram a API devolve `wamid: null` com o `mid` em
11
+ `external_id`, e o SDK deixava de aceitar esse recibo (`malformed_response`) em
12
+ `send`, `sendMedia` e `sendReaction`. `messages.send` e `conversations.reply`
13
+ aceitam `quick_replies`; `conversations.reply` usa a Conta de canal como origem
14
+ em Conversas do Instagram; `conversations.list` filtra por `channel` e
15
+ `channel_account_id`. Novo recurso `channelAccounts` (`list`, `get` e Regras de
16
+ comentário: `listCommentRules`, `getCommentRule`, `createCommentRule`,
17
+ `updateCommentRule`). `ChannelAccount.instagram` traz a saúde da conexão
18
+ (`token_status`, `token_expires_at`, `token_refreshed_at`); `Message` tipa
19
+ `content.edited` (`{ count, at }`), `revoked_at`, `channel` e `external_id`.
20
+
21
+ CLI: `messages send --quick-reply`/`--quick-replies-json`, novo
22
+ `messages send-media` (WhatsApp ou Instagram), `conversations list --channel
23
+ --channel-account-id` e o comando `channel-accounts` (com `comment-rules`).
24
+
25
+ MCP: o output schema de envio aceita o recibo do Instagram (antes
26
+ `send_message`, `send_media_message` e `reply_to_conversation` devolviam erro
27
+ em envio entregue) e as telas reconhecem o recibo por `external_id`. Tools
28
+ novas no catálogo completo: `list_channel_accounts`, `list_comment_rules`,
29
+ `get_comment_rule`, `create_comment_rule`, `update_comment_rule`;
30
+ `get_channel_account` fica disponível sem UI no catálogo completo. O perfil
31
+ `assistant` não muda.
32
+
3
33
  ## 0.10.0
4
34
 
5
35
  ### Novidades
package/README.md CHANGED
@@ -61,6 +61,10 @@ const result = await boto.messages.send({
61
61
  console.log(result.wamid, result.status);
62
62
  ```
63
63
 
64
+ No Instagram o recibo traz `wamid: null`, `channel: "instagram"` e o `mid` da
65
+ Meta em `external_id`. Para correlacionar envios de qualquer canal, use
66
+ `result.external_id ?? result.wamid`.
67
+
64
68
  A conta é derivada da chave de API. Você nunca passa um id de conta: o isolamento multi-tenant é garantido no servidor.
65
69
 
66
70
  ## Mensagens
@@ -91,7 +95,8 @@ await boto.messages.send({
91
95
  from: "uuid-ou-phone_number_id",
92
96
  });
93
97
 
94
- // Responder sem combinar manualmente Contato e Número
98
+ // Responder sem combinar manualmente Contato e origem: no WhatsApp sai pelo
99
+ // Número da Conversa; no Instagram, pela Conta de canal (channel_account.id).
95
100
  await boto.conversations.reply("uuid-da-conversa", {
96
101
  text: "Resposta do agente",
97
102
  });
@@ -127,6 +132,20 @@ const r = await boto.messages.sendReaction({
127
132
  });
128
133
  r.reaction?.action; // "react" | "unreact"
129
134
 
135
+ // Instagram: o mesmo endpoint, com o IGSID do contato em `to`. `from` aceita o
136
+ // id da conta na Meta ou o UUID da Conta de canal (channelAccounts.list).
137
+ const ig = await boto.messages.send({
138
+ to: "17841400000000123",
139
+ text: "Tenho estes horários no sábado:",
140
+ // Opções de resposta: só Instagram, só com texto, até 13 (título ≤ 20).
141
+ quick_replies: [
142
+ { title: "9h", payload: "sabado_09" },
143
+ { title: "10h30", payload: "sabado_1030" },
144
+ ],
145
+ });
146
+ ig.wamid; // null
147
+ ig.external_id; // "aWdEZ...mlk" (mid)
148
+
130
149
  // Listar na ordem real das mensagens (histórico importado incluído)
131
150
  const page = await boto.messages.list({ sort: "event_at", limit: 50 });
132
151
  page.data[0]?.source; // "api" | "app" | "history" | "broadcast"
@@ -138,6 +157,45 @@ invalid_request`; reação recusa com `invalid_reaction`, `missing_reaction_targ
138
157
  `reaction_target_not_found`, `reaction_target_invalid` ou `reaction_target_expired`.
139
158
  O cursor de `messages.list` vale só para o `sort` que o gerou.
140
159
 
160
+ `quick_replies` só existe no Instagram e só com texto, dentro da janela de 24h:
161
+ no WhatsApp a API recusa com `channel_not_supported`; acima de 13 opções,
162
+ `too_many_quick_replies`; título acima de 20 caracteres,
163
+ `quick_reply_title_too_long`; fora da janela, `quick_replies_window_closed`.
164
+ No Instagram não existe `caption` em mídia (`unsupported_caption`).
165
+
166
+ ## Contas de canal e Regras de comentário
167
+
168
+ ```ts
169
+ // Números do WhatsApp e Contas do Instagram lado a lado
170
+ const { data: contas } = await boto.channelAccounts.list({ channel: "instagram" });
171
+ const conta = await boto.channelAccounts.get(contas[0]!.id); // UUID ou id na Meta
172
+ // Saúde da conexão do Instagram (o token nunca é exposto)
173
+ conta.instagram?.token_status; // "ok" | "expiring" | "expired" | "invalid" | "revoked" | "unknown"
174
+
175
+ // Conversas de uma origem específica
176
+ await boto.conversations.list({ channel: "instagram", channel_account_id: conta.id });
177
+
178
+ // Regras de comentário (comment-rules:read / comment-rules:write)
179
+ const regra = await boto.channelAccounts.createCommentRule(conta.id, {
180
+ keyword: "preço",
181
+ dm_text: "Oi! Te mandei os valores por aqui.",
182
+ reply_text: "Te chamei no direct!",
183
+ });
184
+ await boto.channelAccounts.listCommentRules(conta.id);
185
+ await boto.channelAccounts.updateCommentRule(conta.id, regra.id, { is_active: false });
186
+ ```
187
+
188
+ `keyword` vazia vale para qualquer comentário e `media_id` vazio para todos os
189
+ posts. Criar ou ativar exige plano com Regras de comentário (`422
190
+ 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`.
192
+
193
+ Com `token_status` `expired`, `invalid` ou `revoked`, os envios pela conta
194
+ falham até reconectá-la em Canais. Mensagens do Instagram editadas pelo contato
195
+ trazem o conteúdo atualizado com `content.edited` (`{ count, at }`); as apagadas,
196
+ `revoked_at`. Os Eventos `instagram.message.edited` e `instagram.message.revoked`
197
+ chegam pelo webhook e por `events.list`.
198
+
141
199
  ## Clientes e templates
142
200
 
143
201
  ```ts
@@ -215,8 +273,8 @@ if (page.paging.next) {
215
273
  page = await boto.contacts.list({ limit: 50, after: page.paging.next });
216
274
  }
217
275
 
218
- // Offset/página (customers, templates, broadcasts, phoneNumbers, users,
219
- // conversations.listAssignments): params { page, per_page }.
276
+ // Offset/página (customers, templates, broadcasts, phoneNumbers,
277
+ // channelAccounts, users, conversations.listAssignments): params { page, per_page }.
220
278
  const { data, meta } = await boto.templates.list({ page: 2, per_page: 20 });
221
279
  console.log(meta.total_count, meta.total_pages);
222
280
  ```
@@ -295,13 +353,14 @@ new BotoZap({
295
353
 
296
354
  O SDK cobre os recursos da API `/v1`:
297
355
 
298
- - `messages` — enviar texto, template e mídia por link, **listar** e buscar por id
356
+ - `messages` — enviar texto (com `quick_replies` no Instagram), template e mídia por link, **listar** e buscar por id
299
357
  - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
300
358
  - `templates` — listar, buscar, **criar**
301
359
  - `broadcasts` — criar, destinatários, agendar, enviar, cancelar
302
360
  - `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
303
- - `conversations` — listar, buscar, atualizar, 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)
361
+ - `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)
304
362
  - `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)
305
364
  - `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
306
365
  - `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
307
366
  - `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
package/dist/index.cjs CHANGED
@@ -53,6 +53,7 @@ __export(index_exports, {
53
53
  BotoZap: () => BotoZap,
54
54
  BotoZapError: () => BotoZapError,
55
55
  Calendar: () => Calendar,
56
+ ChannelAccounts: () => ChannelAccounts,
56
57
  ContactFields: () => ContactFields,
57
58
  ContactStages: () => ContactStages,
58
59
  CrmResource: () => CrmResource,
@@ -5168,7 +5169,8 @@ var Messages = class {
5168
5169
  to: params.to,
5169
5170
  type: "text",
5170
5171
  text: { body: params.text },
5171
- from: params.from
5172
+ from: params.from,
5173
+ ...params.quick_replies !== void 0 ? { quick_replies: params.quick_replies } : {}
5172
5174
  }
5173
5175
  });
5174
5176
  return assertSendResult(result);
@@ -5232,8 +5234,8 @@ var Messages = class {
5232
5234
  );
5233
5235
  }
5234
5236
  /**
5235
- * Reage a uma mensagem recebida (WhatsApp). `emoji: ""` retira a reação.
5236
- * O retorno traz `reaction` com o alvo e a ação.
5237
+ * Reage a uma mensagem recebida (WhatsApp ou Instagram). `emoji: ""` retira
5238
+ * a reação. O retorno traz `reaction` com o alvo e a ação.
5237
5239
  */
5238
5240
  async sendReaction(params, options = {}) {
5239
5241
  return postMessage(
@@ -5280,10 +5282,12 @@ async function postMessage(client, body, options) {
5280
5282
  return assertSendResult(result);
5281
5283
  }
5282
5284
  function assertSendResult(value) {
5283
- if (typeof value.wamid !== "string" || typeof value.to !== "string" || typeof value.status !== "string" || value.id !== null && typeof value.id !== "string") {
5285
+ const hasWamid = typeof value?.wamid === "string";
5286
+ const hasExternalId = value?.wamid === null && typeof value.external_id === "string" && value.external_id !== "";
5287
+ if (!value || !(hasWamid || hasExternalId) || typeof value.to !== "string" || typeof value.status !== "string" || value.id !== null && typeof value.id !== "string") {
5284
5288
  throw new BotoZapError(
5285
5289
  "malformed_response",
5286
- "resposta de envio sem id/wamid/to/status v\xE1lidos",
5290
+ "resposta de envio sem id/wamid (ou external_id)/to/status v\xE1lidos",
5287
5291
  0
5288
5292
  );
5289
5293
  }
@@ -5555,7 +5559,9 @@ var Conversations = class {
5555
5559
  phone_number_id: params.phone_number_id,
5556
5560
  status: params.status,
5557
5561
  contact: params.contact,
5558
- phone_number: params.phone_number
5562
+ phone_number: params.phone_number,
5563
+ channel: params.channel,
5564
+ channel_account_id: params.channel_account_id
5559
5565
  }
5560
5566
  }
5561
5567
  );
@@ -5567,17 +5573,19 @@ var Conversations = class {
5567
5573
  );
5568
5574
  }
5569
5575
  /**
5570
- * Responde uma Conversa sem o chamador precisar combinar Contato e Número.
5571
- * A leitura e o envio usam a mesma chave; o POST /messages revalida Conta,
5572
- * ambiente, identidade, janela, quota e billing antes de chamar a Meta.
5576
+ * Responde uma Conversa sem o chamador precisar combinar Contato e origem.
5577
+ * No WhatsApp a origem é o Número da Conversa; no Instagram, a Conta de
5578
+ * canal (`channel_account.id`). A leitura e o envio usam a mesma chave; o
5579
+ * POST /messages revalida Conta, ambiente, identidade, janela, quota e
5580
+ * billing antes de chamar a Meta.
5573
5581
  */
5574
5582
  async reply(id, params, options = {}) {
5575
5583
  const conversation = await this.get(id);
5576
- const from = conversation.phone_number_id;
5584
+ const from = conversation.channel === "instagram" ? conversation.channel_account?.id : conversation.phone_number_id;
5577
5585
  if (typeof from !== "string" || !from.trim()) {
5578
5586
  throw new BotoZapError(
5579
5587
  "malformed_response",
5580
- "Conversa sem UUID interno do N\xFAmero de origem.",
5588
+ conversation.channel === "instagram" ? "Conversa do Instagram sem UUID da Conta de canal de origem." : "Conversa sem UUID interno do N\xFAmero de origem.",
5581
5589
  0
5582
5590
  );
5583
5591
  }
@@ -5590,7 +5598,15 @@ var Conversations = class {
5590
5598
  422
5591
5599
  );
5592
5600
  }
5593
- return this.client.messages.send({ to, text: params.text, from }, options);
5601
+ return this.client.messages.send(
5602
+ {
5603
+ to,
5604
+ text: params.text,
5605
+ from,
5606
+ ...params.quick_replies !== void 0 ? { quick_replies: params.quick_replies } : {}
5607
+ },
5608
+ options
5609
+ );
5594
5610
  }
5595
5611
  update(id, params) {
5596
5612
  return this.client.requestItem(
@@ -5732,6 +5748,74 @@ function enc6(id) {
5732
5748
  return encodeURIComponent(id);
5733
5749
  }
5734
5750
 
5751
+ // src/resources/channel-accounts.ts
5752
+ var ChannelAccounts = class {
5753
+ constructor(client) {
5754
+ this.client = client;
5755
+ }
5756
+ client;
5757
+ /** Lista as Contas de canal da conta (paginação por offset/página). numbers:read. */
5758
+ list(params = {}) {
5759
+ return this.client.requestOffsetList(
5760
+ "GET",
5761
+ "/channel_accounts",
5762
+ {
5763
+ query: {
5764
+ page: params.page,
5765
+ per_page: params.per_page,
5766
+ channel: params.channel,
5767
+ customer_id: params.customer_id
5768
+ }
5769
+ }
5770
+ );
5771
+ }
5772
+ /** Busca uma Conta de canal pelo UUID interno ou pelo id na Meta (`external_id`). numbers:read. */
5773
+ get(id) {
5774
+ return this.client.requestItem("GET", `/channel_accounts/${enc7(id)}`);
5775
+ }
5776
+ /** Lista as Regras de comentário de uma Conta do Instagram (UUID). comment-rules:read. */
5777
+ listCommentRules(channelAccountId, params = {}) {
5778
+ return this.client.requestOffsetList(
5779
+ "GET",
5780
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules`,
5781
+ { query: { page: params.page, per_page: params.per_page } }
5782
+ );
5783
+ }
5784
+ /** Busca uma Regra de comentário. comment-rules:read. */
5785
+ getCommentRule(channelAccountId, ruleId) {
5786
+ return this.client.requestItem(
5787
+ "GET",
5788
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}`
5789
+ );
5790
+ }
5791
+ /**
5792
+ * Cria uma Regra de comentário. comment-rules:write. Exige plano que inclua
5793
+ * Regras de comentário (senão 422 `plan_restricted`); palavra-chave repetida
5794
+ * para o mesmo alvo é 409 `duplicate_rule`.
5795
+ */
5796
+ createCommentRule(channelAccountId, params) {
5797
+ return this.client.requestItem(
5798
+ "POST",
5799
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules`,
5800
+ { body: params }
5801
+ );
5802
+ }
5803
+ /**
5804
+ * 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.
5806
+ */
5807
+ updateCommentRule(channelAccountId, ruleId, params) {
5808
+ return this.client.requestItem(
5809
+ "PATCH",
5810
+ `/channel_accounts/${enc7(channelAccountId)}/comment-rules/${enc7(ruleId)}`,
5811
+ { body: params }
5812
+ );
5813
+ }
5814
+ };
5815
+ function enc7(id) {
5816
+ return encodeURIComponent(id);
5817
+ }
5818
+
5735
5819
  // src/resources/media.ts
5736
5820
  var Media = class {
5737
5821
  constructor(client) {
@@ -5890,6 +5974,8 @@ var BotoZap = class {
5890
5974
  conversations;
5891
5975
  webhooks;
5892
5976
  phoneNumbers;
5977
+ /** Contas de canal (WhatsApp e Instagram) e Regras de comentário do Instagram. */
5978
+ channelAccounts;
5893
5979
  contactStages;
5894
5980
  contactFields;
5895
5981
  calendar;
@@ -5943,6 +6029,7 @@ var BotoZap = class {
5943
6029
  this.conversations = new Conversations(this);
5944
6030
  this.webhooks = new Webhooks(this);
5945
6031
  this.phoneNumbers = new PhoneNumbers(this);
6032
+ this.channelAccounts = new ChannelAccounts(this);
5946
6033
  this.media = new Media(this);
5947
6034
  this.events = new Events(this);
5948
6035
  this.usage = new Usage(this);
@@ -6142,6 +6229,7 @@ var WEBHOOK_CATEGORIES = [
6142
6229
  BotoZap,
6143
6230
  BotoZapError,
6144
6231
  Calendar,
6232
+ ChannelAccounts,
6145
6233
  ContactFields,
6146
6234
  ContactStages,
6147
6235
  CrmResource,