@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 +25 -0
- package/README.md +18 -3
- package/dist/index.cjs +43 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +240 -8
- package/dist/index.d.ts +240 -8
- package/dist/index.js +43 -5
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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,
|
|
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
|
-
/**
|
|
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
|
-
|
|
5631
|
-
|
|
5632
|
-
|
|
5633
|
-
|
|
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);
|