@theokit/gateway-whatsapp 0.3.1 → 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 +43 -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 +117 -3
- package/dist/index.d.ts +117 -3
- 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. */
|
|
@@ -166,11 +176,30 @@ interface WhatsAppBackend {
|
|
|
166
176
|
|
|
167
177
|
/** Cloud (Meta WhatsApp Business Cloud API) backend config (ADR D304). */
|
|
168
178
|
interface WhatsAppCloudConfig {
|
|
169
|
-
/**
|
|
179
|
+
/**
|
|
180
|
+
* The Meta system user's access token for the WhatsApp Business account.
|
|
181
|
+
*
|
|
182
|
+
* @platform-term Meta calls this an **access token**. Unlike the other adapters' terms, this one
|
|
183
|
+
* is NOT pinned to a package under `node_modules` — the Cloud backend calls the Graph API with
|
|
184
|
+
* `fetch`, so there is no Meta SDK in the dependency graph to check against. It rests on Meta's
|
|
185
|
+
* own documentation, and our client sends it as `authorization: Bearer …`, never as an
|
|
186
|
+
* `access_token` parameter.
|
|
187
|
+
* @issued-at Meta Business Manager, under System Users → Generate token, scoped to the WhatsApp
|
|
188
|
+
* Business account.
|
|
189
|
+
*/
|
|
170
190
|
readonly accessToken: string;
|
|
171
191
|
/** Meta-issued phone-number-id (NOT the user-facing phone). */
|
|
172
192
|
readonly phoneNumberId: string;
|
|
173
|
-
/**
|
|
193
|
+
/**
|
|
194
|
+
* The Meta app secret, used to verify `X-Hub-Signature-256` on inbound WhatsApp webhooks.
|
|
195
|
+
*
|
|
196
|
+
* @platform-term Meta calls this an **app secret** — note it belongs to the Meta app, not to the
|
|
197
|
+
* WhatsApp Business account, which is why it is issued somewhere different from the access token
|
|
198
|
+
* above. It signs inbound payloads and never
|
|
199
|
+
* authenticates outbound calls, which is why it is optional: an adapter that only sends does
|
|
200
|
+
* not need it.
|
|
201
|
+
* @issued-at Meta for Developers, under the app's Settings → Basic.
|
|
202
|
+
*/
|
|
174
203
|
readonly appSecret: string;
|
|
175
204
|
/** Graph API version. Defaults to `v18.0`. */
|
|
176
205
|
readonly apiVersion?: string;
|
|
@@ -273,6 +302,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
273
302
|
private connected;
|
|
274
303
|
private handler?;
|
|
275
304
|
private statusHandler?;
|
|
305
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
306
|
+
private warnedAboutFormat;
|
|
276
307
|
private inboundUnsubscribe?;
|
|
277
308
|
private statusUnsubscribe?;
|
|
278
309
|
/**
|
|
@@ -421,6 +452,17 @@ interface BaileysSocketLike {
|
|
|
421
452
|
id?: string;
|
|
422
453
|
};
|
|
423
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
|
+
};
|
|
424
466
|
end?(error?: Error): void;
|
|
425
467
|
}
|
|
426
468
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -478,6 +520,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
478
520
|
* @public
|
|
479
521
|
*/
|
|
480
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
|
+
}
|
|
481
552
|
/** Construction options. @public */
|
|
482
553
|
interface WhatsAppBaileysBackendOptions {
|
|
483
554
|
/**
|
|
@@ -495,6 +566,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
495
566
|
/**
|
|
496
567
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
497
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
|
+
*
|
|
498
576
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
499
577
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
500
578
|
* without a route out the QR the session can never be paired.
|
|
@@ -548,6 +626,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
548
626
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
549
627
|
*/
|
|
550
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;
|
|
551
647
|
private inboundHandler?;
|
|
552
648
|
private statusHandler?;
|
|
553
649
|
/**
|
|
@@ -569,6 +665,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
569
665
|
* guard once and opened two live sessions.
|
|
570
666
|
*/
|
|
571
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;
|
|
572
674
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
573
675
|
disconnect(): Promise<void>;
|
|
574
676
|
/**
|
|
@@ -826,6 +928,18 @@ interface BridgeHandle {
|
|
|
826
928
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
827
929
|
* pairings fail fast instead of hanging the app.
|
|
828
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
|
+
*
|
|
829
943
|
* @public
|
|
830
944
|
*/
|
|
831
945
|
|
|
@@ -1058,4 +1172,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1058
1172
|
*/
|
|
1059
1173
|
declare function splitForWhatsApp(text: string): string[];
|
|
1060
1174
|
|
|
1061
|
-
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. */
|
|
@@ -166,11 +176,30 @@ interface WhatsAppBackend {
|
|
|
166
176
|
|
|
167
177
|
/** Cloud (Meta WhatsApp Business Cloud API) backend config (ADR D304). */
|
|
168
178
|
interface WhatsAppCloudConfig {
|
|
169
|
-
/**
|
|
179
|
+
/**
|
|
180
|
+
* The Meta system user's access token for the WhatsApp Business account.
|
|
181
|
+
*
|
|
182
|
+
* @platform-term Meta calls this an **access token**. Unlike the other adapters' terms, this one
|
|
183
|
+
* is NOT pinned to a package under `node_modules` — the Cloud backend calls the Graph API with
|
|
184
|
+
* `fetch`, so there is no Meta SDK in the dependency graph to check against. It rests on Meta's
|
|
185
|
+
* own documentation, and our client sends it as `authorization: Bearer …`, never as an
|
|
186
|
+
* `access_token` parameter.
|
|
187
|
+
* @issued-at Meta Business Manager, under System Users → Generate token, scoped to the WhatsApp
|
|
188
|
+
* Business account.
|
|
189
|
+
*/
|
|
170
190
|
readonly accessToken: string;
|
|
171
191
|
/** Meta-issued phone-number-id (NOT the user-facing phone). */
|
|
172
192
|
readonly phoneNumberId: string;
|
|
173
|
-
/**
|
|
193
|
+
/**
|
|
194
|
+
* The Meta app secret, used to verify `X-Hub-Signature-256` on inbound WhatsApp webhooks.
|
|
195
|
+
*
|
|
196
|
+
* @platform-term Meta calls this an **app secret** — note it belongs to the Meta app, not to the
|
|
197
|
+
* WhatsApp Business account, which is why it is issued somewhere different from the access token
|
|
198
|
+
* above. It signs inbound payloads and never
|
|
199
|
+
* authenticates outbound calls, which is why it is optional: an adapter that only sends does
|
|
200
|
+
* not need it.
|
|
201
|
+
* @issued-at Meta for Developers, under the app's Settings → Basic.
|
|
202
|
+
*/
|
|
174
203
|
readonly appSecret: string;
|
|
175
204
|
/** Graph API version. Defaults to `v18.0`. */
|
|
176
205
|
readonly apiVersion?: string;
|
|
@@ -273,6 +302,8 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
273
302
|
private connected;
|
|
274
303
|
private handler?;
|
|
275
304
|
private statusHandler?;
|
|
305
|
+
/** Whether the "this platform carries no format flag" warning has already been emitted. */
|
|
306
|
+
private warnedAboutFormat;
|
|
276
307
|
private inboundUnsubscribe?;
|
|
277
308
|
private statusUnsubscribe?;
|
|
278
309
|
/**
|
|
@@ -421,6 +452,17 @@ interface BaileysSocketLike {
|
|
|
421
452
|
id?: string;
|
|
422
453
|
};
|
|
423
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
|
+
};
|
|
424
466
|
end?(error?: Error): void;
|
|
425
467
|
}
|
|
426
468
|
/** How a socket comes into being. Replaced wholesale in tests. */
|
|
@@ -478,6 +520,35 @@ declare function createBaileysSocket(opts: BaileysSocketOptions): Promise<Bailey
|
|
|
478
520
|
* @public
|
|
479
521
|
*/
|
|
480
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
|
+
}
|
|
481
552
|
/** Construction options. @public */
|
|
482
553
|
interface WhatsAppBaileysBackendOptions {
|
|
483
554
|
/**
|
|
@@ -495,6 +566,13 @@ interface WhatsAppBaileysBackendOptions {
|
|
|
495
566
|
/**
|
|
496
567
|
* Where the pairing QR goes, as often as WhatsApp reissues it.
|
|
497
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
|
+
*
|
|
498
576
|
* Defaults to stderr. It is exposed here because a host that is not a terminal — a service, a
|
|
499
577
|
* container, a web app — has no way to read stderr back to the person holding the phone, and
|
|
500
578
|
* without a route out the QR the session can never be paired.
|
|
@@ -548,6 +626,24 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
548
626
|
* `rules/error-handling.md` § 3: fail clear, and log with enough context to act.
|
|
549
627
|
*/
|
|
550
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;
|
|
551
647
|
private inboundHandler?;
|
|
552
648
|
private statusHandler?;
|
|
553
649
|
/**
|
|
@@ -569,6 +665,12 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
|
|
|
569
665
|
* guard once and opened two live sessions.
|
|
570
666
|
*/
|
|
571
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;
|
|
572
674
|
/** Close the socket. Idempotent, and safe when never connected. */
|
|
573
675
|
disconnect(): Promise<void>;
|
|
574
676
|
/**
|
|
@@ -826,6 +928,18 @@ interface BridgeHandle {
|
|
|
826
928
|
* EC-6 absorbed: `connect()` races against a 120s timeout so unattended QR
|
|
827
929
|
* pairings fail fast instead of hanging the app.
|
|
828
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
|
+
*
|
|
829
943
|
* @public
|
|
830
944
|
*/
|
|
831
945
|
|
|
@@ -1058,4 +1172,4 @@ declare function mapWhatsAppWebError(ipcError: string | undefined): ErrorPayload
|
|
|
1058
1172
|
*/
|
|
1059
1173
|
declare function splitForWhatsApp(text: string): string[];
|
|
1060
1174
|
|
|
1061
|
-
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(
|