@botozap/sdk 0.5.0 → 0.8.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,30 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 505f0a6: **Breaking (types only):** remove `provision_phone_number` from `CreateSetupLinkParams` and `SetupLink`. Number provisioning is not offered: the option never had any effect and the API ignores it and stops returning it. Code that still passes it gets a TypeScript error; just drop the field. No runtime change.
8
+
9
+ Document the setup link redirects as the API ships them: `success_redirect_url`/`failure_redirect_url` must be `https://`, without credentials and up to 2048 characters (otherwise `422 invalid_redirect_url`). After a final state the customer goes to the success URL with `setup_link_id` and `status=completed`, to the failure URL with `status=failed` when the link is exhausted, or with `status=cancelled` when they choose to go back on a retryable error (the link stays valid). The partner's query string is preserved and the link token is never sent. `theme_config` is documented as reserved (always `null`).
10
+
11
+ ## 0.7.0
12
+
13
+ ### Minor Changes
14
+
15
+ - 5ffc8f4: Cover the API additions of 2026-09-25:
16
+
17
+ - `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.
18
+ - `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.
19
+ - 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`.
20
+ - `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`.
21
+
22
+ ## 0.6.0
23
+
24
+ ### Minor Changes
25
+
26
+ - 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.
27
+
3
28
  ## 0.5.0
4
29
 
5
30
  ### Minor Changes
package/README.md CHANGED
@@ -231,12 +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
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
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, remover, saúde (a rota de update não expõe campos editáveis, então o SDK não tem `phoneNumbers.update`)
237
+ - `phoneNumbers` — listar, buscar, **atualizar o `label`** (nome local, até 100 caracteres; `null` limpa), remover, saúde
238
238
  - `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
239
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
240
241
  - `users`, `apiLogs`, `webhookDeliveries` — leitura
241
242
 
242
243
  Inbound e mudanças de status compartilham um stream crescente. Guarde
@@ -305,7 +306,16 @@ const msgs = await boto.messages.list({ limit: 50, direction: "inbound" });
305
306
  await boto.customers.update(customerId, { name: "Padaria do João" });
306
307
  const link = await boto.customers.createSetupLink(customerId, {
307
308
  allowed_connection_types: ["dedicated"],
309
+ // https, sem usuário/senha, até 2048 caracteres (senão 422 invalid_redirect_url).
310
+ // Concluído → success com ?setup_link_id=…&status=completed. Link esgotado →
311
+ // failure com status=failed; cliente volta num erro recuperável → failure com
312
+ // status=cancelled (o link segue válido). A query da URL é preservada e o
313
+ // token do link nunca é enviado.
314
+ success_redirect_url: "https://seu-app.com/whatsapp/ok?ref=42",
315
+ failure_redirect_url: "https://seu-app.com/whatsapp/erro",
308
316
  });
317
+ // Envie link.url ao Cliente. No sucesso, confirme o número em phoneNumbers.list:
318
+ // uma conexão concluída ainda pode ter pendência de registro.
309
319
 
310
320
  await boto.webhooks.create({
311
321
  url: "https://seu-app.com/hooks",
@@ -313,6 +323,11 @@ await boto.webhooks.create({
313
323
  customer_id, // opcional: só entregas deste Cliente (omitido = todos da Conta)
314
324
  });
315
325
  const { data: numeros } = await boto.phoneNumbers.list({ customer_id });
326
+ await boto.phoneNumbers.update(numeros[0]!.id, { label: "Recepção" });
327
+
328
+ // Custo da Meta (aproximado; a fatura da Meta é a autoridade). Custo ausente
329
+ // vem null, nunca 0 — veja `unavailable_reason` e `estimated_cost`.
330
+ const custos = await boto.usage.metaCosts({ customer_id, from: "2026-09-01", to: "2026-09-25" });
316
331
  ```
317
332
 
318
333
  ## Exemplos
package/dist/index.cjs CHANGED
@@ -5264,7 +5264,12 @@ var Customers = class {
5264
5264
  { query: { page: params.page, per_page: params.per_page } }
5265
5265
  );
5266
5266
  }
5267
- /** Cria um link de setup sob um cliente. */
5267
+ /**
5268
+ * Cria um link de setup sob um cliente (expira em 30 dias). Envie a `url`
5269
+ * devolvida ao Cliente; veja em {@link CreateSetupLinkParams} como funcionam
5270
+ * os redirecionamentos. URL de redirecionamento inválida lança
5271
+ * `BotoZapError` com `code: "invalid_redirect_url"` (422).
5272
+ */
5268
5273
  createSetupLink(customerId, params = {}) {
5269
5274
  return this.client.requestItem(
5270
5275
  "POST",
@@ -5627,10 +5632,19 @@ var PhoneNumbers = class {
5627
5632
  `/phone_numbers/${enc6(id)}`
5628
5633
  );
5629
5634
  }
5630
- // NOTA: `update` foi removido de propósito. A rota PATCH /v1/phone_numbers/:id
5631
- // responde SEMPRE 422 `no_updatable_fields` — o schema atual só tem campos de
5632
- // identidade e campos sincronizados da Meta, nenhum editável por aqui. Expor o
5633
- // método só entregaria uma chamada garantidamente quebrada.
5635
+ /**
5636
+ * Atualiza o nome local (`label`) do Número. É o único campo editável:
5637
+ * identidade e dados sincronizados da Meta (`display_phone_number`,
5638
+ * `verified_name`, `quality_rating`) não mudam por aqui. `{id}` aceita o
5639
+ * UUID interno ou o `phone_number_id` da Meta.
5640
+ */
5641
+ update(id, params) {
5642
+ return this.client.requestItem(
5643
+ "PATCH",
5644
+ `/phone_numbers/${enc6(id)}`,
5645
+ { body: { label: params.label } }
5646
+ );
5647
+ }
5634
5648
  /** Remove um número. Responde 204 (sem corpo). */
5635
5649
  delete(id) {
5636
5650
  return this.client.request("DELETE", `/phone_numbers/${enc6(id)}`);
@@ -5706,6 +5720,28 @@ var Events = class {
5706
5720
  }
5707
5721
  };
5708
5722
 
5723
+ // src/resources/usage.ts
5724
+ var Usage = class {
5725
+ constructor(client) {
5726
+ this.client = client;
5727
+ }
5728
+ client;
5729
+ /**
5730
+ * Custo da Meta por dia, categoria e tipo, lido da Pricing Analytics
5731
+ * sincronizada uma vez por dia por WABA. Scope `customers:read`; o sandbox
5732
+ * fica de fora. Intervalo grande demais responde 422 `range_too_large`.
5733
+ */
5734
+ metaCosts(params = {}) {
5735
+ return this.client.requestItem("GET", "/usage/meta-costs", {
5736
+ query: {
5737
+ customer_id: params.customer_id,
5738
+ from: params.from,
5739
+ to: params.to
5740
+ }
5741
+ });
5742
+ }
5743
+ };
5744
+
5709
5745
  // src/resources/read-only.ts
5710
5746
  var Users = class {
5711
5747
  constructor(client) {
@@ -5784,6 +5820,7 @@ var BotoZap = class {
5784
5820
  radar;
5785
5821
  media;
5786
5822
  events;
5823
+ usage;
5787
5824
  users;
5788
5825
  apiLogs;
5789
5826
  webhookDeliveries;
@@ -5824,6 +5861,7 @@ var BotoZap = class {
5824
5861
  this.phoneNumbers = new PhoneNumbers(this);
5825
5862
  this.media = new Media(this);
5826
5863
  this.events = new Events(this);
5864
+ this.usage = new Usage(this);
5827
5865
  this.users = new Users(this);
5828
5866
  this.apiLogs = new ApiLogs(this);
5829
5867
  this.webhookDeliveries = new WebhookDeliveries(this);