@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/CHANGELOG.md +92 -0
- package/README.md +12 -1
- package/dist/index.cjs +69 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +55 -0
- package/dist/index.d.ts +55 -0
- package/dist/index.js +69 -5
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
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
|
|
637
|
-
|
|
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 };
|