@botozap/sdk 0.8.0 → 0.9.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/dist/index.d.ts CHANGED
@@ -14,6 +14,19 @@ interface SendResult {
14
14
  status: MessageStatus;
15
15
  /** Presente apenas quando a chave é do ambiente sandbox. */
16
16
  sandbox?: boolean;
17
+ /** Só em `type: "reaction"`: alvo e ação (`react`/`unreact`). */
18
+ type?: "reaction";
19
+ reaction?: SendReactionResult;
20
+ }
21
+ /** Eco de `POST /v1/messages` com `type: "reaction"`. */
22
+ interface SendReactionResult {
23
+ /** UUID interno da mensagem alvo. */
24
+ message_id: string;
25
+ /** wamid da mensagem alvo. */
26
+ wamid: string;
27
+ /** `""` quando a reação foi retirada. */
28
+ emoji: string;
29
+ action: "react" | "unreact";
17
30
  }
18
31
  /** Componente de template do WhatsApp (header, body, button…). */
19
32
  interface TemplatePayload {
@@ -72,8 +85,20 @@ interface Customer {
72
85
  name?: string;
73
86
  [key: string]: unknown;
74
87
  }
88
+ /**
89
+ * Origem da mensagem: `api` (esta API), `app` (Painel ou app WhatsApp Business
90
+ * em coexistência), `history` (histórico importado), `broadcast` (Transmissão).
91
+ * Valores novos podem surgir.
92
+ */
93
+ type MessageSource = "api" | "app" | "history" | "broadcast" | (string & {});
75
94
  interface Message {
76
95
  id: string;
96
+ /** Origem da mensagem (ver `MessageSource`). */
97
+ source?: MessageSource;
98
+ /** Chegada à BotoZap (ISO 8601); chave de `sort=created_at`. */
99
+ created_at?: string;
100
+ /** Data real da mensagem no canal; `null` quando desconhecida. Chave de `sort=event_at`. */
101
+ event_at?: string | null;
77
102
  [key: string]: unknown;
78
103
  }
79
104
  interface Broadcast {
@@ -138,6 +163,10 @@ interface Conversation {
138
163
  * + 24h); `null` sem clique recente. Não altera a regra da janela de 24h.
139
164
  */
140
165
  fep_reply_by?: string | null;
166
+ /** Última mensagem da Conversa (inclui `source`); `null` sem mensagens. */
167
+ last_message?: (Partial<Message> & {
168
+ source?: MessageSource;
169
+ }) | null;
141
170
  [key: string]: unknown;
142
171
  }
143
172
  interface Assignment {
@@ -149,7 +178,7 @@ interface Webhook {
149
178
  /** Cliente cujas entregas o endpoint recebe; `null` = todos os da Conta. */
150
179
  customer_id?: string | null;
151
180
  url: string;
152
- events?: string[];
181
+ events?: (WebhookCategory | (string & {}))[];
153
182
  active?: boolean;
154
183
  /** True quando o endpoint tem Authorization no Vault. O valor nunca é devolvido. */
155
184
  has_authorization?: boolean;
@@ -171,10 +200,24 @@ interface ApiLog {
171
200
  id: string;
172
201
  [key: string]: unknown;
173
202
  }
203
+ /**
204
+ * Status de uma entrega de webhook. `limited`: recebida cortada pelo limite de
205
+ * repasse do plano Free; não será tentada.
206
+ */
207
+ type WebhookDeliveryStatus = "pending" | "success" | "failed" | "exhausted" | "limited";
174
208
  interface WebhookDelivery {
175
209
  id: string;
210
+ status?: WebhookDeliveryStatus;
176
211
  [key: string]: unknown;
177
212
  }
213
+ /**
214
+ * Categorias aceitas em `webhooks.create({ events })`. `app_messages` é opt-in
215
+ * (coexistência: `whatsapp.message.echo`, `.edited`, `.revoked`) e só chega a
216
+ * Endpoints que a assinaram explicitamente; `events` vazio não a recebe.
217
+ * `account` inclui `whatsapp.phone_number.connected`.
218
+ */
219
+ declare const WEBHOOK_CATEGORIES: readonly ["messages", "statuses", "crm", "account", "app_messages"];
220
+ type WebhookCategory = (typeof WEBHOOK_CATEGORIES)[number];
178
221
  /** Evento autoritativo do stream durável da Conta e ambiente autenticados. */
179
222
  interface BotoZapEvent {
180
223
  id: string;
@@ -288,6 +331,18 @@ interface SetupLink {
288
331
 
289
332
  /** Public /api/v1/ai contracts. Revisions are opaque strings unless the endpoint explicitly uses a number. */
290
333
  type AiProvider = "anthropic" | "openai" | "google" | "openrouter" | "deepseek" | "xai";
334
+ /** Provedores que aceitam credencial NOVA hoje; os demais respondem 422 `provider_not_enabled`. */
335
+ declare const AI_CREDENTIAL_PROVIDERS: readonly ["openai", "anthropic"];
336
+ /** Item de `ai.providers.get().providers`. */
337
+ type AiProviderInfo = {
338
+ id: AiProvider;
339
+ label: string;
340
+ key_url: string | null;
341
+ description: string | null;
342
+ /** false: criar credencial desse provedor responde 422 `provider_not_enabled`. */
343
+ accepts_new_credentials: boolean;
344
+ [key: string]: unknown;
345
+ };
291
346
  /** Every BYOK purpose. #498 added granular purposes; without their own binding they inherit the Customer default. */
292
347
  declare const AI_PURPOSES: readonly ["default", "agent_turn", "agent_operator", "router", "followup", "proposal", "transcription", "embedding", "guard", "evaluator", "classification", "compaction", "case_chat", "learning_judge", "learning_distiller", "vision", "commercial_proposal"];
293
348
  type AiPurpose = (typeof AI_PURPOSES)[number];
@@ -1881,7 +1936,7 @@ declare class AiCredentialsResource {
1881
1936
  get(input: AiScope & {
1882
1937
  id: string;
1883
1938
  }): Promise<AiCredential>;
1884
- /** Cria credencial própria no Vault; a resposta nunca contém a chave. */
1939
+ /** Cria credencial própria no Vault; a resposta nunca contém a chave. Só `AI_CREDENTIAL_PROVIDERS` (openai/anthropic); os demais: 422 `provider_not_enabled`. */
1885
1940
  create(input: AiScope & {
1886
1941
  provider: AiProvider;
1887
1942
  label: string;
@@ -1913,7 +1968,7 @@ declare class AiProvidersResource {
1913
1968
  constructor(client: BotoZap);
1914
1969
  /** GET /ai/providers */
1915
1970
  get(input: AiScope): Promise<{
1916
- providers: AiRecord[];
1971
+ providers: AiProviderInfo[];
1917
1972
  purposes: Record<string, string>;
1918
1973
  credentials: AiCredential[];
1919
1974
  bindings: AiBinding[];
@@ -3341,8 +3396,15 @@ declare class Radar {
3341
3396
  configureStageRule(stageId: string, input: StageRuleInput): Promise<StageRule>;
3342
3397
  }
3343
3398
 
3399
+ /**
3400
+ * Ordem de `messages.list`: `created_at` (padrão, chegada à BotoZap) ou
3401
+ * `event_at` (data real da mensagem; útil com histórico importado). O cursor é
3402
+ * da ordem que o gerou: reuse-o com o mesmo `sort`.
3403
+ */
3404
+ type MessageSort = "created_at" | "event_at";
3344
3405
  /** Filtros de `messages.list` (paginação por cursor). Ver GET /v1/messages. */
3345
3406
  interface ListMessagesParams extends CursorParams {
3407
+ sort?: MessageSort;
3346
3408
  /** id da Meta OU uuid interno do número. */
3347
3409
  phone_number_id?: string;
3348
3410
  /** uuid interno da conversa (o `id` de /v1/conversations). */
@@ -3398,16 +3460,128 @@ interface SendDocumentParams {
3398
3460
  from?: string;
3399
3461
  }
3400
3462
  type SendMediaParams = SendImageParams | SendVideoParams | SendAudioParams | SendDocumentParams;
3463
+ /** Header de `interactive` (texto; mídia só em button e cta_url). */
3464
+ type InteractiveHeader = {
3465
+ type: "text";
3466
+ text: string;
3467
+ } | {
3468
+ type: "image";
3469
+ image: {
3470
+ link: string;
3471
+ };
3472
+ } | {
3473
+ type: "video";
3474
+ video: {
3475
+ link: string;
3476
+ };
3477
+ } | {
3478
+ type: "document";
3479
+ document: {
3480
+ link: string;
3481
+ filename?: string;
3482
+ };
3483
+ };
3484
+ interface InteractiveBase {
3485
+ header?: InteractiveHeader;
3486
+ body: {
3487
+ text: string;
3488
+ };
3489
+ footer?: {
3490
+ text: string;
3491
+ };
3492
+ }
3493
+ /** Até 3 botões de resposta (título até 20 caracteres, ids únicos). */
3494
+ interface InteractiveButtonPayload extends InteractiveBase {
3495
+ type: "button";
3496
+ action: {
3497
+ buttons: {
3498
+ type?: "reply";
3499
+ reply: {
3500
+ id: string;
3501
+ title: string;
3502
+ };
3503
+ }[];
3504
+ };
3505
+ }
3506
+ /** Lista: até 10 seções e 10 opções no total; `title` da seção obrigatório com mais de uma. */
3507
+ interface InteractiveListPayload extends InteractiveBase {
3508
+ type: "list";
3509
+ header?: {
3510
+ type: "text";
3511
+ text: string;
3512
+ };
3513
+ action: {
3514
+ button: string;
3515
+ sections: {
3516
+ title?: string;
3517
+ rows: {
3518
+ id: string;
3519
+ title: string;
3520
+ description?: string;
3521
+ }[];
3522
+ }[];
3523
+ };
3524
+ }
3525
+ /** Botão de link (URL https pública). */
3526
+ interface InteractiveCtaUrlPayload extends InteractiveBase {
3527
+ type: "cta_url";
3528
+ action: {
3529
+ name: "cta_url";
3530
+ parameters: {
3531
+ display_text: string;
3532
+ url: string;
3533
+ };
3534
+ };
3535
+ }
3536
+ /** Objeto `interactive` no formato da Cloud API (validado pela API). */
3537
+ type InteractivePayload = InteractiveButtonPayload | InteractiveListPayload | InteractiveCtaUrlPayload;
3538
+ interface SendInteractiveParams {
3539
+ to: string;
3540
+ interactive: InteractivePayload;
3541
+ from?: string;
3542
+ }
3543
+ interface SendLocationParams {
3544
+ to: string;
3545
+ latitude: number;
3546
+ longitude: number;
3547
+ name?: string;
3548
+ address?: string;
3549
+ from?: string;
3550
+ }
3551
+ interface SendReactionParams {
3552
+ to: string;
3553
+ /** UUID interno ou wamid da mensagem RECEBIDA do contato (até 30 dias). */
3554
+ message_id: string;
3555
+ /** Emoji da reação; `""` retira a reação. */
3556
+ emoji: string;
3557
+ from?: string;
3558
+ }
3559
+ interface SendOptions {
3560
+ /** Reuse for retries of the same send; a different payload conflicts. */
3561
+ idempotencyKey?: string;
3562
+ }
3401
3563
  /** Endpoints de mensagem (POST /v1/messages, GET /v1/messages/:id). */
3402
3564
  declare class Messages {
3403
3565
  private readonly client;
3404
3566
  constructor(client: BotoZap);
3405
3567
  /** Envia uma mensagem de texto. */
3406
- send(params: SendTextParams): Promise<SendResult>;
3568
+ send(params: SendTextParams, options?: SendOptions): Promise<SendResult>;
3407
3569
  /** Envia uma mensagem usando um template aprovado. */
3408
- sendTemplate(params: SendTemplateParams): Promise<SendResult>;
3570
+ sendTemplate(params: SendTemplateParams, options?: SendOptions): Promise<SendResult>;
3409
3571
  /** Envia mídia por URL pública. */
3410
- sendMedia(params: SendMediaParams): Promise<SendResult>;
3572
+ sendMedia(params: SendMediaParams, options?: SendOptions): Promise<SendResult>;
3573
+ /**
3574
+ * Envia botões de resposta, lista ou botão de link (WhatsApp; mensagem livre,
3575
+ * exige janela de 24h aberta).
3576
+ */
3577
+ sendInteractive(params: SendInteractiveParams, options?: SendOptions): Promise<SendResult>;
3578
+ /** Envia uma localização (WhatsApp; mensagem livre). */
3579
+ sendLocation(params: SendLocationParams, options?: SendOptions): Promise<SendResult>;
3580
+ /**
3581
+ * Reage a uma mensagem recebida (WhatsApp). `emoji: ""` retira a reação.
3582
+ * O retorno traz `reaction` com o alvo e a ação.
3583
+ */
3584
+ sendReaction(params: SendReactionParams, options?: SendOptions): Promise<SendResult>;
3411
3585
  /** Lista as mensagens da conta (paginação por cursor). */
3412
3586
  list(params?: ListMessagesParams): Promise<CursorList<Message>>;
3413
3587
  /** Busca uma mensagem pelo id interno. */
@@ -3734,7 +3908,7 @@ declare class Conversations {
3734
3908
  * A leitura e o envio usam a mesma chave; o POST /messages revalida Conta,
3735
3909
  * ambiente, identidade, janela, quota e billing antes de chamar a Meta.
3736
3910
  */
3737
- reply(id: string, params: ReplyConversationParams): Promise<SendResult>;
3911
+ reply(id: string, params: ReplyConversationParams, options?: SendOptions): Promise<SendResult>;
3738
3912
  update(id: string, params: Record<string, unknown>): Promise<Conversation>;
3739
3913
  /** Lista as atribuições da conversa (paginação por offset/página). */
3740
3914
  listAssignments(id: string, params?: OffsetParams): Promise<OffsetList<Assignment>>;
@@ -4036,8 +4210,8 @@ declare class ApiLogs {
4036
4210
  interface ListWebhookDeliveriesParams extends CursorParams {
4037
4211
  /** Alias de `endpoint_id` na rota — entregas de um endpoint específico. */
4038
4212
  webhook_id?: string;
4039
- /** delivery_status (pending|success|failed|exhausted). */
4040
- status?: string;
4213
+ /** delivery_status (pending|success|failed|exhausted|limited). */
4214
+ status?: WebhookDeliveryStatus | (string & {});
4041
4215
  /** Tipo do evento (ex.: "webhook.test", "messages"). */
4042
4216
  event_type?: string;
4043
4217
  }
@@ -4048,9 +4222,35 @@ declare class WebhookDeliveries {
4048
4222
  list(params?: ListWebhookDeliveriesParams): Promise<CursorList<WebhookDelivery>>;
4049
4223
  }
4050
4224
 
4225
+ /** Identidade e permissões efetivas da credencial autenticada. */
4226
+ interface Me {
4227
+ /** UUID da Conta derivado pela API a partir da chave autenticada. */
4228
+ account_id: string;
4229
+ /** Ambiente ao qual a chave pertence. */
4230
+ environment: "live" | "sandbox";
4231
+ /** Scopes efetivos concedidos à chave. */
4232
+ scopes: string[];
4233
+ /** Ausente em versões anteriores da API; OAuth exige todos os campos abaixo. */
4234
+ auth_type?: "api_key" | "oauth";
4235
+ user_id?: string;
4236
+ client_id?: string;
4237
+ grant_id?: string;
4238
+ /** Contratos de rota permitidos, por exemplo GET /v1/contacts/:id. */
4239
+ allowed_routes?: string[];
4240
+ }
4241
+ /** Introspecção da identidade da chave autenticada. */
4242
+ declare class MeResource {
4243
+ private readonly client;
4244
+ constructor(client: BotoZap);
4245
+ /** Retorna a Conta, o ambiente e os scopes efetivos da chave. */
4246
+ get(): Promise<Me>;
4247
+ }
4248
+
4051
4249
  interface BotoZapOptions {
4052
- /** Chave de API da conta (cabeçalho Authorization: Bearer). */
4053
- apiKey: string;
4250
+ /** Chave de API da conta. Use apenas uma credencial: apiKey ou accessToken. */
4251
+ apiKey?: string;
4252
+ /** Token OAuth, ou provider chamado em cada requisição para usar o token atualizado. */
4253
+ accessToken?: string | (() => string | Promise<string>);
4054
4254
  /** Sobrescreve a URL base. Padrão: https://botozap.com.br/api/v1 */
4055
4255
  baseUrl?: string;
4056
4256
  /** Injeta um fetch (testes, runtimes sem fetch global). */
@@ -4098,7 +4298,8 @@ declare class BotoZap {
4098
4298
  readonly users: Users;
4099
4299
  readonly apiLogs: ApiLogs;
4100
4300
  readonly webhookDeliveries: WebhookDeliveries;
4101
- private readonly apiKey;
4301
+ readonly me: MeResource;
4302
+ private readonly credential;
4102
4303
  private readonly baseUrl;
4103
4304
  private readonly fetchImpl;
4104
4305
  constructor(options: BotoZapOptions);
@@ -4130,12 +4331,33 @@ declare class BotoZap {
4130
4331
  * `Retry-After` / `X-RateLimit-*`. Os headers são só os da RESPOSTA; nenhum
4131
4332
  * header de request (que carrega a apiKey) entra aqui.
4132
4333
  */
4334
+ type SendFailureDetails = {
4335
+ outcome?: "rejected" | "accepted" | "unknown";
4336
+ retry?: "backoff" | "after_correction" | "reconcile_first" | "unknown";
4337
+ };
4133
4338
  declare class BotoZapError extends Error {
4134
4339
  readonly code: string;
4135
4340
  readonly status: number;
4341
+ readonly outcome?: SendFailureDetails["outcome"];
4342
+ readonly retry?: SendFailureDetails["retry"];
4136
4343
  /** Headers da resposta HTTP. Ausente em erros sem resposta (status 0). */
4137
4344
  readonly headers?: Record<string, string>;
4138
- constructor(code: string, message: string, status: number, headers?: Record<string, string>);
4345
+ constructor(code: string, message: string, status: number, headers?: Record<string, string>, details?: SendFailureDetails);
4139
4346
  }
4347
+ /**
4348
+ * Códigos de erro conhecidos da API (não exaustivo; valores novos podem surgir).
4349
+ * Envio (POST /v1/messages): `invalid_reaction`, `missing_reaction_target`,
4350
+ * `reaction_target_not_found`, `reaction_target_invalid`,
4351
+ * `reaction_target_expired`, `unsupported_type`, `free_form_limit_reached`
4352
+ * (429, limite 1:1 do Free). Plano: `plan_restricted` (403, escritas de IA,
4353
+ * Agenda, Calendário e Jornadas fora do plano), `free_number_cap` (402, setup
4354
+ * além do teto de Números do Free). IA: `provider_not_enabled` (422, credencial
4355
+ * nova de provedor com `accepts_new_credentials: false`).
4356
+ */
4357
+ type BotoZapErrorCode = "invalid_request" | "unsupported_type" | "invalid_reaction" | "missing_reaction_target" | "reaction_target_not_found" | "reaction_target_invalid" | "reaction_target_expired" | "free_form_limit_reached" | "quota_exceeded" | "plan_restricted" | "free_number_cap" | "provider_not_enabled" | (string & {});
4358
+ /** Códigos que indicam limite ou restrição do plano contratado. */
4359
+ declare const PLAN_ERROR_CODES: readonly ["plan_restricted", "free_form_limit_reached", "free_number_cap"];
4360
+ /** True quando o erro é recusa por plano (upgrade resolve; retry não). */
4361
+ declare function isPlanError(error: unknown): error is BotoZapError;
4140
4362
 
4141
- export { AI_CONFIGURABLE_PURPOSES, AI_OPERATIONS, AI_PURPOSES, type AddRecipientsError, type AddRecipientsResult, AgendaConfiguration, AgendaExceptions, type AgendaRecord, Ai, type AiAgent, type AiAgentConfig, type AiAgentCoverage, type AiAgentInput, type AiAgentVersion, AiAgentsResource, type AiAlert, type AiAlertBulkFilters, type AiAlertListItem, AiAlertsResource, type AiArtifactUploadInput, type AiAudioPricing, type AiBinding, type AiBindingTarget, type AiBudget, type AiBudgetInput, type AiCapabilitySignal, type AiCapabilityUsage, type AiCapabilityUsageList, type AiCase, type AiCaseChat, type AiCaseEvent, type AiCaseKind, type AiCaseReply, type AiCaseReplyInput, type AiCaseSource, AiCasesResource, type AiCatalogItems, type AiCatalogModel, type AiCatalogProduct, type AiCatalogSyncInput, type AiCatalogSyncResult, type AiChannelGate, type AiCommercialDecision, type AiCommercialEffect, type AiCommercialJob, type AiCommercialProposal, AiCommercialProposalsResource, type AiCommercialRequest, type AiCommercialSettings, type AiConfigurablePurpose, type AiContactAuthorization, type AiConversationCheckpoint, type AiCredential, AiCredentialsResource, type AiDraftResult, type AiEligibilityOverview, AiEligibilityResource, type AiEligibilitySettings, type AiEnrollment, type AiEvolution, AiEvolutionResource, type AiEvolutionSource, type AiExecution, type AiExecutionCitations, type AiExecutionSecurity, AiExecutionsResource, type AiField, type AiFlow, type AiFlowGraph, type AiFlowInput, type AiFlowSettings, type AiFlowVersion, type AiFollowupEffect, type AiFollowupEvent, AiFollowupFlowsResource, type AiFollowupPromise, type AiFollowupPromiseDetail, type AiFollowupPromiseStatus, type AiFollowupQueueFilters, type AiFollowupQueuePage, type AiFollowupQueueRow, AiFollowupsResource, type AiGateMode, type AiInference, type AiInferenceOrigin, type AiInferenceOutcome, type AiInferenceSummary, AiInferencesResource, type AiKnowledgeChunk, type AiKnowledgeCitation, type AiKnowledgeConversation, type AiKnowledgeHit, type AiKnowledgeImport, type AiKnowledgePreview, AiKnowledgeResource, type AiKnowledgeSearchDiagnostics, type AiKnowledgeSource, type AiMemory, type AiMemoryEntry, type AiMemoryEntryEvent, AiMemoryResource, type AiModelCatalogSnapshot, type AiModelCatalogSync, type AiNoticeCheck, type AiNoticeEffect, type AiNoticeField, type AiNoticeJob, type AiNoticeSettings, AiNoticesResource, type AiOperation, type AiOperatorMetrics, AiOperatorResource, type AiPage, type AiPlatformSkill, type AiPlatformSkillComposition, type AiPreparedUpload, type AiProposal, AiProposalsResource, type AiProvider, type AiProviderModel, AiProvidersResource, type AiPurpose, type AiRate, type AiRateInput, type AiRecord, type AiRevision, type AiRouter, type AiRouterConfig, type AiRouterTest, AiRoutersResource, type AiScope, type AiSkill, type AiSkillInput, type AiSkillNearMiss, type AiSkillVersion, AiSkillsResource, type AiSourceKind, type AiStyleAdjustment, type AiStyleAdjustmentId, AiStyleAdjustmentsResource, type AiToolId, type AiTurnPromise, type AiUploadReceiptCallback, AiUploadsResource, AiUsageResource, type AiUsageSummary, type AiUsageTokens, type AiWindow, type ApiLog, type Appointment, type AppointmentAvailability, type AppointmentExceptionInput, type AppointmentFields, type AppointmentHistory, type AppointmentQuery, type AppointmentScheduleInput, type AppointmentServiceInput, type AppointmentStatus, Appointments, type Assignment, type AvailabilityQuery, BotoZap, BotoZapError, type BotoZapEvent, type BotoZapOptions, type Broadcast, type BroadcastRecipient, type BroadcastRecipientInput, Calendar, type CalendarConnection, type CalendarJob, type CalendarSelection, type Contact, type ContactField, ContactFields, type ContactStage, ContactStages, type Conversation, type ConversationEntryPoint, type ConversationNote, type ConversationReferral, type ConversationReminder, type CreateAppointment, type CreateAssignmentParams, type CreateBroadcastParams, type CreateContactParams, type CreateCustomerParams, type CreateDemand, type CreateOpportunity, type CreateSetupLinkParams, type CreateTemplateParams, type CreateWebhookParams, type CrmActivity, type CrmConversation, type CrmFields, type CrmMetadata, type CrmQuery, type CrmRecord, CrmResource, type CursorList, type CursorPaging, type CursorParams, type Customer, type Demand, type DemandFields, type EventList, type EventPaging, Inbox, type InboxMutation, type InboxMutationResult, type InboxState, type InboxTools, type Journey, type JourneyConfig, type JourneyEnrollment, type JourneyQuery, type JourneyRun, type JourneyStep, Journeys, type ListApiLogsParams, type ListBroadcastsParams, type ListContactsParams, type ListConversationsParams, type ListEventsParams, type ListMessagesParams, type ListPhoneNumbersParams, type ListRecipientsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type MediaAsset, type MediaUploadResult, type Message, type MessageStatus, type MetaCostCategory, type MetaCostDay, type MetaCostEstimate, type MetaCostGroup, type MetaCostReport, type MetaCostSource, type MetaCostSync, type MetaCostUnavailableReason, type MetaCostsParams, type OffsetList, type OffsetMeta, type OffsetParams, type Opportunity, type OpportunityFields, type PhoneNumber, Radar, type RadarEntry, type RadarPage, type RadarQuery, type ReplyConversationParams, type RequestOptions, SavedReplies, type SavedReply, type SavedReplyInput, type SavedReplyQuery, type ScheduleBroadcastParams, type SendAudioParams, type SendDocumentParams, type SendImageParams, type SendMediaParams, type SendResult, type SendTemplateParams, type SendTextParams, type SendVideoParams, type SetupLink, type StageColor, type StageRule, type StageRuleInput, type Template, type TemplatePayload, type UpdateAppointment, type UpdateBroadcastParams, type UpdateContactParams, type UpdateCustomerParams, type UpdatePhoneNumberParams, type UpdateSetupLinkParams, type UpdateWebhookParams, type UploadMediaParams, type User, type Webhook, type WebhookAuthorizationHeaders, type WebhookDelivery };
4363
+ export { AI_CONFIGURABLE_PURPOSES, AI_CREDENTIAL_PROVIDERS, AI_OPERATIONS, AI_PURPOSES, type AddRecipientsError, type AddRecipientsResult, AgendaConfiguration, AgendaExceptions, type AgendaRecord, Ai, type AiAgent, type AiAgentConfig, type AiAgentCoverage, type AiAgentInput, type AiAgentVersion, AiAgentsResource, type AiAlert, type AiAlertBulkFilters, type AiAlertListItem, AiAlertsResource, type AiArtifactUploadInput, type AiAudioPricing, type AiBinding, type AiBindingTarget, type AiBudget, type AiBudgetInput, type AiCapabilitySignal, type AiCapabilityUsage, type AiCapabilityUsageList, type AiCase, type AiCaseChat, type AiCaseEvent, type AiCaseKind, type AiCaseReply, type AiCaseReplyInput, type AiCaseSource, AiCasesResource, type AiCatalogItems, type AiCatalogModel, type AiCatalogProduct, type AiCatalogSyncInput, type AiCatalogSyncResult, type AiChannelGate, type AiCommercialDecision, type AiCommercialEffect, type AiCommercialJob, type AiCommercialProposal, AiCommercialProposalsResource, type AiCommercialRequest, type AiCommercialSettings, type AiConfigurablePurpose, type AiContactAuthorization, type AiConversationCheckpoint, type AiCredential, AiCredentialsResource, type AiDraftResult, type AiEligibilityOverview, AiEligibilityResource, type AiEligibilitySettings, type AiEnrollment, type AiEvolution, AiEvolutionResource, type AiEvolutionSource, type AiExecution, type AiExecutionCitations, type AiExecutionSecurity, AiExecutionsResource, type AiField, type AiFlow, type AiFlowGraph, type AiFlowInput, type AiFlowSettings, type AiFlowVersion, type AiFollowupEffect, type AiFollowupEvent, AiFollowupFlowsResource, type AiFollowupPromise, type AiFollowupPromiseDetail, type AiFollowupPromiseStatus, type AiFollowupQueueFilters, type AiFollowupQueuePage, type AiFollowupQueueRow, AiFollowupsResource, type AiGateMode, type AiInference, type AiInferenceOrigin, type AiInferenceOutcome, type AiInferenceSummary, AiInferencesResource, type AiKnowledgeChunk, type AiKnowledgeCitation, type AiKnowledgeConversation, type AiKnowledgeHit, type AiKnowledgeImport, type AiKnowledgePreview, AiKnowledgeResource, type AiKnowledgeSearchDiagnostics, type AiKnowledgeSource, type AiMemory, type AiMemoryEntry, type AiMemoryEntryEvent, AiMemoryResource, type AiModelCatalogSnapshot, type AiModelCatalogSync, type AiNoticeCheck, type AiNoticeEffect, type AiNoticeField, type AiNoticeJob, type AiNoticeSettings, AiNoticesResource, type AiOperation, type AiOperatorMetrics, AiOperatorResource, type AiPage, type AiPlatformSkill, type AiPlatformSkillComposition, type AiPreparedUpload, type AiProposal, AiProposalsResource, type AiProvider, type AiProviderInfo, type AiProviderModel, AiProvidersResource, type AiPurpose, type AiRate, type AiRateInput, type AiRecord, type AiRevision, type AiRouter, type AiRouterConfig, type AiRouterTest, AiRoutersResource, type AiScope, type AiSkill, type AiSkillInput, type AiSkillNearMiss, type AiSkillVersion, AiSkillsResource, type AiSourceKind, type AiStyleAdjustment, type AiStyleAdjustmentId, AiStyleAdjustmentsResource, type AiToolId, type AiTurnPromise, type AiUploadReceiptCallback, AiUploadsResource, AiUsageResource, type AiUsageSummary, type AiUsageTokens, type AiWindow, type ApiLog, type Appointment, type AppointmentAvailability, type AppointmentExceptionInput, type AppointmentFields, type AppointmentHistory, type AppointmentQuery, type AppointmentScheduleInput, type AppointmentServiceInput, type AppointmentStatus, Appointments, type Assignment, type AvailabilityQuery, BotoZap, BotoZapError, type BotoZapErrorCode, type BotoZapEvent, type BotoZapOptions, type Broadcast, type BroadcastRecipient, type BroadcastRecipientInput, Calendar, type CalendarConnection, type CalendarJob, type CalendarSelection, type Contact, type ContactField, ContactFields, type ContactStage, ContactStages, type Conversation, type ConversationEntryPoint, type ConversationNote, type ConversationReferral, type ConversationReminder, type CreateAppointment, type CreateAssignmentParams, type CreateBroadcastParams, type CreateContactParams, type CreateCustomerParams, type CreateDemand, type CreateOpportunity, type CreateSetupLinkParams, type CreateTemplateParams, type CreateWebhookParams, type CrmActivity, type CrmConversation, type CrmFields, type CrmMetadata, type CrmQuery, type CrmRecord, CrmResource, type CursorList, type CursorPaging, type CursorParams, type Customer, type Demand, type DemandFields, type EventList, type EventPaging, Inbox, type InboxMutation, type InboxMutationResult, type InboxState, type InboxTools, type InteractiveButtonPayload, type InteractiveCtaUrlPayload, type InteractiveHeader, type InteractiveListPayload, type InteractivePayload, type Journey, type JourneyConfig, type JourneyEnrollment, type JourneyQuery, type JourneyRun, type JourneyStep, Journeys, type ListApiLogsParams, type ListBroadcastsParams, type ListContactsParams, type ListConversationsParams, type ListEventsParams, type ListMessagesParams, type ListPhoneNumbersParams, type ListRecipientsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type Me, type MediaAsset, type MediaUploadResult, type Message, type MessageSort, type MessageSource, type MessageStatus, type MetaCostCategory, type MetaCostDay, type MetaCostEstimate, type MetaCostGroup, type MetaCostReport, type MetaCostSource, type MetaCostSync, type MetaCostUnavailableReason, type MetaCostsParams, type OffsetList, type OffsetMeta, type OffsetParams, type Opportunity, type OpportunityFields, PLAN_ERROR_CODES, type PhoneNumber, Radar, type RadarEntry, type RadarPage, type RadarQuery, type ReplyConversationParams, type RequestOptions, SavedReplies, type SavedReply, type SavedReplyInput, type SavedReplyQuery, type ScheduleBroadcastParams, type SendAudioParams, type SendDocumentParams, type SendFailureDetails, type SendImageParams, type SendInteractiveParams, type SendLocationParams, type SendMediaParams, type SendOptions, type SendReactionParams, type SendReactionResult, type SendResult, type SendTemplateParams, type SendTextParams, type SendVideoParams, type SetupLink, type StageColor, type StageRule, type StageRuleInput, type Template, type TemplatePayload, type UpdateAppointment, type UpdateBroadcastParams, type UpdateContactParams, type UpdateCustomerParams, type UpdatePhoneNumberParams, type UpdateSetupLinkParams, type UpdateWebhookParams, type UploadMediaParams, type User, WEBHOOK_CATEGORIES, type Webhook, type WebhookAuthorizationHeaders, type WebhookCategory, type WebhookDelivery, type WebhookDeliveryStatus, isPlanError };
package/dist/index.js CHANGED
@@ -39,16 +39,28 @@ function assertAudioPricing(value) {
39
39
  var BotoZapError = class extends Error {
40
40
  code;
41
41
  status;
42
+ outcome;
43
+ retry;
42
44
  /** Headers da resposta HTTP. Ausente em erros sem resposta (status 0). */
43
45
  headers;
44
- constructor(code, message, status, headers) {
46
+ constructor(code, message, status, headers, details) {
45
47
  super(message);
46
48
  this.name = "BotoZapError";
47
49
  this.code = code;
48
50
  this.status = status;
49
51
  this.headers = headers;
52
+ this.outcome = details?.outcome;
53
+ this.retry = details?.retry;
50
54
  }
51
55
  };
56
+ var PLAN_ERROR_CODES = [
57
+ "plan_restricted",
58
+ "free_form_limit_reached",
59
+ "free_number_cap"
60
+ ];
61
+ function isPlanError(error) {
62
+ return error instanceof BotoZapError && PLAN_ERROR_CODES.includes(error.code);
63
+ }
52
64
 
53
65
  // src/resources/ai/upload.ts
54
66
  var receipts = /* @__PURE__ */ new WeakMap();
@@ -3813,6 +3825,7 @@ var AI_OPERATIONS = [
3813
3825
  ];
3814
3826
 
3815
3827
  // src/resources/ai/types.ts
3828
+ var AI_CREDENTIAL_PROVIDERS = ["openai", "anthropic"];
3816
3829
  var AI_PURPOSES = [
3817
3830
  "default",
3818
3831
  "agent_turn",
@@ -3936,7 +3949,7 @@ var AiCredentialsResource = class {
3936
3949
  get(input) {
3937
3950
  return request(this.client, AI_OPERATIONS[11], input);
3938
3951
  }
3939
- /** Cria credencial própria no Vault; a resposta nunca contém a chave. */
3952
+ /** Cria credencial própria no Vault; a resposta nunca contém a chave. Só `AI_CREDENTIAL_PROVIDERS` (openai/anthropic); os demais: 422 `provider_not_enabled`. */
3940
3953
  create(input) {
3941
3954
  return request(this.client, AI_OPERATIONS[12], input);
3942
3955
  }
@@ -5080,8 +5093,9 @@ var Messages = class {
5080
5093
  }
5081
5094
  client;
5082
5095
  /** Envia uma mensagem de texto. */
5083
- async send(params) {
5096
+ async send(params, options = {}) {
5084
5097
  const result = await this.client.requestObject("POST", "/messages", {
5098
+ idempotencyKey: options.idempotencyKey,
5085
5099
  body: {
5086
5100
  to: params.to,
5087
5101
  type: "text",
@@ -5092,8 +5106,9 @@ var Messages = class {
5092
5106
  return assertSendResult(result);
5093
5107
  }
5094
5108
  /** Envia uma mensagem usando um template aprovado. */
5095
- async sendTemplate(params) {
5109
+ async sendTemplate(params, options = {}) {
5096
5110
  const result = await this.client.requestObject("POST", "/messages", {
5111
+ idempotencyKey: options.idempotencyKey,
5097
5112
  body: {
5098
5113
  to: params.to,
5099
5114
  type: "template",
@@ -5104,7 +5119,7 @@ var Messages = class {
5104
5119
  return assertSendResult(result);
5105
5120
  }
5106
5121
  /** Envia mídia por URL pública. */
5107
- async sendMedia(params) {
5122
+ async sendMedia(params, options = {}) {
5108
5123
  const media = { link: params.link };
5109
5124
  if ("caption" in params && params.caption !== void 0) {
5110
5125
  media.caption = params.caption;
@@ -5113,6 +5128,7 @@ var Messages = class {
5113
5128
  media.filename = params.filename;
5114
5129
  }
5115
5130
  const result = await this.client.requestObject("POST", "/messages", {
5131
+ idempotencyKey: options.idempotencyKey,
5116
5132
  body: {
5117
5133
  to: params.to,
5118
5134
  from: params.from,
@@ -5122,6 +5138,47 @@ var Messages = class {
5122
5138
  });
5123
5139
  return assertSendResult(result);
5124
5140
  }
5141
+ /**
5142
+ * Envia botões de resposta, lista ou botão de link (WhatsApp; mensagem livre,
5143
+ * exige janela de 24h aberta).
5144
+ */
5145
+ async sendInteractive(params, options = {}) {
5146
+ return postMessage(
5147
+ this.client,
5148
+ { to: params.to, from: params.from, type: "interactive", interactive: params.interactive },
5149
+ options
5150
+ );
5151
+ }
5152
+ /** Envia uma localização (WhatsApp; mensagem livre). */
5153
+ async sendLocation(params, options = {}) {
5154
+ const location = {
5155
+ latitude: params.latitude,
5156
+ longitude: params.longitude
5157
+ };
5158
+ if (params.name !== void 0) location.name = params.name;
5159
+ if (params.address !== void 0) location.address = params.address;
5160
+ return postMessage(
5161
+ this.client,
5162
+ { to: params.to, from: params.from, type: "location", location },
5163
+ options
5164
+ );
5165
+ }
5166
+ /**
5167
+ * Reage a uma mensagem recebida (WhatsApp). `emoji: ""` retira a reação.
5168
+ * O retorno traz `reaction` com o alvo e a ação.
5169
+ */
5170
+ async sendReaction(params, options = {}) {
5171
+ return postMessage(
5172
+ this.client,
5173
+ {
5174
+ to: params.to,
5175
+ from: params.from,
5176
+ type: "reaction",
5177
+ reaction: { message_id: params.message_id, emoji: params.emoji }
5178
+ },
5179
+ options
5180
+ );
5181
+ }
5125
5182
  /** Lista as mensagens da conta (paginação por cursor). */
5126
5183
  list(params = {}) {
5127
5184
  return this.client.requestCursorList("GET", "/messages", {
@@ -5129,6 +5186,7 @@ var Messages = class {
5129
5186
  limit: params.limit,
5130
5187
  after: params.after,
5131
5188
  before: params.before,
5189
+ sort: params.sort,
5132
5190
  phone_number_id: params.phone_number_id,
5133
5191
  conversation_id: params.conversation_id,
5134
5192
  direction: params.direction,
@@ -5146,6 +5204,13 @@ var Messages = class {
5146
5204
  );
5147
5205
  }
5148
5206
  };
5207
+ async function postMessage(client, body, options) {
5208
+ const result = await client.requestObject("POST", "/messages", {
5209
+ idempotencyKey: options.idempotencyKey,
5210
+ body
5211
+ });
5212
+ return assertSendResult(result);
5213
+ }
5149
5214
  function assertSendResult(value) {
5150
5215
  if (typeof value.wamid !== "string" || typeof value.to !== "string" || typeof value.status !== "string" || value.id !== null && typeof value.id !== "string") {
5151
5216
  throw new BotoZapError(
@@ -5436,7 +5501,7 @@ var Conversations = class {
5436
5501
  * A leitura e o envio usam a mesma chave; o POST /messages revalida Conta,
5437
5502
  * ambiente, identidade, janela, quota e billing antes de chamar a Meta.
5438
5503
  */
5439
- async reply(id, params) {
5504
+ async reply(id, params, options = {}) {
5440
5505
  const conversation = await this.get(id);
5441
5506
  const from = conversation.phone_number_id;
5442
5507
  if (typeof from !== "string" || !from.trim()) {
@@ -5455,7 +5520,7 @@ var Conversations = class {
5455
5520
  422
5456
5521
  );
5457
5522
  }
5458
- return this.client.messages.send({ to, text: params.text, from });
5523
+ return this.client.messages.send({ to, text: params.text, from }, options);
5459
5524
  }
5460
5525
  update(id, params) {
5461
5526
  return this.client.requestItem(
@@ -5732,6 +5797,18 @@ var WebhookDeliveries = class {
5732
5797
  }
5733
5798
  };
5734
5799
 
5800
+ // src/resources/me.ts
5801
+ var MeResource = class {
5802
+ constructor(client) {
5803
+ this.client = client;
5804
+ }
5805
+ client;
5806
+ /** Retorna a Conta, o ambiente e os scopes efetivos da chave. */
5807
+ get() {
5808
+ return this.client.requestItem("GET", "/me");
5809
+ }
5810
+ };
5811
+
5735
5812
  // src/client.ts
5736
5813
  var DEFAULT_BASE_URL = "https://botozap.com.br/api/v1";
5737
5814
  var BotoZap = class {
@@ -5760,14 +5837,15 @@ var BotoZap = class {
5760
5837
  users;
5761
5838
  apiLogs;
5762
5839
  webhookDeliveries;
5763
- apiKey;
5840
+ me;
5841
+ credential;
5764
5842
  baseUrl;
5765
5843
  fetchImpl;
5766
5844
  constructor(options) {
5767
- if (!options || !options.apiKey) {
5768
- throw new Error("BotoZap: apiKey \xE9 obrigat\xF3rio.");
5845
+ if (!options || Boolean(options.apiKey) === Boolean(options.accessToken)) {
5846
+ throw new Error("BotoZap: informe apenas apiKey ou accessToken.");
5769
5847
  }
5770
- this.apiKey = options.apiKey;
5848
+ this.credential = options.accessToken ?? options.apiKey;
5771
5849
  this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
5772
5850
  const resolvedFetch = options.fetch ?? globalThis.fetch;
5773
5851
  if (typeof resolvedFetch !== "function") {
@@ -5801,6 +5879,7 @@ var BotoZap = class {
5801
5879
  this.users = new Users(this);
5802
5880
  this.apiLogs = new ApiLogs(this);
5803
5881
  this.webhookDeliveries = new WebhookDeliveries(this);
5882
+ this.me = new MeResource(this);
5804
5883
  }
5805
5884
  /** PUT de artefato em URL assinada, sem token BotoZap nem cookies. Não segue redirecionamentos. */
5806
5885
  async putArtifact(url, contentType, file) {
@@ -5842,12 +5921,16 @@ var BotoZap = class {
5842
5921
  if (value !== void 0) url.searchParams.set(key, String(value));
5843
5922
  }
5844
5923
  }
5924
+ const credential = typeof this.credential === "function" ? await this.credential() : this.credential;
5925
+ if (!credential || /[\s,]/.test(credential)) {
5926
+ throw new BotoZapError("invalid_credential", "Credencial Bearer inv\xE1lida.", 401);
5927
+ }
5845
5928
  let res;
5846
5929
  try {
5847
5930
  res = await this.fetchImpl(url.toString(), {
5848
5931
  method,
5849
5932
  headers: {
5850
- Authorization: `Bearer ${this.apiKey}`,
5933
+ Authorization: `Bearer ${credential}`,
5851
5934
  ...opts.body instanceof FormData ? {} : { "Content-Type": "application/json" },
5852
5935
  Accept: "application/json",
5853
5936
  ...opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {}
@@ -5856,6 +5939,7 @@ var BotoZap = class {
5856
5939
  signal: opts.signal
5857
5940
  });
5858
5941
  } catch (cause) {
5942
+ if (cause instanceof BotoZapError) throw cause;
5859
5943
  const detail = cause instanceof Error ? cause.message : String(cause);
5860
5944
  throw new BotoZapError(
5861
5945
  "network_error",
@@ -5876,7 +5960,11 @@ var BotoZap = class {
5876
5960
  envelope?.error?.code ?? "http_error",
5877
5961
  envelope?.error?.message ?? `HTTP ${res.status}`,
5878
5962
  res.status,
5879
- headers
5963
+ headers,
5964
+ {
5965
+ outcome: envelope?.error?.outcome === "rejected" || envelope?.error?.outcome === "accepted" || envelope?.error?.outcome === "unknown" ? envelope.error.outcome : void 0,
5966
+ retry: envelope?.error?.retry === "backoff" || envelope?.error?.retry === "after_correction" || envelope?.error?.retry === "reconcile_first" || envelope?.error?.retry === "unknown" ? envelope.error.retry : void 0
5967
+ }
5880
5968
  );
5881
5969
  }
5882
5970
  return data;
@@ -5940,8 +6028,18 @@ function safeJson(text) {
5940
6028
  return text;
5941
6029
  }
5942
6030
  }
6031
+
6032
+ // src/types.ts
6033
+ var WEBHOOK_CATEGORIES = [
6034
+ "messages",
6035
+ "statuses",
6036
+ "crm",
6037
+ "account",
6038
+ "app_messages"
6039
+ ];
5943
6040
  export {
5944
6041
  AI_CONFIGURABLE_PURPOSES,
6042
+ AI_CREDENTIAL_PROVIDERS,
5945
6043
  AI_OPERATIONS,
5946
6044
  AI_PURPOSES,
5947
6045
  AgendaConfiguration,
@@ -5978,7 +6076,10 @@ export {
5978
6076
  CrmResource,
5979
6077
  Inbox,
5980
6078
  Journeys,
6079
+ PLAN_ERROR_CODES,
5981
6080
  Radar,
5982
- SavedReplies
6081
+ SavedReplies,
6082
+ WEBHOOK_CATEGORIES,
6083
+ isPlanError
5983
6084
  };
5984
6085
  //# sourceMappingURL=index.js.map