@theokit/gateway-whatsapp 0.3.2 → 0.3.3
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 +21 -0
- package/README.md +80 -2
- package/dist/bridge/whatsapp-web-bridge.mjs +37 -6
- package/dist/index.cjs +149 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +96 -1
- package/dist/index.d.ts +96 -1
- package/dist/index.js +149 -8
- package/dist/index.js.map +1 -1
- package/package.json +11 -8
package/dist/index.d.cts
CHANGED
|
@@ -27,6 +27,16 @@ interface WhatsAppInboundEvent {
|
|
|
27
27
|
readonly text: string;
|
|
28
28
|
/** Receipt timestamp (ms since epoch). */
|
|
29
29
|
readonly receivedAt: number;
|
|
30
|
+
/**
|
|
31
|
+
* The account owner wrote this to themselves — a note-to-self, not a message from a stranger.
|
|
32
|
+
*
|
|
33
|
+
* Absent means "somebody else", never "not checked": only the path that deliberately admits a
|
|
34
|
+
* `fromMe` message inside the self-chat sets it. A consumer applying a sender policy should read
|
|
35
|
+
* this BEFORE an allowlist, because the sender identity cannot carry the answer — the self-chat
|
|
36
|
+
* reports the account's LID, and no user can be expected to look up their own LID to allowlist
|
|
37
|
+
* themselves.
|
|
38
|
+
*/
|
|
39
|
+
readonly fromSelf?: boolean;
|
|
30
40
|
/** Backend that emitted this event. */
|
|
31
41
|
readonly backend: "cloud" | "web" | "baileys";
|
|
32
42
|
/** Raw envelope for the escape hatch. */
|
|
@@ -292,6 +302,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
292
302
|
private connected;
|
|
293
303
|
private handler?;
|
|
294
304
|
private statusHandler?;
|
|
305
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
306
|
+
private warnedAboutFormat;
|
|
295
307
|
private inboundUnsubscribe?;
|
|
296
308
|
private statusUnsubscribe?;
|
|
297
309
|
/**
|
|
@@ -440,6 +452,17 @@ interface BaileysSocketLike {
|
|
|
440
452
|
id?: string;
|
|
441
453
|
};
|
|
442
454
|
} | undefined>;
|
|
455
|
+
/**
|
|
456
|
+
* Who this socket logged in as — present once the connection opens.
|
|
457
|
+
*
|
|
458
|
+
* Optional because a socket that never opened has no identity to report, and because tests
|
|
459
|
+
* replace this object wholesale. The backend reads BOTH ids: the self-chat is addressed by
|
|
460
|
+
* `lid`, not by `id`, so knowing only one leaves it unrecognised.
|
|
461
|
+
*/
|
|
462
|
+
readonly user?: {
|
|
463
|
+
readonly id?: string;
|
|
464
|
+
readonly lid?: string;
|
|
465
|
+
};
|
|
443
466
|
end?(error?: Error): void;
|
|
444
467
|
}
|
|
445
468
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -497,6 +520,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
497
520
|
* @public
|
|
498
521
|
*/
|
|
499
522
|
|
|
523
|
+
/**
|
|
524
|
+
* What the pairing is doing, for a caller that must ASK rather than be told.
|
|
525
|
+
*
|
|
526
|
+
* {@link WhatsAppBaileysBackendOptions.onQr} is push: it fires when WhatsApp issues a code, at a
|
|
527
|
+
* moment the caller does not choose. A screen is pull — it loads when someone opens it and has to
|
|
528
|
+
* ask what is true right now. With only the callback, showing a QR anywhere means every consumer
|
|
529
|
+
* keeping its own copy of the latest code and its own notion of whether pairing already succeeded,
|
|
530
|
+
* which is this backend's bookkeeping copied into each of them.
|
|
531
|
+
*
|
|
532
|
+
* @public
|
|
533
|
+
*/
|
|
534
|
+
interface WhatsAppPairingState {
|
|
535
|
+
/**
|
|
536
|
+
* `idle` before `connect()`, `awaiting_scan` while a code is outstanding, `connected` once the
|
|
537
|
+
* socket opens, `closed` when it dies without a scan.
|
|
538
|
+
*/
|
|
539
|
+
readonly status: "idle" | "awaiting_scan" | "connected" | "closed";
|
|
540
|
+
/**
|
|
541
|
+
* The most recent code, present only while `awaiting_scan`.
|
|
542
|
+
*
|
|
543
|
+
* WhatsApp reissues roughly every 20 seconds and the previous one stops working, so a screen
|
|
544
|
+
* holding the old square shows something that cannot be scanned. It is cleared on `connected`
|
|
545
|
+
* and on `closed` for the same reason: offering a code that leads nowhere is worse than
|
|
546
|
+
* offering none.
|
|
547
|
+
*/
|
|
548
|
+
readonly qr?: string;
|
|
549
|
+
/** When that code arrived, so a UI can show its age instead of a stale square. */
|
|
550
|
+
readonly qrAt?: number;
|
|
551
|
+
}
|
|
500
552
|
/** Construction options. @public */
|
|
501
553
|
interface WhatsAppBaileysBackendOptions {
|
|
502
554
|
/**
|
|
@@ -514,6 +566,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
514
566
|
/**
|
|
515
567
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
516
568
|
*
|
|
569
|
+
* **QR IS THE ONLY WAY IN.** Baileys exposes `requestPairingCode`, and WhatsApp refuses the codes
|
|
570
|
+
* this backend asks for — measured 2026-08-30 across three attempts, on both the 12- and 13-digit
|
|
571
|
+
* forms of a Brazilian number. The reference implementation of this same transport documents the
|
|
572
|
+
* same conclusion in one line ("Login is QR-only") while sending a custom `browser` triple exactly
|
|
573
|
+
* as this one does, so the triple is NOT established as the cause and no cause is claimed here.
|
|
574
|
+
* What is established is the outcome: a caller with no route to display a QR has no route to pair.
|
|
575
|
+
*
|
|
517
576
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
518
577
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
519
578
|
* without a route out the QR the session can never be paired.
|
|
@@ -567,6 +626,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
567
626
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
568
627
|
*/
|
|
569
628
|
private lastCloseError?;
|
|
629
|
+
/** The pairing, as a caller may ask for it. Never handed out mutable. */
|
|
630
|
+
private pairingState;
|
|
631
|
+
/**
|
|
632
|
+
* The JIDs that ARE this account, normalised. Empty until a socket reports who it logged in as.
|
|
633
|
+
*
|
|
634
|
+
* Empty means "not learned yet", and `isDispatchable` reads that as refusing everything this
|
|
635
|
+
* account sent — the same behaviour as before self-chat support existed. A backend that
|
|
636
|
+
* guessed here would answer in a stranger's conversation.
|
|
637
|
+
*/
|
|
638
|
+
private selfJids;
|
|
639
|
+
/**
|
|
640
|
+
* Ids this backend sent, most recent last. This is what stops the agent answering itself.
|
|
641
|
+
*
|
|
642
|
+
* Bounded because it is a loop guard, not a log: an unbounded set on a long-lived socket is a
|
|
643
|
+
* leak, and nothing needs to recognise an echo from an hour ago — WhatsApp delivers our own
|
|
644
|
+
* message back within seconds or not at all.
|
|
645
|
+
*/
|
|
646
|
+
private sentWamids;
|
|
570
647
|
private inboundHandler?;
|
|
571
648
|
private statusHandler?;
|
|
572
649
|
/**
|
|
@@ -588,6 +665,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
588
665
|
* guard once and opened two live sessions.
|
|
589
666
|
*/
|
|
590
667
|
connect(): Promise<boolean>;
|
|
668
|
+
/**
|
|
669
|
+
* What the pairing is doing right now.
|
|
670
|
+
*
|
|
671
|
+
* Read it as often as a screen needs; it is a snapshot, not a subscription.
|
|
672
|
+
*/
|
|
673
|
+
get pairing(): WhatsAppPairingState;
|
|
591
674
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
592
675
|
disconnect(): Promise<void>;
|
|
593
676
|
/**
|
|
@@ -845,6 +928,18 @@ interface BridgeHandle {
|
|
|
845
928
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
846
929
|
* pairings fail fast instead of hanging the app.
|
|
847
930
|
*
|
|
931
|
+
* **THE CONSUMER MUST PROVIDE A BROWSER.** `whatsapp-web.js` drives a real Chrome through
|
|
932
|
+
* Puppeteer, and this package ships none: the repository leaves `puppeteer` out of
|
|
933
|
+
* `pnpm.onlyBuiltDependencies`, so its postinstall never downloads one. Without a browser the
|
|
934
|
+
* bridge starts, cannot find Chrome, and says so in its own protocol rather than crashing —
|
|
935
|
+
* which is the whole of the B-002 fix, and is still not a connection. Set
|
|
936
|
+
* `PUPPETEER_EXECUTABLE_PATH` to a Chrome or Chromium you already have; the bridge is spawned
|
|
937
|
+
* without an explicit `env`, so it inherits yours.
|
|
938
|
+
*
|
|
939
|
+
* B-002 asked for exactly this sentence or for a buildable `puppeteer`, and shipped with
|
|
940
|
+
* neither. Measured 2026-08-29: with the variable set, the bridge reaches WhatsApp and issues
|
|
941
|
+
* a pairing QR. {@link WhatsAppBaileysBackend} needs no browser, which is why it exists.
|
|
942
|
+
*
|
|
848
943
|
* @public
|
|
849
944
|
*/
|
|
850
945
|
|
|
@@ -1077,4 +1172,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1077
1172
|
*/
|
|
1078
1173
|
declare function splitForWhatsApp(text: string): string[];
|
|
1079
1174
|
|
|
1080
|
-
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 WhatsAppSendResult, type WhatsAppStatusReceipt, WhatsAppWebBackend, type WhatsAppWebBackendOptions, type WhatsAppWebConfig, createBaileysSocket, defaultBridgeScriptPath, digitsOnly, formatCommand, mapWhatsAppCloudError, mapWhatsAppWebError, normalizeInboundMessages, normalizeStatusReceipts, parseEvent, parseWebhookPayload, splitForWhatsApp, verifyWebhookSignature, verifyWebhookSubscription };
|
|
1175
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -27,6 +27,16 @@ interface WhatsAppInboundEvent {
|
|
|
27
27
|
readonly text: string;
|
|
28
28
|
/** Receipt timestamp (ms since epoch). */
|
|
29
29
|
readonly receivedAt: number;
|
|
30
|
+
/**
|
|
31
|
+
* The account owner wrote this to themselves — a note-to-self, not a message from a stranger.
|
|
32
|
+
*
|
|
33
|
+
* Absent means "somebody else", never "not checked": only the path that deliberately admits a
|
|
34
|
+
* `fromMe` message inside the self-chat sets it. A consumer applying a sender policy should read
|
|
35
|
+
* this BEFORE an allowlist, because the sender identity cannot carry the answer — the self-chat
|
|
36
|
+
* reports the account's LID, and no user can be expected to look up their own LID to allowlist
|
|
37
|
+
* themselves.
|
|
38
|
+
*/
|
|
39
|
+
readonly fromSelf?: boolean;
|
|
30
40
|
/** Backend that emitted this event. */
|
|
31
41
|
readonly backend: "cloud" | "web" | "baileys";
|
|
32
42
|
/** Raw envelope for the escape hatch. */
|
|
@@ -292,6 +302,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
292
302
|
private connected;
|
|
293
303
|
private handler?;
|
|
294
304
|
private statusHandler?;
|
|
305
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
306
|
+
private warnedAboutFormat;
|
|
295
307
|
private inboundUnsubscribe?;
|
|
296
308
|
private statusUnsubscribe?;
|
|
297
309
|
/**
|
|
@@ -440,6 +452,17 @@ interface BaileysSocketLike {
|
|
|
440
452
|
id?: string;
|
|
441
453
|
};
|
|
442
454
|
} | undefined>;
|
|
455
|
+
/**
|
|
456
|
+
* Who this socket logged in as — present once the connection opens.
|
|
457
|
+
*
|
|
458
|
+
* Optional because a socket that never opened has no identity to report, and because tests
|
|
459
|
+
* replace this object wholesale. The backend reads BOTH ids: the self-chat is addressed by
|
|
460
|
+
* `lid`, not by `id`, so knowing only one leaves it unrecognised.
|
|
461
|
+
*/
|
|
462
|
+
readonly user?: {
|
|
463
|
+
readonly id?: string;
|
|
464
|
+
readonly lid?: string;
|
|
465
|
+
};
|
|
443
466
|
end?(error?: Error): void;
|
|
444
467
|
}
|
|
445
468
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -497,6 +520,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
497
520
|
* @public
|
|
498
521
|
*/
|
|
499
522
|
|
|
523
|
+
/**
|
|
524
|
+
* What the pairing is doing, for a caller that must ASK rather than be told.
|
|
525
|
+
*
|
|
526
|
+
* {@link WhatsAppBaileysBackendOptions.onQr} is push: it fires when WhatsApp issues a code, at a
|
|
527
|
+
* moment the caller does not choose. A screen is pull — it loads when someone opens it and has to
|
|
528
|
+
* ask what is true right now. With only the callback, showing a QR anywhere means every consumer
|
|
529
|
+
* keeping its own copy of the latest code and its own notion of whether pairing already succeeded,
|
|
530
|
+
* which is this backend's bookkeeping copied into each of them.
|
|
531
|
+
*
|
|
532
|
+
* @public
|
|
533
|
+
*/
|
|
534
|
+
interface WhatsAppPairingState {
|
|
535
|
+
/**
|
|
536
|
+
* `idle` before `connect()`, `awaiting_scan` while a code is outstanding, `connected` once the
|
|
537
|
+
* socket opens, `closed` when it dies without a scan.
|
|
538
|
+
*/
|
|
539
|
+
readonly status: "idle" | "awaiting_scan" | "connected" | "closed";
|
|
540
|
+
/**
|
|
541
|
+
* The most recent code, present only while `awaiting_scan`.
|
|
542
|
+
*
|
|
543
|
+
* WhatsApp reissues roughly every 20 seconds and the previous one stops working, so a screen
|
|
544
|
+
* holding the old square shows something that cannot be scanned. It is cleared on `connected`
|
|
545
|
+
* and on `closed` for the same reason: offering a code that leads nowhere is worse than
|
|
546
|
+
* offering none.
|
|
547
|
+
*/
|
|
548
|
+
readonly qr?: string;
|
|
549
|
+
/** When that code arrived, so a UI can show its age instead of a stale square. */
|
|
550
|
+
readonly qrAt?: number;
|
|
551
|
+
}
|
|
500
552
|
/** Construction options. @public */
|
|
501
553
|
interface WhatsAppBaileysBackendOptions {
|
|
502
554
|
/**
|
|
@@ -514,6 +566,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
514
566
|
/**
|
|
515
567
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
516
568
|
*
|
|
569
|
+
* **QR IS THE ONLY WAY IN.** Baileys exposes `requestPairingCode`, and WhatsApp refuses the codes
|
|
570
|
+
* this backend asks for — measured 2026-08-30 across three attempts, on both the 12- and 13-digit
|
|
571
|
+
* forms of a Brazilian number. The reference implementation of this same transport documents the
|
|
572
|
+
* same conclusion in one line ("Login is QR-only") while sending a custom `browser` triple exactly
|
|
573
|
+
* as this one does, so the triple is NOT established as the cause and no cause is claimed here.
|
|
574
|
+
* What is established is the outcome: a caller with no route to display a QR has no route to pair.
|
|
575
|
+
*
|
|
517
576
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
518
577
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
519
578
|
* without a route out the QR the session can never be paired.
|
|
@@ -567,6 +626,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
567
626
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
568
627
|
*/
|
|
569
628
|
private lastCloseError?;
|
|
629
|
+
/** The pairing, as a caller may ask for it. Never handed out mutable. */
|
|
630
|
+
private pairingState;
|
|
631
|
+
/**
|
|
632
|
+
* The JIDs that ARE this account, normalised. Empty until a socket reports who it logged in as.
|
|
633
|
+
*
|
|
634
|
+
* Empty means "not learned yet", and `isDispatchable` reads that as refusing everything this
|
|
635
|
+
* account sent — the same behaviour as before self-chat support existed. A backend that
|
|
636
|
+
* guessed here would answer in a stranger's conversation.
|
|
637
|
+
*/
|
|
638
|
+
private selfJids;
|
|
639
|
+
/**
|
|
640
|
+
* Ids this backend sent, most recent last. This is what stops the agent answering itself.
|
|
641
|
+
*
|
|
642
|
+
* Bounded because it is a loop guard, not a log: an unbounded set on a long-lived socket is a
|
|
643
|
+
* leak, and nothing needs to recognise an echo from an hour ago — WhatsApp delivers our own
|
|
644
|
+
* message back within seconds or not at all.
|
|
645
|
+
*/
|
|
646
|
+
private sentWamids;
|
|
570
647
|
private inboundHandler?;
|
|
571
648
|
private statusHandler?;
|
|
572
649
|
/**
|
|
@@ -588,6 +665,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
588
665
|
* guard once and opened two live sessions.
|
|
589
666
|
*/
|
|
590
667
|
connect(): Promise<boolean>;
|
|
668
|
+
/**
|
|
669
|
+
* What the pairing is doing right now.
|
|
670
|
+
*
|
|
671
|
+
* Read it as often as a screen needs; it is a snapshot, not a subscription.
|
|
672
|
+
*/
|
|
673
|
+
get pairing(): WhatsAppPairingState;
|
|
591
674
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
592
675
|
disconnect(): Promise<void>;
|
|
593
676
|
/**
|
|
@@ -845,6 +928,18 @@ interface BridgeHandle {
|
|
|
845
928
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
846
929
|
* pairings fail fast instead of hanging the app.
|
|
847
930
|
*
|
|
931
|
+
* **THE CONSUMER MUST PROVIDE A BROWSER.** `whatsapp-web.js` drives a real Chrome through
|
|
932
|
+
* Puppeteer, and this package ships none: the repository leaves `puppeteer` out of
|
|
933
|
+
* `pnpm.onlyBuiltDependencies`, so its postinstall never downloads one. Without a browser the
|
|
934
|
+
* bridge starts, cannot find Chrome, and says so in its own protocol rather than crashing —
|
|
935
|
+
* which is the whole of the B-002 fix, and is still not a connection. Set
|
|
936
|
+
* `PUPPETEER_EXECUTABLE_PATH` to a Chrome or Chromium you already have; the bridge is spawned
|
|
937
|
+
* without an explicit `env`, so it inherits yours.
|
|
938
|
+
*
|
|
939
|
+
* B-002 asked for exactly this sentence or for a buildable `puppeteer`, and shipped with
|
|
940
|
+
* neither. Measured 2026-08-29: with the variable set, the bridge reaches WhatsApp and issues
|
|
941
|
+
* a pairing QR. {@link WhatsAppBaileysBackend} needs no browser, which is why it exists.
|
|
942
|
+
*
|
|
848
943
|
* @public
|
|
849
944
|
*/
|
|
850
945
|
|
|
@@ -1077,4 +1172,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1077
1172
|
*/
|
|
1078
1173
|
declare function splitForWhatsApp(text: string): string[];
|
|
1079
1174
|
|
|
1080
|
-
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 WhatsAppSendResult, type WhatsAppStatusReceipt, WhatsAppWebBackend, type WhatsAppWebBackendOptions, type WhatsAppWebConfig, createBaileysSocket, defaultBridgeScriptPath, digitsOnly, formatCommand, mapWhatsAppCloudError, mapWhatsAppWebError, normalizeInboundMessages, normalizeStatusReceipts, parseEvent, parseWebhookPayload, splitForWhatsApp, verifyWebhookSignature, verifyWebhookSubscription };
|
|
1175
|
+
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 };
|
package/dist/index.js
CHANGED
|
@@ -79,18 +79,29 @@ function resolveParties(key, remoteJid) {
|
|
|
79
79
|
if (fromPhone.length === 0 || channelId.length === 0) return void 0;
|
|
80
80
|
return { fromPhone, channelId, isGroup };
|
|
81
81
|
}
|
|
82
|
-
function isDispatchable(key, remoteJid) {
|
|
83
|
-
if (
|
|
84
|
-
|
|
82
|
+
function isDispatchable(key, remoteJid, wamid, ctx) {
|
|
83
|
+
if (remoteJid === STATUS_BROADCAST_JID) return "no";
|
|
84
|
+
if (key.fromMe !== true) return "yes";
|
|
85
|
+
const selfJids = ctx?.selfJids;
|
|
86
|
+
if (selfJids === void 0 || selfJids.size === 0) return "no";
|
|
87
|
+
if (!selfJids.has(normalizeWhatsAppId(remoteJid))) return "no";
|
|
88
|
+
return ctx?.sentWamids?.has(wamid) === true ? "no" : "yes-from-self";
|
|
85
89
|
}
|
|
86
|
-
function
|
|
87
|
-
const envelope = asObject(raw);
|
|
90
|
+
function addressingOf(envelope) {
|
|
88
91
|
const key = envelope === void 0 ? void 0 : asObject(envelope.key);
|
|
89
92
|
if (key === void 0) return void 0;
|
|
90
93
|
const remoteJid = asText(key.remoteJid);
|
|
91
94
|
const wamid = asText(key.id);
|
|
92
95
|
if (remoteJid === void 0 || wamid === void 0) return void 0;
|
|
93
|
-
|
|
96
|
+
return { key, remoteJid, wamid };
|
|
97
|
+
}
|
|
98
|
+
function normalizeBaileysMessage(raw, ctx) {
|
|
99
|
+
const envelope = asObject(raw);
|
|
100
|
+
const addressed = addressingOf(envelope);
|
|
101
|
+
if (addressed === void 0) return void 0;
|
|
102
|
+
const { key, remoteJid, wamid } = addressed;
|
|
103
|
+
const verdict = isDispatchable(key, remoteJid, wamid, ctx);
|
|
104
|
+
if (verdict === "no") return void 0;
|
|
94
105
|
const text = extractText(envelope?.message);
|
|
95
106
|
if (text === void 0) return void 0;
|
|
96
107
|
const parties = resolveParties(key, remoteJid);
|
|
@@ -107,6 +118,7 @@ function normalizeBaileysMessage(raw) {
|
|
|
107
118
|
receivedAt: seconds * 1e3,
|
|
108
119
|
backend: "baileys",
|
|
109
120
|
raw,
|
|
121
|
+
...verdict === "yes-from-self" ? { fromSelf: true } : {},
|
|
110
122
|
...contactName !== void 0 ? { contactName } : {}
|
|
111
123
|
};
|
|
112
124
|
}
|
|
@@ -276,6 +288,7 @@ function endQuietly(socket) {
|
|
|
276
288
|
}
|
|
277
289
|
var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
|
|
278
290
|
var DEFAULT_SEND_TIMEOUT_MS = 3e4;
|
|
291
|
+
var SENT_WAMID_WINDOW = 256;
|
|
279
292
|
var WhatsAppBaileysBackend = class {
|
|
280
293
|
constructor(opts) {
|
|
281
294
|
this.opts = opts;
|
|
@@ -310,6 +323,54 @@ var WhatsAppBaileysBackend = class {
|
|
|
310
323
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
311
324
|
*/
|
|
312
325
|
lastCloseError;
|
|
326
|
+
/** The pairing, as a caller may ask for it. Never handed out mutable. */
|
|
327
|
+
pairingState = { status: "idle" };
|
|
328
|
+
/**
|
|
329
|
+
* The JIDs that ARE this account, normalised. Empty until a socket reports who it logged in as.
|
|
330
|
+
*
|
|
331
|
+
* Empty means "not learned yet", and `isDispatchable` reads that as refusing everything this
|
|
332
|
+
* account sent — the same behaviour as before self-chat support existed. A backend that
|
|
333
|
+
* guessed here would answer in a stranger's conversation.
|
|
334
|
+
*/
|
|
335
|
+
selfJids = /* @__PURE__ */ new Set();
|
|
336
|
+
/**
|
|
337
|
+
* Ids this backend sent, most recent last. This is what stops the agent answering itself.
|
|
338
|
+
*
|
|
339
|
+
* Bounded because it is a loop guard, not a log: an unbounded set on a long-lived socket is a
|
|
340
|
+
* leak, and nothing needs to recognise an echo from an hour ago — WhatsApp delivers our own
|
|
341
|
+
* message back within seconds or not at all.
|
|
342
|
+
*/
|
|
343
|
+
sentWamids = /* @__PURE__ */ new Set();
|
|
344
|
+
/** Record one id we sent, evicting the oldest once the window is full. @internal */
|
|
345
|
+
rememberSent(wamid) {
|
|
346
|
+
this.sentWamids.add(wamid);
|
|
347
|
+
while (this.sentWamids.size > SENT_WAMID_WINDOW) {
|
|
348
|
+
const oldest = this.sentWamids.values().next();
|
|
349
|
+
if (oldest.done === true) break;
|
|
350
|
+
this.sentWamids.delete(oldest.value);
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* Learn which JIDs are this account, from the socket that just logged in.
|
|
355
|
+
*
|
|
356
|
+
* Both forms are recorded: the phone JID and the LID. The self-chat is addressed by LID —
|
|
357
|
+
* measured on a real account, where a note-to-self arrived on `231116569108705@lid` while the
|
|
358
|
+
* account's phone JID was `553598838687` — so recording only one leaves the self-chat
|
|
359
|
+
* unrecognised and the feature silently off.
|
|
360
|
+
*
|
|
361
|
+
* @internal
|
|
362
|
+
*/
|
|
363
|
+
learnSelfJids(socket) {
|
|
364
|
+
const user = socket.user;
|
|
365
|
+
const ids = [user?.id, user?.lid].filter((id) => typeof id === "string" && id.length > 0).map((id) => normalizeWhatsAppId(id)).filter((id) => id.length > 0);
|
|
366
|
+
this.selfJids = new Set(ids);
|
|
367
|
+
if (process.env.THEOKIT_WHATSAPP_TRACE === "1") {
|
|
368
|
+
process.stderr.write(
|
|
369
|
+
`[whatsapp-baileys][trace] selfJids learned: ${ids.length === 0 ? "(none)" : ids.join(", ")}
|
|
370
|
+
`
|
|
371
|
+
);
|
|
372
|
+
}
|
|
373
|
+
}
|
|
313
374
|
inboundHandler;
|
|
314
375
|
statusHandler;
|
|
315
376
|
/**
|
|
@@ -366,20 +427,68 @@ var WhatsAppBaileysBackend = class {
|
|
|
366
427
|
}
|
|
367
428
|
if (this.socket !== void 0 && this.socket !== socket) endQuietly(this.socket);
|
|
368
429
|
this.socket = socket;
|
|
430
|
+
this.learnSelfJids(socket);
|
|
369
431
|
this.connected = true;
|
|
370
432
|
return true;
|
|
371
433
|
}
|
|
434
|
+
/**
|
|
435
|
+
* What the pairing is doing right now.
|
|
436
|
+
*
|
|
437
|
+
* Read it as often as a screen needs; it is a snapshot, not a subscription.
|
|
438
|
+
*/
|
|
439
|
+
get pairing() {
|
|
440
|
+
return this.pairingState;
|
|
441
|
+
}
|
|
372
442
|
/** Build a socket through the injected factory, or the real one. @internal */
|
|
373
443
|
async buildSocket() {
|
|
374
444
|
const factory = this.opts.socketFactory ?? createBaileysSocket;
|
|
375
445
|
return factory({
|
|
376
446
|
sessionDir: this.opts.sessionDir,
|
|
377
|
-
|
|
447
|
+
// ALWAYS supplied, even when the caller wants none: a backend that only forwards cannot
|
|
448
|
+
// answer `pairing`, and the caller's own handler still runs, so wiring one costs nothing.
|
|
449
|
+
onQr: (qr) => {
|
|
450
|
+
this.pairingState = { status: "awaiting_scan", qr, qrAt: Date.now() };
|
|
451
|
+
this.opts.onQr?.(qr);
|
|
452
|
+
}
|
|
453
|
+
});
|
|
454
|
+
}
|
|
455
|
+
/**
|
|
456
|
+
* Trace one inbound batch BEFORE any filter, when `THEOKIT_WHATSAPP_TRACE=1`.
|
|
457
|
+
*
|
|
458
|
+
* Two independent filters can discard an envelope — the batch `type` here and `fromMe` inside
|
|
459
|
+
* `normalizeBaileysMessage` — and from outside, both look identical: nothing happens. Telling
|
|
460
|
+
* them apart by reading the code is guessing; this is how you find out which one fired.
|
|
461
|
+
*
|
|
462
|
+
* Deliberately content-free. A Baileys session pairs a REAL account carrying real
|
|
463
|
+
* conversations, so the trace records shape (type, direction, group, has-text) and the last
|
|
464
|
+
* four digits of the jid, never the message and never a full contact number.
|
|
465
|
+
*
|
|
466
|
+
* @internal
|
|
467
|
+
*/
|
|
468
|
+
traceBatch(payload) {
|
|
469
|
+
if (process.env.THEOKIT_WHATSAPP_TRACE !== "1") return;
|
|
470
|
+
const messages = payload.messages ?? [];
|
|
471
|
+
const rows = messages.map((raw) => {
|
|
472
|
+
const key = raw?.key ?? {};
|
|
473
|
+
const jid = typeof key.remoteJid === "string" ? key.remoteJid : "";
|
|
474
|
+
const message = raw?.message;
|
|
475
|
+
return [
|
|
476
|
+
`fromMe=${String(key.fromMe === true)}`,
|
|
477
|
+
`jid=\u2026${jid.replace(/\D/g, "").slice(-4)}`,
|
|
478
|
+
`group=${String(jid.endsWith("@g.us"))}`,
|
|
479
|
+
`hasMessage=${String(message !== null && message !== void 0)}`
|
|
480
|
+
].join(" ");
|
|
378
481
|
});
|
|
482
|
+
process.stderr.write(
|
|
483
|
+
`[whatsapp-baileys][trace] upsert type=${payload.type ?? "(none)"} n=${messages.length}` + (rows.length === 0 ? "\n" : `
|
|
484
|
+
${rows.join("\n ")}
|
|
485
|
+
`)
|
|
486
|
+
);
|
|
379
487
|
}
|
|
380
488
|
/** Route this socket's inbound batches into the handler, while it is still current. @internal */
|
|
381
489
|
subscribeInbound(socket, isCurrent) {
|
|
382
490
|
socket.ev.on("messages.upsert", (payload) => {
|
|
491
|
+
this.traceBatch(payload);
|
|
383
492
|
if (payload.type !== void 0 && payload.type !== "notify") return;
|
|
384
493
|
if (!isCurrent()) return;
|
|
385
494
|
for (const raw of payload.messages ?? []) this.dispatchInbound(raw);
|
|
@@ -406,12 +515,14 @@ var WhatsAppBaileysBackend = class {
|
|
|
406
515
|
socket.ev.on("connection.update", (update) => {
|
|
407
516
|
if (!isCurrent()) return;
|
|
408
517
|
if (update.connection === "open") {
|
|
518
|
+
this.pairingState = { status: "connected" };
|
|
409
519
|
settle(true);
|
|
410
520
|
return;
|
|
411
521
|
}
|
|
412
522
|
if (update.connection !== "close") return;
|
|
413
523
|
this.lastCloseError = update.lastDisconnect?.error;
|
|
414
524
|
this.connected = false;
|
|
525
|
+
this.pairingState = { status: "closed" };
|
|
415
526
|
if (this.socket === socket) this.socket = void 0;
|
|
416
527
|
endQuietly(socket);
|
|
417
528
|
settle(false);
|
|
@@ -534,6 +645,7 @@ var WhatsAppBaileysBackend = class {
|
|
|
534
645
|
};
|
|
535
646
|
}
|
|
536
647
|
const wamid = outcome?.key?.id;
|
|
648
|
+
if (wamid !== void 0) this.rememberSent(wamid);
|
|
537
649
|
return wamid !== void 0 ? { ok: true, wamid } : { ok: true };
|
|
538
650
|
}).catch((err) => ({
|
|
539
651
|
ok: false,
|
|
@@ -577,7 +689,10 @@ var WhatsAppBaileysBackend = class {
|
|
|
577
689
|
dispatchInbound(raw) {
|
|
578
690
|
const handler = this.inboundHandler;
|
|
579
691
|
if (handler === void 0) return;
|
|
580
|
-
const event = normalizeBaileysMessage(raw
|
|
692
|
+
const event = normalizeBaileysMessage(raw, {
|
|
693
|
+
selfJids: this.selfJids,
|
|
694
|
+
sentWamids: this.sentWamids
|
|
695
|
+
});
|
|
581
696
|
if (event === void 0) return;
|
|
582
697
|
void handler(event).catch((err) => {
|
|
583
698
|
const message = err instanceof Error ? err.message : String(err);
|
|
@@ -1467,6 +1582,30 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
1467
1582
|
connected = false;
|
|
1468
1583
|
handler;
|
|
1469
1584
|
statusHandler;
|
|
1585
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
1586
|
+
warnedAboutFormat = false;
|
|
1587
|
+
/**
|
|
1588
|
+
* Say, once, that a declared `format` has nowhere to go on this platform.
|
|
1589
|
+
*
|
|
1590
|
+
* WhatsApp's emphasis is INLINE — `*bold*`, `_italic_` — carried in the message text itself,
|
|
1591
|
+
* with no field on the request to set and no escape sequence to suppress it. So a caller
|
|
1592
|
+
* declaring `markdown` has already put the syntax in the text, and one declaring `html` is
|
|
1593
|
+
* asking for something the platform does not have.
|
|
1594
|
+
*
|
|
1595
|
+
* Reading the field is what turns a silent discard into a stated one — the swallowed-error
|
|
1596
|
+
* shape `rules/error-handling.md` refuses.
|
|
1597
|
+
*
|
|
1598
|
+
* @internal
|
|
1599
|
+
*/
|
|
1600
|
+
warnFormatUnsupported(format) {
|
|
1601
|
+
if (format === void 0 || format === "plain") return;
|
|
1602
|
+
if (this.warnedAboutFormat) return;
|
|
1603
|
+
this.warnedAboutFormat = true;
|
|
1604
|
+
process.stderr.write(
|
|
1605
|
+
`[whatsapp] format="${format}" was declared, and WhatsApp cannot carry it as a flag \u2014 its emphasis is inline in the text. Sending as-is; this is logged once.
|
|
1606
|
+
`
|
|
1607
|
+
);
|
|
1608
|
+
}
|
|
1470
1609
|
// EC-H: track unsubscribe handles so onInbound REPLACES instead of stacks.
|
|
1471
1610
|
inboundUnsubscribe;
|
|
1472
1611
|
statusUnsubscribe;
|
|
@@ -1610,6 +1749,7 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
1610
1749
|
if (out.text.length === 0) {
|
|
1611
1750
|
return { ok: false, error: { code: "empty_text", message: "Empty text rejected." } };
|
|
1612
1751
|
}
|
|
1752
|
+
this.warnFormatUnsupported(out.format);
|
|
1613
1753
|
const parts = splitForWhatsApp(out.text);
|
|
1614
1754
|
if (parts.length === 0) {
|
|
1615
1755
|
return {
|
|
@@ -1641,6 +1781,7 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
1641
1781
|
* first thing a mistyped allowlist causes is an operator wondering why the bot went mute.
|
|
1642
1782
|
*/
|
|
1643
1783
|
isRefusedBySenderAllowlist(inbound) {
|
|
1784
|
+
if (inbound.fromSelf === true) return false;
|
|
1644
1785
|
if (this.allowedSenders === void 0) return false;
|
|
1645
1786
|
if (isSenderAllowed(inbound.fromPhone, this.allowedSenders)) return false;
|
|
1646
1787
|
process.stderr.write(
|