@oxidezap/baileyrs 0.0.35 → 0.1.0

package/lib/Socket/messages.d.ts

@@ -10,8 +10,11 @@ import type { SocketContext } from './types.js';
  * it across the delete and restore it on a fresh contextInfo.
  *
  * Mutates `msg` in place.
+ *
+ * `contentType` is a parameter so the send path can hand over the type it has
+ * already resolved rather than have it scanned out of `msg` a second time.
  */
-export declare function stripContextInfoForBridge(msg: WAMessageContent): void;
+export declare function stripContextInfoForBridge(msg: WAMessageContent, contentType?: keyof WAProto.IMessage | undefined): void;
 export declare const makeMessageMethods: (ctx: SocketContext) => {
     sendMessage: (jid: string, content: AnyMessageContent, options?: Omit<MessageGenerationOptions, 'waClient' | 'logger' | 'userJid' | 'mediaInNote'>) => Promise<WAMessage>;
     updateMediaMessage: (message: WAMessage) => Promise<WAMessage>;

package/lib/Socket/messages.js

@@ -22,9 +22,11 @@ function getMediaContent(content) {
  * it across the delete and restore it on a fresh contextInfo.
  *
  * Mutates `msg` in place.
+ *
+ * `contentType` is a parameter so the send path can hand over the type it has
+ * already resolved rather than have it scanned out of `msg` a second time.
  */
-export function stripContextInfoForBridge(msg) {
-    const contentType = getContentType(msg);
+export function stripContextInfoForBridge(msg, contentType = getContentType(msg)) {
     const pinAddOnDuration = contentType === 'pinInChatMessage' ? msg.messageContextInfo?.messageAddOnDurationInSecs : undefined;
     delete msg.messageContextInfo;
     if (pinAddOnDuration !== undefined && pinAddOnDuration !== null) {
@@ -85,7 +87,7 @@ export const makeMessageMethods = (ctx) => ({
                 return fullMsg;
             }
         }
-        stripContextInfoForBridge(msg);
+        stripContextInfoForBridge(msg, contentType);
         let msgId;
         const msgBytes = encodeProto('Message', msg);
         if (jid === 'status@broadcast' && options?.statusJidList?.length) {

package/lib/Socket/terminal-close-reporter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Reports the terminal `connection.update { close }` — exactly once, after
+ * teardown, and never silently not at all.
+ *
+ * That sentence is the whole contract this branch sells, and getting it wrong
+ * has two opposite failure modes, both bad:
+ *
+ *  - **Not reported.** The consumer's handler never runs, so it never builds a
+ *    replacement socket. A bot offline with nothing in its logs — the original
+ *    bug this branch exists to fix.
+ *  - **Reported early, or twice.** The replacement socket overlaps the old
+ *    one's auth-store flush and `free()`, or every listener sees two terminal
+ *    notifications for one socket and a handler that cleans up on close loops.
+ *
+ * Keeping both away used to be inline logic split across the dispatcher hook
+ * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
+ * of that in review — a publish that could never run, a throwing listener
+ * taking the process down, `logout()` resolving before the close it caused,
+ * the watchdog not releasing its waiters, a suppression check that also
+ * matched non-terminal teardown, a fallback that did not count itself. Every
+ * one was a different way of answering the same question, so it is one object
+ * now, with the answer in one place.
+ */
+import type { ILogger } from '../Utils/logger.js';
+/**
+ * How long teardown may run before the close is reported anyway.
+ *
+ * A deliberate trade of one guarantee for the other: past this point the close
+ * goes out with teardown still running, because losing the event entirely is
+ * the worse of the two failures. Teardown takes milliseconds in practice, so
+ * reaching this means a consumer end handler or a store flush never settled —
+ * and the error logged alongside says exactly that. Generous rather than
+ * tight, since firing early is the harmful direction.
+ */
+export declare const TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS = 60000;
+export interface TerminalCloseReporter {
+    /**
+     * Run `teardown`, then publish. Used by the dispatcher, which learns about
+     * the close first and hands over the publishing so the socket can finish
+     * releasing its resources before a consumer can react.
+     *
+     * Never rejects and never leaves `publish` uncalled: teardown failures are
+     * logged, a throwing listener is contained, and a teardown that hangs is
+     * cut short by the watchdog.
+     */
+    reportAfter: (teardown: () => Promise<void>, publish: () => void) => void;
+    /**
+     * Publish immediately, for a close nothing else will announce — a `logout()`
+     * with no live client, or one whose `logout()` threw before the bridge
+     * dispatched anything.
+     */
+    reportNow: (publish: () => void) => void;
+    /**
+     * Whether a terminal close has been *claimed* — reported, or reported-and-
+     * still-tearing-down. Not "published": `reportAfter` publishes only once
+     * teardown finishes, so a check keyed on delivery would see `false` right
+     * after the bridge announced the logout and let `logout()` add a second
+     * close of its own.
+     *
+     * `logout()` uses this rather than "is the socket closing", which is also
+     * true for a plain `end()` — and those report nothing, so keying off them
+     * would let a logout racing one finish with no close at all.
+     */
+    hasReported: () => boolean;
+    /**
+     * Settles once the most recent report has been published — the moment the
+     * consumer sees it, not the moment teardown finishes, so a waiter is not
+     * left hanging when the watchdog is what released the event.
+     *
+     * Resolves immediately when nothing has been reported.
+     */
+    published: () => Promise<void>;
+}
+export declare const makeTerminalCloseReporter: (opts: {
+    logger: ILogger;
+    /** Overridable for tests; production uses the constant above. */
+    publishTimeoutMs?: number;
+}) => TerminalCloseReporter;
+//# sourceMappingURL=terminal-close-reporter.d.ts.map

package/lib/Socket/terminal-close-reporter.js

@@ -0,0 +1,108 @@
+/**
+ * Reports the terminal `connection.update { close }` — exactly once, after
+ * teardown, and never silently not at all.
+ *
+ * That sentence is the whole contract this branch sells, and getting it wrong
+ * has two opposite failure modes, both bad:
+ *
+ *  - **Not reported.** The consumer's handler never runs, so it never builds a
+ *    replacement socket. A bot offline with nothing in its logs — the original
+ *    bug this branch exists to fix.
+ *  - **Reported early, or twice.** The replacement socket overlaps the old
+ *    one's auth-store flush and `free()`, or every listener sees two terminal
+ *    notifications for one socket and a handler that cleans up on close loops.
+ *
+ * Keeping both away used to be inline logic split across the dispatcher hook
+ * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
+ * of that in review — a publish that could never run, a throwing listener
+ * taking the process down, `logout()` resolving before the close it caused,
+ * the watchdog not releasing its waiters, a suppression check that also
+ * matched non-terminal teardown, a fallback that did not count itself. Every
+ * one was a different way of answering the same question, so it is one object
+ * now, with the answer in one place.
+ */
+/**
+ * How long teardown may run before the close is reported anyway.
+ *
+ * A deliberate trade of one guarantee for the other: past this point the close
+ * goes out with teardown still running, because losing the event entirely is
+ * the worse of the two failures. Teardown takes milliseconds in practice, so
+ * reaching this means a consumer end handler or a store flush never settled —
+ * and the error logged alongside says exactly that. Generous rather than
+ * tight, since firing early is the harmful direction.
+ */
+export const TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS = 60000;
+export const makeTerminalCloseReporter = (opts) => {
+    const { logger } = opts;
+    const publishTimeoutMs = opts.publishTimeoutMs ?? TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS;
+    /** Claims, not deliveries — see `hasReported`. */
+    let claimed = 0;
+    let publishedPromise;
+    /** One publish per claim, whatever gets there first, and never throwing. */
+    const makeOnce = (publish, settle) => {
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            try {
+                publish();
+            }
+            catch (err) {
+                // `publish` emits on the consumer's bus. Letting this escape
+                // would surface as an unhandled rejection on a detached chain —
+                // process exit under Node's default handler.
+                logger.error({ err }, 'connection.update listener threw on the terminal close');
+            }
+            settle();
+        };
+    };
+    return {
+        reportAfter: (teardown, publish) => {
+            claimed++;
+            let settle;
+            publishedPromise = new Promise(resolve => {
+                settle = resolve;
+            });
+            const publishOnce = makeOnce(publish, settle);
+            // Deliberately referenced: a pending promise does not keep Node's
+            // event loop alive, so an unref'd timer lets a minimal bot exit
+            // before it can publish — and the close handler that would have
+            // built the replacement never runs, which is what this guards.
+            // Cleared the moment teardown settles, so it holds the loop only
+            // while one is in flight.
+            const watchdog = setTimeout(() => {
+                logger.error({ afterMs: publishTimeoutMs }, 'socket teardown is still running; reporting the close anyway');
+                publishOnce();
+            }, publishTimeoutMs);
+            const finish = (err) => {
+                clearTimeout(watchdog);
+                if (err)
+                    logger.error({ err }, 'socket teardown failed after a terminal disconnect');
+                publishOnce();
+            };
+            // `teardown()` is called inside the try because it can throw
+            // *synchronously*, before returning a promise — `.then` would never
+            // run and the close would stay unpublished until the watchdog, or
+            // forever if the timer were ever removed. The no-silent-failure
+            // promise has to hold for that path too.
+            try {
+                void teardown().then(() => finish(), finish);
+            }
+            catch (err) {
+                finish(err);
+            }
+        },
+        reportNow: publish => {
+            claimed++;
+            let settle;
+            publishedPromise = new Promise(resolve => {
+                settle = resolve;
+            });
+            makeOnce(publish, settle)();
+        },
+        hasReported: () => claimed > 0,
+        published: () => publishedPromise ?? Promise.resolve()
+    };
+};
+//# sourceMappingURL=terminal-close-reporter.js.map

package/lib/Socket/terminal-close.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Which bridge disconnects end the socket for good.
+ *
+ * This mirrors one decision that lives in the Rust engine, so keep it honest:
+ * `whatsapp-rust` clears `enable_auto_reconnect` and breaks out of its run loop
+ * on exactly these, and retries everything else on the WA Web Fibonacci backoff
+ * (`client/lifecycle.rs`).
+ *
+ * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
+ * `void` — it spawns the loop as a background task, so the loop's exit is not
+ * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
+ * bridge exposes loop completion, this table is how the socket knows a client
+ * has become dead weight that only `free()` can reclaim.
+ *
+ * The upstream Baileys contract this buys us: `connection.update { close }`
+ * means "this socket is finished, build a new one" — which is what every
+ * consumer written against upstream already assumes, because upstream has no
+ * auto-reconnect at all. Transient drops therefore never surface as `close`;
+ * they surface as `connecting`.
+ *
+ * Events deliberately absent from the terminal set, and why:
+ *  - `disconnected` — the engine only dispatches `Event::Disconnected` for an
+ *    *unexpected* loop exit, and every terminal path sets `expected_disconnect`
+ *    first, which suppresses it (`client/lifecycle.rs`). So this one is the
+ *    "engine is retrying" signal — with one exception the dispatcher handles:
+ *    under `setAutoReconnect(false)` the run loop dispatches `Disconnected`
+ *    and only *then* tests the flag and breaks out, which makes the very same
+ *    event terminal. Absence from this list means "not terminal on its own",
+ *    not "never terminal".
+ *  - `streamError` — reaches JS only from the engine's catch-all `<stream:error>`
+ *    branch (unknown code, `<ack/>`, `<xml-not-well-formed>`); the coded ones
+ *    (401/409/515/516/429/503) dispatch their own events instead. Every case
+ *    that gets here keeps the connection or recycles it deliberately.
+ *  - `pairError` — pairing failed, but the engine keeps its loop and re-emits a
+ *    QR; nothing about the client is dead.
+ */
+/** True when the engine will keep retrying after this `<failure>`. */
+export declare const isReconnectableConnectFailure: (reason: number | undefined) => boolean;
+//# sourceMappingURL=terminal-close.d.ts.map

package/lib/Socket/terminal-close.js

@@ -0,0 +1,51 @@
+/**
+ * Which bridge disconnects end the socket for good.
+ *
+ * This mirrors one decision that lives in the Rust engine, so keep it honest:
+ * `whatsapp-rust` clears `enable_auto_reconnect` and breaks out of its run loop
+ * on exactly these, and retries everything else on the WA Web Fibonacci backoff
+ * (`client/lifecycle.rs`).
+ *
+ * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
+ * `void` — it spawns the loop as a background task, so the loop's exit is not
+ * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
+ * bridge exposes loop completion, this table is how the socket knows a client
+ * has become dead weight that only `free()` can reclaim.
+ *
+ * The upstream Baileys contract this buys us: `connection.update { close }`
+ * means "this socket is finished, build a new one" — which is what every
+ * consumer written against upstream already assumes, because upstream has no
+ * auto-reconnect at all. Transient drops therefore never surface as `close`;
+ * they surface as `connecting`.
+ *
+ * Events deliberately absent from the terminal set, and why:
+ *  - `disconnected` — the engine only dispatches `Event::Disconnected` for an
+ *    *unexpected* loop exit, and every terminal path sets `expected_disconnect`
+ *    first, which suppresses it (`client/lifecycle.rs`). So this one is the
+ *    "engine is retrying" signal — with one exception the dispatcher handles:
+ *    under `setAutoReconnect(false)` the run loop dispatches `Disconnected`
+ *    and only *then* tests the flag and breaks out, which makes the very same
+ *    event terminal. Absence from this list means "not terminal on its own",
+ *    not "never terminal".
+ *  - `streamError` — reaches JS only from the engine's catch-all `<stream:error>`
+ *    branch (unknown code, `<ack/>`, `<xml-not-well-formed>`); the coded ones
+ *    (401/409/515/516/429/503) dispatch their own events instead. Every case
+ *    that gets here keeps the connection or recycles it deliberately.
+ *  - `pairError` — pairing failed, but the engine keeps its loop and re-emits a
+ *    QR; nothing about the client is dead.
+ */
+/**
+ * `ConnectFailureReason` wire codes the engine retries — the JS mirror of
+ * `ConnectFailureReason::should_reconnect()`, which matches only
+ * `InternalServerError | ServiceUnavailable`.
+ *
+ * A `<failure>` with no reason at all is NOT retried: the engine parses it as
+ * `Unknown(0)`, which fails `should_reconnect()`.
+ */
+const RECONNECTABLE_CONNECT_FAILURE_REASONS = new Set([
+    500, // InternalServerError
+    503 // ServiceUnavailable
+]);
+/** True when the engine will keep retrying after this `<failure>`. */
+export const isReconnectableConnectFailure = (reason) => reason !== undefined && RECONNECTABLE_CONNECT_FAILURE_REASONS.has(reason);
+//# sourceMappingURL=terminal-close.js.map

package/lib/Utils/event-buffer.js

@@ -362,6 +362,37 @@ export const makeEventBuffer = (logger) => {
     let flushPendingTimeout;
     ev.on('event', (events) => {
         for (const event of Object.keys(events)) {
+            if (event === 'connection.update') {
+                // Delivered listener by listener, unlike every other event.
+                // `EventEmitter.emit()` stops at the first listener that throws,
+                // so one bad handler would keep the rest — including the app's
+                // reconnect handler — from ever seeing a terminal `close`, and
+                // the bot would stay offline. This is the lifecycle channel;
+                // losing delivery here is the failure mode the socket's whole
+                // close contract exists to prevent.
+                // `rawListeners`, not `listeners`: the latter unwraps `once()`
+                // handlers to the function underneath, so calling that would
+                // never run the wrapper that unregisters them and the listener
+                // would stay subscribed for every later update. `once` is not on
+                // `BaileysEventEmitter` today, so this is unreachable rather than
+                // broken — but the two differ only in this respect and the raw
+                // one is the correct primitive for calling listeners by hand.
+                for (const listener of ev.rawListeners(event)) {
+                    try {
+                        // `.call(ev, …)` so `this` is still the emitter, as it
+                        // would be under `emit()`. A listener declared as a
+                        // normal function that does `this.off('connection.update', …)`
+                        // — a common self-removing pattern — would otherwise
+                        // throw on `undefined` and be swallowed by the catch.
+                        ;
+                        listener.call(ev, events[event]);
+                    }
+                    catch (err) {
+                        logger.error({ err, event }, 'connection.update listener threw; continuing with the rest');
+                    }
+                }
+                continue;
+            }
             ev.emit(event, events[event]);
         }
     });

package/lib/Utils/messages.d.ts

@@ -57,6 +57,17 @@ export type DownloadMediaMessageContext = {
  */
 export declare const downloadMediaMessage: <Type extends 'buffer' | 'stream'>(message: WAMessage, type: Type, options: MediaDownloadOptions, ctx: DownloadMediaMessageContext) => Promise<Type extends "buffer" ? Buffer<ArrayBufferLike> : Readable>;
 export declare const _registerActiveBridgeClient: (client: WasmWhatsAppClient, logger?: ILogger) => void;
+/**
+ * Drop the module-level pointer when `sock.end()` frees the client it points
+ * at. Without this the global keeps a strong reference to a freed
+ * `WasmWhatsAppClient`, so the next standalone `downloadContentFromMessage()`
+ * call reaches into a null wasm pointer and fails with an opaque
+ * wasm-bindgen error instead of the actionable "no bridge client" Boom.
+ *
+ * Identity-checked on purpose: a multi-account host that ends socket A after
+ * creating socket B must not clear B's registration.
+ */
+export declare const _unregisterActiveBridgeClient: (client: WasmWhatsAppClient) => void;
 /**
  * Upstream-Baileys-compatible standalone media download. Builds a synthetic
  * `WAMessage` from the supplied media subcontent (image/video/audio/etc fields)

package/lib/Utils/messages.js

@@ -505,10 +505,14 @@ export const generateWAMessageContent = async (message, options) => {
 };
 export const generateWAMessageFromContent = (jid, message, options) => {
     const innerMessage = normalizeMessageContent(message);
-    const key = getContentType(innerMessage);
     const timestamp = unixTimestampSeconds(options.timestamp);
     const { quoted, userJid } = options;
+    // Only the quote and ephemeral branches read the content key, and a plain
+    // send takes neither, so resolve it on demand instead of on every send.
+    let key;
     if (quoted && !isJidNewsletter(jid)) {
+        const contentKey = getContentType(innerMessage);
+        key = contentKey;
         const participant = quoted.key.fromMe
             ? userJid // TODO: Add support for LIDs
             : quoted.participant || quoted.key.participant || quoted.key.remoteJid;
@@ -520,7 +524,7 @@ export const generateWAMessageFromContent = (jid, message, options) => {
         if (typeof quotedContent === 'object' && quotedContent && 'contextInfo' in quotedContent) {
             delete quotedContent.contextInfo;
         }
-        const contextInfo = ('contextInfo' in innerMessage[key] && innerMessage[key]?.contextInfo) || {};
+        const contextInfo = ('contextInfo' in innerMessage[contentKey] && innerMessage[contentKey]?.contextInfo) || {};
         contextInfo.participant = jidNormalizedUser(participant);
         contextInfo.stanzaId = quoted.key.id;
         contextInfo.quotedMessage = quotedMsg;
@@ -529,26 +533,27 @@ export const generateWAMessageFromContent = (jid, message, options) => {
         if (jid !== quoted.key.remoteJid) {
             contextInfo.remoteJid = quoted.key.remoteJid;
         }
-        if (contextInfo && innerMessage[key]) {
+        if (contextInfo && innerMessage[contentKey]) {
             /* @ts-ignore */
-            innerMessage[key].contextInfo = contextInfo;
+            innerMessage[contentKey].contextInfo = contextInfo;
         }
     }
     if (
     // if we want to send a disappearing message
     !!options?.ephemeralExpiration &&
-        // and it's not a protocol message -- delete, toggle disappear message
-        key !== 'protocolMessage' &&
-        // already not converted to disappearing message
-        key !== 'ephemeralMessage' &&
         // newsletters don't support ephemeral messages
         !isJidNewsletter(jid)) {
-        /* @ts-ignore */
-        innerMessage[key].contextInfo = {
-            ...innerMessage[key].contextInfo,
-            expiration: options.ephemeralExpiration || WA_DEFAULT_EPHEMERAL
-            //ephemeralSettingTimestamp: options.ephemeralOptions.eph_setting_ts?.toString()
-        };
+        const contentKey = key ?? getContentType(innerMessage);
+        // skip protocol messages -- delete, toggle disappear message -- and
+        // content already converted to a disappearing message
+        if (contentKey !== 'protocolMessage' && contentKey !== 'ephemeralMessage') {
+            /* @ts-ignore */
+            innerMessage[contentKey].contextInfo = {
+                ...innerMessage[contentKey].contextInfo,
+                expiration: options.ephemeralExpiration || WA_DEFAULT_EPHEMERAL
+                //ephemeralSettingTimestamp: options.ephemeralOptions.eph_setting_ts?.toString()
+            };
+        }
     }
     // `create` copies into a fresh instance; content built by
     // `generateWAMessageContent` already is one, and the branches above mutate
@@ -720,6 +725,22 @@ export const _registerActiveBridgeClient = (client, logger) => {
     activeBridgeClient = client;
     activeBridgeLogger = logger;
 };
+/**
+ * Drop the module-level pointer when `sock.end()` frees the client it points
+ * at. Without this the global keeps a strong reference to a freed
+ * `WasmWhatsAppClient`, so the next standalone `downloadContentFromMessage()`
+ * call reaches into a null wasm pointer and fails with an opaque
+ * wasm-bindgen error instead of the actionable "no bridge client" Boom.
+ *
+ * Identity-checked on purpose: a multi-account host that ends socket A after
+ * creating socket B must not clear B's registration.
+ */
+export const _unregisterActiveBridgeClient = (client) => {
+    if (activeBridgeClient !== client)
+        return;
+    activeBridgeClient = undefined;
+    activeBridgeLogger = undefined;
+};
 const noopLogger = {
     level: 'silent',
     child: () => noopLogger,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oxidezap/baileyrs",
   "type": "module",
-  "version": "0.0.35",
+  "version": "0.1.0",
   "description": "A Rust-powered WhatsApp Web library for JavaScript, with a Baileys-compatible API",
   "keywords": [
     "whatsapp",
@@ -75,7 +75,7 @@
   },
   "dependencies": {
     "@hapi/boom": "^9.1.4",
-    "@oxidezap/whatsapp-rust-bridge": "0.6.4",
+    "@oxidezap/whatsapp-rust-bridge": "0.6.5",
     "long": "^5.3.2",
     "pino": "^10.3.1",
     "protobufjs": "^7.6.5"