@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/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 (key.fromMe === true) return false;
84
- return remoteJid !== STATUS_BROADCAST_JID;
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 normalizeBaileysMessage(raw) {
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
- if (!isDispatchable(key, remoteJid)) return void 0;
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
- ...this.opts.onQr !== void 0 ? { onQr: this.opts.onQr } : {}
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(