@theokit/gateway-whatsapp 0.3.2 → 0.4.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 +94 -0
- package/README.md +91 -2
- package/dist/bridge/whatsapp-web-bridge.mjs +37 -6
- package/dist/index.cjs +218 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +151 -1
- package/dist/index.d.ts +151 -1
- package/dist/index.js +218 -13
- package/dist/index.js.map +1 -1
- package/package.json +11 -8
package/dist/index.d.cts
CHANGED
|
@@ -23,10 +23,33 @@ interface WhatsAppInboundEvent {
|
|
|
23
23
|
readonly conversationType: "dm" | "group";
|
|
24
24
|
/** Channel id — either the sender phone (DM) or the group id (group). */
|
|
25
25
|
readonly channelId: string;
|
|
26
|
+
/**
|
|
27
|
+
* The address this message arrived on, verbatim — the one a reply must be sent to.
|
|
28
|
+
*
|
|
29
|
+
* `channelId` is normalised to digits, which is what the allowlist compares and what a session
|
|
30
|
+
* key is built from. That normalisation strips the DOMAIN, and the domain is what says which kind
|
|
31
|
+
* of identifier this is: `@s.whatsapp.net` is a phone JID, `@g.us` a group, `@lid` an account's
|
|
32
|
+
* linked identity. A note-to-self arrives addressed by LID, so replying to the digits rebuilds
|
|
33
|
+
* `…@s.whatsapp.net` — an address that does not exist, and a send that reports ok and lands
|
|
34
|
+
* nowhere (#84).
|
|
35
|
+
*
|
|
36
|
+
* Optional because the Cloud backend has no JID to report; it addresses recipients by phone.
|
|
37
|
+
*/
|
|
38
|
+
readonly channelJid?: string;
|
|
26
39
|
/** Plain-text body (already filtered by EC-4 — text-only in v1). */
|
|
27
40
|
readonly text: string;
|
|
28
41
|
/** Receipt timestamp (ms since epoch). */
|
|
29
42
|
readonly receivedAt: number;
|
|
43
|
+
/**
|
|
44
|
+
* The account owner wrote this to themselves — a note-to-self, not a message from a stranger.
|
|
45
|
+
*
|
|
46
|
+
* Absent means "somebody else", never "not checked": only the path that deliberately admits a
|
|
47
|
+
* `fromMe` message inside the self-chat sets it. A consumer applying a sender policy should read
|
|
48
|
+
* this BEFORE an allowlist, because the sender identity cannot carry the answer — the self-chat
|
|
49
|
+
* reports the account's LID, and no user can be expected to look up their own LID to allowlist
|
|
50
|
+
* themselves.
|
|
51
|
+
*/
|
|
52
|
+
readonly fromSelf?: boolean;
|
|
30
53
|
/** Backend that emitted this event. */
|
|
31
54
|
readonly backend: "cloud" | "web" | "baileys";
|
|
32
55
|
/** Raw envelope for the escape hatch. */
|
|
@@ -292,6 +315,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
292
315
|
private connected;
|
|
293
316
|
private handler?;
|
|
294
317
|
private statusHandler?;
|
|
318
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
319
|
+
private warnedAboutFormat;
|
|
295
320
|
private inboundUnsubscribe?;
|
|
296
321
|
private statusUnsubscribe?;
|
|
297
322
|
/**
|
|
@@ -379,6 +404,13 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
379
404
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
380
405
|
/** Status receipts (sent/delivered/read/failed). Adapter-specific (D307). */
|
|
381
406
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
407
|
+
/**
|
|
408
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
409
|
+
*
|
|
410
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
411
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
412
|
+
*/
|
|
413
|
+
deliver(event: MessageEvent): Promise<"ok" | "no_handler" | "handler_threw">;
|
|
382
414
|
}
|
|
383
415
|
|
|
384
416
|
/**
|
|
@@ -440,6 +472,29 @@ interface BaileysSocketLike {
|
|
|
440
472
|
id?: string;
|
|
441
473
|
};
|
|
442
474
|
} | undefined>;
|
|
475
|
+
/**
|
|
476
|
+
* Ask the server which numbers are registered, and under which JID it routes them.
|
|
477
|
+
*
|
|
478
|
+
* Optional because an older Baileys, or a fake in a test that predates this, may not have it.
|
|
479
|
+
* When it is absent the backend sends to the number as given — the behaviour before #82 — rather
|
|
480
|
+
* than refusing everything, because refusing on a missing capability would turn an upgrade
|
|
481
|
+
* problem into an outage.
|
|
482
|
+
*/
|
|
483
|
+
onWhatsApp?(...numbers: string[]): Promise<Array<{
|
|
484
|
+
exists?: boolean;
|
|
485
|
+
jid?: string;
|
|
486
|
+
}> | undefined>;
|
|
487
|
+
/**
|
|
488
|
+
* Who this socket logged in as — present once the connection opens.
|
|
489
|
+
*
|
|
490
|
+
* Optional because a socket that never opened has no identity to report, and because tests
|
|
491
|
+
* replace this object wholesale. The backend reads BOTH ids: the self-chat is addressed by
|
|
492
|
+
* `lid`, not by `id`, so knowing only one leaves it unrecognised.
|
|
493
|
+
*/
|
|
494
|
+
readonly user?: {
|
|
495
|
+
readonly id?: string;
|
|
496
|
+
readonly lid?: string;
|
|
497
|
+
};
|
|
443
498
|
end?(error?: Error): void;
|
|
444
499
|
}
|
|
445
500
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -497,6 +552,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
497
552
|
* @public
|
|
498
553
|
*/
|
|
499
554
|
|
|
555
|
+
/**
|
|
556
|
+
* What the pairing is doing, for a caller that must ASK rather than be told.
|
|
557
|
+
*
|
|
558
|
+
* {@link WhatsAppBaileysBackendOptions.onQr} is push: it fires when WhatsApp issues a code, at a
|
|
559
|
+
* moment the caller does not choose. A screen is pull — it loads when someone opens it and has to
|
|
560
|
+
* ask what is true right now. With only the callback, showing a QR anywhere means every consumer
|
|
561
|
+
* keeping its own copy of the latest code and its own notion of whether pairing already succeeded,
|
|
562
|
+
* which is this backend's bookkeeping copied into each of them.
|
|
563
|
+
*
|
|
564
|
+
* @public
|
|
565
|
+
*/
|
|
566
|
+
interface WhatsAppPairingState {
|
|
567
|
+
/**
|
|
568
|
+
* `idle` before `connect()`, `awaiting_scan` while a code is outstanding, `connected` once the
|
|
569
|
+
* socket opens, `closed` when it dies without a scan.
|
|
570
|
+
*/
|
|
571
|
+
readonly status: "idle" | "awaiting_scan" | "connected" | "closed";
|
|
572
|
+
/**
|
|
573
|
+
* The most recent code, present only while `awaiting_scan`.
|
|
574
|
+
*
|
|
575
|
+
* WhatsApp reissues roughly every 20 seconds and the previous one stops working, so a screen
|
|
576
|
+
* holding the old square shows something that cannot be scanned. It is cleared on `connected`
|
|
577
|
+
* and on `closed` for the same reason: offering a code that leads nowhere is worse than
|
|
578
|
+
* offering none.
|
|
579
|
+
*/
|
|
580
|
+
readonly qr?: string;
|
|
581
|
+
/** When that code arrived, so a UI can show its age instead of a stale square. */
|
|
582
|
+
readonly qrAt?: number;
|
|
583
|
+
}
|
|
500
584
|
/** Construction options. @public */
|
|
501
585
|
interface WhatsAppBaileysBackendOptions {
|
|
502
586
|
/**
|
|
@@ -514,6 +598,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
514
598
|
/**
|
|
515
599
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
516
600
|
*
|
|
601
|
+
* **QR IS THE ONLY WAY IN.** Baileys exposes `requestPairingCode`, and WhatsApp refuses the codes
|
|
602
|
+
* this backend asks for — measured 2026-08-30 across three attempts, on both the 12- and 13-digit
|
|
603
|
+
* forms of a Brazilian number. The reference implementation of this same transport documents the
|
|
604
|
+
* same conclusion in one line ("Login is QR-only") while sending a custom `browser` triple exactly
|
|
605
|
+
* as this one does, so the triple is NOT established as the cause and no cause is claimed here.
|
|
606
|
+
* What is established is the outcome: a caller with no route to display a QR has no route to pair.
|
|
607
|
+
*
|
|
517
608
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
518
609
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
519
610
|
* without a route out the QR the session can never be paired.
|
|
@@ -567,6 +658,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
567
658
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
568
659
|
*/
|
|
569
660
|
private lastCloseError?;
|
|
661
|
+
/** The pairing, as a caller may ask for it. Never handed out mutable. */
|
|
662
|
+
private pairingState;
|
|
663
|
+
/**
|
|
664
|
+
* The JIDs that ARE this account, normalised. Empty until a socket reports who it logged in as.
|
|
665
|
+
*
|
|
666
|
+
* Empty means "not learned yet", and `isDispatchable` reads that as refusing everything this
|
|
667
|
+
* account sent — the same behaviour as before self-chat support existed. A backend that
|
|
668
|
+
* guessed here would answer in a stranger's conversation.
|
|
669
|
+
*/
|
|
670
|
+
private selfJids;
|
|
671
|
+
/**
|
|
672
|
+
* Ids this backend sent, most recent last. This is what stops the agent answering itself.
|
|
673
|
+
*
|
|
674
|
+
* Bounded because it is a loop guard, not a log: an unbounded set on a long-lived socket is a
|
|
675
|
+
* leak, and nothing needs to recognise an echo from an hour ago — WhatsApp delivers our own
|
|
676
|
+
* message back within seconds or not at all.
|
|
677
|
+
*/
|
|
678
|
+
private sentWamids;
|
|
570
679
|
private inboundHandler?;
|
|
571
680
|
private statusHandler?;
|
|
572
681
|
/**
|
|
@@ -579,6 +688,14 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
579
688
|
* the failure it guards against is a message delivered to the wrong person.
|
|
580
689
|
*/
|
|
581
690
|
private sendQueue;
|
|
691
|
+
/**
|
|
692
|
+
* What WhatsApp answered about each recipient, for the life of the session.
|
|
693
|
+
*
|
|
694
|
+
* Holds the routable JID, or {@link UNROUTABLE} for a number the server does not know. Both are
|
|
695
|
+
* worth remembering: a second send to a number that does not exist should refuse as fast as the
|
|
696
|
+
* first, without another round-trip.
|
|
697
|
+
*/
|
|
698
|
+
private readonly jidCache;
|
|
582
699
|
constructor(opts: WhatsAppBaileysBackendOptions);
|
|
583
700
|
/**
|
|
584
701
|
* Open the socket and wait for it to report `open`.
|
|
@@ -588,6 +705,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
588
705
|
* guard once and opened two live sessions.
|
|
589
706
|
*/
|
|
590
707
|
connect(): Promise<boolean>;
|
|
708
|
+
/**
|
|
709
|
+
* What the pairing is doing right now.
|
|
710
|
+
*
|
|
711
|
+
* Read it as often as a screen needs; it is a snapshot, not a subscription.
|
|
712
|
+
*/
|
|
713
|
+
get pairing(): WhatsAppPairingState;
|
|
591
714
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
592
715
|
disconnect(): Promise<void>;
|
|
593
716
|
/**
|
|
@@ -599,6 +722,21 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
599
722
|
* retries, because a retry after a slow ack duplicates the message.
|
|
600
723
|
*/
|
|
601
724
|
send(message: WhatsAppOutboundMessage): Promise<WhatsAppSendResult>;
|
|
725
|
+
/**
|
|
726
|
+
* The JID WhatsApp routes this message to, or `undefined` when it routes to nobody.
|
|
727
|
+
*
|
|
728
|
+
* A group id is not a phone number and `onWhatsApp` answers about numbers, so groups pass
|
|
729
|
+
* straight through — asking would refuse every group message.
|
|
730
|
+
*
|
|
731
|
+
* The answer is cached for the life of the session. It is a fact about a number's registration,
|
|
732
|
+
* which does not change while a socket lives, and paying a round-trip per message would make
|
|
733
|
+
* every send slower for something already known.
|
|
734
|
+
*
|
|
735
|
+
* A socket without `onWhatsApp` — an older Baileys, or a fake predating this — sends to the
|
|
736
|
+
* number as given, which is the behaviour from before #82. Refusing on a missing capability
|
|
737
|
+
* would turn an upgrade problem into an outage.
|
|
738
|
+
*/
|
|
739
|
+
private resolveJid;
|
|
602
740
|
/** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
|
|
603
741
|
onInbound(handler: (event: WhatsAppInboundEvent) => Promise<void>): () => void;
|
|
604
742
|
/**
|
|
@@ -845,6 +983,18 @@ interface BridgeHandle {
|
|
|
845
983
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
846
984
|
* pairings fail fast instead of hanging the app.
|
|
847
985
|
*
|
|
986
|
+
* **THE CONSUMER MUST PROVIDE A BROWSER.** `whatsapp-web.js` drives a real Chrome through
|
|
987
|
+
* Puppeteer, and this package ships none: the repository leaves `puppeteer` out of
|
|
988
|
+
* `pnpm.onlyBuiltDependencies`, so its postinstall never downloads one. Without a browser the
|
|
989
|
+
* bridge starts, cannot find Chrome, and says so in its own protocol rather than crashing —
|
|
990
|
+
* which is the whole of the B-002 fix, and is still not a connection. Set
|
|
991
|
+
* `PUPPETEER_EXECUTABLE_PATH` to a Chrome or Chromium you already have; the bridge is spawned
|
|
992
|
+
* without an explicit `env`, so it inherits yours.
|
|
993
|
+
*
|
|
994
|
+
* B-002 asked for exactly this sentence or for a buildable `puppeteer`, and shipped with
|
|
995
|
+
* neither. Measured 2026-08-29: with the variable set, the bridge reaches WhatsApp and issues
|
|
996
|
+
* a pairing QR. {@link WhatsAppBaileysBackend} needs no browser, which is why it exists.
|
|
997
|
+
*
|
|
848
998
|
* @public
|
|
849
999
|
*/
|
|
850
1000
|
|
|
@@ -1077,4 +1227,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1077
1227
|
*/
|
|
1078
1228
|
declare function splitForWhatsApp(text: string): string[];
|
|
1079
1229
|
|
|
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 };
|
|
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -23,10 +23,33 @@ interface WhatsAppInboundEvent {
|
|
|
23
23
|
readonly conversationType: "dm" | "group";
|
|
24
24
|
/** Channel id — either the sender phone (DM) or the group id (group). */
|
|
25
25
|
readonly channelId: string;
|
|
26
|
+
/**
|
|
27
|
+
* The address this message arrived on, verbatim — the one a reply must be sent to.
|
|
28
|
+
*
|
|
29
|
+
* `channelId` is normalised to digits, which is what the allowlist compares and what a session
|
|
30
|
+
* key is built from. That normalisation strips the DOMAIN, and the domain is what says which kind
|
|
31
|
+
* of identifier this is: `@s.whatsapp.net` is a phone JID, `@g.us` a group, `@lid` an account's
|
|
32
|
+
* linked identity. A note-to-self arrives addressed by LID, so replying to the digits rebuilds
|
|
33
|
+
* `…@s.whatsapp.net` — an address that does not exist, and a send that reports ok and lands
|
|
34
|
+
* nowhere (#84).
|
|
35
|
+
*
|
|
36
|
+
* Optional because the Cloud backend has no JID to report; it addresses recipients by phone.
|
|
37
|
+
*/
|
|
38
|
+
readonly channelJid?: string;
|
|
26
39
|
/** Plain-text body (already filtered by EC-4 — text-only in v1). */
|
|
27
40
|
readonly text: string;
|
|
28
41
|
/** Receipt timestamp (ms since epoch). */
|
|
29
42
|
readonly receivedAt: number;
|
|
43
|
+
/**
|
|
44
|
+
* The account owner wrote this to themselves — a note-to-self, not a message from a stranger.
|
|
45
|
+
*
|
|
46
|
+
* Absent means "somebody else", never "not checked": only the path that deliberately admits a
|
|
47
|
+
* `fromMe` message inside the self-chat sets it. A consumer applying a sender policy should read
|
|
48
|
+
* this BEFORE an allowlist, because the sender identity cannot carry the answer — the self-chat
|
|
49
|
+
* reports the account's LID, and no user can be expected to look up their own LID to allowlist
|
|
50
|
+
* themselves.
|
|
51
|
+
*/
|
|
52
|
+
readonly fromSelf?: boolean;
|
|
30
53
|
/** Backend that emitted this event. */
|
|
31
54
|
readonly backend: "cloud" | "web" | "baileys";
|
|
32
55
|
/** Raw envelope for the escape hatch. */
|
|
@@ -292,6 +315,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
292
315
|
private connected;
|
|
293
316
|
private handler?;
|
|
294
317
|
private statusHandler?;
|
|
318
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
319
|
+
private warnedAboutFormat;
|
|
295
320
|
private inboundUnsubscribe?;
|
|
296
321
|
private statusUnsubscribe?;
|
|
297
322
|
/**
|
|
@@ -379,6 +404,13 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
379
404
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
380
405
|
/** Status receipts (sent/delivered/read/failed). Adapter-specific (D307). */
|
|
381
406
|
onStatusReceipt(handler: (receipt: WhatsAppStatusReceipt) => Promise<void>): () => void;
|
|
407
|
+
/**
|
|
408
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
409
|
+
*
|
|
410
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
411
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
412
|
+
*/
|
|
413
|
+
deliver(event: MessageEvent): Promise<"ok" | "no_handler" | "handler_threw">;
|
|
382
414
|
}
|
|
383
415
|
|
|
384
416
|
/**
|
|
@@ -440,6 +472,29 @@ interface BaileysSocketLike {
|
|
|
440
472
|
id?: string;
|
|
441
473
|
};
|
|
442
474
|
} | undefined>;
|
|
475
|
+
/**
|
|
476
|
+
* Ask the server which numbers are registered, and under which JID it routes them.
|
|
477
|
+
*
|
|
478
|
+
* Optional because an older Baileys, or a fake in a test that predates this, may not have it.
|
|
479
|
+
* When it is absent the backend sends to the number as given — the behaviour before #82 — rather
|
|
480
|
+
* than refusing everything, because refusing on a missing capability would turn an upgrade
|
|
481
|
+
* problem into an outage.
|
|
482
|
+
*/
|
|
483
|
+
onWhatsApp?(...numbers: string[]): Promise<Array<{
|
|
484
|
+
exists?: boolean;
|
|
485
|
+
jid?: string;
|
|
486
|
+
}> | undefined>;
|
|
487
|
+
/**
|
|
488
|
+
* Who this socket logged in as — present once the connection opens.
|
|
489
|
+
*
|
|
490
|
+
* Optional because a socket that never opened has no identity to report, and because tests
|
|
491
|
+
* replace this object wholesale. The backend reads BOTH ids: the self-chat is addressed by
|
|
492
|
+
* `lid`, not by `id`, so knowing only one leaves it unrecognised.
|
|
493
|
+
*/
|
|
494
|
+
readonly user?: {
|
|
495
|
+
readonly id?: string;
|
|
496
|
+
readonly lid?: string;
|
|
497
|
+
};
|
|
443
498
|
end?(error?: Error): void;
|
|
444
499
|
}
|
|
445
500
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -497,6 +552,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
497
552
|
* @public
|
|
498
553
|
*/
|
|
499
554
|
|
|
555
|
+
/**
|
|
556
|
+
* What the pairing is doing, for a caller that must ASK rather than be told.
|
|
557
|
+
*
|
|
558
|
+
* {@link WhatsAppBaileysBackendOptions.onQr} is push: it fires when WhatsApp issues a code, at a
|
|
559
|
+
* moment the caller does not choose. A screen is pull — it loads when someone opens it and has to
|
|
560
|
+
* ask what is true right now. With only the callback, showing a QR anywhere means every consumer
|
|
561
|
+
* keeping its own copy of the latest code and its own notion of whether pairing already succeeded,
|
|
562
|
+
* which is this backend's bookkeeping copied into each of them.
|
|
563
|
+
*
|
|
564
|
+
* @public
|
|
565
|
+
*/
|
|
566
|
+
interface WhatsAppPairingState {
|
|
567
|
+
/**
|
|
568
|
+
* `idle` before `connect()`, `awaiting_scan` while a code is outstanding, `connected` once the
|
|
569
|
+
* socket opens, `closed` when it dies without a scan.
|
|
570
|
+
*/
|
|
571
|
+
readonly status: "idle" | "awaiting_scan" | "connected" | "closed";
|
|
572
|
+
/**
|
|
573
|
+
* The most recent code, present only while `awaiting_scan`.
|
|
574
|
+
*
|
|
575
|
+
* WhatsApp reissues roughly every 20 seconds and the previous one stops working, so a screen
|
|
576
|
+
* holding the old square shows something that cannot be scanned. It is cleared on `connected`
|
|
577
|
+
* and on `closed` for the same reason: offering a code that leads nowhere is worse than
|
|
578
|
+
* offering none.
|
|
579
|
+
*/
|
|
580
|
+
readonly qr?: string;
|
|
581
|
+
/** When that code arrived, so a UI can show its age instead of a stale square. */
|
|
582
|
+
readonly qrAt?: number;
|
|
583
|
+
}
|
|
500
584
|
/** Construction options. @public */
|
|
501
585
|
interface WhatsAppBaileysBackendOptions {
|
|
502
586
|
/**
|
|
@@ -514,6 +598,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
514
598
|
/**
|
|
515
599
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
516
600
|
*
|
|
601
|
+
* **QR IS THE ONLY WAY IN.** Baileys exposes `requestPairingCode`, and WhatsApp refuses the codes
|
|
602
|
+
* this backend asks for — measured 2026-08-30 across three attempts, on both the 12- and 13-digit
|
|
603
|
+
* forms of a Brazilian number. The reference implementation of this same transport documents the
|
|
604
|
+
* same conclusion in one line ("Login is QR-only") while sending a custom `browser` triple exactly
|
|
605
|
+
* as this one does, so the triple is NOT established as the cause and no cause is claimed here.
|
|
606
|
+
* What is established is the outcome: a caller with no route to display a QR has no route to pair.
|
|
607
|
+
*
|
|
517
608
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
518
609
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
519
610
|
* without a route out the QR the session can never be paired.
|
|
@@ -567,6 +658,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
567
658
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
568
659
|
*/
|
|
569
660
|
private lastCloseError?;
|
|
661
|
+
/** The pairing, as a caller may ask for it. Never handed out mutable. */
|
|
662
|
+
private pairingState;
|
|
663
|
+
/**
|
|
664
|
+
* The JIDs that ARE this account, normalised. Empty until a socket reports who it logged in as.
|
|
665
|
+
*
|
|
666
|
+
* Empty means "not learned yet", and `isDispatchable` reads that as refusing everything this
|
|
667
|
+
* account sent — the same behaviour as before self-chat support existed. A backend that
|
|
668
|
+
* guessed here would answer in a stranger's conversation.
|
|
669
|
+
*/
|
|
670
|
+
private selfJids;
|
|
671
|
+
/**
|
|
672
|
+
* Ids this backend sent, most recent last. This is what stops the agent answering itself.
|
|
673
|
+
*
|
|
674
|
+
* Bounded because it is a loop guard, not a log: an unbounded set on a long-lived socket is a
|
|
675
|
+
* leak, and nothing needs to recognise an echo from an hour ago — WhatsApp delivers our own
|
|
676
|
+
* message back within seconds or not at all.
|
|
677
|
+
*/
|
|
678
|
+
private sentWamids;
|
|
570
679
|
private inboundHandler?;
|
|
571
680
|
private statusHandler?;
|
|
572
681
|
/**
|
|
@@ -579,6 +688,14 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
579
688
|
* the failure it guards against is a message delivered to the wrong person.
|
|
580
689
|
*/
|
|
581
690
|
private sendQueue;
|
|
691
|
+
/**
|
|
692
|
+
* What WhatsApp answered about each recipient, for the life of the session.
|
|
693
|
+
*
|
|
694
|
+
* Holds the routable JID, or {@link UNROUTABLE} for a number the server does not know. Both are
|
|
695
|
+
* worth remembering: a second send to a number that does not exist should refuse as fast as the
|
|
696
|
+
* first, without another round-trip.
|
|
697
|
+
*/
|
|
698
|
+
private readonly jidCache;
|
|
582
699
|
constructor(opts: WhatsAppBaileysBackendOptions);
|
|
583
700
|
/**
|
|
584
701
|
* Open the socket and wait for it to report `open`.
|
|
@@ -588,6 +705,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
588
705
|
* guard once and opened two live sessions.
|
|
589
706
|
*/
|
|
590
707
|
connect(): Promise<boolean>;
|
|
708
|
+
/**
|
|
709
|
+
* What the pairing is doing right now.
|
|
710
|
+
*
|
|
711
|
+
* Read it as often as a screen needs; it is a snapshot, not a subscription.
|
|
712
|
+
*/
|
|
713
|
+
get pairing(): WhatsAppPairingState;
|
|
591
714
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
592
715
|
disconnect(): Promise<void>;
|
|
593
716
|
/**
|
|
@@ -599,6 +722,21 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
599
722
|
* retries, because a retry after a slow ack duplicates the message.
|
|
600
723
|
*/
|
|
601
724
|
send(message: WhatsAppOutboundMessage): Promise<WhatsAppSendResult>;
|
|
725
|
+
/**
|
|
726
|
+
* The JID WhatsApp routes this message to, or `undefined` when it routes to nobody.
|
|
727
|
+
*
|
|
728
|
+
* A group id is not a phone number and `onWhatsApp` answers about numbers, so groups pass
|
|
729
|
+
* straight through — asking would refuse every group message.
|
|
730
|
+
*
|
|
731
|
+
* The answer is cached for the life of the session. It is a fact about a number's registration,
|
|
732
|
+
* which does not change while a socket lives, and paying a round-trip per message would make
|
|
733
|
+
* every send slower for something already known.
|
|
734
|
+
*
|
|
735
|
+
* A socket without `onWhatsApp` — an older Baileys, or a fake predating this — sends to the
|
|
736
|
+
* number as given, which is the behaviour from before #82. Refusing on a missing capability
|
|
737
|
+
* would turn an upgrade problem into an outage.
|
|
738
|
+
*/
|
|
739
|
+
private resolveJid;
|
|
602
740
|
/** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
|
|
603
741
|
onInbound(handler: (event: WhatsAppInboundEvent) => Promise<void>): () => void;
|
|
604
742
|
/**
|
|
@@ -845,6 +983,18 @@ interface BridgeHandle {
|
|
|
845
983
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
846
984
|
* pairings fail fast instead of hanging the app.
|
|
847
985
|
*
|
|
986
|
+
* **THE CONSUMER MUST PROVIDE A BROWSER.** `whatsapp-web.js` drives a real Chrome through
|
|
987
|
+
* Puppeteer, and this package ships none: the repository leaves `puppeteer` out of
|
|
988
|
+
* `pnpm.onlyBuiltDependencies`, so its postinstall never downloads one. Without a browser the
|
|
989
|
+
* bridge starts, cannot find Chrome, and says so in its own protocol rather than crashing —
|
|
990
|
+
* which is the whole of the B-002 fix, and is still not a connection. Set
|
|
991
|
+
* `PUPPETEER_EXECUTABLE_PATH` to a Chrome or Chromium you already have; the bridge is spawned
|
|
992
|
+
* without an explicit `env`, so it inherits yours.
|
|
993
|
+
*
|
|
994
|
+
* B-002 asked for exactly this sentence or for a buildable `puppeteer`, and shipped with
|
|
995
|
+
* neither. Measured 2026-08-29: with the variable set, the bridge reaches WhatsApp and issues
|
|
996
|
+
* a pairing QR. {@link WhatsAppBaileysBackend} needs no browser, which is why it exists.
|
|
997
|
+
*
|
|
848
998
|
* @public
|
|
849
999
|
*/
|
|
850
1000
|
|
|
@@ -1077,4 +1227,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1077
1227
|
*/
|
|
1078
1228
|
declare function splitForWhatsApp(text: string): string[];
|
|
1079
1229
|
|
|
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 };
|
|
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 };
|