@theokit/gateway-whatsapp 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +166 -0
- package/README.md +118 -4
- package/dist/index.cjs +346 -96
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +241 -93
- package/dist/index.d.ts +241 -93
- package/dist/index.js +346 -96
- package/dist/index.js.map +1 -1
- package/package.json +18 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,62 @@
|
|
|
1
1
|
import type { ChildProcess } from 'node:child_process';
|
|
2
|
-
import { GatewayConfigurationError, GatewayConfigurationErrorOptions, BasePlatformAdapter, OutboundMessage, SendResult, MessageEvent } from '@theokit/gateway';
|
|
2
|
+
import { GatewayConfigurationError, GatewayConfigurationErrorOptions, BasePlatformAdapter, OutboundMessage, SendResult, MessageEvent, WhatsAppMessageEvent } from '@theokit/gateway';
|
|
3
3
|
export { WhatsAppMessageEvent } from '@theokit/gateway';
|
|
4
4
|
|
|
5
|
+
/** Inbound webhook payload — the full envelope Meta POSTs. */
|
|
6
|
+
interface MetaWebhookEnvelope {
|
|
7
|
+
readonly object: string;
|
|
8
|
+
readonly entry: ReadonlyArray<MetaWebhookEntry>;
|
|
9
|
+
}
|
|
10
|
+
interface MetaWebhookEntry {
|
|
11
|
+
readonly id: string;
|
|
12
|
+
readonly changes: ReadonlyArray<MetaWebhookChange>;
|
|
13
|
+
}
|
|
14
|
+
interface MetaWebhookChange {
|
|
15
|
+
readonly value: MetaWebhookValue;
|
|
16
|
+
readonly field: string;
|
|
17
|
+
}
|
|
18
|
+
interface MetaWebhookValue {
|
|
19
|
+
readonly messaging_product: "whatsapp";
|
|
20
|
+
readonly metadata: {
|
|
21
|
+
readonly display_phone_number: string;
|
|
22
|
+
readonly phone_number_id: string;
|
|
23
|
+
};
|
|
24
|
+
readonly contacts?: ReadonlyArray<{
|
|
25
|
+
readonly profile: {
|
|
26
|
+
readonly name?: string;
|
|
27
|
+
};
|
|
28
|
+
readonly wa_id: string;
|
|
29
|
+
}>;
|
|
30
|
+
readonly messages?: ReadonlyArray<MetaIncomingMessage>;
|
|
31
|
+
readonly statuses?: ReadonlyArray<MetaStatusUpdate>;
|
|
32
|
+
}
|
|
33
|
+
interface MetaIncomingMessage {
|
|
34
|
+
readonly from: string;
|
|
35
|
+
readonly id: string;
|
|
36
|
+
readonly timestamp: string;
|
|
37
|
+
readonly type: string;
|
|
38
|
+
readonly text?: {
|
|
39
|
+
readonly body: string;
|
|
40
|
+
};
|
|
41
|
+
readonly context?: {
|
|
42
|
+
readonly from: string;
|
|
43
|
+
readonly id: string;
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
interface MetaStatusUpdate {
|
|
47
|
+
readonly id: string;
|
|
48
|
+
readonly status: "sent" | "delivered" | "read" | "failed";
|
|
49
|
+
readonly timestamp: string;
|
|
50
|
+
readonly recipient_id: string;
|
|
51
|
+
}
|
|
52
|
+
/** One component of a template — header, body or button — with its parameters. */
|
|
53
|
+
interface MetaTemplateComponent {
|
|
54
|
+
readonly type: string;
|
|
55
|
+
readonly parameters?: ReadonlyArray<Record<string, unknown>>;
|
|
56
|
+
readonly sub_type?: string;
|
|
57
|
+
readonly index?: string;
|
|
58
|
+
}
|
|
59
|
+
|
|
5
60
|
/**
|
|
6
61
|
* Backend abstraction (ADR D303). Lets `WhatsAppAdapter` stay backend-agnostic
|
|
7
62
|
* while we ship both Cloud (Meta API) and Web (`whatsapp-web.js` subprocess)
|
|
@@ -74,6 +129,14 @@ interface WhatsAppStatusReceipt {
|
|
|
74
129
|
readonly recipient: string;
|
|
75
130
|
/** Receipt timestamp. */
|
|
76
131
|
readonly timestamp: number;
|
|
132
|
+
/**
|
|
133
|
+
* Cloud only: the `phone_number_id` the receipt was addressed to, from the webhook's
|
|
134
|
+
* `metadata`. One Meta app signs every number's webhooks with one secret, so a route serving
|
|
135
|
+
* several numbers needs this to keep one number's receipts, and the recipient numbers they name,
|
|
136
|
+
* away from another number's handler. Absent on the web and Baileys backends, which serve one
|
|
137
|
+
* account each, and on a Cloud envelope that names no number.
|
|
138
|
+
*/
|
|
139
|
+
readonly phoneNumberId?: string;
|
|
77
140
|
}
|
|
78
141
|
/**
|
|
79
142
|
* What went wrong, in the vocabulary a caller can branch on.
|
|
@@ -132,6 +195,18 @@ interface WhatsAppSendResult {
|
|
|
132
195
|
*/
|
|
133
196
|
interface WhatsAppBackend {
|
|
134
197
|
readonly kind: "cloud" | "web" | "baileys";
|
|
198
|
+
/**
|
|
199
|
+
* The Meta Cloud phone number id this backend answers for. Absent on the web and Baileys
|
|
200
|
+
* backends, which hold one account's own socket and have no such id.
|
|
201
|
+
*
|
|
202
|
+
* Meta signs the webhooks of every number of one app with one secret, so a valid signature does
|
|
203
|
+
* not say which number an envelope was for. A `WhatsAppAdapter` reads this field, not the
|
|
204
|
+
* backend's class, to drop a message addressed to another number: a wrapped backend, a test
|
|
205
|
+
* double, or one built from the package's other module format keeps the check by declaring it.
|
|
206
|
+
* `WhatsAppAdapter.toDeliverableEvents` refuses to run on a backend that does not, rather
|
|
207
|
+
* than deliver every number's messages.
|
|
208
|
+
*/
|
|
209
|
+
readonly phoneNumberId?: string;
|
|
135
210
|
/**
|
|
136
211
|
* Make the backend usable, and report whether it is.
|
|
137
212
|
*
|
|
@@ -177,16 +252,25 @@ interface WhatsAppBackend {
|
|
|
177
252
|
}
|
|
178
253
|
|
|
179
254
|
/**
|
|
180
|
-
*
|
|
181
|
-
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
182
|
-
*
|
|
183
|
-
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
184
|
-
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
185
|
-
* `WhatsAppBackend` seam (D303).
|
|
255
|
+
* Does an inbound WhatsApp message reach the agent, and as what?
|
|
186
256
|
*
|
|
187
|
-
*
|
|
257
|
+
* The addressed-number check, the sender allowlist, the group-mention rule and the conversion to
|
|
258
|
+
* the gateway's event shape, as functions of their inputs (the only state is the set of foreign
|
|
259
|
+
* numbers already reported, which the caller owns). `WhatsAppAdapter` holds the configuration and
|
|
260
|
+
* passes it in; every adapter path that decides an inbound message goes through
|
|
261
|
+
* `decideForOwnNumber` (own-number.ts), which calls `isForAnotherNumber` (foreign-number.ts) and
|
|
262
|
+
* `decideInbound`, so there is one rule set to keep.
|
|
188
263
|
*/
|
|
189
264
|
|
|
265
|
+
/** EC-7: digit-only normalizer for mention comparison (handles `+`, `-`, `()`, spaces). */
|
|
266
|
+
declare function digitsOnly(s: string): string;
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* The options `WhatsAppAdapter` is built from: one config per backend and the options they share.
|
|
270
|
+
*
|
|
271
|
+
* Moved out of `adapter.ts` unchanged (B-674), so that file stays within its 500-line budget.
|
|
272
|
+
* `adapter.ts` re-exports every type here, so no import of them changes.
|
|
273
|
+
*/
|
|
190
274
|
/** Cloud (Meta WhatsApp Business Cloud API) backend config (ADR D304). */
|
|
191
275
|
interface WhatsAppCloudConfig {
|
|
192
276
|
/**
|
|
@@ -209,8 +293,10 @@ interface WhatsAppCloudConfig {
|
|
|
209
293
|
* @platform-term Meta calls this an **app secret** — note it belongs to the Meta app, not to the
|
|
210
294
|
* WhatsApp Business account, which is why it is issued somewhere different from the access token
|
|
211
295
|
* above. It signs inbound payloads and never
|
|
212
|
-
* authenticates outbound calls, which is why it
|
|
213
|
-
* not need it.
|
|
296
|
+
* authenticates outbound calls, which is why it may be empty: an adapter that only sends does
|
|
297
|
+
* not need it. Verifying a webhook needs it: `verifyWebhookSignature` throws
|
|
298
|
+
* `ConfigurationError` for an empty or whitespace-only secret, because anyone can compute an
|
|
299
|
+
* HMAC under an empty key.
|
|
214
300
|
* @issued-at Meta for Developers, under the app's Settings → Basic.
|
|
215
301
|
*/
|
|
216
302
|
readonly appSecret: string;
|
|
@@ -296,8 +382,18 @@ interface WhatsAppAdapterCommonOptions {
|
|
|
296
382
|
*/
|
|
297
383
|
readonly allowedSenders?: string;
|
|
298
384
|
}
|
|
299
|
-
|
|
300
|
-
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* `WhatsAppAdapter` — WhatsApp platform adapter for `@theokit/gateway`
|
|
388
|
+
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
389
|
+
*
|
|
390
|
+
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
391
|
+
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
392
|
+
* `WhatsAppBackend` seam (D303).
|
|
393
|
+
*
|
|
394
|
+
* @public
|
|
395
|
+
*/
|
|
396
|
+
|
|
301
397
|
/**
|
|
302
398
|
* Adapter facade. Implements `BasePlatformAdapter` (D172).
|
|
303
399
|
*
|
|
@@ -307,10 +403,25 @@ declare function digitsOnly(s: string): string;
|
|
|
307
403
|
declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
308
404
|
readonly platform: "whatsapp";
|
|
309
405
|
private readonly backendImpl;
|
|
310
|
-
|
|
406
|
+
/**
|
|
407
|
+
* The bot's number, digits only. Kept as its own field because the documented construction
|
|
408
|
+
* path is tested by reading it (`fromCloud` defaulting it to the phone number id).
|
|
409
|
+
*/
|
|
311
410
|
private readonly botPhoneId;
|
|
312
|
-
/**
|
|
313
|
-
private readonly
|
|
411
|
+
/** The sender allowlist and group rule the inbound path decides by. */
|
|
412
|
+
private readonly rules;
|
|
413
|
+
/**
|
|
414
|
+
* The Cloud phone number id this adapter answers for, read from the backend's declared
|
|
415
|
+
* `phoneNumberId` at construction (so `fromCloud`, `new WhatsAppAdapter(new WhatsAppCloudBackend(...))`
|
|
416
|
+
* and any backend declaring the field decide alike), `undefined` for a backend that declares none.
|
|
417
|
+
* Meta signs every number of one app with one secret, so a signed message is only this adapter's
|
|
418
|
+
* when its `phoneNumberId` is this one.
|
|
419
|
+
*/
|
|
420
|
+
private readonly ownPhoneNumberId;
|
|
421
|
+
/** Foreign phone number id endings already named on stderr, so each is reported once. */
|
|
422
|
+
private readonly reportedForeignNumbers;
|
|
423
|
+
/** The rules both inbound paths share; `onInbound` skips the precondition (see `decideForOwnNumber`). */
|
|
424
|
+
private readonly decide;
|
|
314
425
|
/** Mirrors the sibling adapters: guards connect() against opening a second session. */
|
|
315
426
|
private connected;
|
|
316
427
|
private handler?;
|
|
@@ -388,21 +499,51 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
388
499
|
connect(): Promise<boolean>;
|
|
389
500
|
disconnect(): Promise<void>;
|
|
390
501
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
502
|
+
private sendText;
|
|
503
|
+
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
391
504
|
/**
|
|
392
|
-
*
|
|
505
|
+
* The event `onInbound` would hand its handler for this inbound message, or `undefined` when the
|
|
506
|
+
* sender allowlist refuses it or the group rule drops it. A refusal writes the same stderr line
|
|
507
|
+
* `onInbound` writes.
|
|
508
|
+
*
|
|
509
|
+
* It also drops a message addressed to another phone number id than the one the backend
|
|
510
|
+
* declares (one app may serve several numbers under one secret), naming that id on stderr once.
|
|
511
|
+
* A Cloud message on an adapter whose backend declares no `phoneNumberId` throws, as in
|
|
512
|
+
* `toDeliverableEvents`; a WhatsApp Web or Baileys message has no number to compare.
|
|
393
513
|
*
|
|
394
|
-
*
|
|
395
|
-
* whether a message was meant for us, this one asks whether the sender may reach us at all.
|
|
514
|
+
* Pass the result to `deliver()`. Neither the backend nor the network is called.
|
|
396
515
|
*
|
|
397
|
-
*
|
|
398
|
-
*
|
|
516
|
+
* @throws {ConfigurationError} (`missing_phone_number_id`) for a Cloud message when the backend
|
|
517
|
+
* declares no `phoneNumberId`.
|
|
518
|
+
* @public
|
|
519
|
+
*/
|
|
520
|
+
toDeliverableEvent(inbound: WhatsAppInboundEvent): WhatsAppMessageEvent | undefined;
|
|
521
|
+
/**
|
|
522
|
+
* The events of one Meta Cloud webhook envelope that may reach the agent, in envelope order, with
|
|
523
|
+
* the sender allowlist and the group rule applied. Status receipts and non-text messages yield no
|
|
524
|
+
* event, so a status-only envelope returns `[]`. Each refused or dropped message writes the
|
|
525
|
+
* same stderr line `onInbound` writes. Messages addressed to another `phone_number_id` are
|
|
526
|
+
* dropped (see `toDeliverableEvent`).
|
|
527
|
+
*
|
|
528
|
+
* The adapter's backend must declare its `phoneNumberId`. `fromCloud` and any
|
|
529
|
+
* `WhatsAppCloudBackend` do; a backend that wraps one by delegation must expose the field too.
|
|
530
|
+
* Without it there is no number to compare, and every number of the Meta app would reach this
|
|
531
|
+
* adapter's agent, so this method fails closed instead (docs/adr/0006).
|
|
532
|
+
*
|
|
533
|
+
* The route that receives the webhook verifies `X-Hub-Signature-256` first (with
|
|
534
|
+
* `verifyWebhookSignature`, or theokit's `whatsapp()` route validator); this method does not. Meta redelivers on timeout, and
|
|
535
|
+
* `event.whatsapp.wamid` is the key a route can use to ignore a repeat. Neither the backend nor
|
|
536
|
+
* the network is called.
|
|
537
|
+
*
|
|
538
|
+
* @throws {ConfigurationError} (`missing_phone_number_id`) when the backend declares no
|
|
539
|
+
* `phoneNumberId`.
|
|
540
|
+
* @public
|
|
541
|
+
*/
|
|
542
|
+
toDeliverableEvents(envelope: MetaWebhookEnvelope): WhatsAppMessageEvent[];
|
|
543
|
+
/**
|
|
544
|
+
* Status receipts (sent/delivered/read/failed). Adapter-specific (D307). A receipt names the
|
|
545
|
+
* customer's number, so one addressed to another phone number id is dropped, as messages are.
|
|
399
546
|
*/
|
|
400
|
-
private isRefusedBySenderAllowlist;
|
|
401
|
-
/** D309 + EC-7: group filter with digit-only normalization. */
|
|
402
|
-
private shouldDropGroupMessage;
|
|
403
|
-
private toMessageEvent;
|
|
404
|
-
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
405
|
-
/** Status receipts (sent/delivered/read/failed). Adapter-specific (D307). */
|
|
406
547
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
407
548
|
/**
|
|
408
549
|
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
@@ -749,61 +890,6 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
749
890
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
750
891
|
}
|
|
751
892
|
|
|
752
|
-
/** Inbound webhook payload — the full envelope Meta POSTs. */
|
|
753
|
-
interface MetaWebhookEnvelope {
|
|
754
|
-
readonly object: string;
|
|
755
|
-
readonly entry: ReadonlyArray<MetaWebhookEntry>;
|
|
756
|
-
}
|
|
757
|
-
interface MetaWebhookEntry {
|
|
758
|
-
readonly id: string;
|
|
759
|
-
readonly changes: ReadonlyArray<MetaWebhookChange>;
|
|
760
|
-
}
|
|
761
|
-
interface MetaWebhookChange {
|
|
762
|
-
readonly value: MetaWebhookValue;
|
|
763
|
-
readonly field: string;
|
|
764
|
-
}
|
|
765
|
-
interface MetaWebhookValue {
|
|
766
|
-
readonly messaging_product: "whatsapp";
|
|
767
|
-
readonly metadata: {
|
|
768
|
-
readonly display_phone_number: string;
|
|
769
|
-
readonly phone_number_id: string;
|
|
770
|
-
};
|
|
771
|
-
readonly contacts?: ReadonlyArray<{
|
|
772
|
-
readonly profile: {
|
|
773
|
-
readonly name?: string;
|
|
774
|
-
};
|
|
775
|
-
readonly wa_id: string;
|
|
776
|
-
}>;
|
|
777
|
-
readonly messages?: ReadonlyArray<MetaIncomingMessage>;
|
|
778
|
-
readonly statuses?: ReadonlyArray<MetaStatusUpdate>;
|
|
779
|
-
}
|
|
780
|
-
interface MetaIncomingMessage {
|
|
781
|
-
readonly from: string;
|
|
782
|
-
readonly id: string;
|
|
783
|
-
readonly timestamp: string;
|
|
784
|
-
readonly type: string;
|
|
785
|
-
readonly text?: {
|
|
786
|
-
readonly body: string;
|
|
787
|
-
};
|
|
788
|
-
readonly context?: {
|
|
789
|
-
readonly from: string;
|
|
790
|
-
readonly id: string;
|
|
791
|
-
};
|
|
792
|
-
}
|
|
793
|
-
interface MetaStatusUpdate {
|
|
794
|
-
readonly id: string;
|
|
795
|
-
readonly status: "sent" | "delivered" | "read" | "failed";
|
|
796
|
-
readonly timestamp: string;
|
|
797
|
-
readonly recipient_id: string;
|
|
798
|
-
}
|
|
799
|
-
/** One component of a template — header, body or button — with its parameters. */
|
|
800
|
-
interface MetaTemplateComponent {
|
|
801
|
-
readonly type: string;
|
|
802
|
-
readonly parameters?: ReadonlyArray<Record<string, unknown>>;
|
|
803
|
-
readonly sub_type?: string;
|
|
804
|
-
readonly index?: string;
|
|
805
|
-
}
|
|
806
|
-
|
|
807
893
|
/**
|
|
808
894
|
* `WhatsAppCloudBackend` — Meta WhatsApp Business Cloud API backend (ADR D304).
|
|
809
895
|
*
|
|
@@ -863,6 +949,14 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
863
949
|
*/
|
|
864
950
|
private generation;
|
|
865
951
|
private readonly appSecret;
|
|
952
|
+
/**
|
|
953
|
+
* The Meta phone number id this backend sends as and answers for. Declared through
|
|
954
|
+
* `WhatsAppBackend.phoneNumberId`, so an adapter holding this backend can refuse a signed message
|
|
955
|
+
* addressed to another number of the same app.
|
|
956
|
+
*/
|
|
957
|
+
readonly phoneNumberId: string;
|
|
958
|
+
/** Foreign phone number id endings already named on stderr, so each is reported once. */
|
|
959
|
+
private readonly reportedForeignNumbers;
|
|
866
960
|
private inboundHandler?;
|
|
867
961
|
private statusHandler?;
|
|
868
962
|
constructor(opts: WhatsAppCloudBackendOptions);
|
|
@@ -907,10 +1001,38 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
907
1001
|
* Webhook entrypoint. The user calls this from inside their POST /webhook
|
|
908
1002
|
* route after `verifyWebhookSubscription` on GET.
|
|
909
1003
|
*
|
|
910
|
-
*
|
|
911
|
-
*
|
|
1004
|
+
* Only messages addressed to this backend's `phoneNumberId` reach the inbound handler, and only
|
|
1005
|
+
* status receipts addressed to it reach the status handler. Meta signs every number of one app
|
|
1006
|
+
* with one secret and an app-level webhook URL receives every subscribed number, so a valid
|
|
1007
|
+
* signature does not say which number a message or receipt was for; one for another number, or
|
|
1008
|
+
* naming none, is dropped and its id written to stderr once (`isForAnotherNumber`, the rule
|
|
1009
|
+
* `WhatsAppAdapter` applies too).
|
|
1010
|
+
*
|
|
1011
|
+
* @returns `true` if the signature is valid and the body was dispatched (or held nothing to
|
|
1012
|
+
* dispatch). `false` if the signature is invalid (answer 401), or if the body holds a
|
|
1013
|
+
* message for this number while no inbound handler is subscribed (before `onInbound`,
|
|
1014
|
+
* or after `disconnect()`): the whole body is refused, never a part of it dropped, and
|
|
1015
|
+
* one line on stderr says which; answer non-2xx so Meta redelivers once a handler is
|
|
1016
|
+
* subscribed. `"unreadable_body"` if the signature is valid but the body is not JSON
|
|
1017
|
+
* or has a shape {@link parseWebhookPayload} refuses: nothing is dispatched and one
|
|
1018
|
+
* line on stderr says why. This is not forgery, and redelivery cannot recover it:
|
|
1019
|
+
* Meta resends the same bytes, which are refused again. Answer it differently from a
|
|
1020
|
+
* bad signature (the README example answers 200 so Meta stops retrying). Status receipts with no status handler subscribed
|
|
1021
|
+
* are discarded on purpose: subscribing to receipts is optional, and refusing them
|
|
1022
|
+
* would make Meta redeliver every receipt to a route that never wants one.
|
|
1023
|
+
* @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
|
|
1024
|
+
* whitespace only: a signature under an empty key proves nothing.
|
|
1025
|
+
*/
|
|
1026
|
+
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean | "unreadable_body">;
|
|
1027
|
+
/**
|
|
1028
|
+
* Hand each status receipt addressed to this backend's number to the status handler.
|
|
1029
|
+
*
|
|
1030
|
+
* Same rule as messages: a receipt names the recipient's phone number, so one number's receipts
|
|
1031
|
+
* reaching another number's handler hands one tenant's customer numbers to another tenant.
|
|
912
1032
|
*/
|
|
913
|
-
|
|
1033
|
+
private dispatchStatusReceipts;
|
|
1034
|
+
/** Hand each message, already scoped to this backend's number, to the inbound handler. */
|
|
1035
|
+
private dispatchInbound;
|
|
914
1036
|
/**
|
|
915
1037
|
* Parse a signed webhook body, or report `undefined` when it is not JSON.
|
|
916
1038
|
*
|
|
@@ -928,6 +1050,29 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
928
1050
|
private dispatchContained;
|
|
929
1051
|
}
|
|
930
1052
|
|
|
1053
|
+
/**
|
|
1054
|
+
* Meta's `X-Hub-Signature-256` check for a Cloud webhook body (ADR D312).
|
|
1055
|
+
*
|
|
1056
|
+
* Its own module, apart from the envelope normalizers in `webhook.ts`, because this is the line
|
|
1057
|
+
* between a signed webhook and anyone's POST, and mutation testing measures it file by file.
|
|
1058
|
+
*
|
|
1059
|
+
* @public
|
|
1060
|
+
*/
|
|
1061
|
+
/**
|
|
1062
|
+
* Verify the `X-Hub-Signature-256` HMAC-SHA256 against the app secret (D312).
|
|
1063
|
+
*
|
|
1064
|
+
* EC-3 absorbed: length-guard BEFORE `timingSafeEqual` so a malformed header
|
|
1065
|
+
* (e.g. `sha256=ab`) returns `false` instead of throwing `RangeError` (DoS).
|
|
1066
|
+
*
|
|
1067
|
+
* An empty or whitespace-only `appSecret` throws rather than answering: an HMAC under an empty
|
|
1068
|
+
* key is computable by anyone, so a match would prove nothing about Meta. `fromCloud` accepts an
|
|
1069
|
+
* empty secret for an adapter that only sends; such an adapter cannot verify a webhook.
|
|
1070
|
+
*
|
|
1071
|
+
* @returns `true` iff the signature matches.
|
|
1072
|
+
* @throws {ConfigurationError} `missing_option` when `appSecret` is empty or whitespace only.
|
|
1073
|
+
*/
|
|
1074
|
+
declare function verifyWebhookSignature(rawBody: Buffer | string, signatureHeader: string | undefined, appSecret: string): boolean;
|
|
1075
|
+
|
|
931
1076
|
/**
|
|
932
1077
|
* Webhook helpers for Meta WhatsApp Business Cloud API (ADR D306, D312).
|
|
933
1078
|
*
|
|
@@ -950,16 +1095,19 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
950
1095
|
* echoes the challenge as `text/plain` on success.
|
|
951
1096
|
*/
|
|
952
1097
|
declare function verifyWebhookSubscription(query: Record<string, string | undefined>, expectedVerifyToken: string): string | null;
|
|
1098
|
+
|
|
953
1099
|
/**
|
|
954
|
-
*
|
|
955
|
-
*
|
|
956
|
-
*
|
|
957
|
-
*
|
|
958
|
-
*
|
|
959
|
-
*
|
|
1100
|
+
* Parse the raw JSON payload into a typed envelope, or `null` when its shape is not one the
|
|
1101
|
+
* normalizers can read: no `object`, an `entry` that is not an array, or any entry, change or
|
|
1102
|
+
* listed contact, message or status that is not an object (an entry with no `changes` array, a
|
|
1103
|
+
* `null` change, `messages: 5`). The whole body is refused rather than its bad entries skipped, so
|
|
1104
|
+
* nothing in a batch is dropped without the route seeing it. A body is also refused when a field the
|
|
1105
|
+
* inbound rules read with string methods is not a string: a `metadata.phone_number_id` that is not
|
|
1106
|
+
* absent or a string, a text message whose `id`, `from` or `text.body` is not a string, a contact
|
|
1107
|
+
* whose `wa_id` or `profile.name` is not a string, or a status whose `id`, `status` or
|
|
1108
|
+
* `recipient_id` is not a string. Past a non-null result neither normalizer throws, and every
|
|
1109
|
+
* string field of an event or receipt holds a string. Timestamps are not checked here.
|
|
960
1110
|
*/
|
|
961
|
-
declare function verifyWebhookSignature(rawBody: Buffer | string, signatureHeader: string | undefined, appSecret: string): boolean;
|
|
962
|
-
/** Parse the raw JSON payload into a typed envelope. Returns `null` if shape is unrecognized. */
|
|
963
1111
|
declare function parseWebhookPayload(json: unknown): MetaWebhookEnvelope | null;
|
|
964
1112
|
/**
|
|
965
1113
|
* Extract the inbound messages from one Meta webhook envelope.
|
|
@@ -1227,4 +1375,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1227
1375
|
*/
|
|
1228
1376
|
declare function splitForWhatsApp(text: string): string[];
|
|
1229
1377
|
|
|
1230
|
-
export { type BaileysSocketFactory, type BaileysSocketLike, type BaileysSocketOptions, ConfigurationError, type ConfigurationErrorOptions, type IpcCommand, type IpcEvent, LineBuffer, type MetaTemplateComponent, WhatsAppAdapter, type WhatsAppAdapterCommonOptions, type WhatsAppAdapterOptions, type WhatsAppBackend, WhatsAppBaileysBackend, type WhatsAppBaileysBackendOptions, type WhatsAppBaileysConfig, WhatsAppBridgeError, WhatsAppCloudBackend, type WhatsAppCloudBackendOptions, type WhatsAppCloudConfig, WhatsAppConnectTimeoutError, type WhatsAppInboundEvent, type WhatsAppOutboundMessage, type WhatsAppPairingState, type WhatsAppSendResult, type WhatsAppStatusReceipt, WhatsAppWebBackend, type WhatsAppWebBackendOptions, type WhatsAppWebConfig, createBaileysSocket, defaultBridgeScriptPath, digitsOnly, formatCommand, mapWhatsAppCloudError, mapWhatsAppWebError, normalizeInboundMessages, normalizeStatusReceipts, parseEvent, parseWebhookPayload, splitForWhatsApp, verifyWebhookSignature, verifyWebhookSubscription };
|
|
1378
|
+
export { type BaileysSocketFactory, type BaileysSocketLike, type BaileysSocketOptions, ConfigurationError, type ConfigurationErrorOptions, type IpcCommand, type IpcEvent, LineBuffer, type MetaTemplateComponent, type MetaWebhookEnvelope, WhatsAppAdapter, type WhatsAppAdapterCommonOptions, type WhatsAppAdapterOptions, type WhatsAppBackend, WhatsAppBaileysBackend, type WhatsAppBaileysBackendOptions, type WhatsAppBaileysConfig, WhatsAppBridgeError, WhatsAppCloudBackend, type WhatsAppCloudBackendOptions, type WhatsAppCloudConfig, WhatsAppConnectTimeoutError, type WhatsAppInboundEvent, type WhatsAppOutboundMessage, type WhatsAppPairingState, type WhatsAppSendResult, type WhatsAppStatusReceipt, WhatsAppWebBackend, type WhatsAppWebBackendOptions, type WhatsAppWebConfig, createBaileysSocket, defaultBridgeScriptPath, digitsOnly, formatCommand, mapWhatsAppCloudError, mapWhatsAppWebError, normalizeInboundMessages, normalizeStatusReceipts, parseEvent, parseWebhookPayload, splitForWhatsApp, verifyWebhookSignature, verifyWebhookSubscription };
|