@raylongsolutions/saaselixir 0.0.0-stage → 1.0.1

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.
@@ -0,0 +1,382 @@
1
+ /** A WhatsApp message to send. Give a `template` (approved on your number), or `text` for a chat the customer opened in the last 24 hours. */
2
+ export interface SendMessage {
3
+ /** The customer's number with its country code, for example "919876543210". */
4
+ to: string;
5
+ /** Name of an approved template. */
6
+ template?: string;
7
+ /** Language of the template. Default "en". */
8
+ language?: string;
9
+ /** What goes in the template's blanks, in order: {{1}}, {{2}} and so on. */
10
+ values?: string[];
11
+ /** A picture, video or document link for a template with a media header, or the words for a text header. */
12
+ header?: string;
13
+ /** Words for a button that takes a changing part of a link, by button position (0 is the first button). */
14
+ buttons?: Record<number, string>;
15
+ /** Plain words, only for a chat that is still open. */
16
+ text?: string;
17
+ /** Your own id for this message, up to 60 characters. The same reference is never sent twice. The SDK makes one if you leave it out. */
18
+ reference?: string;
19
+ /** Send from this number when the account has more than one. */
20
+ channelId?: string;
21
+ }
22
+ export interface SendResult {
23
+ messageId: number;
24
+ /** Where the message stands now, for example "queued" or "sent". Delivered and read arrive by callback. */
25
+ status: string;
26
+ reference: string;
27
+ /** True when this reference had been sent before, so nothing new went out. */
28
+ repeated: boolean;
29
+ }
30
+ export interface Bot {
31
+ id: number;
32
+ name: string;
33
+ status: string;
34
+ /** The live version, or null while it has never been published. */
35
+ publishedVersion: number | null;
36
+ updatedAt: string;
37
+ }
38
+ /** What came back from building or changing a chatbot or automation by description. */
39
+ export interface BuildResult extends Bot {
40
+ /** What it did, in a sentence or two. */
41
+ summary: string;
42
+ /** Things left for you to finish on the screen, for example choosing a template. */
43
+ todo: string[];
44
+ /** What this cost, in rupees, from your AI wallet. */
45
+ charged: number;
46
+ /** Present when you asked for `publish: true`. */
47
+ published?: boolean;
48
+ version?: number;
49
+ /** Why it could not be published. */
50
+ problems?: string[];
51
+ channelId?: string | null;
52
+ }
53
+ export interface PublishResult extends Bot {
54
+ published: true;
55
+ version: number;
56
+ }
57
+ export interface BuildInput {
58
+ /** Describe it in plain words, 10 to 4000 characters. */
59
+ description: string;
60
+ name?: string;
61
+ /** Publish straight away when it is complete. */
62
+ publish?: boolean;
63
+ }
64
+ export interface EditInput {
65
+ instruction: string;
66
+ publish?: boolean;
67
+ }
68
+ export interface AutomationInput extends BuildInput {
69
+ channelId?: string;
70
+ }
71
+ export interface CallOptions {
72
+ timeoutMs?: number;
73
+ }
74
+ /** The calls SaasElixir makes to your address when a message moves on. */
75
+ export type MessageEventName = 'message.sent' | 'message.delivered' | 'message.read' | 'message.failed';
76
+ export interface MessageEvent {
77
+ event: MessageEventName;
78
+ messageId: number;
79
+ /** The reference you gave when you sent it. */
80
+ reference: string;
81
+ at: string;
82
+ /** Why it failed, for message.failed. */
83
+ error?: string;
84
+ }
85
+ /**
86
+ * A customer wrote to you. Sent only when "customer replies" is switched on beside your address on the API page.
87
+ * It can arrive more than once: use `wamid` to ignore repeats.
88
+ */
89
+ export interface ReplyEvent {
90
+ event: 'message.received';
91
+ /** WhatsApp's id of the customer's message. */
92
+ wamid: string;
93
+ /** The customer's number, digits only, with country code. */
94
+ from: string;
95
+ /** The name they use on WhatsApp. May be empty. */
96
+ name: string;
97
+ channelId: string;
98
+ /** text, interactive, button, image, video, audio, document, sticker, location, contacts and so on. */
99
+ type: string;
100
+ /** Their words, a button's title, or a photo or document caption. */
101
+ text?: string;
102
+ /** For a tap on a reply button or a list choice. */
103
+ button?: {
104
+ id: string;
105
+ title: string;
106
+ };
107
+ /** For a photo, video, audio, document or sticker: WhatsApp's id of the file. */
108
+ mediaId?: string;
109
+ /** Set when they answered a message you sent through the API: its messageId and your own reference. */
110
+ replyToMessageId?: number;
111
+ replyToReference?: string;
112
+ at: string;
113
+ }
114
+ export interface TestEvent {
115
+ event: 'test';
116
+ at: string;
117
+ }
118
+ export type WebhookEvent = MessageEvent | ReplyEvent | TestEvent;
119
+ /** Options for sending to many people. */
120
+ export interface BulkOptions {
121
+ /** How many go out at the same moment. Default 5, up to 20. */
122
+ concurrency?: number;
123
+ /**
124
+ * Gives each person the reference `<prefix>-<position>` when they have none of their own. Run the same list again with the same prefix
125
+ * and nobody is sent twice, so an interrupted run can simply be started again.
126
+ */
127
+ referencePrefix?: string;
128
+ /** Send once to each number even when it is listed twice. Default true. */
129
+ dedupe?: boolean;
130
+ /** Stop at the first failure of any kind. Default false: one bad number does not stop the rest. */
131
+ stopOnError?: boolean;
132
+ /** Called after each person, so you can show progress or save how far you got. */
133
+ onProgress?: (done: BulkItem, counts: {
134
+ total: number;
135
+ finished: number;
136
+ sent: number;
137
+ failed: number;
138
+ }) => void;
139
+ timeoutMs?: number;
140
+ }
141
+ export interface BulkItem {
142
+ to: string;
143
+ reference: string;
144
+ /** "sent": accepted by SaasElixir. "failed": refused or not reached, see `error`. "skipped": not tried, see `error`. */
145
+ outcome: 'sent' | 'failed' | 'skipped';
146
+ result?: SendResult;
147
+ error?: {
148
+ code: string;
149
+ message: string;
150
+ };
151
+ }
152
+ export interface BulkResult {
153
+ total: number;
154
+ sent: number;
155
+ failed: number;
156
+ skipped: number;
157
+ /** One row per person, in the order you gave. */
158
+ items: BulkItem[];
159
+ /** Set when the run stopped early because everything after would fail the same way, for example "no_balance" or "paused". */
160
+ stoppedBecause?: string;
161
+ }
162
+ export interface Template {
163
+ name: string;
164
+ language: string;
165
+ category: string;
166
+ /** APPROVED, PENDING, REJECTED and so on. Only APPROVED can be sent. */
167
+ status: string;
168
+ body: string;
169
+ /** How many blanks ({{1}}, {{2}}) the body has, so how many `values` to give. */
170
+ bodyVars: number;
171
+ headerFormat: string;
172
+ /** What the header needs when sending: "" none, "text", or "image", "video" or "document" (give a link). */
173
+ headerInput: '' | 'text' | 'image' | 'video' | 'document';
174
+ footer: string;
175
+ rejectedReason: string;
176
+ }
177
+ export interface TemplateList {
178
+ channelId: string;
179
+ templates: Template[];
180
+ }
181
+ export interface NumberBalance {
182
+ channelId: string;
183
+ number: string;
184
+ name: string;
185
+ /** Rupees. A message costs about a rupee or less, so under 1 nothing goes out. */
186
+ balance: number;
187
+ /** True when the number is live and holds at least a rupee. */
188
+ canSend: boolean;
189
+ }
190
+ /** Where a message stands: sending, accepted (WhatsApp has it), delivered, read or failed. */
191
+ export interface MessageInfo {
192
+ messageId: number;
193
+ reference: string;
194
+ to: string;
195
+ status: 'sending' | 'accepted' | 'delivered' | 'read' | 'failed' | (string & {});
196
+ template: string | null;
197
+ createdAt: string;
198
+ deliveredAt: string | null;
199
+ readAt: string | null;
200
+ /** Why it failed. */
201
+ error?: string;
202
+ }
203
+ export interface Contact {
204
+ contactId: number;
205
+ phone: string;
206
+ name: string;
207
+ tags: string[];
208
+ /** True when this person asked not to be messaged. Sends to them are refused. */
209
+ optedOut: boolean;
210
+ createdAt: string | null;
211
+ }
212
+ export interface ContactInput {
213
+ /** With country code, 8 to 15 digits. Spaces, + and dashes are fine. */
214
+ phone: string;
215
+ /** Used when the person is new. Left as it is for someone already there. Default: the number. */
216
+ name?: string;
217
+ /** Up to 10 tag names, each up to 40 characters, no commas. Added whether the person is new or not. */
218
+ tags?: string[];
219
+ /** The number to put them on, when the account has more than one. */
220
+ channelId?: string;
221
+ }
222
+ export interface ContactAdded extends Contact {
223
+ existing: boolean;
224
+ }
225
+ export interface ContactQuery {
226
+ tag?: string; /** Up to 100. Default 50. */
227
+ limit?: number; /** The `next` of the page before. */
228
+ after?: number;
229
+ }
230
+ export interface ContactPage {
231
+ contacts: Contact[]; /** Pass as `after` for the next page; null on the last. */
232
+ next: number | null;
233
+ }
234
+ export interface OptOut {
235
+ phone: string;
236
+ optedOut: boolean;
237
+ at: string | null;
238
+ }
239
+ export interface MemberInput {
240
+ /** With country code. A ten digit number is taken as Indian (+91) unless you pass `country`. */
241
+ phone: string;
242
+ name?: string;
243
+ /** Details to put in a template, by name, for example { plan: 'Gold', city: 'Pune' }. */
244
+ fields?: Record<string, string | number>;
245
+ }
246
+ export interface AudienceCreate {
247
+ name: string;
248
+ /** You confirm these people agreed to receive WhatsApp messages from you. Required: WhatsApp's rule, and a number can be blocked without it. */
249
+ consent: true;
250
+ members: MemberInput[];
251
+ /** Country code for ten digit numbers. Default "91". */
252
+ country?: string;
253
+ }
254
+ export interface RejectedRow {
255
+ index: number;
256
+ phone: string;
257
+ reason: string;
258
+ }
259
+ export interface AudienceCreated {
260
+ id: number;
261
+ name: string;
262
+ members: number;
263
+ fields: string[];
264
+ rejected: RejectedRow[];
265
+ }
266
+ export interface Audience {
267
+ id: number;
268
+ name: string;
269
+ members: number;
270
+ fields: string[];
271
+ createdAt: string;
272
+ }
273
+ export interface AudienceMore extends Audience {
274
+ added: number;
275
+ rejected: RejectedRow[];
276
+ }
277
+ /** What goes in one blank of a template: a detail of each person (with what to say when they have none), or the same words for everyone. */
278
+ export type Value = {
279
+ field: string;
280
+ fallback?: string;
281
+ } | {
282
+ text: string;
283
+ };
284
+ export interface BroadcastInput {
285
+ title: string;
286
+ /** Template name, or { name, language }. Language defaults to "en". */
287
+ template: string | {
288
+ name: string;
289
+ language?: string;
290
+ };
291
+ language?: string;
292
+ audienceId: number;
293
+ /** One value for each {{1}}, {{2}} of the template body, in order. A plain string means those words for everyone. */
294
+ body?: (Value | string)[];
295
+ /** For a template with a button that takes a changing part of a link. */
296
+ button?: Value | string;
297
+ /** A picture, video or document link for a media header, or a Value for a text header. */
298
+ header?: {
299
+ link: string;
300
+ } | {
301
+ text: Value | string;
302
+ };
303
+ /** Send from this number when the account has more than one. */
304
+ channelId?: string;
305
+ /** Count who taps the links in the message. Growth plan. */
306
+ trackClicks?: boolean;
307
+ }
308
+ export interface BroadcastPreview {
309
+ template: {
310
+ name: string;
311
+ language: string;
312
+ category: string;
313
+ body: string;
314
+ bodyVars: number;
315
+ };
316
+ counts: {
317
+ members: number;
318
+ send: number;
319
+ optedOut: number;
320
+ missingValues: number;
321
+ notAllowed: number;
322
+ };
323
+ samples: {
324
+ phone: string;
325
+ name: string;
326
+ rendered: string;
327
+ }[];
328
+ /** In rupees: what each message costs and the total. */
329
+ cost: {
330
+ unit: number;
331
+ total: number;
332
+ };
333
+ /** Rough minutes it will take to go out. */
334
+ minutes: number;
335
+ limits: {
336
+ dailyLimit: number;
337
+ usedToday: number;
338
+ remaining: number | null;
339
+ };
340
+ /** What the number holds, in rupees. */
341
+ wallet: number | null;
342
+ /** Things to fix before it can be made. */
343
+ problems: string[];
344
+ warnings: string[];
345
+ }
346
+ export type BroadcastStatus = 'draft' | 'scheduled' | 'sending' | 'paused' | 'done' | 'cancelled' | 'failed' | (string & {});
347
+ export interface Broadcast {
348
+ id: number;
349
+ title: string;
350
+ template: string;
351
+ status: BroadcastStatus;
352
+ /** People it will go to. */
353
+ recipients: number;
354
+ /** People left out (opted out, a missing detail, not allowed). */
355
+ skipped: number;
356
+ sent: number;
357
+ delivered: number;
358
+ read: number;
359
+ failed: number;
360
+ /** In rupees. */
361
+ estimatedCost: number;
362
+ scheduledFor: string | null;
363
+ createdAt: string;
364
+ error?: string;
365
+ pausedReason?: string;
366
+ }
367
+ export type RecipientState = 'pending' | 'sent' | 'delivered' | 'read' | 'failed' | 'left_out';
368
+ export interface Recipient {
369
+ phone: string;
370
+ name: string;
371
+ state: RecipientState; /** For left_out: opted_out, missing_values or not_allowed. */
372
+ why?: string;
373
+ error?: string;
374
+ }
375
+ export interface RecipientPage {
376
+ recipients: Recipient[];
377
+ next: number | null;
378
+ }
379
+ export interface SendNowOptions {
380
+ /** Refuse (code "too_costly") when the estimate is above this many rupees. Recommended: sending cannot be undone. */
381
+ maxCost?: number;
382
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,5 @@
1
+ import type { Value } from './types.js';
2
+ /** A detail of each person goes here, for example field('plan') or field('first_name', 'there') to say "there" when someone has none. Built in: first_name, name, phone. */
3
+ export declare const field: (name: string, fallback?: string) => Value;
4
+ /** The same words for everyone. A plain string works too. */
5
+ export declare const text: (words: string) => Value;
@@ -0,0 +1,4 @@
1
+ /** A detail of each person goes here, for example field('plan') or field('first_name', 'there') to say "there" when someone has none. Built in: first_name, name, phone. */
2
+ export const field = (name, fallback) => ({ field: name, ...(fallback ? { fallback } : {}) });
3
+ /** The same words for everyone. A plain string works too. */
4
+ export const text = (words) => ({ text: words });
@@ -0,0 +1,12 @@
1
+ import type { WebhookEvent } from './types.js';
2
+ /** The header SaasElixir puts the signature in. */
3
+ export declare const SIGNATURE_HEADER = "x-saaselixir-signature";
4
+ /**
5
+ * Is this call really from SaasElixir? Pass the signing secret from the API page (it starts with whsec_), the body exactly as it
6
+ * arrived (the raw text, not parsed and printed again) and the x-saaselixir-signature header.
7
+ */
8
+ export declare function verifySignature(secret: string, rawBody: string | Uint8Array, signature: string | string[] | null | undefined): boolean;
9
+ /** Checks the signature and hands back the event. Throws an Error when the signature is wrong or the body is not an event. */
10
+ export declare function constructEvent(secret: string, rawBody: string | Uint8Array, signature: string | string[] | null | undefined): WebhookEvent;
11
+ /** For your own tests: the signature SaasElixir would send for this body. */
12
+ export declare const signBody: (secret: string, body: string | Uint8Array) => string;
@@ -0,0 +1,32 @@
1
+ import { createHmac, timingSafeEqual } from 'node:crypto';
2
+ /** The header SaasElixir puts the signature in. */
3
+ export const SIGNATURE_HEADER = 'x-saaselixir-signature';
4
+ const hex = (secret, body) => createHmac('sha256', secret).update(body).digest('hex');
5
+ /**
6
+ * Is this call really from SaasElixir? Pass the signing secret from the API page (it starts with whsec_), the body exactly as it
7
+ * arrived (the raw text, not parsed and printed again) and the x-saaselixir-signature header.
8
+ */
9
+ export function verifySignature(secret, rawBody, signature) {
10
+ const given = (Array.isArray(signature) ? signature[0] : signature)?.trim().toLowerCase() ?? '';
11
+ if (!secret || !/^[0-9a-f]{64}$/.test(given))
12
+ return false;
13
+ return timingSafeEqual(Buffer.from(hex(secret, rawBody), 'hex'), Buffer.from(given, 'hex'));
14
+ }
15
+ /** Checks the signature and hands back the event. Throws an Error when the signature is wrong or the body is not an event. */
16
+ export function constructEvent(secret, rawBody, signature) {
17
+ if (!verifySignature(secret, rawBody, signature))
18
+ throw new Error('The signature does not match. This call did not come from SaasElixir, or the body was changed on the way.');
19
+ const text = typeof rawBody === 'string' ? rawBody : new TextDecoder().decode(rawBody);
20
+ let event;
21
+ try {
22
+ event = JSON.parse(text);
23
+ }
24
+ catch {
25
+ throw new Error('The body is not JSON.');
26
+ }
27
+ if (!event || typeof event !== 'object' || typeof event.event !== 'string')
28
+ throw new Error('The body is not a SaasElixir event.');
29
+ return event;
30
+ }
31
+ /** For your own tests: the signature SaasElixir would send for this body. */
32
+ export const signBody = hex;