@oxidezap/baileyrs 0.0.35 → 0.1.1

package/README.md

@@ -25,7 +25,7 @@ so existing integrations can migrate with minimal changes. See
 | Media encrypt/decrypt | Node.js crypto | Rust AES-256-CBC + HMAC |
 | Media upload/download | JS fetch + temp files | Rust with CDN failover, auth refresh, resumable upload |
 | Key management | JS auth state | Rust `PersistenceManager` |
-| Auto-reconnect | Manual `startSock()` loop | Built-in with fibonacci backoff |
+| Auto-reconnect | Manual `startSock()` loop | Transient drops retried in Rust (fibonacci backoff); terminal ones still yours |
 
 ## Documentation
 
@@ -51,9 +51,16 @@ import makeWASocket from '@oxidezap/baileyrs'
 ### Drop-in replacement for upstream Baileys
 
 baileyrs is API-compatible with [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys).
-Existing projects switch over by aliasing the package — **no source changes needed**
-(one exception: carrying an existing pairing across takes a one-line import swap,
-see [Migrating from Upstream Baileys](#migrating-from-upstream-baileys)):
+Existing projects switch over by aliasing the package — **the API and imports
+need no source changes**. Two things do:
+
+- Carrying an existing pairing across takes a one-line import swap, see
+  [Migrating from Upstream Baileys](#migrating-from-upstream-baileys).
+- If your `connection.update` handler was written for a version of baileyrs
+  before 0.1, see [Gotchas](#gotchas): a `close` now always means the socket
+  is finished, and you have to recreate it. Code written against upstream
+  Baileys already does the right thing.
+
 
 ```sh
 npm install @whiskeysockets/baileys@npm:@oxidezap/baileyrs
@@ -78,27 +85,57 @@ now resolves to baileyrs.
 import makeWASocket, { Boom, DisconnectReason, useMultiFileAuthState } from '@oxidezap/baileyrs'
 
 const { state } = await useMultiFileAuthState('auth_info')
-const sock = makeWASocket({ auth: state })
 
-sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
-    if (connection === 'close') {
-        const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
-        if (statusCode === DisconnectReason.loggedOut) {
-            console.log('Logged out')
-        }
-        // Auto-reconnect is handled by the Rust engine — no need to call makeWASocket again
-    }
-    if (connection === 'open') {
-        console.log('Connected')
+// setTimeout caps at ~2^31-1 ms (~24.8 days) and fires immediately past that,
+// so a long ban has to be waited out in chunks.
+async function waitUntil(deadlineMs: number) {
+    for (let left = deadlineMs - Date.now(); left > 0; left = deadlineMs - Date.now()) {
+        await new Promise(resolve => setTimeout(resolve, Math.min(left, 2_147_483_647)))
     }
-})
+}
 
-sock.ev.on('messages.upsert', ({ messages }) => {
-    for (const msg of messages) {
-        console.log('received message', msg.key.id)
-    }
-})
+async function connectToWhatsApp() {
+    const sock = makeWASocket({ auth: state })
+
+    sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+        if (connection === 'close') {
+            // `close` means this socket is finished — same as upstream Baileys.
+            // Transient drops never get here; the Rust engine retries those and
+            // reports `connecting`.
+            const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+            // See the reconnect table under Gotchas: a few terminal closes
+            // reject the replacement just as fast, so they are not worth
+            // retrying — or not yet. `Example/example.ts` has the full policy.
+            if (statusCode === DisconnectReason.loggedOut || statusCode === 405) {
+                console.log('Closed for good', statusCode)
+            } else if (statusCode === DisconnectReason.forbidden) {
+                // Temporary ban: `expire` is unix seconds. A missing or past
+                // expiry means the ban is over — reconnect like any other
+                // terminal close rather than staying offline forever.
+                const expire = (lastDisconnect?.error as Boom)?.data?.expire
+                console.log('Temporarily banned until', expire)
+                waitUntil(typeof expire === 'number' ? expire * 1000 : 0).then(connectToWhatsApp)
+            } else {
+                setTimeout(connectToWhatsApp, 5_000)
+            }
+        }
+        if (connection === 'open') {
+            console.log('Connected')
+        }
+    })
+
+    // Register every handler in here. A replacement socket is a new emitter,
+    // so anything attached outside stops firing after the first reconnect.
+    sock.ev.on('messages.upsert', ({ messages }) => {
+        for (const msg of messages) {
+            console.log('received message', msg.key.id)
+        }
+    })
 
+    return sock
+}
+
+const sock = await connectToWhatsApp()
 await sock.sendMessage('1234567890@s.whatsapp.net', { text: 'Hello!' })
 ```
 
@@ -156,9 +193,25 @@ preserved. No QR re-scan, no logged-out events.
 
 A few behaviors that differ from upstream — almost always to your advantage:
 
-- **Auto-reconnect is built in.** Don't call `makeWASocket()` again from
-  `connection.update`'s `'close'` branch. The Rust engine retries with
-  fibonacci backoff; opening a second socket leaks the first one.
+- **Auto-reconnect is built in, but `close` still means `close`.** The Rust
+  engine retries transient drops on a fibonacci backoff and reports them as
+  `connection: 'connecting'`, so the canonical upstream handler never fires
+  for those and you never end up with two sockets on one account. A
+  `connection: 'close'` is only emitted once the engine has given up — a
+  replaced session, an outdated build, a temporary ban, an unrecoverable
+  `<failure>` — and by then the socket has already released its resources.
+  Ignoring it leaves the bot permanently offline, so handle it the upstream
+  way and build a replacement — with three exceptions, because some of those
+  failures reject the replacement just as fast:
+
+  | `statusCode` | what to do |
+  | --- | --- |
+  | `DisconnectReason.loggedOut` (401) | stop; needs a fresh pairing |
+  | `405` | stop; the server rejected this build, and the next one too |
+  | `DisconnectReason.forbidden` (403) | wait until `lastDisconnect.error.data.expire` (unix seconds) — it is a temporary ban |
+  | anything else | reconnect, after a short delay |
+
+  `Example/example.ts` implements exactly this.
 - **No `getMessage` / `cachedGroupMetadata` polyfill required.** The Rust
   side caches group metadata and message keys natively. You can still pass
   them — they're respected as overrides — but they're optional.
@@ -167,6 +220,76 @@ A few behaviors that differ from upstream — almost always to your advantage:
   `(err as Boom).output.statusCode` pattern works unchanged. If your
   `package.json` was pulling `@hapi/boom` only for baileys, you can drop
   the dependency.
+- **Your key store also holds bridge state, so "empty" is not "unpaired".**
+  See [Bridge state in your key store](#bridge-state-in-your-key-store) — this
+  one can break a boot path, so it has its own section.
+
+### Bridge state in your key store
+
+Upstream Baileys keeps engine state in `creds` (persisted by `saveCreds`) and
+puts only Signal key material in `keys`. baileyrs uses that same `keys` store
+as the persistence channel for the Rust core's own state as well: its device
+record, and the byte-level records the Signal namespaces are projected from.
+Those live under namespaces reserved with the **`bridge-` prefix**:
+
+| namespace | what it holds |
+| --- | --- |
+| `bridge-native-*` | the core's own encoding of a namespace that also has a Baileys projection (`bridge-native-session`, `bridge-native-prekey`, `bridge-native-device`, …) |
+| `bridge-*` | core records with no Baileys equivalent (`bridge-signed-prekey`, `bridge-sent-message`, `bridge-msg-secret`, `bridge-meta`, …) |
+
+No upstream Baileys namespace starts with `bridge-`, and none of your data is
+stored under one. Which of them you actually see depends on what the engine
+touches; `bridge-native-device` shows up first, because the core reads its
+device record while the socket is still `connecting` — **before any QR, before
+any pairing**.
+
+That last point is the one that bites. A store that counted rows to decide
+whether this was a first run reports a session that does not exist:
+
+```js
+// WRONG on baileyrs: bridge-native-device is already in the table before pairing,
+// so this never reports empty again — the bot skips its pairing flow and hangs.
+const isEmpty = () => !creds.registered && !creds.me?.id && countKeys() === 0
+
+// Right, on baileyrs and upstream alike: creds are the pairing record.
+const isEmpty = () => !creds.registered && !creds.me?.id
+```
+
+**A non-empty key store is not evidence of a session.** `creds.registered` and
+`creds.me?.id` are, and they are the only thing to check.
+
+When you need to present a store the way upstream would — counting rows,
+listing the Signal namespaces, exporting an upstream-shaped dump — filter the
+bridge rows out with the exported classifier rather than matching the prefix
+yourself. It is derived from the internal routing catalog, so a namespace added
+in a later release is covered without you changing anything:
+
+```ts
+// Aliased install? Import from '@whiskeysockets/baileys' instead; it resolves here.
+import { BRIDGE_INTERNAL_KEY_TYPES, isBridgeInternalKeyType } from '@oxidezap/baileyrs'
+
+isBridgeInternalKeyType('bridge-native-device') // true
+isBridgeInternalKeyType('pre-key')              // false
+
+// Every bridge-internal namespace, e.g. for a SQL `NOT IN (...)` clause. The
+// store also holds the Baileys namespaces the engine projects into it.
+BRIDGE_INTERNAL_KEY_TYPES
+```
+
+> **Do not drop these rows from a backup or a store-to-store move.** They are
+> effective state, not metadata. `bridge-signed-prekey`, `bridge-sender-key-devices`,
+> `bridge-base-key`, `bridge-sent-message`, `bridge-msg-secret`,
+> `bridge-mutation-mac` and `bridge-meta` have no Baileys projection at all, and
+> a Signal session that turned native-only lives under `bridge-native-session`
+> alone. Restoring only the non-bridge rows rolls those sessions back or loses
+> the state outright. Filter the bridge rows only where the destination is an
+> upstream-shaped view that cannot represent them; a full backup, or a move
+> between two baileyrs stores, carries every `bridge-` row across.
+
+This applies to stores you own — the upstream `{ creds, keys }` shape that
+baileyrs auto-wraps, including `useLegacyMultiFileAuthState`. It does not apply
+to `useMultiFileAuthState`, whose `keys` is a projection over the engine's own
+store; the `bridge-` namespaces never surface through it.
 
 ## Disclaimer
 

package/lib/Compatibility/legacy-store/namespaces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Namespace prefix reserved for bridge-internal state. Every namespace the
+ * routing catalog writes back to a legacy key store starts with it, and no
+ * Baileys Signal namespace does, so the prefix is treated as reserved: a
+ * namespace added to the catalog later is classified without a code change.
+ */
+export declare const BRIDGE_INTERNAL_KEY_PREFIX = "bridge-";
+/**
+ * Every namespace `wrapLegacyStore` can write that is not a Signal key.
+ * Derived from the routing catalog so it cannot drift from what is written.
+ */
+export declare const BRIDGE_INTERNAL_KEY_TYPES: readonly string[];
+/**
+ * Whether a `SignalKeyStore` namespace holds bridge-internal state rather than
+ * Signal key material. Custom stores use it to skip those rows when they
+ * enumerate, count or migrate. Never throws: anything that is not a known
+ * namespace, including a non-string, is reported as not internal.
+ */
+export declare function isBridgeInternalKeyType(type: unknown): boolean;
+//# sourceMappingURL=namespaces.d.ts.map

package/lib/Compatibility/legacy-store/namespaces.js

@@ -0,0 +1,27 @@
+// Public classifier for the namespaces the bridge parks in a consumer's key store.
+import { StoreCatalog } from './constants.js';
+/**
+ * Namespace prefix reserved for bridge-internal state. Every namespace the
+ * routing catalog writes back to a legacy key store starts with it, and no
+ * Baileys Signal namespace does, so the prefix is treated as reserved: a
+ * namespace added to the catalog later is classified without a code change.
+ */
+export const BRIDGE_INTERNAL_KEY_PREFIX = 'bridge-';
+/**
+ * Every namespace `wrapLegacyStore` can write that is not a Signal key.
+ * Derived from the routing catalog so it cannot drift from what is written.
+ */
+export const BRIDGE_INTERNAL_KEY_TYPES = Object.freeze([...new Set(Object.values(StoreCatalog).map(route => route.nativeType))].toSorted());
+const internalTypes = new Set(BRIDGE_INTERNAL_KEY_TYPES);
+/**
+ * Whether a `SignalKeyStore` namespace holds bridge-internal state rather than
+ * Signal key material. Custom stores use it to skip those rows when they
+ * enumerate, count or migrate. Never throws: anything that is not a known
+ * namespace, including a non-string, is reported as not internal.
+ */
+export function isBridgeInternalKeyType(type) {
+    if (typeof type !== 'string' || type.length === 0)
+        return false;
+    return type.startsWith(BRIDGE_INTERNAL_KEY_PREFIX) || internalTypes.has(type);
+}
+//# sourceMappingURL=namespaces.js.map

package/lib/Compatibility/newsletter-results.d.ts

@@ -0,0 +1,15 @@
+import type { NewsletterMetadataResult } from '@oxidezap/whatsapp-rust-bridge';
+import type { NewsletterMetadata, NewsletterViewRole } from '../Types/Newsletter.js';
+/** Upstream's `NewsletterViewRole`, or undefined for a role it does not name. */
+export declare const bridgeNewsletterRoleToBaileys: (role: string | undefined) => NewsletterViewRole | undefined;
+/**
+ * Neutral newsletter metadata in upstream's shape.
+ *
+ * Four upstream fields have no source in the bridge result and stay absent
+ * rather than being invented: `owner` (the result carries the viewer's role,
+ * not the owner's jid), `mute_state` (the result's `state` is the newsletter's
+ * lifecycle, Active/Suspended, not a mute), `reaction_codes`, and
+ * `thread_metadata`.
+ */
+export declare const bridgeNewsletterMetadataToBaileys: (result: NewsletterMetadataResult) => NewsletterMetadata;
+//# sourceMappingURL=newsletter-results.d.ts.map

package/lib/Compatibility/newsletter-results.js

@@ -0,0 +1,38 @@
+/**
+ * The bridge spells these the way the core's enums are named, and upstream
+ * spells them in screaming case. Written out rather than upper-cased blindly so
+ * a variant the core adds later shows up as `undefined` instead of as a string
+ * nobody declared.
+ */
+const VERIFICATION = {
+    Verified: 'VERIFIED',
+    Unverified: 'UNVERIFIED'
+};
+const VIEW_ROLE = {
+    Owner: 'OWNER',
+    Admin: 'ADMIN',
+    Subscriber: 'SUBSCRIBER',
+    Guest: 'GUEST'
+};
+/** Upstream's `NewsletterViewRole`, or undefined for a role it does not name. */
+export const bridgeNewsletterRoleToBaileys = (role) => role === undefined ? undefined : VIEW_ROLE[role];
+/**
+ * Neutral newsletter metadata in upstream's shape.
+ *
+ * Four upstream fields have no source in the bridge result and stay absent
+ * rather than being invented: `owner` (the result carries the viewer's role,
+ * not the owner's jid), `mute_state` (the result's `state` is the newsletter's
+ * lifecycle, Active/Suspended, not a mute), `reaction_codes`, and
+ * `thread_metadata`.
+ */
+export const bridgeNewsletterMetadataToBaileys = (result) => ({
+    id: result.jid,
+    name: result.name,
+    ...(result.description !== undefined ? { description: result.description } : {}),
+    ...(result.inviteCode !== undefined ? { invite: result.inviteCode } : {}),
+    ...(result.creationTime !== undefined ? { creation_time: result.creationTime } : {}),
+    subscribers: result.subscriberCount,
+    ...(VERIFICATION[result.verification] !== undefined ? { verification: VERIFICATION[result.verification] } : {}),
+    ...(result.pictureUrl !== undefined ? { picture: { url: result.pictureUrl } } : {})
+});
+//# sourceMappingURL=newsletter-results.js.map

package/lib/Compatibility/proto-runtime.js

@@ -558,34 +558,44 @@ class ProtoCompatibilityRuntime {
         const reader = new LongBinaryReader(asUint8Array(input));
         return this.hydrate(schemaId, codec.decode(reader, length));
     }
+    /**
+     * A fresh instance rather than an in-place re-parent: the codec installs its
+     * own `toJSON` on what it returns, and deleting that normalizes the object
+     * into dictionary mode, where every later read is a megamorphic lookup.
+     */
     hydrate(schemaId, value) {
-        const object = isObject(value) ? value : {};
+        const source = isObject(value) ? value : {};
+        const instance = Object.create(this.constructorFor(schemaId).prototype);
         const messageFields = this.messageFieldsByName[schemaId];
-        for (const key in object) {
+        for (const key in source) {
+            const nested = source[key];
             const field = messageFields[key];
-            if (!field)
-                continue;
-            const nested = object[key];
-            if (field[3] & PROTO_FIELD_FLAG.repeated) {
-                if (Array.isArray(nested))
-                    for (const item of nested)
-                        if (isObject(item))
-                            this.hydrate(field[2], item);
+            if (!field) {
+                instance[key] = nested;
             }
-            else if (field[3] & PROTO_FIELD_FLAG.map) {
-                if (isObject(nested))
-                    for (const item of Object.values(nested))
+            else if (field[3] & PROTO_FIELD_FLAG.repeated) {
+                if (Array.isArray(nested)) {
+                    for (let index = 0; index < nested.length; index++) {
+                        const item = nested[index];
                         if (isObject(item))
-                            this.hydrate(field[2], item);
+                            nested[index] = this.hydrate(field[2], item);
+                    }
+                }
+                instance[key] = nested;
             }
-            else if (isObject(nested)) {
-                this.hydrate(field[2], nested);
+            else if (field[3] & PROTO_FIELD_FLAG.map && isObject(nested)) {
+                const entries = {};
+                for (const entry in nested) {
+                    const item = nested[entry];
+                    entries[entry] = isObject(item) ? this.hydrate(field[2], item) : item;
+                }
+                instance[key] = entries;
+            }
+            else {
+                instance[key] = isObject(nested) ? this.hydrate(field[2], nested) : nested;
             }
         }
-        if (hasOwn(object, 'toJSON'))
-            delete object.toJSON;
-        Object.setPrototypeOf(object, this.constructorFor(schemaId).prototype);
-        return object;
+        return instance;
     }
     projectForEncode(schemaId, value) {
         if (!isObject(value))

package/lib/Compatibility/websocket-client.d.ts

@@ -12,8 +12,13 @@ export declare class WebSocketClient extends EventEmitter {
     protected readonly socket: {
         readonly readyState: ReadyState;
     };
-    private closing;
-    private closed;
+    /**
+     * One value rather than a pair of booleans plus a promise that could
+     * disagree with them. `closing` carries the in-flight close so a second
+     * caller joins it instead of returning while the first `disconnect()` is
+     * still running — which is how teardown reached `free()` on a busy client.
+     */
+    private closeState;
     private readonly getClient;
     private listenerMutationDepth;
     constructor(url: string | URL, config: SocketConfig, getClient: () => WasmWhatsAppClient | undefined);
@@ -32,6 +37,22 @@ export declare class WebSocketClient extends EventEmitter {
     off(eventName: string | symbol, listener: EventListener): this;
     removeAllListeners(eventName?: string | symbol): this;
     connect(): void;
+    /**
+     * Idempotent, and a second caller joins the first rather than returning
+     * while it is still going.
+     *
+     * The early return used to be bare: `void ws.close(); await sock.end()` saw
+     * the flag, returned immediately, and let teardown reach `free()` with the
+     * original `disconnect()` still in flight — the wasm heap corruption
+     * `bridge-free-safety.test.ts` documents. Awaiting a *second* `disconnect()`
+     * does not join the first one.
+     *
+     * The state is stored before `disconnect()` is called, and the work is
+     * deferred by a microtask to make that ordering hold: an inline async body
+     * runs eagerly to its first `await`, so `disconnect()` would be invoked
+     * while the state still said `open`, and anything it reaches synchronously
+     * that calls back into `close()` would issue a second one.
+     */
     close(): Promise<void>;
     send(str: string | Uint8Array, cb?: (err?: Error) => void): boolean;
     private get readyState();

package/lib/Compatibility/websocket-client.js

@@ -7,8 +7,13 @@ export const isRawNodeForwardingEnabled = (client) => client.hasRawNodeListeners
 export class WebSocketClient extends EventEmitter {
     constructor(url, config, getClient) {
         super();
-        this.closing = false;
-        this.closed = false;
+        /**
+         * One value rather than a pair of booleans plus a promise that could
+         * disagree with them. `closing` carries the in-flight close so a second
+         * caller joins it instead of returning while the first `disconnect()` is
+         * still running — which is how teardown reached `free()` on a busy client.
+         */
+        this.closeState = { phase: 'open' };
         this.listenerMutationDepth = 0;
         this.url = url instanceof URL ? url : new URL(url);
         this.config = config;
@@ -24,13 +29,13 @@ export class WebSocketClient extends EventEmitter {
         return this.getClient()?.isConnected() ?? false;
     }
     get isClosed() {
-        return this.closed;
+        return this.closeState.phase === 'closed';
     }
     get isClosing() {
-        return this.closing;
+        return this.closeState.phase === 'closing';
     }
     get isConnecting() {
-        return !this.isOpen && !this.closing && !this.closed;
+        return !this.isOpen && this.closeState.phase === 'open';
     }
     get hasRawNodeListeners() {
         return this.eventNames().some(eventName => isRawNodeEventName(eventName));
@@ -84,20 +89,44 @@ export class WebSocketClient extends EventEmitter {
         const client = this.getClient();
         if (!client || client.isConnected())
             return;
-        this.closed = false;
+        // A close in flight has already told the client to disconnect, which is
+        // exactly what makes `isConnected()` false above. Reopening here would
+        // clear the `closing` phase, and the next `close()` would start a second
+        // disconnect against the same client while the first is still running.
+        if (this.closeState.phase === 'closing')
+            return;
+        this.closeState = { phase: 'open' };
         void client.connect().catch(error => this.emit('error', error));
     }
+    /**
+     * Idempotent, and a second caller joins the first rather than returning
+     * while it is still going.
+     *
+     * The early return used to be bare: `void ws.close(); await sock.end()` saw
+     * the flag, returned immediately, and let teardown reach `free()` with the
+     * original `disconnect()` still in flight — the wasm heap corruption
+     * `bridge-free-safety.test.ts` documents. Awaiting a *second* `disconnect()`
+     * does not join the first one.
+     *
+     * The state is stored before `disconnect()` is called, and the work is
+     * deferred by a microtask to make that ordering hold: an inline async body
+     * runs eagerly to its first `await`, so `disconnect()` would be invoked
+     * while the state still said `open`, and anything it reaches synchronously
+     * that calls back into `close()` would issue a second one.
+     */
     async close() {
-        if (this.closing || this.closed)
-            return;
-        this.closing = true;
-        try {
-            await this.getClient()?.disconnect();
-        }
-        finally {
-            this.closing = false;
-            this.closed = true;
-        }
+        if (this.closeState.phase !== 'open')
+            return this.closeState.done;
+        const done = Promise.resolve().then(async () => {
+            try {
+                await this.getClient()?.disconnect();
+            }
+            finally {
+                this.closeState = { phase: 'closed', done };
+            }
+        });
+        this.closeState = { phase: 'closing', done };
+        return done;
     }
     send(str, cb) {
         const client = this.getClient();
@@ -110,9 +139,9 @@ export class WebSocketClient extends EventEmitter {
     get readyState() {
         if (this.isOpen)
             return 1;
-        if (this.closing)
+        if (this.closeState.phase === 'closing')
             return 2;
-        if (this.closed)
+        if (this.closeState.phase === 'closed')
             return 3;
         return 0;
     }

package/lib/Socket/bridge-client-owner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Owns the bridge client's lifetime.
+ *
+ * The socket's startup is async and its teardown can start at any point during
+ * it — a `sock.end()` right after `makeWASocket()`, an `await using` scope
+ * exiting, or a terminal disconnect the dispatcher reports while `init()` is
+ * still building the client. That window used to be managed by hand across six
+ * closure variables and a scattering of `if (ended) return` checks, which is
+ * where every teardown bug in this file came from: startup dereferencing a
+ * handle teardown had already nulled, a client built after teardown with
+ * nobody left to free it, an `end()` that resolved for its second caller while
+ * the first was still flushing, and a re-entrant close releasing the same wasm
+ * handle twice.
+ *
+ * All of those are one question — *what phase is this client in?* — so it is
+ * one discriminated union rather than a set of booleans that can disagree:
+ *
+ * ```
+ *   starting ──adopt()──► running ──close()──► closing ──► closed
+ *      │                     │                    ▲
+ *      └──────close()────────┴──discard()─────────┘
+ * ```
+ *
+ * Two rules make the whole thing safe, and both are properties of the union
+ * rather than of any individual method:
+ *
+ *  - **The transition is synchronous and happens first.** `close()` publishes
+ *    `closing` — carrying the promise callers await — before any teardown work
+ *    starts, so re-entering it finds an in-flight close instead of starting a
+ *    second one. That is why the work is deferred by a microtask rather than
+ *    started inline: an async body would otherwise run eagerly to its first
+ *    `await`, i.e. before the state was stored.
+ *  - **`closing` still carries the client.** The socket's transport close
+ *    reads it back through `peek()` (`ws.close()` is `getClient()?.disconnect()`),
+ *    so dropping the handle at the start of teardown silently turns that into
+ *    a no-op and moves the disconnect after the auth-store flush. `isClosing()`
+ *    — not `peek()` — is the "should I still be doing work" signal.
+ */
+import type { WasmWhatsAppClient } from '@oxidezap/whatsapp-rust-bridge';
+import type { ILogger } from '../Utils/logger.js';
+export interface BridgeClientOwnerOptions {
+    logger: ILogger;
+    /**
+     * The socket's own shutdown work. Receives the adopted client, if there is
+     * one, while it is still usable, and the error teardown was started with.
+     *
+     * Runs once. Throwing propagates to `close()`'s callers; the client is
+     * released either way.
+     */
+    teardown: (client: WasmWhatsAppClient | undefined, error: Error | undefined) => Promise<void>;
+    /**
+     * Hand the client back to the bridge. Separate from `teardown` because
+     * ordering matters and the two have different failure semantics: this one
+     * is best-effort and never throws out.
+     */
+    release: (client: WasmWhatsAppClient) => Promise<void>;
+}
+export interface BridgeClientOwner {
+    /** The client while `running` or `closing`; undefined before and after. */
+    peek: () => WasmWhatsAppClient | undefined;
+    /**
+     * Publish a freshly built client. Returns `false` when teardown has already
+     * started — the client is released here and the caller must stop, because
+     * nothing else will ever own it.
+     */
+    adopt: (client: WasmWhatsAppClient) => boolean;
+    /** True from the moment `close()` is called. Startup checks it between awaits. */
+    isClosing: () => boolean;
+    /** Runs teardown once; later callers await that same run. */
+    close: (error: Error | undefined) => Promise<void>;
+    /**
+     * Drop the client without tearing the socket down — for a startup that
+     * failed after adopting, where the client exists but its read loop never
+     * started. Joins an in-flight close rather than releasing a client that
+     * close already owns.
+     */
+    discard: () => Promise<void>;
+    /**
+     * Resolves once every release this owner started has finished, including
+     * the one a refused `adopt()` kicks off. Startup awaits it on the way out
+     * so its own promise does not settle with a release still in flight.
+     *
+     * A release can outlive the set it started in, so this drains rather than
+     * awaiting one snapshot.
+     */
+    settled: () => Promise<void>;
+}
+export declare const makeBridgeClientOwner: (opts: BridgeClientOwnerOptions) => BridgeClientOwner;
+//# sourceMappingURL=bridge-client-owner.d.ts.map