@theokit/gateway-whatsapp 0.3.3 → 0.4.1

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
@@ -23,6 +23,19 @@ 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). */
@@ -391,6 +404,13 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
391
404
  onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
392
405
  /** Status receipts (sent/delivered/read/failed). Adapter-specific (D307). */
393
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">;
394
414
  }
395
415
 
396
416
  /**
@@ -452,6 +472,18 @@ interface BaileysSocketLike {
452
472
  id?: string;
453
473
  };
454
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>;
455
487
  /**
456
488
  * Who this socket logged in as — present once the connection opens.
457
489
  *
@@ -656,6 +688,14 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
656
688
  * the failure it guards against is a message delivered to the wrong person.
657
689
  */
658
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;
659
699
  constructor(opts: WhatsAppBaileysBackendOptions);
660
700
  /**
661
701
  * Open the socket and wait for it to report `open`.
@@ -682,6 +722,21 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
682
722
  * retries, because a retry after a slow ack duplicates the message.
683
723
  */
684
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;
685
740
  /** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
686
741
  onInbound(handler: (event: WhatsAppInboundEvent) => Promise<void>): () => void;
687
742
  /**
package/dist/index.d.ts CHANGED
@@ -23,6 +23,19 @@ 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). */
@@ -391,6 +404,13 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
391
404
  onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
392
405
  /** Status receipts (sent/delivered/read/failed). Adapter-specific (D307). */
393
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">;
394
414
  }
395
415
 
396
416
  /**
@@ -452,6 +472,18 @@ interface BaileysSocketLike {
452
472
  id?: string;
453
473
  };
454
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>;
455
487
  /**
456
488
  * Who this socket logged in as — present once the connection opens.
457
489
  *
@@ -656,6 +688,14 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
656
688
  * the failure it guards against is a message delivered to the wrong person.
657
689
  */
658
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;
659
699
  constructor(opts: WhatsAppBaileysBackendOptions);
660
700
  /**
661
701
  * Open the socket and wait for it to report `open`.
@@ -682,6 +722,21 @@ declare class WhatsAppBaileysBackend implements WhatsAppBackend {
682
722
  * retries, because a retry after a slow ack duplicates the message.
683
723
  */
684
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;
685
740
  /** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
686
741
  onInbound(handler: (event: WhatsAppInboundEvent) => Promise<void>): () => void;
687
742
  /**
package/dist/index.js CHANGED
@@ -77,7 +77,7 @@ function resolveParties(key, remoteJid) {
77
77
  const fromPhone = normalizeWhatsAppId(senderJid);
78
78
  const channelId = normalizeWhatsAppId(remoteJid);
79
79
  if (fromPhone.length === 0 || channelId.length === 0) return void 0;
80
- return { fromPhone, channelId, isGroup };
80
+ return { fromPhone, channelId, channelJid: remoteJid, isGroup };
81
81
  }
82
82
  function isDispatchable(key, remoteJid, wamid, ctx) {
83
83
  if (remoteJid === STATUS_BROADCAST_JID) return "no";
@@ -114,6 +114,7 @@ function normalizeBaileysMessage(raw, ctx) {
114
114
  fromPhone: parties.fromPhone,
115
115
  conversationType: parties.isGroup ? "group" : "dm",
116
116
  channelId: parties.channelId,
117
+ channelJid: parties.channelJid,
117
118
  text,
118
119
  receivedAt: seconds * 1e3,
119
120
  backend: "baileys",
@@ -288,6 +289,7 @@ function endQuietly(socket) {
288
289
  }
289
290
  var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
290
291
  var DEFAULT_SEND_TIMEOUT_MS = 3e4;
292
+ var UNROUTABLE = "__unroutable__";
291
293
  var SENT_WAMID_WINDOW = 256;
292
294
  var WhatsAppBaileysBackend = class {
293
295
  constructor(opts) {
@@ -383,6 +385,14 @@ var WhatsAppBaileysBackend = class {
383
385
  * the failure it guards against is a message delivered to the wrong person.
384
386
  */
385
387
  sendQueue = Promise.resolve();
388
+ /**
389
+ * What WhatsApp answered about each recipient, for the life of the session.
390
+ *
391
+ * Holds the routable JID, or {@link UNROUTABLE} for a number the server does not know. Both are
392
+ * worth remembering: a second send to a number that does not exist should refuse as fast as the
393
+ * first, without another round-trip.
394
+ */
395
+ jidCache = /* @__PURE__ */ new Map();
386
396
  /**
387
397
  * Open the socket and wait for it to report `open`.
388
398
  *
@@ -631,10 +641,20 @@ var WhatsAppBaileysBackend = class {
631
641
  inFlight: Promise.resolve()
632
642
  };
633
643
  }
634
- const jid = `${message.to}@${message.isGroup ? "g.us" : "s.whatsapp.net"}`;
635
644
  const timeoutMs = this.opts.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
636
- const inFlight = socket.sendMessage(jid, { text: message.text });
637
- const result = this.raceSend(inFlight, timeoutMs).then((outcome) => {
645
+ const send = this.resolveJid(socket, message).then(
646
+ async (jid) => jid === void 0 ? UNROUTABLE : await socket.sendMessage(jid, { text: message.text })
647
+ );
648
+ const result = this.raceSend(send, timeoutMs).then((outcome) => {
649
+ if (outcome === UNROUTABLE) {
650
+ return {
651
+ ok: false,
652
+ error: {
653
+ code: "undeliverable",
654
+ message: `WhatsApp does not route to "${message.to}" \u2014 the number is not registered, or not in the form this account can reach. Nothing was sent.`
655
+ }
656
+ };
657
+ }
638
658
  if (outcome === "timeout") {
639
659
  return {
640
660
  ok: false,
@@ -654,7 +674,41 @@ var WhatsAppBaileysBackend = class {
654
674
  message: err instanceof Error ? err.message : String(err)
655
675
  }
656
676
  }));
657
- return { result, inFlight };
677
+ return { result, inFlight: send };
678
+ }
679
+ /**
680
+ * The JID WhatsApp routes this message to, or `undefined` when it routes to nobody.
681
+ *
682
+ * A group id is not a phone number and `onWhatsApp` answers about numbers, so groups pass
683
+ * straight through — asking would refuse every group message.
684
+ *
685
+ * The answer is cached for the life of the session. It is a fact about a number's registration,
686
+ * which does not change while a socket lives, and paying a round-trip per message would make
687
+ * every send slower for something already known.
688
+ *
689
+ * A socket without `onWhatsApp` — an older Baileys, or a fake predating this — sends to the
690
+ * number as given, which is the behaviour from before #82. Refusing on a missing capability
691
+ * would turn an upgrade problem into an outage.
692
+ */
693
+ async resolveJid(socket, message) {
694
+ if (message.to.includes("@")) return message.to;
695
+ if (message.isGroup) return `${message.to}@g.us`;
696
+ if (socket.onWhatsApp === void 0) return `${message.to}@s.whatsapp.net`;
697
+ const cached = this.jidCache.get(message.to);
698
+ if (cached !== void 0) return cached === UNROUTABLE ? void 0 : cached;
699
+ let answer;
700
+ try {
701
+ answer = await socket.onWhatsApp(message.to);
702
+ } catch {
703
+ return `${message.to}@s.whatsapp.net`;
704
+ }
705
+ const entry = answer?.[0];
706
+ if (entry?.exists !== true || entry.jid === void 0 || entry.jid === "") {
707
+ this.jidCache.set(message.to, UNROUTABLE);
708
+ return void 0;
709
+ }
710
+ this.jidCache.set(message.to, entry.jid);
711
+ return entry.jid;
658
712
  }
659
713
  /** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
660
714
  onInbound(handler) {
@@ -1813,6 +1867,7 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
1813
1867
  wamid: inbound.wamid,
1814
1868
  phoneNumberId: inbound.phoneNumberId,
1815
1869
  contactName: inbound.contactName,
1870
+ channelJid: inbound.channelJid,
1816
1871
  backend: inbound.backend,
1817
1872
  raw: inbound.raw
1818
1873
  }
@@ -1852,6 +1907,15 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
1852
1907
  }
1853
1908
  };
1854
1909
  }
1910
+ /**
1911
+ * Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
1912
+ *
1913
+ * One line over `runHandler`, which owns the containment: a handler is user code, its throw is
1914
+ * named as the handler's failure rather than the platform's, and delivery continues.
1915
+ */
1916
+ async deliver(event) {
1917
+ return this.runHandler(this.handler, event);
1918
+ }
1855
1919
  };
1856
1920
 
1857
1921
  export { ConfigurationError, LineBuffer, WhatsAppAdapter, WhatsAppBaileysBackend, WhatsAppBridgeError, WhatsAppCloudBackend, WhatsAppConnectTimeoutError, WhatsAppWebBackend, createBaileysSocket, defaultBridgeScriptPath, digitsOnly, formatCommand, mapWhatsAppCloudError, mapWhatsAppWebError, normalizeInboundMessages, normalizeStatusReceipts, parseEvent, parseWebhookPayload, splitForWhatsApp, verifyWebhookSignature, verifyWebhookSubscription };