@theokit/gateway-whatsapp 0.4.1 → 0.5.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 +129 -0
- package/README.md +115 -4
- package/dist/index.cjs +326 -94
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +224 -85
- package/dist/index.d.ts +224 -85
- package/dist/index.js +326 -94
- package/dist/index.js.map +1 -1
- package/package.json +18 -3
package/dist/index.d.ts
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
|
*
|
|
@@ -176,6 +251,22 @@ interface WhatsAppBackend {
|
|
|
176
251
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
177
252
|
}
|
|
178
253
|
|
|
254
|
+
/**
|
|
255
|
+
* Does an inbound WhatsApp message reach the agent, and as what?
|
|
256
|
+
*
|
|
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` and `decideInbound`, so
|
|
262
|
+
* there is one rule set to keep. `WhatsAppCloudBackend.handleWebhookPayload` calls `isForAnotherNumber` as well, for
|
|
263
|
+
* messages and for status receipts, so a route built on the backend alone is scoped to its number
|
|
264
|
+
* too.
|
|
265
|
+
*/
|
|
266
|
+
|
|
267
|
+
/** EC-7: digit-only normalizer for mention comparison (handles `+`, `-`, `()`, spaces). */
|
|
268
|
+
declare function digitsOnly(s: string): string;
|
|
269
|
+
|
|
179
270
|
/**
|
|
180
271
|
* `WhatsAppAdapter` — WhatsApp platform adapter for `@theokit/gateway`
|
|
181
272
|
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
@@ -209,8 +300,10 @@ interface WhatsAppCloudConfig {
|
|
|
209
300
|
* @platform-term Meta calls this an **app secret** — note it belongs to the Meta app, not to the
|
|
210
301
|
* WhatsApp Business account, which is why it is issued somewhere different from the access token
|
|
211
302
|
* above. It signs inbound payloads and never
|
|
212
|
-
* authenticates outbound calls, which is why it
|
|
213
|
-
* not need it.
|
|
303
|
+
* authenticates outbound calls, which is why it may be empty: an adapter that only sends does
|
|
304
|
+
* not need it. Verifying a webhook needs it: `verifyWebhookSignature` throws
|
|
305
|
+
* `ConfigurationError` for an empty or whitespace-only secret, because anyone can compute an
|
|
306
|
+
* HMAC under an empty key.
|
|
214
307
|
* @issued-at Meta for Developers, under the app's Settings → Basic.
|
|
215
308
|
*/
|
|
216
309
|
readonly appSecret: string;
|
|
@@ -296,8 +389,6 @@ interface WhatsAppAdapterCommonOptions {
|
|
|
296
389
|
*/
|
|
297
390
|
readonly allowedSenders?: string;
|
|
298
391
|
}
|
|
299
|
-
/** EC-7: digit-only normalizer for mention comparison (handles `+`, `-`, `()`, spaces). */
|
|
300
|
-
declare function digitsOnly(s: string): string;
|
|
301
392
|
/**
|
|
302
393
|
* Adapter facade. Implements `BasePlatformAdapter` (D172).
|
|
303
394
|
*
|
|
@@ -307,10 +398,25 @@ declare function digitsOnly(s: string): string;
|
|
|
307
398
|
declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
308
399
|
readonly platform: "whatsapp";
|
|
309
400
|
private readonly backendImpl;
|
|
310
|
-
|
|
401
|
+
/**
|
|
402
|
+
* The bot's number, digits only. Kept as its own field because the documented construction
|
|
403
|
+
* path is tested by reading it (`fromCloud` defaulting it to the phone number id).
|
|
404
|
+
*/
|
|
311
405
|
private readonly botPhoneId;
|
|
312
|
-
/**
|
|
313
|
-
private readonly
|
|
406
|
+
/** The sender allowlist and group rule the inbound path decides by. */
|
|
407
|
+
private readonly rules;
|
|
408
|
+
/**
|
|
409
|
+
* The Cloud phone number id this adapter answers for, read from the backend's declared
|
|
410
|
+
* `phoneNumberId` at construction (so `fromCloud`, `new WhatsAppAdapter(new WhatsAppCloudBackend(...))`
|
|
411
|
+
* and any backend declaring the field decide alike), `undefined` for a backend that declares none.
|
|
412
|
+
* Meta signs every number of one app with one secret, so a signed message is only this adapter's
|
|
413
|
+
* when its `phoneNumberId` is this one.
|
|
414
|
+
*/
|
|
415
|
+
private readonly ownPhoneNumberId;
|
|
416
|
+
/** Foreign phone number id endings already named on stderr, so each is reported once. */
|
|
417
|
+
private readonly reportedForeignNumbers;
|
|
418
|
+
/** The rules both inbound paths share; `onInbound` skips the precondition (see `decideForOwnNumber`). */
|
|
419
|
+
private readonly decide;
|
|
314
420
|
/** Mirrors the sibling adapters: guards connect() against opening a second session. */
|
|
315
421
|
private connected;
|
|
316
422
|
private handler?;
|
|
@@ -388,21 +494,50 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
388
494
|
connect(): Promise<boolean>;
|
|
389
495
|
disconnect(): Promise<void>;
|
|
390
496
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
497
|
+
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
391
498
|
/**
|
|
392
|
-
*
|
|
499
|
+
* The event `onInbound` would hand its handler for this inbound message, or `undefined` when the
|
|
500
|
+
* sender allowlist refuses it or the group rule drops it. A refusal writes the same stderr line
|
|
501
|
+
* `onInbound` writes.
|
|
502
|
+
*
|
|
503
|
+
* It also drops a message addressed to another phone number id than the one the backend
|
|
504
|
+
* declares (one app may serve several numbers under one secret), naming that id on stderr once.
|
|
505
|
+
* A Cloud message on an adapter whose backend declares no `phoneNumberId` throws, as in
|
|
506
|
+
* `toDeliverableEvents`; a WhatsApp Web or Baileys message has no number to compare.
|
|
393
507
|
*
|
|
394
|
-
*
|
|
395
|
-
* whether a message was meant for us, this one asks whether the sender may reach us at all.
|
|
508
|
+
* Pass the result to `deliver()`. Neither the backend nor the network is called.
|
|
396
509
|
*
|
|
397
|
-
*
|
|
398
|
-
*
|
|
510
|
+
* @throws {ConfigurationError} (`missing_phone_number_id`) for a Cloud message when the backend
|
|
511
|
+
* declares no `phoneNumberId`.
|
|
512
|
+
* @public
|
|
513
|
+
*/
|
|
514
|
+
toDeliverableEvent(inbound: WhatsAppInboundEvent): WhatsAppMessageEvent | undefined;
|
|
515
|
+
/**
|
|
516
|
+
* The events of one Meta Cloud webhook envelope that may reach the agent, in envelope order, with
|
|
517
|
+
* the sender allowlist and the group rule applied. Status receipts and non-text messages yield no
|
|
518
|
+
* event, so a status-only envelope returns `[]`. Each refused or dropped message writes the
|
|
519
|
+
* same stderr line `onInbound` writes. Messages addressed to another `phone_number_id` are
|
|
520
|
+
* dropped (see `toDeliverableEvent`).
|
|
521
|
+
*
|
|
522
|
+
* The adapter's backend must declare its `phoneNumberId`. `fromCloud` and any
|
|
523
|
+
* `WhatsAppCloudBackend` do; a backend that wraps one by delegation must expose the field too.
|
|
524
|
+
* Without it there is no number to compare, and every number of the Meta app would reach this
|
|
525
|
+
* adapter's agent, so this method fails closed instead (docs/adr/0006).
|
|
526
|
+
*
|
|
527
|
+
* The route that receives the webhook verifies `X-Hub-Signature-256` first (with
|
|
528
|
+
* `verifyWebhookSignature`, or theokit's `whatsapp()` route validator); this method does not. Meta redelivers on timeout, and
|
|
529
|
+
* `event.whatsapp.wamid` is the key a route can use to ignore a repeat. Neither the backend nor
|
|
530
|
+
* the network is called.
|
|
531
|
+
*
|
|
532
|
+
* @throws {ConfigurationError} (`missing_phone_number_id`) when the backend declares no
|
|
533
|
+
* `phoneNumberId`.
|
|
534
|
+
* @public
|
|
535
|
+
*/
|
|
536
|
+
toDeliverableEvents(envelope: MetaWebhookEnvelope): WhatsAppMessageEvent[];
|
|
537
|
+
/**
|
|
538
|
+
* Status receipts (sent/delivered/read/failed). Adapter-specific (D307). A receipt names the
|
|
539
|
+
* customer's number, so one addressed to another phone number id is dropped, as messages are.
|
|
399
540
|
*/
|
|
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
541
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
407
542
|
/**
|
|
408
543
|
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
@@ -749,61 +884,6 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
749
884
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
750
885
|
}
|
|
751
886
|
|
|
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
887
|
/**
|
|
808
888
|
* `WhatsAppCloudBackend` — Meta WhatsApp Business Cloud API backend (ADR D304).
|
|
809
889
|
*
|
|
@@ -863,6 +943,14 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
863
943
|
*/
|
|
864
944
|
private generation;
|
|
865
945
|
private readonly appSecret;
|
|
946
|
+
/**
|
|
947
|
+
* The Meta phone number id this backend sends as and answers for. Declared through
|
|
948
|
+
* `WhatsAppBackend.phoneNumberId`, so an adapter holding this backend can refuse a signed message
|
|
949
|
+
* addressed to another number of the same app.
|
|
950
|
+
*/
|
|
951
|
+
readonly phoneNumberId: string;
|
|
952
|
+
/** Foreign phone number id endings already named on stderr, so each is reported once. */
|
|
953
|
+
private readonly reportedForeignNumbers;
|
|
866
954
|
private inboundHandler?;
|
|
867
955
|
private statusHandler?;
|
|
868
956
|
constructor(opts: WhatsAppCloudBackendOptions);
|
|
@@ -907,10 +995,35 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
907
995
|
* Webhook entrypoint. The user calls this from inside their POST /webhook
|
|
908
996
|
* route after `verifyWebhookSubscription` on GET.
|
|
909
997
|
*
|
|
910
|
-
*
|
|
911
|
-
*
|
|
998
|
+
* Only messages addressed to this backend's `phoneNumberId` reach the inbound handler, and only
|
|
999
|
+
* status receipts addressed to it reach the status handler. Meta signs every number of one app
|
|
1000
|
+
* with one secret and an app-level webhook URL receives every subscribed number, so a valid
|
|
1001
|
+
* signature does not say which number a message or receipt was for; one for another number, or
|
|
1002
|
+
* naming none, is dropped and its id written to stderr once (`isForAnotherNumber`, the rule
|
|
1003
|
+
* `WhatsAppAdapter` applies too).
|
|
1004
|
+
*
|
|
1005
|
+
* @returns `true` if the signature is valid and the body was dispatched (or held nothing to
|
|
1006
|
+
* dispatch). `false` if the signature is invalid, if the signed body is not JSON or
|
|
1007
|
+
* has a shape {@link parseWebhookPayload} refuses, or if it holds a message for this
|
|
1008
|
+
* number while no inbound handler is subscribed (before `onInbound`, or after
|
|
1009
|
+
* `disconnect()`): the whole body is refused, never a part of it dropped, and one line
|
|
1010
|
+
* on stderr says which. Answer `false` with a non-2xx (401 for a bad signature) so the
|
|
1011
|
+
* drop is seen and Meta redelivers. Status receipts with no status handler subscribed
|
|
1012
|
+
* are discarded on purpose: subscribing to receipts is optional, and refusing them
|
|
1013
|
+
* would make Meta redeliver every receipt to a route that never wants one.
|
|
1014
|
+
* @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
|
|
1015
|
+
* whitespace only: a signature under an empty key proves nothing.
|
|
912
1016
|
*/
|
|
913
1017
|
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean>;
|
|
1018
|
+
/**
|
|
1019
|
+
* Hand each status receipt addressed to this backend's number to the status handler.
|
|
1020
|
+
*
|
|
1021
|
+
* Same rule as messages: a receipt names the recipient's phone number, so one number's receipts
|
|
1022
|
+
* reaching another number's handler hands one tenant's customer numbers to another tenant.
|
|
1023
|
+
*/
|
|
1024
|
+
private dispatchStatusReceipts;
|
|
1025
|
+
/** Hand each message, already scoped to this backend's number, to the inbound handler. */
|
|
1026
|
+
private dispatchInbound;
|
|
914
1027
|
/**
|
|
915
1028
|
* Parse a signed webhook body, or report `undefined` when it is not JSON.
|
|
916
1029
|
*
|
|
@@ -928,6 +1041,29 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
928
1041
|
private dispatchContained;
|
|
929
1042
|
}
|
|
930
1043
|
|
|
1044
|
+
/**
|
|
1045
|
+
* Meta's `X-Hub-Signature-256` check for a Cloud webhook body (ADR D312).
|
|
1046
|
+
*
|
|
1047
|
+
* Its own module, apart from the envelope normalizers in `webhook.ts`, because this is the line
|
|
1048
|
+
* between a signed webhook and anyone's POST, and mutation testing measures it file by file.
|
|
1049
|
+
*
|
|
1050
|
+
* @public
|
|
1051
|
+
*/
|
|
1052
|
+
/**
|
|
1053
|
+
* Verify the `X-Hub-Signature-256` HMAC-SHA256 against the app secret (D312).
|
|
1054
|
+
*
|
|
1055
|
+
* EC-3 absorbed: length-guard BEFORE `timingSafeEqual` so a malformed header
|
|
1056
|
+
* (e.g. `sha256=ab`) returns `false` instead of throwing `RangeError` (DoS).
|
|
1057
|
+
*
|
|
1058
|
+
* An empty or whitespace-only `appSecret` throws rather than answering: an HMAC under an empty
|
|
1059
|
+
* key is computable by anyone, so a match would prove nothing about Meta. `fromCloud` accepts an
|
|
1060
|
+
* empty secret for an adapter that only sends; such an adapter cannot verify a webhook.
|
|
1061
|
+
*
|
|
1062
|
+
* @returns `true` iff the signature matches.
|
|
1063
|
+
* @throws {ConfigurationError} `missing_option` when `appSecret` is empty or whitespace only.
|
|
1064
|
+
*/
|
|
1065
|
+
declare function verifyWebhookSignature(rawBody: Buffer | string, signatureHeader: string | undefined, appSecret: string): boolean;
|
|
1066
|
+
|
|
931
1067
|
/**
|
|
932
1068
|
* Webhook helpers for Meta WhatsApp Business Cloud API (ADR D306, D312).
|
|
933
1069
|
*
|
|
@@ -950,16 +1086,19 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
950
1086
|
* echoes the challenge as `text/plain` on success.
|
|
951
1087
|
*/
|
|
952
1088
|
declare function verifyWebhookSubscription(query: Record<string, string | undefined>, expectedVerifyToken: string): string | null;
|
|
1089
|
+
|
|
953
1090
|
/**
|
|
954
|
-
*
|
|
955
|
-
*
|
|
956
|
-
*
|
|
957
|
-
*
|
|
958
|
-
*
|
|
959
|
-
*
|
|
1091
|
+
* Parse the raw JSON payload into a typed envelope, or `null` when its shape is not one the
|
|
1092
|
+
* normalizers can read: no `object`, an `entry` that is not an array, or any entry, change or
|
|
1093
|
+
* listed contact, message or status that is not an object (an entry with no `changes` array, a
|
|
1094
|
+
* `null` change, `messages: 5`). The whole body is refused rather than its bad entries skipped, so
|
|
1095
|
+
* nothing in a batch is dropped without the route seeing it. A body is also refused when a field the
|
|
1096
|
+
* inbound rules read with string methods is not a string: a `metadata.phone_number_id` that is not
|
|
1097
|
+
* absent or a string, a text message whose `id`, `from` or `text.body` is not a string, a contact
|
|
1098
|
+
* whose `wa_id` or `profile.name` is not a string, or a status whose `id`, `status` or
|
|
1099
|
+
* `recipient_id` is not a string. Past a non-null result neither normalizer throws, and every
|
|
1100
|
+
* string field of an event or receipt holds a string. Timestamps are not checked here.
|
|
960
1101
|
*/
|
|
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
1102
|
declare function parseWebhookPayload(json: unknown): MetaWebhookEnvelope | null;
|
|
964
1103
|
/**
|
|
965
1104
|
* Extract the inbound messages from one Meta webhook envelope.
|
|
@@ -1227,4 +1366,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1227
1366
|
*/
|
|
1228
1367
|
declare function splitForWhatsApp(text: string): string[];
|
|
1229
1368
|
|
|
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 };
|
|
1369
|
+
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 };
|