@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 +32 -0
- package/README.md +28 -6
- package/dist/index.cjs +6 -82
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +73 -76
- package/dist/index.d.ts +73 -76
- package/dist/index.js +6 -82
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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,
|
|
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,
|
|
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
|
-
/**
|
|
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);
|