@botozap/sdk 0.4.1 → 0.7.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,37 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 5ffc8f4: Cover the API additions of 2026-09-25:
8
+
9
+ - `Contact.display_name` (the name the business gives the contact, 1–200 characters; `null` when unset) and `display_name` on `CreateContactParams`/`UpdateContactParams` (`null` or `""` clears it). It is independent from `profile_name`, which comes from the channel.
10
+ - `phoneNumbers.update(id, { label })` is back: `PATCH /v1/phone_numbers/:id` now accepts the local `label` (up to 100 characters, no control characters; `null` or `""` clears). `PhoneNumber.label` is typed and `UpdatePhoneNumberParams` is exported.
11
+ - New `usage.metaCosts({ customer_id?, from?, to? })` for `GET /v1/usage/meta-costs` (scope `customers:read`), fully typed as `MetaCostReport` (per-currency `totals`, `by_day`, `by_category` with `cost`, `estimated_cost` and `cost_source`; `unavailable`/`unavailable_reason`, `estimate` and `sync`). Missing Meta cost stays `null`, never `0`.
12
+ - `Conversation` declares `entry_point` (`"ctwa" | "organic" | null`), `referral` (`ConversationReferral`: `source_id`, `source_url`, `headline`, `ctwa_clid`, `received_at`), `fep_expires_at` and `fep_reply_by`.
13
+
14
+ ## 0.6.0
15
+
16
+ ### Minor Changes
17
+
18
+ - 5e435ea: `Appointment.google_etag` and `Appointment.google_base_data` become optional and deprecated: they are internal Google Calendar sync data and the API stops sending them on 2026-10-26.
19
+
20
+ ## 0.5.0
21
+
22
+ ### Minor Changes
23
+
24
+ - eda9708: `AiAgent` gains `lifecycle`, `serving`, `serving_via` and `channel_account_id`, returned by `ai.agents.list` and `ai.agents.get`.
25
+ - 4127500: **Breaking:** remove WhatsApp Flows (`client.flows`, the `Flow`/`FlowVersion` types and the `CreateFlowParams`/`ListFlowsParams`/`FlowPhoneParams`/`CreateFlowVersionParams`/`SetFlowDataEndpointParams` exports). The API no longer serves `/v1/flows/*`; every call already failed with 404. AI follow-up flows (`ai.followupFlows`) are unaffected.
26
+
27
+ Align three types with the API:
28
+
29
+ - `CreateWebhookParams`/`UpdateWebhookParams` accept `customer_id` (limits deliveries to one Customer of the account; `null` on update removes the filter) and `Webhook` declares `customer_id`.
30
+ - **Breaking (types only):** `broadcasts.addRecipients` takes `BroadcastRecipientInput[]` (`{ to_recipient, components? }`) instead of `unknown[]`; plain strings were always rejected per item by the API. `AddRecipientsResult.errors` is typed as `AddRecipientsError[]` (`{ index, to_recipient?, reason }`).
31
+ - **Breaking (types only):** `BotoZapEvent.message_id` is `string | null` (the WhatsApp `wamid`, `null` outside WhatsApp) and the event declares `external_id` (channel message id: `wamid` on WhatsApp, `mid` on Instagram).
32
+
33
+ - 3b79628: `webhooks.update` accepts `secret` to rotate the signing secret (`PATCH /v1/webhooks/:id`).
34
+
3
35
  ## 0.4.1
4
36
 
5
37
  ### Patch Changes
package/README.md CHANGED
@@ -174,7 +174,7 @@ if (page.paging.next) {
174
174
  page = await boto.contacts.list({ limit: 50, after: page.paging.next });
175
175
  }
176
176
 
177
- // Offset/página (customers, templates, broadcasts, phoneNumbers, users, flows,
177
+ // Offset/página (customers, templates, broadcasts, phoneNumbers, users,
178
178
  // conversations.listAssignments): params { page, per_page }.
179
179
  const { data, meta } = await boto.templates.list({ page: 2, per_page: 20 });
180
180
  console.log(meta.total_count, meta.total_pages);
@@ -231,13 +231,13 @@ O SDK cobre os recursos da API `/v1`:
231
231
  - `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
232
232
  - `templates` — listar, buscar, **criar**
233
233
  - `broadcasts` — criar, destinatários, agendar, enviar, cancelar
234
- - `contacts` — listar, buscar, criar, atualizar, remover
235
- - `conversations` — listar, buscar, atualizar, atribuições
236
- - `webhooks` — CRUD e teste
237
- - `phoneNumbers` — listar, buscar, remover, saúde (a rota de update não expõe campos editáveis, então o SDK não tem `phoneNumbers.update`)
238
- - `flows` — criar, versionar, publicar, data endpoint (as operações por flow exigem `phone_number_id`, que amarra o flow à sua WABA)
234
+ - `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
235
+ - `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)
236
+ - `webhooks` — CRUD e teste; `customer_id` opcional limita as entregas a um Cliente da Conta (`null` no update remove o filtro)
237
+ - `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
239
238
  - `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
240
239
  - `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
240
+ - `usage` — `metaCosts`: custo aproximado da Meta por dia, categoria e moeda (Pricing Analytics), com estimativa por tarifa publicada onde a Meta não devolveu custo
241
241
  - `users`, `apiLogs`, `webhookDeliveries` — leitura
242
242
 
243
243
  Inbound e mudanças de status compartilham um stream crescente. Guarde
@@ -254,6 +254,11 @@ for (const event of page.data) {
254
254
  ultimoCursor = page.paging.cursor;
255
255
  ```
256
256
 
257
+ Cada Evento traz `message_id` (o `wamid`, só no WhatsApp; `null` em outros
258
+ canais) e `external_id` (o id da mensagem no canal de origem: `wamid` no
259
+ WhatsApp, `mid` no Instagram). Para correlacionar mensagens de qualquer canal,
260
+ use `external_id`; ambos podem ser `null` em Eventos sem mensagem.
261
+
257
262
  Passe um `AbortSignal` quando a leitura fizer parte de um tail cancelável:
258
263
 
259
264
  ```ts
@@ -274,6 +279,17 @@ await boto.broadcasts.create({
274
279
  template_language: "pt_BR",
275
280
  });
276
281
 
282
+ // Destinatários: objetos { to_recipient, components? } (até 1000 por chamada,
283
+ // só em draft). Strings soltas NÃO são aceitas. Itens inválidos voltam em
284
+ // `errors` ({ index, to_recipient?, reason }) sem derrubar o lote.
285
+ const { added, duplicates, errors } = await boto.broadcasts.addRecipients(broadcastId, [
286
+ { to_recipient: "5592999990000" },
287
+ {
288
+ to_recipient: "5592988880000",
289
+ components: [{ type: "body", parameters: [{ type: "text", text: "Ana" }] }],
290
+ },
291
+ ]);
292
+
277
293
  // Criar um template (submetido à Meta para análise).
278
294
  await boto.templates.create({
279
295
  name: "boas_vindas",
@@ -295,8 +311,14 @@ const link = await boto.customers.createSetupLink(customerId, {
295
311
  await boto.webhooks.create({
296
312
  url: "https://seu-app.com/hooks",
297
313
  events: ["messages", "statuses"], // categorias aceitas pela API (a rota rejeita nomes finos)
314
+ customer_id, // opcional: só entregas deste Cliente (omitido = todos da Conta)
298
315
  });
299
316
  const { data: numeros } = await boto.phoneNumbers.list({ customer_id });
317
+ await boto.phoneNumbers.update(numeros[0]!.id, { label: "Recepção" });
318
+
319
+ // Custo da Meta (aproximado; a fatura da Meta é a autoridade). Custo ausente
320
+ // vem null, nunca 0 — veja `unavailable_reason` e `estimated_cost`.
321
+ const custos = await boto.usage.metaCosts({ customer_id, from: "2026-09-01", to: "2026-09-25" });
300
322
  ```
301
323
 
302
324
  ## Exemplos
package/dist/index.cjs CHANGED
@@ -5364,7 +5364,12 @@ var Broadcasts = class {
5364
5364
  }
5365
5365
  );
5366
5366
  }
5367
- /** Adiciona destinatários (lista de números ou contatos). */
5367
+ /**
5368
+ * Adiciona destinatários a uma transmissão em `draft` (até 1000 por chamada).
5369
+ * Cada item é um objeto `{ to_recipient, components? }` — strings soltas não
5370
+ * são aceitas. Itens inválidos não derrubam o lote: voltam em `errors`.
5371
+ * Duplicatas (no lote ou já cadastradas) contam em `duplicates`.
5372
+ */
5368
5373
  addRecipients(id, recipients) {
5369
5374
  return this.client.requestItem(
5370
5375
  "POST",
@@ -5642,85 +5647,6 @@ function enc6(id) {
5642
5647
  return encodeURIComponent(id);
5643
5648
  }
5644
5649
 
5645
- // src/resources/flows.ts
5646
- var Flows = class {
5647
- constructor(client) {
5648
- this.client = client;
5649
- }
5650
- client;
5651
- /**
5652
- * Lista os flows de uma WABA (paginação por offset/página). Informe
5653
- * `phone_number_id` OU `waba_connection_id` — a rota exige um deles.
5654
- */
5655
- list(params = {}) {
5656
- return this.client.requestOffsetList("GET", "/flows", {
5657
- query: {
5658
- page: params.page,
5659
- per_page: params.per_page,
5660
- phone_number_id: params.phone_number_id,
5661
- waba_connection_id: params.waba_connection_id
5662
- }
5663
- });
5664
- }
5665
- get(id, params) {
5666
- return this.client.requestItem("GET", `/flows/${enc7(id)}`, {
5667
- query: { phone_number_id: params.phone_number_id }
5668
- });
5669
- }
5670
- create(params) {
5671
- return this.client.requestItem("POST", "/flows", { body: params });
5672
- }
5673
- /** Remove um flow (só DRAFT, regra da Meta). Responde 204 (sem corpo). */
5674
- delete(id, params) {
5675
- return this.client.request("DELETE", `/flows/${enc7(id)}`, {
5676
- query: { phone_number_id: params.phone_number_id }
5677
- });
5678
- }
5679
- publish(id, params) {
5680
- return this.client.requestItem("POST", `/flows/${enc7(id)}/publish`, {
5681
- body: { phone_number_id: params.phone_number_id }
5682
- });
5683
- }
5684
- /** Lista as versões de um flow (paginação por offset/página). */
5685
- listVersions(id, params = {}) {
5686
- return this.client.requestOffsetList(
5687
- "GET",
5688
- `/flows/${enc7(id)}/versions`,
5689
- { query: { page: params.page, per_page: params.per_page } }
5690
- );
5691
- }
5692
- createVersion(id, params) {
5693
- return this.client.requestItem(
5694
- "POST",
5695
- `/flows/${enc7(id)}/versions`,
5696
- { body: params }
5697
- );
5698
- }
5699
- setupEncryption(id, params) {
5700
- return this.client.requestItem(
5701
- "POST",
5702
- `/flows/${enc7(id)}/setup_encryption`,
5703
- { body: { phone_number_id: params.phone_number_id } }
5704
- );
5705
- }
5706
- getDataEndpoint(id) {
5707
- return this.client.requestItem(
5708
- "GET",
5709
- `/flows/${enc7(id)}/data_endpoint`
5710
- );
5711
- }
5712
- setDataEndpoint(id, params) {
5713
- return this.client.requestItem(
5714
- "POST",
5715
- `/flows/${enc7(id)}/data_endpoint`,
5716
- { body: params }
5717
- );
5718
- }
5719
- };
5720
- function enc7(id) {
5721
- return encodeURIComponent(id);
5722
- }
5723
-
5724
5650
  // src/resources/media.ts
5725
5651
  var Media = class {
5726
5652
  constructor(client) {
@@ -5856,7 +5782,6 @@ var BotoZap = class {
5856
5782
  opportunities;
5857
5783
  demands;
5858
5784
  radar;
5859
- flows;
5860
5785
  media;
5861
5786
  events;
5862
5787
  users;
@@ -5897,7 +5822,6 @@ var BotoZap = class {
5897
5822
  this.conversations = new Conversations(this);
5898
5823
  this.webhooks = new Webhooks(this);
5899
5824
  this.phoneNumbers = new PhoneNumbers(this);
5900
- this.flows = new Flows(this);
5901
5825
  this.media = new Media(this);
5902
5826
  this.events = new Events(this);
5903
5827
  this.users = new Users(this);