zapo-js 1.2.1 → 1.3.0

package/dist/client/WaClient.d.ts

@@ -13,58 +13,12 @@ import type { WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator
 import type { WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
 import type { WaProfileCoordinator } from './coordinators/WaProfileCoordinator';
 import type { WaStatusCoordinator } from './coordinators/WaStatusCoordinator';
+import type { WaClientExposedFromPlugins, WaClientPluginDefinition, WaClientPluginEventsFromPlugins } from './plugins/types';
 import type { WaClientEventMap, WaClientOptions, WaIgnoreKey, WaIgnoreKeyPredicate } from './types';
 import type { Logger } from '../infra/log/types';
 import { type WaLogoutReason } from '../protocol/stream';
-/**
- * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
- * coordinators (accessible via getters such as {@link message}, {@link group},
- * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
- *
- * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
- * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
- * then use the coordinator getters to drive the session. Call {@link disconnect}
- * to shut down cleanly or {@link logout} to remove the companion device.
- *
- * @example
- * ```ts
- * import { createPinoLogger, createStore, WaClient } from '..'
- * import { createSqliteStore } from '@zapo-js/store-sqlite'
- *
- * const store = createStore({
- *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
- *     providers: {
- *         auth: 'sqlite',
- *         signal: 'sqlite',
- *         preKey: 'sqlite',
- *         session: 'sqlite',
- *         identity: 'sqlite',
- *         senderKey: 'sqlite',
- *         appState: 'sqlite',
- *         privacyToken: 'sqlite',
- *         messages: 'sqlite',
- *         threads: 'sqlite',
- *         contacts: 'sqlite'
- *     }
- * })
- *
- * const client = new WaClient(
- *     { store, sessionId: 'default' },
- *     await createPinoLogger({ level: 'info', pretty: true })
- * )
- *
- * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
- * client.on('connection', (event) => console.log('connection', event))
- * client.on('message', async (event) => {
- *     if (event.message?.conversation === 'ping') {
- *         await client.message.send(event.chatJid!, 'pong')
- *     }
- * })
- *
- * await client.connect()
- * ```
- */
-export declare class WaClient extends EventEmitter {
+/** @internal Implementation backing the exported {@link WaClient}. */
+declare class WaClientImpl extends EventEmitter {
     private readonly options;
     private readonly logger;
     private readonly stores;
@@ -76,6 +30,7 @@ export declare class WaClient extends EventEmitter {
     private acceptingIncomingEvents;
     private activeIncomingHandlers;
     private readonly incomingHandlersDrainedWaiters;
+    private disposePlugins;
     /**
      * @param options Client configuration (store, transport, addons, history...).
      * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
@@ -230,3 +185,83 @@ export declare class WaClient extends EventEmitter {
     private notifyIncomingHandlersDrained;
     private handleError;
 }
+/**
+ * A WhatsApp client instance: per-feature coordinator getters ({@link message},
+ * {@link group}, {@link newsletter}, ...) plus typed `on`/`once`/`off`/`emit`.
+ *
+ * `TPluginEvents` carries the events of the plugins installed on this client.
+ * Prefer deriving the precise type from the construction site (e.g.
+ * `type AppClient = ReturnType<typeof createClient>`) over the bare `WaClient`,
+ * which only knows the core events and no plugin getters.
+ */
+export interface WaClient<TPluginEvents = {}> extends WaClientImpl {
+    on<K extends keyof (WaClientEventMap & TPluginEvents)>(event: K, listener: (WaClientEventMap & TPluginEvents)[K]): this;
+    once<K extends keyof (WaClientEventMap & TPluginEvents)>(event: K, listener: (WaClientEventMap & TPluginEvents)[K]): this;
+    off<K extends keyof (WaClientEventMap & TPluginEvents)>(event: K, listener: (WaClientEventMap & TPluginEvents)[K]): this;
+    emit<K extends keyof (WaClientEventMap & TPluginEvents)>(event: K, payload: Parameters<Extract<(WaClientEventMap & TPluginEvents)[K], (...args: never[]) => unknown>>[0]): boolean;
+}
+/**
+ * Constructor surface for {@link WaClient}. `new WaClient({ plugins })` infers the
+ * exposed plugin getters (e.g. `client.voip`) from the plugin values passed:
+ * no global type augmentation, so a getter exists only when its plugin is installed.
+ */
+export interface WaClientConstructor {
+    new <const P extends readonly WaClientPluginDefinition[] = []>(options: Omit<WaClientOptions, 'plugins'> & {
+        readonly plugins?: P;
+    }, logger?: Logger): WaClient<WaClientPluginEventsFromPlugins<P>> & WaClientExposedFromPlugins<P>;
+}
+/**
+ * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
+ * coordinators (accessible via getters such as {@link message}, {@link group},
+ * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
+ *
+ * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
+ * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
+ * then use the coordinator getters to drive the session. Call {@link disconnect}
+ * to shut down cleanly or {@link logout} to remove the companion device.
+ *
+ * Pass `plugins` to expose plugin getters and events on the returned client,
+ * typed from the values you pass: e.g. `plugins: [voipPlugin()]` adds
+ * `client.voip` and the `voip_*` events, and only then. See
+ * {@link WaClientConstructor}.
+ *
+ * @example
+ * ```ts
+ * import { createPinoLogger, createStore, WaClient } from '..'
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',
+ *         threads: 'sqlite',
+ *         contacts: 'sqlite'
+ *     }
+ * })
+ *
+ * const client = new WaClient(
+ *     { store, sessionId: 'default' },
+ *     await createPinoLogger({ level: 'info', pretty: true })
+ * )
+ *
+ * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
+ * client.on('connection', (event) => console.log('connection', event))
+ * client.on('message', async (event) => {
+ *     if (event.message?.conversation === 'ping') {
+ *         await client.message.send(event.chatJid!, 'pong')
+ *     }
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
+export declare const WaClient: WaClientConstructor;
+export {};

package/dist/client/WaClient.js

@@ -6,6 +6,7 @@ const ignore_key_1 = require("./messaging/ignore-key");
 const history_sync_1 = require("./persistence/history-sync");
 const mailbox_1 = require("./persistence/mailbox");
 const WriteBehindPersistence_1 = require("./persistence/WriteBehindPersistence");
+const install_1 = require("./plugins/install");
 const WaClientFactory_1 = require("./WaClientFactory");
 const ConsoleLogger_1 = require("../infra/log/ConsoleLogger");
 const _proto_1 = require("../proto");
@@ -22,55 +23,8 @@ const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     _proto_1.proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_MESSAGE,
     _proto_1.proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_RESPONSE_MESSAGE
 ]);
-/**
- * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
- * coordinators (accessible via getters such as {@link message}, {@link group},
- * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
- *
- * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
- * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
- * then use the coordinator getters to drive the session. Call {@link disconnect}
- * to shut down cleanly or {@link logout} to remove the companion device.
- *
- * @example
- * ```ts
- * import { createPinoLogger, createStore, WaClient } from '..'
- * import { createSqliteStore } from '@zapo-js/store-sqlite'
- *
- * const store = createStore({
- *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
- *     providers: {
- *         auth: 'sqlite',
- *         signal: 'sqlite',
- *         preKey: 'sqlite',
- *         session: 'sqlite',
- *         identity: 'sqlite',
- *         senderKey: 'sqlite',
- *         appState: 'sqlite',
- *         privacyToken: 'sqlite',
- *         messages: 'sqlite',
- *         threads: 'sqlite',
- *         contacts: 'sqlite'
- *     }
- * })
- *
- * const client = new WaClient(
- *     { store, sessionId: 'default' },
- *     await createPinoLogger({ level: 'info', pretty: true })
- * )
- *
- * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
- * client.on('connection', (event) => console.log('connection', event))
- * client.on('message', async (event) => {
- *     if (event.message?.conversation === 'ping') {
- *         await client.message.send(event.chatJid!, 'pong')
- *     }
- * })
- *
- * await client.connect()
- * ```
- */
-class WaClient extends node_events_1.EventEmitter {
+/** @internal Implementation backing the exported {@link WaClient}. */
+class WaClientImpl extends node_events_1.EventEmitter {
     /**
      * @param options Client configuration (store, transport, addons, history...).
      * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
@@ -81,6 +35,7 @@ class WaClient extends node_events_1.EventEmitter {
         this.acceptingIncomingEvents = true;
         this.activeIncomingHandlers = 0;
         this.incomingHandlersDrainedWaiters = [];
+        this.disposePlugins = null;
         const base = (0, WaClientFactory_1.resolveWaClientBase)(options, logger);
         this.options = base.options;
         this.logger = base.logger;
@@ -118,6 +73,13 @@ class WaClient extends node_events_1.EventEmitter {
         this.deps = dependencies;
         this.appStateSync = dependencies.appStateSync;
         this.mediaTransfer = dependencies.mediaTransfer;
+        this.disposePlugins = (0, install_1.installWaClientPlugins)(this, {
+            options: this.options,
+            logger: this.logger,
+            stores: this.stores,
+            deps: this.deps,
+            queryWithContext: this.queryWithContext.bind(this)
+        }, this.options.plugins ?? []);
         this.bindNodeTransportEvents();
         this.on('connection', (event) => {
             if (event.status !== 'close')
@@ -384,6 +346,11 @@ class WaClient extends node_events_1.EventEmitter {
                 remaining: writeBehindFlush.remaining
             });
         }
+        if (this.disposePlugins) {
+            const dispose = this.disposePlugins;
+            this.disposePlugins = null;
+            await dispose();
+        }
         await this.deps.connectionManager.disconnect();
         this.emit('connection', {
             status: 'close',
@@ -606,4 +573,57 @@ class WaClient extends node_events_1.EventEmitter {
         this.emit('debug_client_error', { error });
     }
 }
-exports.WaClient = WaClient;
+/**
+ * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
+ * coordinators (accessible via getters such as {@link message}, {@link group},
+ * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
+ *
+ * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
+ * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
+ * then use the coordinator getters to drive the session. Call {@link disconnect}
+ * to shut down cleanly or {@link logout} to remove the companion device.
+ *
+ * Pass `plugins` to expose plugin getters and events on the returned client,
+ * typed from the values you pass: e.g. `plugins: [voipPlugin()]` adds
+ * `client.voip` and the `voip_*` events, and only then. See
+ * {@link WaClientConstructor}.
+ *
+ * @example
+ * ```ts
+ * import { createPinoLogger, createStore, WaClient } from '..'
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',
+ *         threads: 'sqlite',
+ *         contacts: 'sqlite'
+ *     }
+ * })
+ *
+ * const client = new WaClient(
+ *     { store, sessionId: 'default' },
+ *     await createPinoLogger({ level: 'info', pretty: true })
+ * )
+ *
+ * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
+ * client.on('connection', (event) => console.log('connection', event))
+ * client.on('message', async (event) => {
+ *     if (event.message?.conversation === 'ping') {
+ *         await client.message.send(event.chatJid!, 'pong')
+ *     }
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
+exports.WaClient = WaClientImpl;

package/dist/client/WaClientFactory.d.ts

@@ -36,6 +36,7 @@ import { SignalMissingPreKeysSyncApi } from '../signal/api/SignalMissingPreKeysS
 import { SignalRotateKeyApi } from '../signal/api/SignalRotateKeyApi';
 import { SignalSessionSyncApi } from '../signal/api/SignalSessionSyncApi';
 import { SenderKeyManager } from '../signal/group/SenderKeyManager';
+import { type SignalSessionResolver } from '../signal/session/resolver';
 import { SignalProtocol } from '../signal/session/SignalProtocol';
 import type { WaStoredContactRecord } from '../store/contracts/contact.store';
 import { WaKeepAlive } from '../transport/keepalive/WaKeepAlive';
@@ -72,6 +73,11 @@ interface WaClientBuildRuntime {
      */
     readonly persistContact: (record: WaStoredContactRecord) => void;
 }
+/**
+ * Internal coordinator graph wired by {@link buildWaClientDependencies}. Exposed
+ * to {@link WaClientPluginContext.deps} for plugin authors – advanced API; new
+ * coordinators may appear in minor releases.
+ */
 export interface WaClientDependencies {
     readonly nodeTransport: WaNodeTransport;
     readonly nodeOrchestrator: WaNodeOrchestrator;
@@ -87,6 +93,7 @@ export interface WaClientDependencies {
     readonly signalMissingPreKeysSync: SignalMissingPreKeysSyncApi;
     readonly signalRotateKey: SignalRotateKeyApi;
     readonly signalSessionSync: SignalSessionSyncApi;
+    readonly sessionResolver: SignalSessionResolver;
     readonly authClient: WaAuthClient;
     readonly messageDispatch: WaMessageDispatchCoordinator;
     readonly messageCoordinator: WaMessageCoordinator;

package/dist/client/WaClientFactory.js

@@ -1030,6 +1030,7 @@ function buildWaClientDependencies(input) {
         signalMissingPreKeysSync,
         signalRotateKey,
         signalSessionSync,
+        sessionResolver,
         authClient,
         messageDispatch,
         messageCoordinator,

package/dist/client/plugins/define.d.ts

@@ -0,0 +1,23 @@
+import type { WaClientPluginContext, WaClientPluginDefinition } from '../plugins/types';
+import type { WaClient } from '../WaClient';
+interface WaClientBehaviorPluginInput {
+    readonly id: string;
+    readonly setup: (ctx: WaClientPluginContext) => void;
+    readonly dispose?: (ctx: WaClientPluginContext) => void | Promise<void>;
+}
+interface WaClientExposePluginInput<K extends string, T> {
+    readonly id: string;
+    readonly exposeAs: K;
+    readonly setup: (ctx: WaClientPluginContext) => T;
+    readonly dispose?: (instance: T, ctx: WaClientPluginContext) => void | Promise<void>;
+}
+/** Type-safe helper for authoring {@link WaClientPluginDefinition} values. */
+export declare function defineWaClientPlugin(input: WaClientBehaviorPluginInput): WaClientPluginDefinition;
+export declare function defineWaClientPlugin<K extends string, T, E = {}>(input: WaClientExposePluginInput<K, T> & {
+    readonly exposeAs: K extends keyof WaClient ? never : K;
+}): WaClientPluginDefinition & {
+    readonly exposeAs: K;
+    readonly setup: (ctx: WaClientPluginContext) => T;
+    readonly __pluginEvents?: E;
+};
+export {};

package/dist/client/plugins/define.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineWaClientPlugin = defineWaClientPlugin;
+function defineWaClientPlugin(input) {
+    if ('exposeAs' in input && input.exposeAs !== undefined) {
+        const exposeInput = input;
+        return {
+            id: exposeInput.id,
+            exposeAs: exposeInput.exposeAs,
+            setup: exposeInput.setup,
+            dispose: exposeInput.dispose
+                ? (instance, ctx) => exposeInput.dispose(instance, ctx)
+                : undefined
+        };
+    }
+    const behaviorInput = input;
+    return {
+        id: behaviorInput.id,
+        setup: behaviorInput.setup,
+        dispose: behaviorInput.dispose ? (_instance, ctx) => behaviorInput.dispose(ctx) : undefined
+    };
+}

package/dist/client/plugins/index.d.ts

@@ -0,0 +1,4 @@
+export { defineWaClientPlugin } from '../plugins/define';
+export { installWaClientPlugins, type WaClientPluginInstallInput } from '../plugins/install';
+export type { WaClientPluginContext, WaClientPluginDefinition } from '../plugins/types';
+export { isWaClientExposePluginDefinition } from '../plugins/types';

package/dist/client/plugins/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWaClientExposePluginDefinition = exports.installWaClientPlugins = exports.defineWaClientPlugin = void 0;
+var define_1 = require("../plugins/define");
+Object.defineProperty(exports, "defineWaClientPlugin", { enumerable: true, get: function () { return define_1.defineWaClientPlugin; } });
+var install_1 = require("../plugins/install");
+Object.defineProperty(exports, "installWaClientPlugins", { enumerable: true, get: function () { return install_1.installWaClientPlugins; } });
+var types_1 = require("../plugins/types");
+Object.defineProperty(exports, "isWaClientExposePluginDefinition", { enumerable: true, get: function () { return types_1.isWaClientExposePluginDefinition; } });

package/dist/client/plugins/install.d.ts

@@ -0,0 +1,18 @@
+import { type WaClientPluginContext, type WaClientPluginDefinition } from '../plugins/types';
+import type { WaClientOptions } from '../types';
+import type { WaClient } from '../WaClient';
+import type { WaClientDependencies } from '../WaClientFactory';
+import type { Logger } from '../../infra/log/types';
+import type { WaStore } from '../../store/types';
+export interface WaClientPluginInstallInput {
+    readonly options: Readonly<WaClientOptions>;
+    readonly logger: Logger;
+    readonly stores: ReturnType<WaStore['session']>;
+    readonly deps: WaClientDependencies;
+    readonly queryWithContext: WaClientPluginContext['queryWithContext'];
+}
+/**
+ * Installs {@link WaClientOptions.plugins} on `client`. Returns a dispose
+ * function invoked by {@link WaClient.disconnect}.
+ */
+export declare function installWaClientPlugins(client: WaClient, input: WaClientPluginInstallInput, plugins: readonly WaClientPluginDefinition[]): () => Promise<void>;

package/dist/client/plugins/install.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installWaClientPlugins = installWaClientPlugins;
+const types_1 = require("../plugins/types");
+const primitives_1 = require("../../util/primitives");
+/**
+ * Installs {@link WaClientOptions.plugins} on `client`. Returns a dispose
+ * function invoked by {@link WaClient.disconnect}.
+ */
+function installWaClientPlugins(client, input, plugins) {
+    const seenIds = new Set();
+    const seenExposeAs = new Set();
+    const disposeCallbacks = [];
+    const registerDispose = (fn) => {
+        disposeCallbacks[disposeCallbacks.length] = fn;
+    };
+    const baseCtx = {
+        client,
+        options: input.options,
+        logger: input.logger,
+        stores: input.stores,
+        deps: input.deps,
+        emit: client.emit.bind(client),
+        on: client.on.bind(client),
+        off: client.off.bind(client),
+        once: client.once.bind(client),
+        queryWithContext: input.queryWithContext,
+        registerIncomingHandler: (registration) => input.deps.lowLevelCoordinator.registerIncomingHandler(registration),
+        registerIncomingStanzaFilter: (filter) => input.deps.lowLevelCoordinator.registerIncomingStanzaFilter(filter),
+        registerDispose
+    };
+    for (let index = 0; index < plugins.length; index += 1) {
+        const plugin = plugins[index];
+        if (seenIds.has(plugin.id)) {
+            throw new Error(`duplicate wa client plugin id: ${plugin.id}`);
+        }
+        seenIds.add(plugin.id);
+        const pluginCtx = {
+            ...baseCtx,
+            logger: input.logger.child({ plugin: plugin.id })
+        };
+        if ((0, types_1.isWaClientExposePluginDefinition)(plugin)) {
+            if (seenExposeAs.has(plugin.exposeAs)) {
+                throw new Error(`duplicate wa client plugin exposeAs: ${plugin.exposeAs}`);
+            }
+            seenExposeAs.add(plugin.exposeAs);
+            if (plugin.exposeAs in client) {
+                throw new Error(`wa client plugin exposeAs "${plugin.exposeAs}" collides with a reserved client member`);
+            }
+            const instance = plugin.setup(pluginCtx);
+            Object.defineProperty(client, plugin.exposeAs, {
+                get: () => instance,
+                enumerable: true,
+                configurable: false
+            });
+            if (plugin.dispose) {
+                const dispose = plugin.dispose;
+                registerDispose(() => dispose(instance, pluginCtx));
+            }
+            pluginCtx.logger.debug('wa client plugin installed', { exposeAs: plugin.exposeAs });
+        }
+        else {
+            plugin.setup(pluginCtx);
+            if (plugin.dispose) {
+                const dispose = plugin.dispose;
+                registerDispose(() => dispose(undefined, pluginCtx));
+            }
+            pluginCtx.logger.debug('wa client plugin installed');
+        }
+    }
+    return async () => {
+        for (let index = disposeCallbacks.length - 1; index >= 0; index -= 1) {
+            try {
+                await disposeCallbacks[index]();
+            }
+            catch (error) {
+                input.logger.warn('wa client plugin dispose failed', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+            }
+        }
+    };
+}

package/dist/client/plugins/types.d.ts

@@ -0,0 +1,76 @@
+import type { WaLowLevelCoordinator } from '../coordinators/WaLowLevelCoordinator';
+import type { WaClientOptions } from '../types';
+import type { WaClient } from '../WaClient';
+import type { WaClientDependencies } from '../WaClientFactory';
+import type { Logger } from '../../infra/log/types';
+import type { WaStore } from '../../store/types';
+import type { BinaryNode } from '../../transport/types';
+/**
+ * Host context passed to every {@link WaClientPluginDefinition.setup}. Carries
+ * the full {@link WaClientDependencies} graph plus event/handler helpers.
+ *
+ * @sensitive deps may reach key material through nested coordinators – do not
+ * log or persist deps wholesale.
+ */
+export interface WaClientPluginContext {
+    readonly client: WaClient;
+    readonly options: Readonly<WaClientOptions>;
+    readonly logger: Logger;
+    readonly stores: ReturnType<WaStore['session']>;
+    /**
+     * Full coordinator dependency graph. Advanced API for plugin authors –
+     * new coordinators may appear in minor releases.
+     */
+    readonly deps: WaClientDependencies;
+    /** Loose so a plugin can emit its own events; consumers see them typed on the client. */
+    readonly emit: (event: string | symbol, ...args: unknown[]) => boolean;
+    readonly on: WaClient['on'];
+    readonly off: WaClient['off'];
+    readonly once: WaClient['once'];
+    readonly queryWithContext: (context: string, node: BinaryNode, timeoutMs?: number, contextData?: Readonly<Record<string, unknown>>, options?: {
+        readonly useSystemId?: boolean;
+    }) => Promise<BinaryNode>;
+    readonly registerIncomingHandler: WaLowLevelCoordinator['registerIncomingHandler'];
+    readonly registerIncomingStanzaFilter: WaLowLevelCoordinator['registerIncomingStanzaFilter'];
+    /** Runs on {@link WaClient.disconnect} after incoming handlers drain. */
+    readonly registerDispose: (fn: () => void | Promise<void>) => void;
+}
+/**
+ * Runtime plugin registration. Use {@link defineWaClientPlugin} for inference.
+ * When `exposeAs` is set, `setup` should return the value exposed at
+ * `client[exposeAs]`; otherwise only side effects (handlers, listeners) run.
+ */
+export interface WaClientPluginDefinition {
+    readonly id: string;
+    readonly exposeAs?: string;
+    readonly setup: (ctx: WaClientPluginContext) => unknown;
+    readonly dispose?: (instance: unknown, ctx: WaClientPluginContext) => void | Promise<void>;
+}
+export declare function isWaClientExposePluginDefinition(plugin: WaClientPluginDefinition): plugin is WaClientPluginDefinition & {
+    readonly exposeAs: string;
+};
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** `{ [exposeAs]: setup-return }` for one plugin definition; `{}` (no-op) for behavior plugins. */
+type ExposedOf<P> = P extends {
+    readonly exposeAs: infer K extends string;
+    readonly setup: (...args: never[]) => infer T;
+} ? {
+    readonly [Q in K]: T;
+} : {};
+/**
+ * Getters contributed by a tuple of plugin definitions, derived from the values
+ * passed to the client (no global augmentation). `[voipPlugin()]` yields
+ * `{ readonly voip: WaVoipCoordinator }`.
+ */
+export type WaClientExposedFromPlugins<P extends readonly unknown[]> = UnionToIntersection<ExposedOf<P[number]>>;
+/** Event map a plugin contributes, carried as a phantom marker on its definition. */
+type EventsOf<P> = P extends {
+    readonly __pluginEvents?: infer E;
+} ? unknown extends E ? {} : E : {};
+/**
+ * Client events contributed by a tuple of plugin definitions, derived from the
+ * plugin values (no global augmentation). Threaded into the client's
+ * `on`/`once`/`off`/`emit` so a `voip_*` event exists only when voip is installed.
+ */
+export type WaClientPluginEventsFromPlugins<P extends readonly unknown[]> = UnionToIntersection<EventsOf<P[number]>>;
+export {};

package/dist/client/plugins/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWaClientExposePluginDefinition = isWaClientExposePluginDefinition;
+function isWaClientExposePluginDefinition(plugin) {
+    return plugin.exposeAs !== undefined && plugin.exposeAs.length > 0;
+}

package/dist/client/types.d.ts

@@ -3,6 +3,7 @@ import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '../ap
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
+import type { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
 import type { WaLinkPreviewOptions } from '../message/addons/link-preview/types';
 import type { WaQuoteRef, WaSendContextInfo } from '../message/context-info';
@@ -173,6 +174,11 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * default auto-fetch globally.
      */
     readonly linkPreview?: WaLinkPreviewOptions;
+    /**
+     * Optional client plugins – behavior hooks and/or coordinators exposed at
+     * `client[exposeAs]`. See {@link defineWaClientPlugin}.
+     */
+    readonly plugins?: readonly WaClientPluginDefinition[];
     /**
      * Test-only overrides intended for running against a fake server.
      *