@botozap/sdk 0.1.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/LICENSE +21 -0
- package/README.md +229 -0
- package/dist/index.cjs +793 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +675 -0
- package/dist/index.d.ts +675 -0
- package/dist/index.js +765 -0
- package/dist/index.js.map +1 -0
- package/package.json +60 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,675 @@
|
|
|
1
|
+
/** Status de uma mensagem no envio. A API pode evoluir os valores. */
|
|
2
|
+
type MessageStatus = "sent" | "delivered" | "read" | "failed" | string;
|
|
3
|
+
/**
|
|
4
|
+
* Retorno de POST /v1/messages. Esta rota responde o objeto DIRETO (sem o
|
|
5
|
+
* envelope `{ data }`), por isso o método `messages.send` devolve `SendResult`
|
|
6
|
+
* cru. Todas as OUTRAS rotas de item vêm embrulhadas em `{ data }` (helper `ok`).
|
|
7
|
+
*/
|
|
8
|
+
interface SendResult {
|
|
9
|
+
id: string | null;
|
|
10
|
+
wamid: string;
|
|
11
|
+
to: string;
|
|
12
|
+
status: MessageStatus;
|
|
13
|
+
/** Presente apenas quando a chave é do ambiente sandbox. */
|
|
14
|
+
sandbox?: boolean;
|
|
15
|
+
}
|
|
16
|
+
/** Componente de template do WhatsApp (header, body, button…). */
|
|
17
|
+
interface TemplatePayload {
|
|
18
|
+
name: string;
|
|
19
|
+
/** A rota exige o objeto `{ code }` (formato da Cloud API) — string solta é rejeitada. */
|
|
20
|
+
language: {
|
|
21
|
+
code: string;
|
|
22
|
+
};
|
|
23
|
+
components?: unknown[];
|
|
24
|
+
}
|
|
25
|
+
/** Bloco de paginação por cursor (resposta de `okCursor`). */
|
|
26
|
+
interface CursorPaging {
|
|
27
|
+
cursors: {
|
|
28
|
+
before: string | null;
|
|
29
|
+
after: string | null;
|
|
30
|
+
};
|
|
31
|
+
/** Cursor para a próxima página (itens mais antigos); null se não há mais. */
|
|
32
|
+
next: string | null;
|
|
33
|
+
/** Cursor para a página anterior (itens mais novos). */
|
|
34
|
+
previous: string | null;
|
|
35
|
+
}
|
|
36
|
+
/** Bloco de paginação por offset/página (resposta de `okOffset`). */
|
|
37
|
+
interface OffsetMeta {
|
|
38
|
+
page: number;
|
|
39
|
+
per_page: number;
|
|
40
|
+
total_pages: number;
|
|
41
|
+
total_count: number;
|
|
42
|
+
}
|
|
43
|
+
/** Lista paginada por cursor: `{ data, paging }`. */
|
|
44
|
+
interface CursorList<T> {
|
|
45
|
+
data: T[];
|
|
46
|
+
paging: CursorPaging;
|
|
47
|
+
}
|
|
48
|
+
/** Lista paginada por offset/página: `{ data, meta }`. */
|
|
49
|
+
interface OffsetList<T> {
|
|
50
|
+
data: T[];
|
|
51
|
+
meta: OffsetMeta;
|
|
52
|
+
}
|
|
53
|
+
/** Params de paginação por cursor (`limit`/`after`/`before`). */
|
|
54
|
+
interface CursorParams {
|
|
55
|
+
/** Quantos itens retornar (1..100). */
|
|
56
|
+
limit?: number;
|
|
57
|
+
/** Cursor `paging.next` para avançar (itens mais antigos). */
|
|
58
|
+
after?: string;
|
|
59
|
+
/** Cursor `paging.previous` para voltar (itens mais novos). */
|
|
60
|
+
before?: string;
|
|
61
|
+
}
|
|
62
|
+
/** Params de paginação por offset/página (`page`/`per_page`). */
|
|
63
|
+
interface OffsetParams {
|
|
64
|
+
page?: number;
|
|
65
|
+
per_page?: number;
|
|
66
|
+
}
|
|
67
|
+
/** Cliente (customer) da sua conta. */
|
|
68
|
+
interface Customer {
|
|
69
|
+
id: string;
|
|
70
|
+
name?: string;
|
|
71
|
+
[key: string]: unknown;
|
|
72
|
+
}
|
|
73
|
+
interface Message {
|
|
74
|
+
id: string;
|
|
75
|
+
[key: string]: unknown;
|
|
76
|
+
}
|
|
77
|
+
interface Broadcast {
|
|
78
|
+
id: string;
|
|
79
|
+
[key: string]: unknown;
|
|
80
|
+
}
|
|
81
|
+
interface BroadcastRecipient {
|
|
82
|
+
id: string;
|
|
83
|
+
[key: string]: unknown;
|
|
84
|
+
}
|
|
85
|
+
interface Contact {
|
|
86
|
+
id: string;
|
|
87
|
+
wa_id?: string;
|
|
88
|
+
[key: string]: unknown;
|
|
89
|
+
}
|
|
90
|
+
interface Conversation {
|
|
91
|
+
id: string;
|
|
92
|
+
[key: string]: unknown;
|
|
93
|
+
}
|
|
94
|
+
interface Assignment {
|
|
95
|
+
id: string;
|
|
96
|
+
[key: string]: unknown;
|
|
97
|
+
}
|
|
98
|
+
interface Webhook {
|
|
99
|
+
id: string;
|
|
100
|
+
url: string;
|
|
101
|
+
events?: string[];
|
|
102
|
+
active?: boolean;
|
|
103
|
+
[key: string]: unknown;
|
|
104
|
+
}
|
|
105
|
+
interface PhoneNumber {
|
|
106
|
+
id: string;
|
|
107
|
+
[key: string]: unknown;
|
|
108
|
+
}
|
|
109
|
+
interface Flow {
|
|
110
|
+
id: string;
|
|
111
|
+
[key: string]: unknown;
|
|
112
|
+
}
|
|
113
|
+
interface FlowVersion {
|
|
114
|
+
[key: string]: unknown;
|
|
115
|
+
}
|
|
116
|
+
interface User {
|
|
117
|
+
id: string;
|
|
118
|
+
[key: string]: unknown;
|
|
119
|
+
}
|
|
120
|
+
interface ApiLog {
|
|
121
|
+
id: string;
|
|
122
|
+
[key: string]: unknown;
|
|
123
|
+
}
|
|
124
|
+
interface WebhookDelivery {
|
|
125
|
+
id: string;
|
|
126
|
+
[key: string]: unknown;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Retorno de POST /v1/media. A rota responde `{ ingest_id, target, resource }`:
|
|
130
|
+
* `target.kind` diz o pipeline usado (`meta_media` traz `media_id` usável em
|
|
131
|
+
* mensagens; `meta_resumable_asset` traz `handle` reutilizável em templates).
|
|
132
|
+
*/
|
|
133
|
+
interface MediaUploadResult {
|
|
134
|
+
ingest_id: string;
|
|
135
|
+
target: {
|
|
136
|
+
kind: "meta_media" | "meta_resumable_asset" | string;
|
|
137
|
+
/** Presente em `kind: "meta_media"` — id usável no envio de mensagens. */
|
|
138
|
+
media_id?: string;
|
|
139
|
+
/** Presente em `kind: "meta_resumable_asset"` — handle reutilizável. */
|
|
140
|
+
handle?: string;
|
|
141
|
+
[key: string]: unknown;
|
|
142
|
+
};
|
|
143
|
+
resource: {
|
|
144
|
+
filename: string;
|
|
145
|
+
mime_type: string;
|
|
146
|
+
size_bytes: number;
|
|
147
|
+
sha256: string;
|
|
148
|
+
source_url: string;
|
|
149
|
+
[key: string]: unknown;
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Link de setup de um cliente (Embedded Signup). Shape do contrato
|
|
154
|
+
* (ver `/v1/customers/:id/setup_links`): a `url` embute o token opaco; o token
|
|
155
|
+
* cru nunca é exposto separadamente.
|
|
156
|
+
*/
|
|
157
|
+
interface SetupLink {
|
|
158
|
+
id: string;
|
|
159
|
+
status: string;
|
|
160
|
+
whatsapp_setup_status: string;
|
|
161
|
+
url: string;
|
|
162
|
+
allowed_connection_types: string[];
|
|
163
|
+
provision_phone_number: boolean;
|
|
164
|
+
language: string | null;
|
|
165
|
+
success_redirect_url: string | null;
|
|
166
|
+
failure_redirect_url: string | null;
|
|
167
|
+
theme_config: unknown;
|
|
168
|
+
expires_at: string | null;
|
|
169
|
+
created_at: string;
|
|
170
|
+
updated_at: string;
|
|
171
|
+
[key: string]: unknown;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** Filtros de `messages.list` (paginação por cursor). Ver GET /v1/messages. */
|
|
175
|
+
interface ListMessagesParams extends CursorParams {
|
|
176
|
+
/** id da Meta OU uuid interno do número. */
|
|
177
|
+
phone_number_id?: string;
|
|
178
|
+
/** uuid interno da conversa (o `id` de /v1/conversations). */
|
|
179
|
+
conversation_id?: string;
|
|
180
|
+
direction?: "inbound" | "outbound";
|
|
181
|
+
/** enum message_status (ex.: "sent", "delivered", "read", "failed"). */
|
|
182
|
+
status?: string;
|
|
183
|
+
/** enum message_kind (ex.: "text", "image", "template"). */
|
|
184
|
+
message_type?: string;
|
|
185
|
+
/** true = só mensagens com mídia; false = só sem mídia. */
|
|
186
|
+
has_media?: boolean;
|
|
187
|
+
}
|
|
188
|
+
interface SendTextParams {
|
|
189
|
+
/** Número de destino em E.164, ex: "+5531988887777". */
|
|
190
|
+
to: string;
|
|
191
|
+
/** Corpo do texto. */
|
|
192
|
+
text: string;
|
|
193
|
+
/** phone_number_id de origem (obrigatório se a conta tem mais de um número). */
|
|
194
|
+
from?: string;
|
|
195
|
+
}
|
|
196
|
+
interface SendTemplateParams {
|
|
197
|
+
to: string;
|
|
198
|
+
template: TemplatePayload;
|
|
199
|
+
from?: string;
|
|
200
|
+
}
|
|
201
|
+
/** Endpoints de mensagem (POST /v1/messages, GET /v1/messages/:id). */
|
|
202
|
+
declare class Messages {
|
|
203
|
+
private readonly client;
|
|
204
|
+
constructor(client: BotoZap);
|
|
205
|
+
/** Envia uma mensagem de texto. */
|
|
206
|
+
send(params: SendTextParams): Promise<SendResult>;
|
|
207
|
+
/** Envia uma mensagem usando um template aprovado. */
|
|
208
|
+
sendTemplate(params: SendTemplateParams): Promise<SendResult>;
|
|
209
|
+
/** Lista as mensagens da conta (paginação por cursor). */
|
|
210
|
+
list(params?: ListMessagesParams): Promise<CursorList<Message>>;
|
|
211
|
+
/** Busca uma mensagem pelo id interno. */
|
|
212
|
+
get(id: string): Promise<Message>;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
interface CreateCustomerParams {
|
|
216
|
+
name: string;
|
|
217
|
+
/** Referência do cliente no seu sistema (único por conta). */
|
|
218
|
+
external_customer_id?: string;
|
|
219
|
+
[key: string]: unknown;
|
|
220
|
+
}
|
|
221
|
+
/** Campos editáveis de um cliente (`PATCH /v1/customers/:id`). */
|
|
222
|
+
interface UpdateCustomerParams {
|
|
223
|
+
name?: string;
|
|
224
|
+
external_customer_id?: string;
|
|
225
|
+
}
|
|
226
|
+
/** Corpo de `POST /v1/customers/:id/setup_links`. */
|
|
227
|
+
interface CreateSetupLinkParams {
|
|
228
|
+
/** Tipos de conexão liberados: "dedicated" e/ou "coexistence". */
|
|
229
|
+
allowed_connection_types?: string[];
|
|
230
|
+
provision_phone_number?: boolean;
|
|
231
|
+
language?: string;
|
|
232
|
+
success_redirect_url?: string;
|
|
233
|
+
failure_redirect_url?: string;
|
|
234
|
+
}
|
|
235
|
+
/** Corpo de `PATCH /v1/customers/:id/setup_links/:linkId`. */
|
|
236
|
+
interface UpdateSetupLinkParams {
|
|
237
|
+
/** "active" | "expired" | "revoked" (a rota rejeita outros valores). */
|
|
238
|
+
status?: string;
|
|
239
|
+
/** Nova expiração (ISO 8601). */
|
|
240
|
+
expires_at?: string;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Endpoints de cliente (`/v1/customers`) e seus links de setup
|
|
244
|
+
* (`/v1/customers/:id/setup_links`).
|
|
245
|
+
*/
|
|
246
|
+
declare class Customers {
|
|
247
|
+
private readonly client;
|
|
248
|
+
constructor(client: BotoZap);
|
|
249
|
+
/** Lista os clientes da conta (paginação por offset/página). */
|
|
250
|
+
list(params?: OffsetParams): Promise<OffsetList<Customer>>;
|
|
251
|
+
/** Busca um cliente pelo id. */
|
|
252
|
+
get(id: string): Promise<Customer>;
|
|
253
|
+
/** Cria um cliente. */
|
|
254
|
+
create(params: CreateCustomerParams): Promise<Customer>;
|
|
255
|
+
/** Atualiza `name` / `external_customer_id` de um cliente. */
|
|
256
|
+
update(id: string, params: UpdateCustomerParams): Promise<Customer>;
|
|
257
|
+
/** Exclui um cliente. Responde 204 (sem corpo). */
|
|
258
|
+
delete(id: string): Promise<void>;
|
|
259
|
+
/** Lista os links de setup de um cliente (paginação por offset/página). */
|
|
260
|
+
listSetupLinks(customerId: string, params?: OffsetParams): Promise<OffsetList<SetupLink>>;
|
|
261
|
+
/** Cria um link de setup sob um cliente. */
|
|
262
|
+
createSetupLink(customerId: string, params?: CreateSetupLinkParams): Promise<SetupLink>;
|
|
263
|
+
/** Atualiza status/expiração de um link de setup. */
|
|
264
|
+
updateSetupLink(customerId: string, linkId: string, params: UpdateSetupLinkParams): Promise<SetupLink>;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
interface Template {
|
|
268
|
+
id: string;
|
|
269
|
+
name?: string;
|
|
270
|
+
[key: string]: unknown;
|
|
271
|
+
}
|
|
272
|
+
/** Filtros de `templates.list` (paginação por offset). Ver GET /v1/templates. */
|
|
273
|
+
interface ListTemplatesParams extends OffsetParams {
|
|
274
|
+
/** Status do template (a rota normaliza para maiúsculas), ex.: "APPROVED". */
|
|
275
|
+
status?: string;
|
|
276
|
+
/** Categoria (a rota normaliza para maiúsculas), ex.: "MARKETING". */
|
|
277
|
+
category?: string;
|
|
278
|
+
/** Filtra pela conexão WABA. */
|
|
279
|
+
waba_connection_id?: string;
|
|
280
|
+
/** phone_number_id (Meta) → resolve a conexão do número (escopado por conta). */
|
|
281
|
+
phone_number_id?: string;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Corpo de `POST /v1/templates` — cria o template e o submete à Meta. A conexão
|
|
285
|
+
* WABA vem de `waba_connection_id` OU `phone_number_id` (um dos dois). Ver a
|
|
286
|
+
* rota para o formato exato de `components`.
|
|
287
|
+
*/
|
|
288
|
+
interface CreateTemplateParams {
|
|
289
|
+
name: string;
|
|
290
|
+
/** Código de idioma, ex.: "pt_BR". */
|
|
291
|
+
language: string;
|
|
292
|
+
/** Categoria da Meta: "MARKETING" | "UTILITY" | "AUTHENTICATION". */
|
|
293
|
+
category: string;
|
|
294
|
+
/** Componentes do template (header/body/buttons…), formato da Cloud API. */
|
|
295
|
+
components: unknown[];
|
|
296
|
+
/** Conexão WABA alvo (alternativa a `phone_number_id`). */
|
|
297
|
+
waba_connection_id?: string;
|
|
298
|
+
/** phone_number_id (Meta) → resolve a conexão do número (alternativa). */
|
|
299
|
+
phone_number_id?: string;
|
|
300
|
+
}
|
|
301
|
+
/** Endpoints de template (GET/POST /v1/templates, GET /v1/templates/:id). */
|
|
302
|
+
declare class Templates {
|
|
303
|
+
private readonly client;
|
|
304
|
+
constructor(client: BotoZap);
|
|
305
|
+
/** Lista os templates da conta (paginação por offset/página). */
|
|
306
|
+
list(params?: ListTemplatesParams): Promise<OffsetList<Template>>;
|
|
307
|
+
/** Busca um template pelo id. */
|
|
308
|
+
get(id: string): Promise<Template>;
|
|
309
|
+
/** Cria um template e o submete à Meta para análise. */
|
|
310
|
+
create(params: CreateTemplateParams): Promise<Template>;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
interface ListBroadcastsParams extends OffsetParams {
|
|
314
|
+
status?: string;
|
|
315
|
+
customer_id?: string;
|
|
316
|
+
phone_number_id?: string;
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Corpo de `POST /v1/broadcasts` — espelha o contrato real da rota. A origem é
|
|
320
|
+
* `phone_number_id` OU `waba_connection_id` (um dos dois obrigatório);
|
|
321
|
+
* `template_name` + `template_language` são obrigatórios. A conta vem da chave,
|
|
322
|
+
* nunca do corpo. (A rota NÃO aceita `customer_id` nem um objeto `template`.)
|
|
323
|
+
*/
|
|
324
|
+
interface CreateBroadcastParams {
|
|
325
|
+
name?: string;
|
|
326
|
+
/** phone_number_id (Meta) do número de origem. */
|
|
327
|
+
phone_number_id?: string;
|
|
328
|
+
/** Alternativa a `phone_number_id`: a conexão WABA de origem. */
|
|
329
|
+
waba_connection_id?: string;
|
|
330
|
+
/** Nome do template aprovado (obrigatório). */
|
|
331
|
+
template_name: string;
|
|
332
|
+
/** Código de idioma do template, ex.: "pt_BR" (obrigatório). */
|
|
333
|
+
template_language: string;
|
|
334
|
+
/** Opcional: id interno do template (revalidado por ownership/conexão). */
|
|
335
|
+
template_id?: string;
|
|
336
|
+
}
|
|
337
|
+
/** Transição de estado via `PATCH /v1/broadcasts/:id`. */
|
|
338
|
+
interface UpdateBroadcastParams {
|
|
339
|
+
/** `stopped` interrompe (sending/scheduled); `draft` cancela um agendamento. */
|
|
340
|
+
status: "stopped" | "draft";
|
|
341
|
+
}
|
|
342
|
+
interface ScheduleBroadcastParams {
|
|
343
|
+
/** Data/hora ISO 8601. */
|
|
344
|
+
scheduled_at: string;
|
|
345
|
+
[key: string]: unknown;
|
|
346
|
+
}
|
|
347
|
+
/** Filtros de `listRecipients` (paginação por cursor + filtro de status). */
|
|
348
|
+
interface ListRecipientsParams extends CursorParams {
|
|
349
|
+
/** Filtra por status do destinatário (ex.: "pending", "sent", "failed"). */
|
|
350
|
+
status?: string;
|
|
351
|
+
}
|
|
352
|
+
/** Resultado de `addRecipients`: quantos entraram, quantos eram duplicados, erros. */
|
|
353
|
+
interface AddRecipientsResult {
|
|
354
|
+
added: number;
|
|
355
|
+
duplicates: number;
|
|
356
|
+
errors: unknown[];
|
|
357
|
+
}
|
|
358
|
+
/** Transmissões: criar, adicionar destinatários, agendar/enviar/cancelar. */
|
|
359
|
+
declare class Broadcasts {
|
|
360
|
+
private readonly client;
|
|
361
|
+
constructor(client: BotoZap);
|
|
362
|
+
/** Lista as transmissões da conta (paginação por offset/página). */
|
|
363
|
+
list(params?: ListBroadcastsParams): Promise<OffsetList<Broadcast>>;
|
|
364
|
+
get(id: string): Promise<Broadcast>;
|
|
365
|
+
create(params: CreateBroadcastParams): Promise<Broadcast>;
|
|
366
|
+
update(id: string, params: UpdateBroadcastParams): Promise<Broadcast>;
|
|
367
|
+
/** Lista os destinatários de uma transmissão (paginação por cursor). */
|
|
368
|
+
listRecipients(id: string, params?: ListRecipientsParams): Promise<CursorList<BroadcastRecipient>>;
|
|
369
|
+
/** Adiciona destinatários (lista de números ou contatos). */
|
|
370
|
+
addRecipients(id: string, recipients: unknown[]): Promise<AddRecipientsResult>;
|
|
371
|
+
/** Remove TODOS os destinatários. Responde 204 (sem corpo). */
|
|
372
|
+
removeRecipients(id: string): Promise<void>;
|
|
373
|
+
schedule(id: string, params: ScheduleBroadcastParams): Promise<Broadcast>;
|
|
374
|
+
send(id: string): Promise<Broadcast>;
|
|
375
|
+
cancel(id: string): Promise<Broadcast>;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
interface ListContactsParams extends CursorParams {
|
|
379
|
+
/** Filtra pelos números do cliente (derivado da conexão do número). */
|
|
380
|
+
customer_id?: string;
|
|
381
|
+
/**
|
|
382
|
+
* Nesta base todo contato pertence a um cliente; `false` nunca casa (página
|
|
383
|
+
* vazia), `true` é no-op.
|
|
384
|
+
*/
|
|
385
|
+
has_customer?: boolean;
|
|
386
|
+
/** Busca parcial (ilike) no nome de perfil. */
|
|
387
|
+
profile_name_contains?: string;
|
|
388
|
+
/** Busca parcial (ilike) no wa_id. */
|
|
389
|
+
wa_id_contains?: string;
|
|
390
|
+
/** Criados em ou após esta data (ISO 8601). */
|
|
391
|
+
created_after?: string;
|
|
392
|
+
/** Criados em ou antes desta data (ISO 8601). */
|
|
393
|
+
created_before?: string;
|
|
394
|
+
}
|
|
395
|
+
interface CreateContactParams {
|
|
396
|
+
/** wa_id canônico (BSUID "BR.1A2B…" ou dígitos E.164). */
|
|
397
|
+
wa_id: string;
|
|
398
|
+
phone_number_id?: string;
|
|
399
|
+
[key: string]: unknown;
|
|
400
|
+
}
|
|
401
|
+
/** Contatos: listar, buscar, criar, atualizar, remover. */
|
|
402
|
+
declare class Contacts {
|
|
403
|
+
private readonly client;
|
|
404
|
+
constructor(client: BotoZap);
|
|
405
|
+
/** Lista os contatos da conta (paginação por cursor). */
|
|
406
|
+
list(params?: ListContactsParams): Promise<CursorList<Contact>>;
|
|
407
|
+
get(id: string): Promise<Contact>;
|
|
408
|
+
create(params: CreateContactParams): Promise<Contact>;
|
|
409
|
+
update(id: string, params: Record<string, unknown>): Promise<Contact>;
|
|
410
|
+
/** Remove um contato. Responde 204 (sem corpo). */
|
|
411
|
+
delete(id: string): Promise<void>;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
interface ListConversationsParams extends CursorParams {
|
|
415
|
+
/** id da Meta OU uuid interno do número. */
|
|
416
|
+
phone_number_id?: string;
|
|
417
|
+
/** "active" | "ended" — derivado da janela de 24h. */
|
|
418
|
+
status?: string;
|
|
419
|
+
/**
|
|
420
|
+
* Busca parcial por contato (nome de perfil, @username, telefone ou wa_id).
|
|
421
|
+
* Tem precedência sobre `phone_number` na rota.
|
|
422
|
+
*/
|
|
423
|
+
contact?: string;
|
|
424
|
+
/** Alias de busca por contato (usado quando `contact` não é informado). */
|
|
425
|
+
phone_number?: string;
|
|
426
|
+
}
|
|
427
|
+
interface CreateAssignmentParams {
|
|
428
|
+
/** Membro a quem atribuir a conversa. */
|
|
429
|
+
user_id: string;
|
|
430
|
+
notes?: string;
|
|
431
|
+
}
|
|
432
|
+
/** Conversas (read + status) e atribuições a membros. */
|
|
433
|
+
declare class Conversations {
|
|
434
|
+
private readonly client;
|
|
435
|
+
constructor(client: BotoZap);
|
|
436
|
+
/** Lista as conversas da conta (paginação por cursor). */
|
|
437
|
+
list(params?: ListConversationsParams): Promise<CursorList<Conversation>>;
|
|
438
|
+
get(id: string): Promise<Conversation>;
|
|
439
|
+
update(id: string, params: Record<string, unknown>): Promise<Conversation>;
|
|
440
|
+
/** Lista as atribuições da conversa (paginação por offset/página). */
|
|
441
|
+
listAssignments(id: string, params?: OffsetParams): Promise<OffsetList<Assignment>>;
|
|
442
|
+
createAssignment(id: string, params: CreateAssignmentParams): Promise<Assignment>;
|
|
443
|
+
getAssignment(id: string, assignmentId: string): Promise<Assignment>;
|
|
444
|
+
updateAssignment(id: string, assignmentId: string, params: Record<string, unknown>): Promise<Assignment>;
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
interface CreateWebhookParams {
|
|
448
|
+
url: string;
|
|
449
|
+
events?: string[];
|
|
450
|
+
active?: boolean;
|
|
451
|
+
[key: string]: unknown;
|
|
452
|
+
}
|
|
453
|
+
/** Webhooks: endpoints assinados que recebem os eventos da conta. */
|
|
454
|
+
declare class Webhooks {
|
|
455
|
+
private readonly client;
|
|
456
|
+
constructor(client: BotoZap);
|
|
457
|
+
/** Lista os endpoints de webhook da conta (paginação por cursor). */
|
|
458
|
+
list(params?: CursorParams): Promise<CursorList<Webhook>>;
|
|
459
|
+
get(id: string): Promise<Webhook>;
|
|
460
|
+
create(params: CreateWebhookParams): Promise<Webhook>;
|
|
461
|
+
update(id: string, params: Record<string, unknown>): Promise<Webhook>;
|
|
462
|
+
/** Remove um endpoint. Responde 204 (sem corpo). */
|
|
463
|
+
delete(id: string): Promise<void>;
|
|
464
|
+
/** Dispara um evento de teste para o endpoint. */
|
|
465
|
+
test(id: string): Promise<{
|
|
466
|
+
success: boolean;
|
|
467
|
+
}>;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
interface ListPhoneNumbersParams extends OffsetParams {
|
|
471
|
+
customer_id?: string;
|
|
472
|
+
}
|
|
473
|
+
/** Números conectados de cada cliente. */
|
|
474
|
+
declare class PhoneNumbers {
|
|
475
|
+
private readonly client;
|
|
476
|
+
constructor(client: BotoZap);
|
|
477
|
+
/** Lista os números da conta (paginação por offset/página). */
|
|
478
|
+
list(params?: ListPhoneNumbersParams): Promise<OffsetList<PhoneNumber>>;
|
|
479
|
+
get(id: string): Promise<PhoneNumber>;
|
|
480
|
+
/** Remove um número. Responde 204 (sem corpo). */
|
|
481
|
+
delete(id: string): Promise<void>;
|
|
482
|
+
/** Saúde do número (qualidade, limite, status na Meta). */
|
|
483
|
+
health(id: string): Promise<Record<string, unknown>>;
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
interface CreateFlowParams {
|
|
487
|
+
name?: string;
|
|
488
|
+
[key: string]: unknown;
|
|
489
|
+
}
|
|
490
|
+
/**
|
|
491
|
+
* Filtros de `flows.list` (paginação por offset). Flows vivem na Meta e a lista
|
|
492
|
+
* é por WABA — a rota GET /v1/flows EXIGE `phone_number_id` OU
|
|
493
|
+
* `waba_connection_id` (sem um deles responde 422 missing_target). Informe um.
|
|
494
|
+
*/
|
|
495
|
+
interface ListFlowsParams extends OffsetParams {
|
|
496
|
+
/** phone_number_id (Meta) → resolve a conexão do número (escopado por conta). */
|
|
497
|
+
phone_number_id?: string;
|
|
498
|
+
/** Alternativa a `phone_number_id`: a conexão WABA cujos flows listar. */
|
|
499
|
+
waba_connection_id?: string;
|
|
500
|
+
}
|
|
501
|
+
/**
|
|
502
|
+
* Flows vivem na Meta, não no nosso banco — a amarração flow → conta é via
|
|
503
|
+
* `phone_number_id` (resolve a WABA e o token). Por isso get/delete/publish/
|
|
504
|
+
* setup_encryption/versions/data_endpoint EXIGEM `phone_number_id`.
|
|
505
|
+
*/
|
|
506
|
+
interface FlowPhoneParams {
|
|
507
|
+
/** phone_number_id (Meta) do número cuja WABA hospeda o flow. */
|
|
508
|
+
phone_number_id: string;
|
|
509
|
+
}
|
|
510
|
+
/** Corpo de `POST /v1/flows/:id/versions` — sobe um novo flow.json. */
|
|
511
|
+
interface CreateFlowVersionParams {
|
|
512
|
+
phone_number_id: string;
|
|
513
|
+
/** JSON do flow (objeto ou string JSON válida). */
|
|
514
|
+
flow_json: unknown;
|
|
515
|
+
[key: string]: unknown;
|
|
516
|
+
}
|
|
517
|
+
/** Corpo de `POST /v1/flows/:id/data_endpoint` — conecta a forward URL do dev. */
|
|
518
|
+
interface SetFlowDataEndpointParams {
|
|
519
|
+
phone_number_id: string;
|
|
520
|
+
/** URL HTTPS do backend do dev que recebe o data_exchange. */
|
|
521
|
+
forward_url: string;
|
|
522
|
+
[key: string]: unknown;
|
|
523
|
+
}
|
|
524
|
+
/** WhatsApp Flows: criar, versionar, publicar e configurar data endpoint. */
|
|
525
|
+
declare class Flows {
|
|
526
|
+
private readonly client;
|
|
527
|
+
constructor(client: BotoZap);
|
|
528
|
+
/**
|
|
529
|
+
* Lista os flows de uma WABA (paginação por offset/página). Informe
|
|
530
|
+
* `phone_number_id` OU `waba_connection_id` — a rota exige um deles.
|
|
531
|
+
*/
|
|
532
|
+
list(params?: ListFlowsParams): Promise<OffsetList<Flow>>;
|
|
533
|
+
get(id: string, params: FlowPhoneParams): Promise<Flow>;
|
|
534
|
+
create(params: CreateFlowParams): Promise<Flow>;
|
|
535
|
+
/** Remove um flow (só DRAFT, regra da Meta). Responde 204 (sem corpo). */
|
|
536
|
+
delete(id: string, params: FlowPhoneParams): Promise<void>;
|
|
537
|
+
publish(id: string, params: FlowPhoneParams): Promise<Flow>;
|
|
538
|
+
/** Lista as versões de um flow (paginação por offset/página). */
|
|
539
|
+
listVersions(id: string, params?: OffsetParams): Promise<OffsetList<FlowVersion>>;
|
|
540
|
+
createVersion(id: string, params: CreateFlowVersionParams): Promise<FlowVersion>;
|
|
541
|
+
setupEncryption(id: string, params: FlowPhoneParams): Promise<Record<string, unknown>>;
|
|
542
|
+
getDataEndpoint(id: string): Promise<Record<string, unknown>>;
|
|
543
|
+
setDataEndpoint(id: string, params: SetFlowDataEndpointParams): Promise<Record<string, unknown>>;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/** Corpo do `POST /v1/media` — espelha o contrato real da rota. */
|
|
547
|
+
interface UploadMediaParams {
|
|
548
|
+
/** URL http(s) de origem do arquivo. A BotoZap baixa (com guard SSRF) e sobe pra Cloud API. */
|
|
549
|
+
source: string;
|
|
550
|
+
/** phone_number_id (da Meta) do número de origem. Obrigatório. */
|
|
551
|
+
phone_number_id: string;
|
|
552
|
+
/** Nome do arquivo (default: derivado da URL). */
|
|
553
|
+
filename?: string;
|
|
554
|
+
/** MIME type (default: Content-Type do download). */
|
|
555
|
+
mime_type?: string;
|
|
556
|
+
/** Pipeline de upload: `meta_media` (default) ou `meta_resumable_asset`. */
|
|
557
|
+
delivery?: "meta_media" | "meta_resumable_asset";
|
|
558
|
+
[key: string]: unknown;
|
|
559
|
+
}
|
|
560
|
+
/** Mídia: sobe um arquivo e devolve um media_id usável em mensagens. */
|
|
561
|
+
declare class Media {
|
|
562
|
+
private readonly client;
|
|
563
|
+
constructor(client: BotoZap);
|
|
564
|
+
upload(params: UploadMediaParams): Promise<MediaUploadResult>;
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/** Membros da conta (somente leitura via API). */
|
|
568
|
+
declare class Users {
|
|
569
|
+
private readonly client;
|
|
570
|
+
constructor(client: BotoZap);
|
|
571
|
+
/** Lista os membros da conta (paginação por offset/página). */
|
|
572
|
+
list(params?: OffsetParams): Promise<OffsetList<User>>;
|
|
573
|
+
}
|
|
574
|
+
interface ListApiLogsParams extends CursorParams {
|
|
575
|
+
/** Origem do log (ex.: "api"). */
|
|
576
|
+
source?: string;
|
|
577
|
+
/** Método HTTP (a rota normaliza para maiúsculas). */
|
|
578
|
+
method?: string;
|
|
579
|
+
/** Código HTTP exato (inteiro). */
|
|
580
|
+
status_code?: number;
|
|
581
|
+
}
|
|
582
|
+
/** Logs de requisições à API (somente leitura, paginação por cursor). */
|
|
583
|
+
declare class ApiLogs {
|
|
584
|
+
private readonly client;
|
|
585
|
+
constructor(client: BotoZap);
|
|
586
|
+
list(params?: ListApiLogsParams): Promise<CursorList<ApiLog>>;
|
|
587
|
+
}
|
|
588
|
+
interface ListWebhookDeliveriesParams extends CursorParams {
|
|
589
|
+
/** Alias de `endpoint_id` na rota — entregas de um endpoint específico. */
|
|
590
|
+
webhook_id?: string;
|
|
591
|
+
/** delivery_status (pending|success|failed|exhausted). */
|
|
592
|
+
status?: string;
|
|
593
|
+
/** Tipo do evento (ex.: "webhook.test", "messages"). */
|
|
594
|
+
event_type?: string;
|
|
595
|
+
}
|
|
596
|
+
/** Histórico de entregas de webhook (somente leitura, paginação por cursor). */
|
|
597
|
+
declare class WebhookDeliveries {
|
|
598
|
+
private readonly client;
|
|
599
|
+
constructor(client: BotoZap);
|
|
600
|
+
list(params?: ListWebhookDeliveriesParams): Promise<CursorList<WebhookDelivery>>;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
interface BotoZapOptions {
|
|
604
|
+
/** Chave de API da conta (cabeçalho Authorization: Bearer). */
|
|
605
|
+
apiKey: string;
|
|
606
|
+
/** Sobrescreve a URL base. Padrão: https://botozap.com.br/api/v1 */
|
|
607
|
+
baseUrl?: string;
|
|
608
|
+
/** Injeta um fetch (testes, runtimes sem fetch global). */
|
|
609
|
+
fetch?: typeof fetch;
|
|
610
|
+
}
|
|
611
|
+
interface RequestOptions {
|
|
612
|
+
query?: Record<string, string | number | undefined>;
|
|
613
|
+
body?: unknown;
|
|
614
|
+
}
|
|
615
|
+
/**
|
|
616
|
+
* Cliente da API da BotoZap.
|
|
617
|
+
*
|
|
618
|
+
* ```ts
|
|
619
|
+
* const boto = new BotoZap({ apiKey: process.env.BOTOZAP_KEY! });
|
|
620
|
+
* await boto.messages.send({ to: "+5531988887777", text: "Olá!" });
|
|
621
|
+
* ```
|
|
622
|
+
*/
|
|
623
|
+
declare class BotoZap {
|
|
624
|
+
readonly messages: Messages;
|
|
625
|
+
readonly customers: Customers;
|
|
626
|
+
readonly templates: Templates;
|
|
627
|
+
readonly broadcasts: Broadcasts;
|
|
628
|
+
readonly contacts: Contacts;
|
|
629
|
+
readonly conversations: Conversations;
|
|
630
|
+
readonly webhooks: Webhooks;
|
|
631
|
+
readonly phoneNumbers: PhoneNumbers;
|
|
632
|
+
readonly flows: Flows;
|
|
633
|
+
readonly media: Media;
|
|
634
|
+
readonly users: Users;
|
|
635
|
+
readonly apiLogs: ApiLogs;
|
|
636
|
+
readonly webhookDeliveries: WebhookDeliveries;
|
|
637
|
+
private readonly apiKey;
|
|
638
|
+
private readonly baseUrl;
|
|
639
|
+
private readonly fetchImpl;
|
|
640
|
+
constructor(options: BotoZapOptions);
|
|
641
|
+
/** Faz uma requisição autenticada e devolve o corpo já parseado. */
|
|
642
|
+
request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
643
|
+
/**
|
|
644
|
+
* Requisição a um endpoint de ITEM (singular). A API embrulha essas respostas
|
|
645
|
+
* em `{ data: <obj> }` (helper `ok`); este método desempacota e devolve a
|
|
646
|
+
* entidade. NÃO é uma heurística "se tem .data desempacota" — o desempacote é
|
|
647
|
+
* o contrato conhecido do endpoint, declarado por quem chama este método (as
|
|
648
|
+
* rotas de LISTA usam `request` e devolvem `{ data, paging|meta }` inteiro; a
|
|
649
|
+
* rota POST /messages responde direto e também usa `request`).
|
|
650
|
+
*/
|
|
651
|
+
requestItem<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
652
|
+
/** Resposta JSON direta que precisa ser um objeto (ex.: POST /messages). */
|
|
653
|
+
requestObject<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
654
|
+
/** Lista paginada por cursor: exige `{ data: [], paging: {} }`. */
|
|
655
|
+
requestCursorList<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
656
|
+
/** Lista paginada por offset: exige `{ data: [], meta: {} }`. */
|
|
657
|
+
requestOffsetList<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
/**
|
|
661
|
+
* Erro lançado quando a API responde fora da faixa 2xx. Carrega o envelope
|
|
662
|
+
* de erro da BotoZap: { error: { code, message } }, mais o status HTTP e, quando
|
|
663
|
+
* houve resposta HTTP (status > 0), os headers dela — úteis num 429 para ler
|
|
664
|
+
* `Retry-After` / `X-RateLimit-*`. Os headers são só os da RESPOSTA; nenhum
|
|
665
|
+
* header de request (que carrega a apiKey) entra aqui.
|
|
666
|
+
*/
|
|
667
|
+
declare class BotoZapError extends Error {
|
|
668
|
+
readonly code: string;
|
|
669
|
+
readonly status: number;
|
|
670
|
+
/** Headers da resposta HTTP. Ausente em erros sem resposta (status 0). */
|
|
671
|
+
readonly headers?: Record<string, string>;
|
|
672
|
+
constructor(code: string, message: string, status: number, headers?: Record<string, string>);
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
export { type AddRecipientsResult, type ApiLog, type Assignment, BotoZap, BotoZapError, type BotoZapOptions, type Broadcast, type BroadcastRecipient, type Contact, type Conversation, type CreateAssignmentParams, type CreateBroadcastParams, type CreateContactParams, type CreateCustomerParams, type CreateFlowParams, type CreateFlowVersionParams, type CreateSetupLinkParams, type CreateTemplateParams, type CreateWebhookParams, type CursorList, type CursorPaging, type CursorParams, type Customer, type Flow, type FlowPhoneParams, type FlowVersion, type ListApiLogsParams, type ListBroadcastsParams, type ListContactsParams, type ListConversationsParams, type ListFlowsParams, type ListMessagesParams, type ListPhoneNumbersParams, type ListRecipientsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type MediaUploadResult, type Message, type MessageStatus, type OffsetList, type OffsetMeta, type OffsetParams, type PhoneNumber, type RequestOptions, type ScheduleBroadcastParams, type SendResult, type SendTemplateParams, type SendTextParams, type SetFlowDataEndpointParams, type SetupLink, type Template, type TemplatePayload, type UpdateBroadcastParams, type UpdateCustomerParams, type UpdateSetupLinkParams, type UploadMediaParams, type User, type Webhook, type WebhookDelivery };
|