@botozap/sdk 0.16.1 → 0.18.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 +39 -0
- package/README.md +57 -1
- package/dist/index.cjs +54 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +172 -8
- package/dist/index.d.ts +172 -8
- package/dist/index.js +53 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,44 @@
|
|
|
1
1
|
# @botozap/sdk
|
|
2
2
|
|
|
3
|
+
## 0.18.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 48db398: Link de setup com canal: cada link conecta um canal só, `whatsapp` (padrão) ou
|
|
8
|
+
`instagram`. No Instagram, o Cliente confirma que a conta é profissional e que as
|
|
9
|
+
mensagens estão liberadas e entra com o Instagram; `allowed_connection_types` não
|
|
10
|
+
vale (a API responde `422 invalid_connection_types`) e o link volta com
|
|
11
|
+
`allowed_connection_types: []` e `url` em `/instagram/setup/<token>`. Canal fora
|
|
12
|
+
desses dois responde `422 invalid_channel`. `whatsapp_setup_status` mantém o nome
|
|
13
|
+
e vale para os dois canais.
|
|
14
|
+
|
|
15
|
+
SDK: `channel?: "whatsapp" | "instagram"` em `CreateSetupLinkParams` e
|
|
16
|
+
`channel: "whatsapp" | "instagram"` em `SetupLink`. CLI: `setup-links create
|
|
17
|
+
--channel <whatsapp|instagram>` e coluna CANAL no `setup-links list`. MCP:
|
|
18
|
+
`create_setup_link` aceita `channel` opcional (padrão `whatsapp`) e o schema de
|
|
19
|
+
saída dos links de setup passa a trazer `channel`.
|
|
20
|
+
|
|
21
|
+
Requer a API com o campo `channel` nos links de setup (app BotoZap, branch
|
|
22
|
+
`feat/setup-link-instagram`): publique o MCP só depois desse deploy, porque o
|
|
23
|
+
schema de saída exige `channel`.
|
|
24
|
+
|
|
25
|
+
## 0.17.0
|
|
26
|
+
|
|
27
|
+
### Minor Changes
|
|
28
|
+
|
|
29
|
+
- ed98a15: Plano e slots adicionais (só chave de API, scopes `billing:read` e
|
|
30
|
+
`billing:write`). O plano pago inclui 1 negócio; cada negócio a mais ocupa um
|
|
31
|
+
slot de R$ 47/mês. SDK ganha `billing.get()`, `billing.slots.create({ idempotencyKey })`
|
|
32
|
+
e `billing.slots.cancel(id)`, os tipos `Billing`, `BillingPlan`, `BusinessSlot`,
|
|
33
|
+
`ConnectionBilling`, `ConnectionBillingOutcome`, `ConnectionBillingRefusal` e
|
|
34
|
+
`CustomerBusinessSlot`, `connection_billing` no link de setup, `business_slot` no
|
|
35
|
+
Cliente e `isBusinessPaymentRequired` para o 402 `business_payment_required` do
|
|
36
|
+
envio (negócio pausado por fatura vencida há mais de 7 dias). CLI ganha
|
|
37
|
+
`billing`, `billing slots create [--idempotency-key]` e `billing slots cancel <id>`.
|
|
38
|
+
MCP ganha `get_billing`, `create_business_slot` e `cancel_business_slot`, só no
|
|
39
|
+
catálogo de chave de API, com `readOnlyHint`, `destructiveHint`, `openWorldHint` e
|
|
40
|
+
`idempotentHint` explícitos; os links de setup passam a trazer `connection_billing`.
|
|
41
|
+
|
|
3
42
|
## 0.16.1
|
|
4
43
|
|
|
5
44
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -386,6 +386,47 @@ catch (err) {
|
|
|
386
386
|
}
|
|
387
387
|
```
|
|
388
388
|
|
|
389
|
+
### Plano e slots adicionais
|
|
390
|
+
|
|
391
|
+
O plano pago inclui 1 negócio. Cada negócio a mais ocupa um slot adicional de
|
|
392
|
+
R$ 47/mês, com assinatura própria. Estas rotas aceitam só chave de API, com os
|
|
393
|
+
scopes `billing:read` e `billing:write` (OAuth não tem acesso).
|
|
394
|
+
|
|
395
|
+
```ts
|
|
396
|
+
const { plan, can_add_slot, slots } = await boto.billing.get();
|
|
397
|
+
|
|
398
|
+
// Compra um slot vazio (gera cobrança de R$ 47/mês). A mesma idempotencyKey
|
|
399
|
+
// devolve o mesmo slot em vez de comprar outro.
|
|
400
|
+
const slot = await boto.billing.slots.create({ idempotencyKey: "compra-2026-10-17" });
|
|
401
|
+
|
|
402
|
+
// Cancela um slot vazio, sem reembolso.
|
|
403
|
+
await boto.billing.slots.cancel(slot.id);
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
Recusas da compra: `402 plan_required` (Free ou teste: assine o plano),
|
|
407
|
+
`402 slot_limit` (já há 2 slots com fatura em aberto: pague uma) e
|
|
408
|
+
`402 billing_customer_required` (conta sem cadastro de cobrança: fale com o
|
|
409
|
+
suporte). Cancelar slot ocupado responde `409 slot_in_use`: desconecte o negócio
|
|
410
|
+
antes. `invoice_url` pode vir `null` logo depois da compra; leia de novo em
|
|
411
|
+
`billing.get()`.
|
|
412
|
+
|
|
413
|
+
Cada link de setup traz `connection_billing`, que diz o que acontece quando o
|
|
414
|
+
Cliente conectar (`included`, `occupies_slot`, `creates_slot` ou `refused`, com
|
|
415
|
+
`message` pronta para mostrar). Cada Cliente traz `business_slot` (`null` quando
|
|
416
|
+
está no que o plano inclui).
|
|
417
|
+
|
|
418
|
+
Quando a fatura de um slot vence há mais de 7 dias, o negócio fica pausado e o
|
|
419
|
+
envio responde `402 business_payment_required`. Pagar libera na hora; não é
|
|
420
|
+
recusa de plano (`isPlanError` é `false`).
|
|
421
|
+
|
|
422
|
+
```ts
|
|
423
|
+
import { isBusinessPaymentRequired } from "@botozap/sdk";
|
|
424
|
+
|
|
425
|
+
catch (err) {
|
|
426
|
+
if (isBusinessPaymentRequired(err)) avisarFaturaVencida();
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
389
430
|
### Webhooks
|
|
390
431
|
|
|
391
432
|
`WEBHOOK_CATEGORIES` lista as categorias de `webhooks.create({ events })`:
|
|
@@ -432,7 +473,7 @@ new BotoZap({
|
|
|
432
473
|
O SDK cobre os recursos da API `/v1`:
|
|
433
474
|
|
|
434
475
|
- `messages` — enviar texto (com `quick_replies` no Instagram), template e mídia por link, **listar** e buscar por id
|
|
435
|
-
- `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar)
|
|
476
|
+
- `customers` — listar, buscar, criar, **atualizar**, **remover**, e **links de setup** (listar/criar/atualizar; `channel` `whatsapp` ou `instagram`, um canal por link)
|
|
436
477
|
- `templates` — listar, buscar, **criar**
|
|
437
478
|
- `broadcasts` — criar, destinatários, agendar, enviar, cancelar
|
|
438
479
|
- `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
|
|
@@ -443,6 +484,7 @@ O SDK cobre os recursos da API `/v1`:
|
|
|
443
484
|
- `media` — subir arquivo (obter um media_id) e **buscar metadados + URL de download** de uma mídia recebida
|
|
444
485
|
- `events` — reler inbound e mudanças de status pelo cursor durável da Conta/ambiente
|
|
445
486
|
- `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
|
|
487
|
+
- `billing` — `get`: plano e slots adicionais; `slots.create` (compra, com `idempotencyKey`) e `slots.cancel` (slot vazio, sem reembolso). Só chave de API
|
|
446
488
|
- `me` — `get`: Conta, ambiente (`live` ou `sandbox`) e scopes efetivos da chave autenticada; não retorna a chave nem uma identidade pessoal
|
|
447
489
|
- `users`, `apiLogs`, `webhookDeliveries` — leitura
|
|
448
490
|
|
|
@@ -531,6 +573,20 @@ const link = await boto.customers.createSetupLink(customerId, {
|
|
|
531
573
|
// Envie link.url ao Cliente. No sucesso, confirme o número em phoneNumbers.list:
|
|
532
574
|
// uma conexão concluída ainda pode ter pendência de registro.
|
|
533
575
|
|
|
576
|
+
// Cada link conecta um canal só: channel "whatsapp" (padrão) ou "instagram"
|
|
577
|
+
// (outro valor → 422 invalid_channel). No Instagram, o Cliente confirma que a
|
|
578
|
+
// conta é profissional e que as mensagens estão liberadas e entra com o
|
|
579
|
+
// Instagram. allowed_connection_types não vale (enviar → 422
|
|
580
|
+
// invalid_connection_types); o link volta com allowed_connection_types: [] e
|
|
581
|
+
// url em /instagram/setup/<token>. whatsapp_setup_status vale para os dois
|
|
582
|
+
// canais e passa a completed quando a conta do Instagram conecta.
|
|
583
|
+
const linkIg = await boto.customers.createSetupLink(customerId, {
|
|
584
|
+
channel: "instagram",
|
|
585
|
+
success_redirect_url: "https://seu-app.com/instagram/ok", // status=completed
|
|
586
|
+
failure_redirect_url: "https://seu-app.com/instagram/erro", // status=cancelled
|
|
587
|
+
});
|
|
588
|
+
// linkIg.channel === "instagram"
|
|
589
|
+
|
|
534
590
|
await boto.webhooks.create({
|
|
535
591
|
url: "https://seu-app.com/hooks",
|
|
536
592
|
events: ["messages", "statuses"], // categorias aceitas pela API (a rota rejeita nomes finos)
|
package/dist/index.cjs
CHANGED
|
@@ -63,6 +63,7 @@ __export(index_exports, {
|
|
|
63
63
|
Radar: () => Radar,
|
|
64
64
|
SavedReplies: () => SavedReplies,
|
|
65
65
|
WEBHOOK_CATEGORIES: () => WEBHOOK_CATEGORIES,
|
|
66
|
+
isBusinessPaymentRequired: () => isBusinessPaymentRequired,
|
|
66
67
|
isPlanError: () => isPlanError
|
|
67
68
|
});
|
|
68
69
|
module.exports = __toCommonJS(index_exports);
|
|
@@ -130,6 +131,9 @@ var PLAN_ERROR_CODES = [
|
|
|
130
131
|
function isPlanError(error) {
|
|
131
132
|
return error instanceof BotoZapError && PLAN_ERROR_CODES.includes(error.code);
|
|
132
133
|
}
|
|
134
|
+
function isBusinessPaymentRequired(error) {
|
|
135
|
+
return error instanceof BotoZapError && error.code === "business_payment_required";
|
|
136
|
+
}
|
|
133
137
|
|
|
134
138
|
// src/resources/ai/upload.ts
|
|
135
139
|
var receipts = /* @__PURE__ */ new WeakMap();
|
|
@@ -5347,7 +5351,8 @@ var Customers = class {
|
|
|
5347
5351
|
* Cria um link de setup sob um cliente (expira em 30 dias). Envie a `url`
|
|
5348
5352
|
* devolvida ao Cliente; veja em {@link CreateSetupLinkParams} como funcionam
|
|
5349
5353
|
* os redirecionamentos. URL de redirecionamento inválida lança
|
|
5350
|
-
* `BotoZapError` com `code: "invalid_redirect_url"` (422)
|
|
5354
|
+
* `BotoZapError` com `code: "invalid_redirect_url"` (422); canal inválido,
|
|
5355
|
+
* `code: "invalid_channel"` (422).
|
|
5351
5356
|
*/
|
|
5352
5357
|
createSetupLink(customerId, params = {}) {
|
|
5353
5358
|
return this.client.requestItem(
|
|
@@ -6002,6 +6007,50 @@ var Usage = class {
|
|
|
6002
6007
|
}
|
|
6003
6008
|
};
|
|
6004
6009
|
|
|
6010
|
+
// src/resources/billing.ts
|
|
6011
|
+
function enc8(id) {
|
|
6012
|
+
return encodeURIComponent(id);
|
|
6013
|
+
}
|
|
6014
|
+
var BillingSlots = class {
|
|
6015
|
+
constructor(client) {
|
|
6016
|
+
this.client = client;
|
|
6017
|
+
}
|
|
6018
|
+
client;
|
|
6019
|
+
/**
|
|
6020
|
+
* Compra um slot vazio: gera cobrança de R$ 47/mês. Scope `billing:write`.
|
|
6021
|
+
* `invoice_url` pode vir `null`; a fatura chega em instantes em
|
|
6022
|
+
* {@link BillingResource.get}. Recusas: 402 `plan_required` (Free ou teste: assine o
|
|
6023
|
+
* plano), 402 `slot_limit` (já há 2 slots com fatura em aberto: pague uma),
|
|
6024
|
+
* 402 `billing_customer_required` (conta sem cadastro de cobrança: fale com o
|
|
6025
|
+
* suporte), 422 `invalid_idempotency_key`.
|
|
6026
|
+
*/
|
|
6027
|
+
create(options = {}) {
|
|
6028
|
+
return this.client.requestItem("POST", "/billing/slots", {
|
|
6029
|
+
idempotencyKey: options.idempotencyKey
|
|
6030
|
+
});
|
|
6031
|
+
}
|
|
6032
|
+
/**
|
|
6033
|
+
* Cancela um slot vazio, sem reembolso. Responde 204, também quando o slot
|
|
6034
|
+
* já estava cancelado. Slot ocupado responde 409 `slot_in_use`: desconecte o
|
|
6035
|
+
* negócio antes. Scope `billing:write`.
|
|
6036
|
+
*/
|
|
6037
|
+
cancel(id) {
|
|
6038
|
+
return this.client.request("DELETE", `/billing/slots/${enc8(id)}`);
|
|
6039
|
+
}
|
|
6040
|
+
};
|
|
6041
|
+
var BillingResource = class {
|
|
6042
|
+
constructor(client) {
|
|
6043
|
+
this.client = client;
|
|
6044
|
+
this.slots = new BillingSlots(client);
|
|
6045
|
+
}
|
|
6046
|
+
client;
|
|
6047
|
+
slots;
|
|
6048
|
+
/** Plano, negócios incluídos e slots ativos. Scope `billing:read`. */
|
|
6049
|
+
get() {
|
|
6050
|
+
return this.client.requestItem("GET", "/billing");
|
|
6051
|
+
}
|
|
6052
|
+
};
|
|
6053
|
+
|
|
6005
6054
|
// src/resources/read-only.ts
|
|
6006
6055
|
var Users = class {
|
|
6007
6056
|
constructor(client) {
|
|
@@ -6095,6 +6144,8 @@ var BotoZap = class {
|
|
|
6095
6144
|
media;
|
|
6096
6145
|
events;
|
|
6097
6146
|
usage;
|
|
6147
|
+
/** Plano da Conta e slots adicionais (só chave de API). */
|
|
6148
|
+
billing;
|
|
6098
6149
|
users;
|
|
6099
6150
|
apiLogs;
|
|
6100
6151
|
webhookDeliveries;
|
|
@@ -6138,6 +6189,7 @@ var BotoZap = class {
|
|
|
6138
6189
|
this.media = new Media(this);
|
|
6139
6190
|
this.events = new Events(this);
|
|
6140
6191
|
this.usage = new Usage(this);
|
|
6192
|
+
this.billing = new BillingResource(this);
|
|
6141
6193
|
this.users = new Users(this);
|
|
6142
6194
|
this.apiLogs = new ApiLogs(this);
|
|
6143
6195
|
this.webhookDeliveries = new WebhookDeliveries(this);
|
|
@@ -6355,6 +6407,7 @@ var WEBHOOK_CATEGORIES = [
|
|
|
6355
6407
|
Radar,
|
|
6356
6408
|
SavedReplies,
|
|
6357
6409
|
WEBHOOK_CATEGORIES,
|
|
6410
|
+
isBusinessPaymentRequired,
|
|
6358
6411
|
isPlanError
|
|
6359
6412
|
});
|
|
6360
6413
|
//# sourceMappingURL=index.cjs.map
|