@botozap/sdk 0.29.0 → 0.30.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,31 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.30.0
4
+
5
+ ### Minor Changes
6
+
7
+ - c72e511: Arquivos do agente (#1447): fotos, vídeos e PDFs que o agente de IA manda na conversa. SDK: `ai.files` (`list`, `get` com `usages` e `preview_url`, `update`, `remove` e `upload` pelo upload direto com `kind: "file"`), `AiAgentFile` e `file_id` no `messages.sendMedia` no lugar do `link`. MCP: `ai_files_list`, `ai_files_get`, `ai_files_update`, `ai_files_remove`, `kind: "file"` (com `description` e `caption`) no `ai_uploads_prepare` e `file_id` no `send_media_message`. CLI: os comandos `ai files`.
8
+
9
+ Tipos: `link` passa a ser opcional em `SendImageParams`, `SendVideoParams` e `SendDocumentParams` (um dos dois, `link` ou `file_id`; o SDK recusa os dois ou nenhum); código que lia `params.link` como `string` precisa tratar o `undefined`. `AiToolId` ganha `conversations.attach_files`, e `AiAgentConfig`, `file_ids`. MCP: `ai_files_upload` (conteúdo em `file_base64`) e os arquivos na configuração de `ai_agents_create`/`ai_agents_save_draft`. CLI: `ai files upload` (`file_path`) e `messages send-media --file-id`.
10
+
11
+ - e4d6580: Avisos de casos no WhatsApp: o mapa de variáveis aceita `contact_phone` (telefone do contato atendido, como `+5579999997101`, ou "não informado" no Instagram) e `contact_name_and_phone` (`Nome (+telefone)`, ou só o nome quando não há telefone) (SDK, em `AiNoticeField`; MCP, no `variable_map` de `ai_notices_update`).
12
+ - 05fa855: Envios sem confirmação da Meta, como o aviso na conversa no painel: `conversations.listPendingSends(id)` lista os envios manuais do WhatsApp (API ou painel) que a Meta não confirmou em cerca de 5 minutos, e `conversations.markPendingSend(id, sendId, "sent" | "not_sent")` diz se o envio chegou ao contato (`sent` põe a mensagem no histórico sem o id da Meta; `not_sent` libera para enviar de novo; nada é reenviado) (SDK). Entram `list_pending_sends` e `mark_pending_send`, só no catálogo completo (MCP). `botozap conversations pending-sends <id>` e `botozap conversations mark-send <id> <sendId> --outcome sent|not_sent` (CLI).
13
+ - 1bfb57a: Roteador: membro com `keep_until_closed` (agente fixo). Escolhido, ele fica com a conversa até a equipe fechar e o contato voltar a escrever, sem trocar de agente mesmo com outra intenção. Aceito em `ai_routers_create`/`ai_routers_update` no MCP e no tipo `AiRouterConfig` do SDK.
14
+ - fc41276: Teste de roteamento com `last_sent_message`: a última mensagem enviada ao contato, que o classificador do roteador lê como contexto para entender respostas curtas como "Sim". Aceito em `ai.routers.test` no SDK e em `ai_routers_test` no MCP.
15
+
16
+ ### Patch Changes
17
+
18
+ - 1270acc: Etapa do funil criada pelo cliente vem com `key: null`. O MCP deixa de recusar a resposta de `list_contact_stages` e `create_contact_stage` nesse caso, e o tipo `ContactStage.key` do SDK passa a `string | null`.
19
+ - 42e3e8b: A descrição da reinscrição (`resubscribe_phone_number_webhooks` no MCP, `phoneNumbers.resubscribeWebhooks` no SDK) diz que `missing` depois de reinscrever pede o link de setup: é o que a API responde quando a conta do WhatsApp mudou de portfólio na Meta.
20
+
21
+ ## 0.29.1
22
+
23
+ ### Patch Changes
24
+
25
+ - a62782e: Casos abertos pela etapa "Avisar a equipe" de um follow-up têm a origem `followup`: `AiCaseSource` passa a incluí-la, na leitura do caso e no filtro `source` de `ai.cases.list`. O filtro de `ai_cases_list` no MCP fica como está, porque a definição anunciada ao ChatGPT é congelada (nova revisão da OpenAI); a origem aparece normalmente nos casos que ele devolve.
26
+
27
+ O agente ganha `followup.return_template` (`{ template_id, variable_map }` ou `null`): o template aprovado que o retorno agendado por ele envia com a janela de 24h fechada, no SDK (`AiAgentConfig`) e nas ferramentas de agente do MCP.
28
+
3
29
  ## 0.29.0
4
30
 
5
31
  ### Minor Changes
package/README.md CHANGED
@@ -282,6 +282,13 @@ await boto.messages.sendMedia({
282
282
  });
283
283
  ```
284
284
 
285
+ Um arquivo pronto da biblioteca do agente (`ai.files.list`) sai por `file_id` no lugar do `link`
286
+ (foto, vídeo e PDF; um dos dois). A legenda da biblioteca não entra sozinha:
287
+
288
+ ```ts
289
+ await boto.messages.sendMedia({ to: "5511999999999", type: "image", file_id: arquivo.id, caption: "Ouro 18k" });
290
+ ```
291
+
285
292
  `caption` é aceito em `image`, `video` e `document`; `audio` aceita apenas o
286
293
  link; `filename` é exclusivo de `document`.
287
294
 
package/dist/index.cjs CHANGED
@@ -35,6 +35,7 @@ __export(index_exports, {
35
35
  AiEligibilityResource: () => AiEligibilityResource,
36
36
  AiEvolutionResource: () => AiEvolutionResource,
37
37
  AiExecutionsResource: () => AiExecutionsResource,
38
+ AiFilesResource: () => AiFilesResource,
38
39
  AiFollowupFlowsResource: () => AiFollowupFlowsResource,
39
40
  AiFollowupsResource: () => AiFollowupsResource,
40
41
  AiInferencesResource: () => AiInferencesResource,
@@ -175,7 +176,12 @@ async function uploadArtifact(client, input) {
175
176
  pdf: "application/pdf",
176
177
  txt: "text/plain",
177
178
  md: "text/markdown",
178
- csv: "text/csv"
179
+ csv: "text/csv",
180
+ jpg: "image/jpeg",
181
+ jpeg: "image/jpeg",
182
+ png: "image/png",
183
+ mp4: "video/mp4",
184
+ mov: "video/quicktime"
179
185
  }[ext] || file.type || "application/octet-stream";
180
186
  const metadata = {
181
187
  customer_id: String(input.customer_id),
@@ -184,7 +190,12 @@ async function uploadArtifact(client, input) {
184
190
  mime_type: mime,
185
191
  byte_size: file.size,
186
192
  sha256,
187
- ...kind === "knowledge" ? { name: String(input.name ?? "") } : {
193
+ ...kind === "file" ? {
194
+ name: String(input.name ?? ""),
195
+ description: String(input.description ?? ""),
196
+ ...input.caption ? { caption: String(input.caption) } : {}
197
+ } : {},
198
+ ...kind === "knowledge" ? { name: String(input.name ?? "") } : kind === "file" ? {} : {
188
199
  ...input.id ? {
189
200
  skill_id: String(input.id),
190
201
  expected_revision: String(input.expected_revision ?? "")
@@ -1959,6 +1970,10 @@ var AI_OPERATIONS = [
1959
1970
  sticky_intent: {
1960
1971
  type: "nullableString",
1961
1972
  optional: true
1973
+ },
1974
+ last_sent_message: {
1975
+ type: "nullableString",
1976
+ optional: true
1962
1977
  }
1963
1978
  }
1964
1979
  },
@@ -2833,14 +2848,14 @@ var AI_OPERATIONS = [
2833
2848
  method: "POST",
2834
2849
  path: "/ai/uploads",
2835
2850
  shape: "item",
2836
- description: "Prepara upload direto. Envie bytes por PUT na URL assinada com os headers retornados, sem Authorization BotoZap. Guarde upload_id para finalizar a mesma importa\xE7\xE3o.",
2851
+ description: "Prepara upload direto. Envie bytes por PUT na URL assinada com os headers retornados, sem Authorization BotoZap. Guarde upload_id para finalizar a mesma importa\xE7\xE3o. kind=file (foto JPG/PNG, v\xEDdeo MP4/MOV ou PDF at\xE9 25 MiB, para o agente mandar na conversa) exige name (at\xE9 80) e description (quando o agente deve mandar, at\xE9 500); caption \xE9 opcional (at\xE9 1.024 caracteres e 1.000 bytes).",
2837
2852
  fields: {
2838
2853
  customer_id: {
2839
2854
  type: "uuid",
2840
2855
  optional: false
2841
2856
  },
2842
2857
  kind: {
2843
- type: "knowledge|skill",
2858
+ type: "knowledge|skill|file",
2844
2859
  optional: false
2845
2860
  },
2846
2861
  file_name: {
@@ -2863,6 +2878,14 @@ var AI_OPERATIONS = [
2863
2878
  type: "string",
2864
2879
  optional: true
2865
2880
  },
2881
+ description: {
2882
+ type: "string",
2883
+ optional: true
2884
+ },
2885
+ caption: {
2886
+ type: "string",
2887
+ optional: true
2888
+ },
2866
2889
  skill_id: {
2867
2890
  type: "uuid",
2868
2891
  optional: true
@@ -3936,6 +3959,99 @@ var AI_OPERATIONS = [
3936
3959
  optional: false
3937
3960
  }
3938
3961
  }
3962
+ },
3963
+ // #1447 arquivos do agente: appended so existing indexes stay stable.
3964
+ {
3965
+ group: "files",
3966
+ name: "list",
3967
+ method: "GET",
3968
+ path: "/ai/files",
3969
+ shape: "item",
3970
+ description: "Biblioteca de fotos, v\xEDdeos e PDFs que o agente pode mandar na conversa, do mais novo ao mais antigo, com status (processing enquanto converte, ready, failed com last_error).",
3971
+ fields: {
3972
+ customer_id: {
3973
+ type: "uuid",
3974
+ optional: false
3975
+ }
3976
+ }
3977
+ },
3978
+ {
3979
+ group: "files",
3980
+ name: "get",
3981
+ method: "GET",
3982
+ path: "/ai/files/:id",
3983
+ shape: "item",
3984
+ description: "Um arquivo da biblioteca, as vers\xF5es de agente que o usam (usages) e um link curto para ver (preview_url, vence em preview_expires_at; n\xE3o guarde nem registre).",
3985
+ fields: {
3986
+ customer_id: {
3987
+ type: "uuid",
3988
+ optional: false
3989
+ },
3990
+ id: {
3991
+ type: "uuid",
3992
+ optional: false
3993
+ }
3994
+ }
3995
+ },
3996
+ {
3997
+ group: "files",
3998
+ name: "update",
3999
+ method: "PATCH",
4000
+ path: "/ai/files/:id",
4001
+ shape: "item",
4002
+ description: "Edita nome, description (quando o agente deve mandar), caption e active (false arquiva) com expected_revision. Vale na hora para os agentes publicados que usam o arquivo. Arquivar o que est\xE1 numa vers\xE3o publicada \xE9 recusado (409 in_use).",
4003
+ fields: {
4004
+ customer_id: {
4005
+ type: "uuid",
4006
+ optional: false
4007
+ },
4008
+ id: {
4009
+ type: "uuid",
4010
+ optional: false
4011
+ },
4012
+ expected_revision: {
4013
+ type: "revision",
4014
+ optional: false
4015
+ },
4016
+ name: {
4017
+ type: "string",
4018
+ optional: true
4019
+ },
4020
+ description: {
4021
+ type: "string",
4022
+ optional: true
4023
+ },
4024
+ caption: {
4025
+ type: "string",
4026
+ optional: true
4027
+ },
4028
+ active: {
4029
+ type: "boolean",
4030
+ optional: true
4031
+ }
4032
+ }
4033
+ },
4034
+ {
4035
+ group: "files",
4036
+ name: "remove",
4037
+ method: "DELETE",
4038
+ path: "/ai/files/:id",
4039
+ shape: "empty",
4040
+ description: "Apaga de vez (pelo OAuth, s\xF3 Administrador). Arquivo numa vers\xE3o publicada de agente \xE9 recusado (409 in_use); as mensagens que j\xE1 o mandaram continuam com a m\xEDdia.",
4041
+ fields: {
4042
+ customer_id: {
4043
+ type: "uuid",
4044
+ optional: false
4045
+ },
4046
+ id: {
4047
+ type: "uuid",
4048
+ optional: false
4049
+ },
4050
+ expected_revision: {
4051
+ type: "revision",
4052
+ optional: false
4053
+ }
4054
+ }
3939
4055
  }
3940
4056
  ];
3941
4057
 
@@ -4732,10 +4848,42 @@ var AiStyleAdjustmentsResource = class {
4732
4848
  return request(this.client, named("styleAdjustments", "save"), input);
4733
4849
  }
4734
4850
  };
4851
+ var AiFilesResource = class {
4852
+ constructor(client) {
4853
+ this.client = client;
4854
+ }
4855
+ client;
4856
+ /** GET /ai/files */
4857
+ list(input) {
4858
+ return request(this.client, named("files", "list"), input);
4859
+ }
4860
+ /** GET /ai/files/:id — com quem usa e o link curto de prévia. */
4861
+ get(input) {
4862
+ return request(this.client, named("files", "get"), input);
4863
+ }
4864
+ /** PATCH /ai/files/:id — vale na hora para os agentes publicados que usam o arquivo. */
4865
+ update(input) {
4866
+ return request(this.client, named("files", "update"), input);
4867
+ }
4868
+ /** DELETE /ai/files/:id — 409 in_use se o arquivo está numa versão publicada. */
4869
+ remove(input) {
4870
+ return request(this.client, named("files", "remove"), input);
4871
+ }
4872
+ /**
4873
+ * Sobe foto (JPG/PNG), vídeo (MP4/MOV) ou PDF de até 25 MiB pelo upload direto (prepare, PUT na URL
4874
+ * assinada, complete). Repetir com os mesmos bytes e dados reaproveita o envio. Vídeo do iPhone e foto
4875
+ * grande voltam `processing` e ficam `ready` depois da conversão.
4876
+ */
4877
+ upload(input) {
4878
+ if (!input.file.size || input.file.size > 25 * 1024 * 1024) throw new Error("Arquivo vazio ou maior que 25 MiB.");
4879
+ return uploadArtifact(this.client, { ...input, kind: "file" });
4880
+ }
4881
+ };
4735
4882
  var Ai = class {
4736
4883
  constructor(client) {
4737
4884
  this.client = client;
4738
4885
  this.uploads = new AiUploadsResource(client);
4886
+ this.files = new AiFilesResource(client);
4739
4887
  this.agents = new AiAgentsResource(client);
4740
4888
  this.credentials = new AiCredentialsResource(client);
4741
4889
  this.providers = new AiProvidersResource(client);
@@ -4760,6 +4908,7 @@ var Ai = class {
4760
4908
  }
4761
4909
  client;
4762
4910
  uploads;
4911
+ files;
4763
4912
  agents;
4764
4913
  credentials;
4765
4914
  providers;
@@ -5282,7 +5431,11 @@ var Messages = class {
5282
5431
  }
5283
5432
  /** Envia mídia por URL pública. */
5284
5433
  async sendMedia(params, options = {}) {
5285
- const media = { link: params.link };
5434
+ const fileId = "file_id" in params ? params.file_id : void 0;
5435
+ if (fileId === void 0 === (params.link === void 0)) {
5436
+ throw new Error("Informe link ou file_id (um dos dois).");
5437
+ }
5438
+ const media = fileId !== void 0 ? { file_id: fileId } : { link: params.link };
5286
5439
  if ("caption" in params && params.caption !== void 0) {
5287
5440
  media.caption = params.caption;
5288
5441
  }
@@ -5850,6 +6003,27 @@ var Conversations = class {
5850
6003
  `/conversations/${enc4(id)}/read`
5851
6004
  );
5852
6005
  }
6006
+ /**
6007
+ * Envios manuais do WhatsApp da conversa que a Meta não confirmou em cerca de 5 minutos, como o
6008
+ * aviso na conversa no painel. Quando a Meta confirma, a mensagem entra no histórico sozinha.
6009
+ * Envios da IA, respostas automáticas, transmissões, réguas e Instagram têm conciliação própria
6010
+ * e não aparecem. Conversa de outra Conta: 404. Scope `conversations:read`.
6011
+ */
6012
+ listPendingSends(id) {
6013
+ return this.client.requestItem("GET", `/conversations/${enc4(id)}/pending-sends`);
6014
+ }
6015
+ /**
6016
+ * Diz se o envio sem confirmação chegou ao contato, como "Saiu" e "Não saiu" no painel:
6017
+ * `sent` põe a mensagem no histórico (sem o id da Meta); `not_sent` libera para enviar de novo.
6018
+ * Nada é reenviado. Envio já resolvido: 409 `send_not_pending`. Scope `messages:send`.
6019
+ */
6020
+ markPendingSend(id, sendId, outcome) {
6021
+ return this.client.requestItem(
6022
+ "POST",
6023
+ `/conversations/${enc4(id)}/pending-sends/${enc4(sendId)}`,
6024
+ { body: { outcome } }
6025
+ );
6026
+ }
5853
6027
  /**
5854
6028
  * Exclui a conversa, com efeito imediato e sem volta: mensagens, notas,
5855
6029
  * atribuições, vínculos com oportunidades e demandas e o que a IA guardou
@@ -6188,8 +6362,11 @@ var PhoneNumbers = class {
6188
6362
  /**
6189
6363
  * Inscreve o BotoZap de novo para receber as mensagens do número, com a
6190
6364
  * autorização já guardada, sem refazer a conexão. Resolve a prontidão
6191
- * `webhooks_lost`; autorização recusada pela Meta responde 409
6192
- * `reconnect_required` (aí só o link de setup resolve). Scope `numbers:write`.
6365
+ * `webhooks_lost` quando o app saiu da conta do WhatsApp. Se a conta mudou de
6366
+ * portfólio na Meta, devolve `missing`, e autorização recusada pela Meta
6367
+ * responde 409 `reconnect_required`: nos dois casos, só o link de setup
6368
+ * resolve. `unknown` = a Meta não confirmou agora; confira com `health` em
6369
+ * instantes. Scope `numbers:write`.
6193
6370
  */
6194
6371
  resubscribeWebhooks(id) {
6195
6372
  return this.client.requestItem("POST", `/phone_numbers/${enc6(id)}/webhook-subscription`);
@@ -6925,6 +7102,7 @@ var WEBHOOK_CATEGORIES = [
6925
7102
  AiEligibilityResource,
6926
7103
  AiEvolutionResource,
6927
7104
  AiExecutionsResource,
7105
+ AiFilesResource,
6928
7106
  AiFollowupFlowsResource,
6929
7107
  AiFollowupsResource,
6930
7108
  AiInferencesResource,