@diegoaltoworks/chatter 0.27.0 → 0.29.0

package/dist/channels/whatsapp/authState.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Turso/libsql-backed Baileys auth state, encrypted at rest.
+ *
+ * Same contract as Baileys' own `useMultiFileAuthState`, but rows in a
+ * `wa_auth` table instead of files, AES-GCM encrypted (see `crypto.ts`) so
+ * session material — which grants full account access — is never stored
+ * readable.
+ *
+ * Only Baileys *types* are imported here (erased at compile time, so they add
+ * no runtime dependency); the few Baileys runtime values this module needs
+ * (`BufferJSON`, `initAuthCreds`, the app-state-sync-key constructor) are
+ * passed in by the caller, which already holds them from the dynamic import
+ * in `baileys.ts` — see that module for why the import is dynamic.
+ */
+import type { Client } from "@libsql/client";
+import type { AuthenticationCreds, AuthenticationState, SignalDataTypeMap } from "@whiskeysockets/baileys";
+export interface TursoAuthStateResult {
+    state: AuthenticationState;
+    saveCreds: () => Promise<void>;
+    /** Wipe the stored session (unlink / re-pair). */
+    clear: () => Promise<void>;
+}
+/** The slice of the dynamically-loaded Baileys module this file needs at runtime. */
+export interface AuthStateRuntime {
+    bufferJSON: {
+        replacer: (key: string, value: unknown) => unknown;
+        reviver: (key: string, value: unknown) => unknown;
+    };
+    initAuthCreds: () => AuthenticationCreds;
+    appStateSyncKeyFromObject: (value: Record<string, unknown>) => SignalDataTypeMap["app-state-sync-key"];
+}
+/**
+ * Sessions share the `wa_auth` table, namespaced by row-id prefix. The
+ * "default" session uses UNPREFIXED ids — exactly a single-session layout —
+ * so an existing default session needs no migration when multi-session
+ * support is introduced.
+ */
+export declare function useTursoAuthState(db: Client, secret: string, sessionId: string, runtime: AuthStateRuntime): Promise<TursoAuthStateResult>;
+//# sourceMappingURL=authState.d.ts.map

package/dist/channels/whatsapp/authState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/authState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,kDAAkD;IAClD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE;QACV,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QACnD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;KACnD,CAAC;IACF,aAAa,EAAE,MAAM,mBAAmB,CAAC;IACzC,yBAAyB,EAAE,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;CAC9C;AAiBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,oBAAoB,CAAC,CA6E/B"}

package/dist/channels/whatsapp/authState.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=authState.test.d.ts.map

package/dist/channels/whatsapp/authState.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.test.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/authState.test.ts"],"names":[],"mappings":""}

package/dist/channels/whatsapp/baileys.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one place `./whatsapp` touches the `@whiskeysockets/baileys` package at
+ * runtime. It's an OPTIONAL peer dependency — `bun install` and every core
+ * import must work without it — so nothing in this subpath may `import` it
+ * statically; every other module here takes what it needs as a value (see
+ * `AuthStateRuntime` in `authState.ts`) or a type-only import (erased at
+ * compile time, so it costs nothing at runtime).
+ *
+ * `loadBaileys()` is the single dynamic import, called lazily when a channel
+ * actually starts, so a missing package fails with an actionable message
+ * instead of a raw "Cannot find module" — or, worse, at unrelated core
+ * imports that never touch WhatsApp at all.
+ */
+import type * as BaileysModule from "@whiskeysockets/baileys";
+export type Baileys = typeof BaileysModule;
+/** Wraps a failed `import("@whiskeysockets/baileys")` in an actionable message. Exported separately so the message content is unit-testable without simulating a real missing module. */
+export declare function wrapMissingBaileysError(cause: unknown): Error;
+export declare function loadBaileys(): Promise<Baileys>;
+/** A silent, structurally pino-compatible logger — Baileys logs very verbosely by default. */
+export declare function silentLogger(): unknown;
+//# sourceMappingURL=baileys.d.ts.map

package/dist/channels/whatsapp/baileys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baileys.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/baileys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,aAAa,MAAM,yBAAyB,CAAC;AAE9D,MAAM,MAAM,OAAO,GAAG,OAAO,aAAa,CAAC;AAE3C,yLAAyL;AACzL,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO7D;AAID,wBAAgB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAQ9C;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,IAAI,OAAO,CAatC"}

package/dist/channels/whatsapp/baileys.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baileys.test.d.ts.map

package/dist/channels/whatsapp/baileys.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baileys.test.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/baileys.test.ts"],"names":[],"mappings":""}

package/dist/channels/whatsapp/channel.d.ts

@@ -0,0 +1,95 @@
+/**
+ * WhatsApp web-client transport: a {@link Channel} that runs one Baileys
+ * socket per configured session id (one WhatsApp number each), auth state
+ * encrypted in the host's own database (`deps.db` — no second connection
+ * opened), and a deploy lease so two overlapping instances can never hold the
+ * same session's socket at once (WhatsApp treats a second connection as a
+ * takeover and logs the first one out).
+ *
+ * Message INTERPRETATION — mention/reply detection, allowlists, loop guards —
+ * is deliberately not this module's job; it hands every raw inbound message
+ * to `config.onMessage` and lets the caller apply `./channels`' reply gates.
+ * This module owns only the connection lifecycle and outbound sending.
+ *
+ * ToS note: Baileys is an unofficial WhatsApp client. Linking a number
+ * carries a real ban risk — use a number you can afford to lose, and treat
+ * this channel as opt-in, never a default.
+ */
+import type { WAMessage, WASocket } from "@whiskeysockets/baileys";
+import type { Channel } from "../index";
+import { type Baileys } from "./baileys";
+import { type WaLeaseStore } from "./lease";
+/** Exponential backoff: 5s, 10s, 20s ... capped at 10 minutes. Hammering
+ * WhatsApp every few seconds during an outage or ban aggravates ban scoring. */
+export declare function reconnectDelayMs(failures: number): number;
+export interface WhatsAppMessageEvent {
+    sessionId: string;
+    sock: WASocket;
+    message: WAMessage;
+}
+export interface WhatsAppChannelConfig {
+    /** Passphrase that encrypts auth state at rest (AES-256-GCM key material). Keep it stable across restarts and deploys — losing it means re-pairing. */
+    sessionSecret: string;
+    /** One Baileys connection per id, each a separate WhatsApp number. Defaults to `["default"]`, whose auth rows are unprefixed (a pre-multi-session deployment needs no migration). */
+    sessionIds?: string[];
+    /**
+     * Called for every raw inbound message on every session. This module does
+     * no interpretation of its own — no mention detection, no allowlists, no
+     * loop guard — so replies belong entirely to the handler; pair it with
+     * `./channels`' `decideChannelAction` and `isEffectivelyFromSelf`. A
+     * throwing/rejecting handler is caught and logged, never left to crash the
+     * socket's event loop.
+     */
+    onMessage?: (event: WhatsAppMessageEvent) => void | Promise<void>;
+    now?: () => number;
+    /** Overridable for tests; defaults to `setTimeout`. */
+    schedule?: (fn: () => void, ms: number) => void;
+    /** Overridable for tests, which fake the Baileys module instead of installing it; defaults to `loadBaileys` from `./baileys`. */
+    loadBaileys?: () => Promise<Baileys>;
+    staleMs?: number;
+    heartbeatMs?: number;
+    waitMs?: number;
+}
+/** A live, leased session: what `stop()` (or losing the lease) must tear down. */
+export interface WaSessionHandle {
+    sock: {
+        end: (error?: Error) => void;
+    };
+    stopHeartbeat: () => void;
+    release: () => Promise<void>;
+}
+/**
+ * Tears down every session in `sessions`: stop renewing, close the socket,
+ * THEN release the lease — releasing before the socket closes could let
+ * another instance connect while this one is still on the wire. Sessions run
+ * independently (`Promise.all`); one release rejecting must not block or skip
+ * the rest.
+ */
+export declare function shutdownWaSessions(sessions: Map<string, WaSessionHandle>): Promise<void>;
+export interface LeaseGatedConnectDeps {
+    leaseStore: WaLeaseStore;
+    instanceId: string;
+    sessions: Map<string, WaSessionHandle>;
+    isStopped: () => boolean;
+    /** The actual Baileys connect — registers its own reconnect-on-close loop; this only gates its FIRST call. */
+    connect: (sessionId: string) => Promise<void>;
+    now?: () => number;
+    staleMs?: number;
+    heartbeatMs?: number;
+    waitMs?: number;
+    schedule?: (fn: () => void, ms: number) => void;
+}
+/**
+ * Acquire `sessionId`'s lease before connecting — two instances must never
+ * run concurrent Baileys clients for the same session. Not holding it (or a
+ * database blip while trying) means wait and re-check instead of connecting.
+ * Once held, a heartbeat renews it for as long as the session runs; if a
+ * heartbeat ever finds the lease gone (this instance went stale and another
+ * took over), the session is torn down and this re-enters the same
+ * wait-and-retry loop rather than staying connected alongside the new holder.
+ */
+export declare function acquireSessionLease(sessionId: string, deps: LeaseGatedConnectDeps): Promise<void>;
+/** Sender-registry name for a session — the default session stays unprefixed so single-number deployments see a plain `"whatsapp"` name. */
+export declare function senderNameFor(channelName: string, sessionId: string): string;
+export declare function createWhatsAppChannel(config: WhatsAppChannelConfig): Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channels/whatsapp/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAIxC,OAAO,EAAE,KAAK,OAAO,EAAmD,MAAM,WAAW,CAAC;AAC1F,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAKjB;gFACgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,uJAAuJ;IACvJ,aAAa,EAAE,MAAM,CAAC;IACtB,qLAAqL;IACrL,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,iIAAiI;IACjI,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QAAE,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAA;KAAE,CAAC;IACvC,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9F;AAYD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,YAAY,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,8GAA8G;IAC9G,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Df;AAED,4IAA4I;AAC5I,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CA8L5E"}

package/dist/channels/whatsapp/channel.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=channel.test.d.ts.map

package/dist/channels/whatsapp/channel.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.test.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/channel.test.ts"],"names":[],"mappings":""}

package/dist/channels/whatsapp/crypto.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encryption for persisted WhatsApp session material (AES-256-GCM).
+ *
+ * The stored auth state grants full account access, so it never touches the
+ * database in plaintext. The key derives from a caller-supplied secret (any
+ * strong passphrase, kept stable across restarts and deploys).
+ */
+export declare function encrypt(plaintext: string, secret: string): string;
+export declare function decrypt(payload: string, secret: string): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/channels/whatsapp/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ/D"}

package/dist/channels/whatsapp/crypto.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crypto.test.d.ts.map

package/dist/channels/whatsapp/crypto.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.test.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/crypto.test.ts"],"names":[],"mappings":""}

package/dist/channels/whatsapp/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WhatsApp web-client transport — a {@link Channel} built on Baileys
+ * (`@whiskeysockets/baileys`, an OPTIONAL peer dependency; nothing in core or
+ * `./channels` imports it, so `bun install` and every core import work
+ * without it).
+ *
+ * ```ts
+ * import { createWhatsAppChannel } from "@diegoaltoworks/chatter/whatsapp";
+ *
+ * const channel = createWhatsAppChannel({
+ *   sessionSecret: process.env.WA_SESSION_SECRET as string,
+ *   sessionIds: (process.env.WA_SESSION_IDS ?? "default").split(","),
+ *   onMessage: async ({ sessionId, sock, message }) => {
+ *     // apply ./channels' decideChannelAction, resolve the reply, sock.sendMessage(...)
+ *   },
+ * });
+ *
+ * await createServer({ ..., channels: [channel] });
+ * ```
+ *
+ * ToS note: Baileys is an unofficial WhatsApp client. A linked number can be
+ * banned — use one you can afford to lose, and keep this channel opt-in.
+ *
+ * @packageDocumentation
+ */
+export type { AuthStateRuntime, TursoAuthStateResult } from "./authState";
+export { useTursoAuthState } from "./authState";
+export type { Baileys } from "./baileys";
+export { loadBaileys } from "./baileys";
+export { acquireSessionLease, createWhatsAppChannel, type LeaseGatedConnectDeps, reconnectDelayMs, senderNameFor, shutdownWaSessions, type WaSessionHandle, type WhatsAppChannelConfig, type WhatsAppMessageEvent, } from "./channel";
+export { decrypt, encrypt } from "./crypto";
+export { canAcquireLease, createTursoWaLeaseStore, LEASE_HEARTBEAT_MS, LEASE_STALE_MS, LEASE_WAIT_MS, type WaLeaseRow, type WaLeaseStore, } from "./lease";
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/whatsapp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}