@botozap/sdk 0.16.1 → 0.17.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,22 @@
1
1
  # @botozap/sdk
2
2
 
3
+ ## 0.17.0
4
+
5
+ ### Minor Changes
6
+
7
+ - ed98a15: Plano e slots adicionais (só chave de API, scopes `billing:read` e
8
+ `billing:write`). O plano pago inclui 1 negócio; cada negócio a mais ocupa um
9
+ slot de R$ 47/mês. SDK ganha `billing.get()`, `billing.slots.create({ idempotencyKey })`
10
+ e `billing.slots.cancel(id)`, os tipos `Billing`, `BillingPlan`, `BusinessSlot`,
11
+ `ConnectionBilling`, `ConnectionBillingOutcome`, `ConnectionBillingRefusal` e
12
+ `CustomerBusinessSlot`, `connection_billing` no link de setup, `business_slot` no
13
+ Cliente e `isBusinessPaymentRequired` para o 402 `business_payment_required` do
14
+ envio (negócio pausado por fatura vencida há mais de 7 dias). CLI ganha
15
+ `billing`, `billing slots create [--idempotency-key]` e `billing slots cancel <id>`.
16
+ MCP ganha `get_billing`, `create_business_slot` e `cancel_business_slot`, só no
17
+ catálogo de chave de API, com `readOnlyHint`, `destructiveHint`, `openWorldHint` e
18
+ `idempotentHint` explícitos; os links de setup passam a trazer `connection_billing`.
19
+
3
20
  ## 0.16.1
4
21
 
5
22
  ### 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 })`:
@@ -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
 
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();
@@ -6002,6 +6006,50 @@ var Usage = class {
6002
6006
  }
6003
6007
  };
6004
6008
 
6009
+ // src/resources/billing.ts
6010
+ function enc8(id) {
6011
+ return encodeURIComponent(id);
6012
+ }
6013
+ var BillingSlots = class {
6014
+ constructor(client) {
6015
+ this.client = client;
6016
+ }
6017
+ client;
6018
+ /**
6019
+ * Compra um slot vazio: gera cobrança de R$ 47/mês. Scope `billing:write`.
6020
+ * `invoice_url` pode vir `null`; a fatura chega em instantes em
6021
+ * {@link BillingResource.get}. Recusas: 402 `plan_required` (Free ou teste: assine o
6022
+ * plano), 402 `slot_limit` (já há 2 slots com fatura em aberto: pague uma),
6023
+ * 402 `billing_customer_required` (conta sem cadastro de cobrança: fale com o
6024
+ * suporte), 422 `invalid_idempotency_key`.
6025
+ */
6026
+ create(options = {}) {
6027
+ return this.client.requestItem("POST", "/billing/slots", {
6028
+ idempotencyKey: options.idempotencyKey
6029
+ });
6030
+ }
6031
+ /**
6032
+ * Cancela um slot vazio, sem reembolso. Responde 204, também quando o slot
6033
+ * já estava cancelado. Slot ocupado responde 409 `slot_in_use`: desconecte o
6034
+ * negócio antes. Scope `billing:write`.
6035
+ */
6036
+ cancel(id) {
6037
+ return this.client.request("DELETE", `/billing/slots/${enc8(id)}`);
6038
+ }
6039
+ };
6040
+ var BillingResource = class {
6041
+ constructor(client) {
6042
+ this.client = client;
6043
+ this.slots = new BillingSlots(client);
6044
+ }
6045
+ client;
6046
+ slots;
6047
+ /** Plano, negócios incluídos e slots ativos. Scope `billing:read`. */
6048
+ get() {
6049
+ return this.client.requestItem("GET", "/billing");
6050
+ }
6051
+ };
6052
+
6005
6053
  // src/resources/read-only.ts
6006
6054
  var Users = class {
6007
6055
  constructor(client) {
@@ -6095,6 +6143,8 @@ var BotoZap = class {
6095
6143
  media;
6096
6144
  events;
6097
6145
  usage;
6146
+ /** Plano da Conta e slots adicionais (só chave de API). */
6147
+ billing;
6098
6148
  users;
6099
6149
  apiLogs;
6100
6150
  webhookDeliveries;
@@ -6138,6 +6188,7 @@ var BotoZap = class {
6138
6188
  this.media = new Media(this);
6139
6189
  this.events = new Events(this);
6140
6190
  this.usage = new Usage(this);
6191
+ this.billing = new BillingResource(this);
6141
6192
  this.users = new Users(this);
6142
6193
  this.apiLogs = new ApiLogs(this);
6143
6194
  this.webhookDeliveries = new WebhookDeliveries(this);
@@ -6355,6 +6406,7 @@ var WEBHOOK_CATEGORIES = [
6355
6406
  Radar,
6356
6407
  SavedReplies,
6357
6408
  WEBHOOK_CATEGORIES,
6409
+ isBusinessPaymentRequired,
6358
6410
  isPlanError
6359
6411
  });
6360
6412
  //# sourceMappingURL=index.cjs.map