@diegoaltoworks/chatter 0.36.0 → 0.37.0

package/dist/bin/wa-pair.js

@@ -150,6 +150,126 @@ function loadBaileys() {
   return cached;
 }
 
+// src/channels/whatsapp/pairing.ts
+var RESTART_REQUIRED_STATUS = 515;
+var MAX_PAIRING_RECONNECTS = 12;
+var PAIRING_RECONNECT_DELAY_MS = 2e3;
+var PAIRING_RECONNECT_MAX_DELAY_MS = 8e3;
+var RESTART_REQUIRED_DELAY_MS = 500;
+function pairingReconnectDelayMs(statusCode, attempt) {
+  if (statusCode === RESTART_REQUIRED_STATUS) return RESTART_REQUIRED_DELAY_MS;
+  return Math.min(
+    PAIRING_RECONNECT_DELAY_MS * 2 ** Math.max(0, attempt - 1),
+    PAIRING_RECONNECT_MAX_DELAY_MS
+  );
+}
+function decidePairingClose(input) {
+  if (input.statusCode === input.loggedOutCode) return { kind: "fatal", reason: "loggedOut" };
+  if (input.attempts >= input.maxAttempts) return { kind: "fatal", reason: "exhausted" };
+  const attempt = input.attempts + 1;
+  return {
+    kind: "reconnect",
+    attempt,
+    delayMs: pairingReconnectDelayMs(input.statusCode, attempt)
+  };
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function runPairing(deps) {
+  const maxAttempts = deps.maxAttempts ?? MAX_PAIRING_RECONNECTS;
+  const schedule = deps.schedule ?? ((fn, ms) => {
+    setTimeout(fn, ms);
+  });
+  return new Promise((resolve) => {
+    let attempts = 0;
+    let generation = 0;
+    let codeRequested = false;
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    const status = (message) => deps.onStatus?.(message);
+    const requestCode = async (sock) => {
+      if (settled || codeRequested || !deps.phoneNumber) return;
+      try {
+        const code = await sock.requestPairingCode(deps.phoneNumber);
+        codeRequested = true;
+        deps.onPairingCode?.(code);
+      } catch (error) {
+        settle({
+          ok: false,
+          reason: "error",
+          message: `Failed to request pairing code: ${describeError(error)}`
+        });
+      }
+    };
+    const handleUpdate = async (update, sock) => {
+      const { connection, lastDisconnect, qr } = update;
+      if (qr && !deps.phoneNumber && deps.onQr) {
+        try {
+          await deps.onQr(qr);
+        } catch (error) {
+          status(`QR render failed: ${describeError(error)}`);
+        }
+      }
+      if (connection === "open") {
+        settle({ ok: true, userId: sock.user?.id });
+        return;
+      }
+      if (connection === "close") {
+        const statusCode = lastDisconnect?.error?.output?.statusCode;
+        const action = decidePairingClose({
+          statusCode,
+          loggedOutCode: deps.loggedOutCode,
+          attempts,
+          maxAttempts
+        });
+        if (action.kind === "fatal") {
+          settle({
+            ok: false,
+            reason: action.reason,
+            message: action.reason === "loggedOut" ? "Pairing rejected (logged out). Run wa-pair again for a fresh code." : `Gave up after ${maxAttempts} reconnect attempts (last close: ${statusCode ?? "?"}). Run wa-pair again.`
+          });
+          return;
+        }
+        attempts = action.attempt;
+        generation += 1;
+        sock.end?.();
+        status(
+          statusCode === RESTART_REQUIRED_STATUS ? `Registered \u2014 WhatsApp asked for a restart (515). Reconnecting to finish the link (${action.attempt}/${maxAttempts})...` : `Connection closed (${statusCode ?? "?"}) \u2014 reconnecting with the stored session (${action.attempt}/${maxAttempts})...`
+        );
+        schedule(() => void attach(), action.delayMs);
+      }
+    };
+    const attach = async () => {
+      if (settled) return;
+      const mine = generation;
+      const attempt = attempts;
+      let sock;
+      try {
+        sock = await deps.connect(attempt);
+      } catch (error) {
+        settle({ ok: false, reason: "error", message: describeError(error) });
+        return;
+      }
+      sock.ev.on("connection.update", (update) => {
+        if (mine !== generation || settled) return;
+        void handleUpdate(update, sock);
+      });
+      if (deps.phoneNumber && !codeRequested) {
+        schedule(() => {
+          if (mine !== generation) return;
+          void requestCode(sock);
+        }, deps.requestCodeDelayMs ?? 3e3);
+      }
+    };
+    void attach();
+  });
+}
+
 // bin/wa-pair.ts
 var args = process.argv.slice(2);
 function flagValue(name) {
@@ -199,10 +319,17 @@ var db = (0, import_client.createClient)({
   url: process.env.TURSO_URL,
   authToken: process.env.TURSO_AUTH_TOKEN || ""
 });
-var MAX_RECONNECTS = 12;
-var codeRequested = false;
-var reconnects = 0;
-var didReset = false;
+async function renderQr(qr) {
+  const qrcodeTerminal = await import("qrcode-terminal").catch(() => void 0);
+  if (!qrcodeTerminal) {
+    console.error(
+      "\u274C QR mode requires the optional peer dependency 'qrcode-terminal'. Install it with `bun add qrcode-terminal`, or re-run with --code <phoneNumber> for pairing-code mode instead."
+    );
+    process.exit(1);
+  }
+  console.log("\nScan this QR code: WhatsApp -> Settings -> Linked Devices -> Link a Device.\n");
+  qrcodeTerminal.default.generate(qr, { small: true });
+}
 async function start() {
   const baileys = await loadBaileys().catch((error) => {
     console.error(`\u274C ${error.message}`);
@@ -213,106 +340,73 @@ async function start() {
     initAuthCreds: baileys.initAuthCreds,
     appStateSyncKeyFromObject: (value) => baileys.proto.Message.AppStateSyncKeyData.fromObject(value)
   };
-  const { state, saveCreds, clear } = await useTursoAuthState(
-    db,
-    sessionSecret,
-    sessionId,
-    runtime
-  );
-  if (reset && !didReset) {
-    didReset = true;
+  if (reset) {
+    const { clear } = await useTursoAuthState(db, sessionSecret, sessionId, runtime);
     await clear();
     console.log(`Session "${sessionId}" wiped. Pairing fresh...`);
-    return start();
-  }
-  if (state.creds.registered && !codeRequested) {
-    console.log(
-      `Already paired. Session "${sessionId}" is connected-ready. Run with --reset to re-pair.`
-    );
-    process.exit(0);
   }
   const { version } = await baileys.fetchLatestBaileysVersion();
-  const noop = () => void 0;
-  const logger = {
-    level: "silent",
-    trace: noop,
-    debug: noop,
-    info: noop,
-    warn: noop,
-    error: noop,
-    fatal: noop
-  };
-  logger.child = () => logger;
-  const sock = baileys.makeWASocket({
-    version,
-    auth: {
-      creds: state.creds,
-      // biome-ignore lint/suspicious/noExplicitAny: structural pino-compatible logger
-      keys: baileys.makeCacheableSignalKeyStore(state.keys, logger)
-    },
-    // biome-ignore lint/suspicious/noExplicitAny: structural pino-compatible logger
-    logger,
-    markOnlineOnConnect: false
-  });
-  sock.ev.on("creds.update", saveCreds);
-  sock.ev.on("connection.update", async (update) => {
-    const { connection, lastDisconnect, qr } = update;
-    if (qr && !phoneNumber) {
-      const qrcodeTerminal = await import("qrcode-terminal").catch(() => void 0);
-      if (!qrcodeTerminal) {
-        console.error(
-          "\u274C QR mode requires the optional peer dependency 'qrcode-terminal'. Install it with `bun add qrcode-terminal`, or re-run with --code <phoneNumber> for pairing-code mode instead."
-        );
-        process.exit(1);
-      }
-      console.log(
-        "\nScan this QR code: WhatsApp -> Settings -> Linked Devices -> Link a Device.\n"
-      );
-      qrcodeTerminal.default.generate(qr, { small: true });
-    }
-    if (connection === "open") {
+  const connect = async (attempt) => {
+    const { state, saveCreds } = await useTursoAuthState(
+      db,
+      sessionSecret,
+      sessionId,
+      runtime
+    );
+    if (attempt === 0 && state.creds.registered) {
       console.log(
-        `
-\u2705 Paired session "${sessionId}" as ${sock.user?.id}. Session saved (encrypted).`
+        `Already paired. Session "${sessionId}" is connected-ready. Run with --reset to re-pair.`
       );
-      console.log("The running server will pick this session up on its next connect.");
       process.exit(0);
     }
-    if (connection === "close") {
-      const statusCode = lastDisconnect?.error?.output?.statusCode;
-      if (codeRequested && reconnects < MAX_RECONNECTS) {
-        reconnects++;
-        console.log(
-          `Connection closed (${statusCode ?? "?"}) - reconnecting (code STILL VALID, keep going on the phone) (${reconnects}/${MAX_RECONNECTS})...`
-        );
-        setTimeout(() => void start(), 2e3);
-        return;
-      }
-      if (statusCode === baileys.DisconnectReason.loggedOut) {
-        console.error("\u274C Pairing rejected (logged out). Run wa-pair again for a fresh code.");
-      } else {
-        console.error(`\u274C Connection closed (${statusCode ?? "?"}). Run wa-pair again.`);
-      }
-      process.exit(1);
-    }
+    const noop = () => void 0;
+    const logger = {
+      level: "silent",
+      trace: noop,
+      debug: noop,
+      info: noop,
+      warn: noop,
+      error: noop,
+      fatal: noop
+    };
+    logger.child = () => logger;
+    const sock = baileys.makeWASocket({
+      version,
+      auth: {
+        creds: state.creds,
+        // biome-ignore lint/suspicious/noExplicitAny: structural pino-compatible logger
+        keys: baileys.makeCacheableSignalKeyStore(state.keys, logger)
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: structural pino-compatible logger
+      logger,
+      markOnlineOnConnect: false
+    });
+    sock.ev.on("creds.update", saveCreds);
+    return sock;
+  };
+  const result = await runPairing({
+    connect,
+    loggedOutCode: baileys.DisconnectReason.loggedOut,
+    phoneNumber,
+    onQr: renderQr,
+    onPairingCode: (code) => {
+      console.log("\n==============================================");
+      console.log(`  Pairing code for +${phoneNumber}:  ${code}`);
+      console.log("==============================================");
+      console.log("On the phone: WhatsApp -> Settings -> Linked Devices ->");
+      console.log("Link a Device -> 'Link with phone number instead' -> enter the code.");
+      console.log("Waiting for confirmation (leave this running)...");
+    },
+    onStatus: (message) => console.log(message)
   });
-  if (phoneNumber && !codeRequested && !state.creds.registered) {
-    setTimeout(async () => {
-      try {
-        const code = await sock.requestPairingCode(phoneNumber);
-        codeRequested = true;
-        console.log("\n==============================================");
-        console.log(`  Pairing code for +${phoneNumber}:  ${code}`);
-        console.log("==============================================");
-        console.log("On the phone: WhatsApp -> Settings -> Linked Devices ->");
-        console.log("Link a Device -> 'Link with phone number instead' -> enter the code.");
-        console.log("Waiting for confirmation (leave this running)...");
-      } catch (error) {
-        console.error("\u274C Failed to request pairing code:", error);
-        process.exit(1);
-      }
-    }, 3e3);
+  if (!result.ok) {
+    console.error(`\u274C ${result.message}`);
+    process.exit(1);
   }
+  console.log(`
+\u2705 Paired session "${sessionId}" as ${result.userId}. Session saved (encrypted).`);
+  console.log("The running server will pick this session up on its next connect.");
+  process.exit(0);
 }
 start().catch((error) => {
   console.error("\u274C Unexpected error:", error);

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

@@ -0,0 +1,106 @@
+/**
+ * Pairing loop for the `wa-pair` CLI — the transport-independent half, kept
+ * out of the bin so it can be unit-tested against a faked socket.
+ *
+ * Both pairing modes close the socket mid-flow as a matter of course:
+ *
+ * - QR mode: the moment a scan registers the device, WhatsApp ALWAYS closes
+ *   with 515 ("restart required"). The link only completes if the client comes
+ *   straight back with the SAME credentials it just registered — the phone is
+ *   sitting on "linking" waiting for exactly that. Exiting there (or wiping
+ *   creds and starting over) fails the pairing every time.
+ * - Pairing-code mode: the socket bounces while the code is being typed.
+ *
+ * So a close during pairing is normal, not fatal: reconnect with stored creds,
+ * bounded, until `open` confirms the link. Only an explicit logout or running
+ * out of attempts ends the run.
+ */
+/** Baileys' "restart required" — emitted immediately after a QR scan registers the device. */
+export declare const RESTART_REQUIRED_STATUS = 515;
+/** Bounded so a genuinely broken pairing terminates instead of looping forever. */
+export declare const MAX_PAIRING_RECONNECTS = 12;
+/**
+ * Backoff between pairing attempts. Deliberately tighter than the transport's
+ * 5s→10min ladder (`reconnectDelayMs`): that one protects a long-lived
+ * connection from hammering WhatsApp during an outage, whereas here a human is
+ * holding a phone that gives the link a limited window — a 515 restart has to
+ * be answered at once, and other bounces within seconds.
+ */
+export declare function pairingReconnectDelayMs(statusCode: number | undefined, attempt: number): number;
+export type PairingCloseAction = {
+    kind: "reconnect";
+    attempt: number;
+    delayMs: number;
+} | {
+    kind: "fatal";
+    reason: "loggedOut" | "exhausted";
+};
+export interface PairingCloseInput {
+    statusCode?: number;
+    /** `DisconnectReason.loggedOut` from the loaded Baileys build. */
+    loggedOutCode: number;
+    /** Reconnects already spent. */
+    attempts: number;
+    maxAttempts: number;
+}
+/**
+ * Pure: what to do about a `connection: "close"` during pairing. A logout is
+ * final (the credentials just got revoked — retrying re-revokes them); every
+ * other close is transient until the attempt budget runs out.
+ */
+export declare function decidePairingClose(input: PairingCloseInput): PairingCloseAction;
+/** The slice of a Baileys socket the pairing loop uses. */
+export interface PairingSocket {
+    ev: {
+        on: (event: "connection.update", listener: (update: PairingConnectionUpdate) => void) => void;
+    };
+    user?: {
+        id?: string;
+    } | null;
+    requestPairingCode: (phoneNumber: string) => Promise<string>;
+    /** Closes a superseded socket so it stops writing to the session. */
+    end?: (error?: Error) => void;
+}
+export interface PairingConnectionUpdate {
+    connection?: string;
+    qr?: string;
+    lastDisconnect?: {
+        error?: unknown;
+    } | null;
+}
+export type PairingResult = {
+    ok: true;
+    userId?: string;
+} | {
+    ok: false;
+    reason: "loggedOut" | "exhausted" | "error";
+    message: string;
+};
+export interface PairingRunDeps {
+    /**
+     * Opens a socket for `attempt` (0 = first). MUST reuse the stored
+     * credentials — a reconnect that starts from blank creds shows a fresh QR
+     * instead of finishing the link the phone is waiting on.
+     */
+    connect: (attempt: number) => PairingSocket | Promise<PairingSocket>;
+    loggedOutCode: number;
+    /** Digits-only number for pairing-code mode; omit for QR mode. */
+    phoneNumber?: string;
+    maxAttempts?: number;
+    /** Delay before asking for a pairing code, giving the socket time to handshake. */
+    requestCodeDelayMs?: number;
+    /** Overridable for tests; defaults to `setTimeout`. */
+    schedule?: (fn: () => void, ms: number) => void;
+    /** Renders the QR (QR mode only). A throw is reported, never swallowed. */
+    onQr?: (qr: string) => void | Promise<void>;
+    onPairingCode?: (code: string) => void;
+    /** Progress lines for the operator (reconnect notices, QR render failures). */
+    onStatus?: (message: string) => void;
+}
+/**
+ * Runs one pairing to a verdict: resolves `{ ok: true }` when the connection
+ * reaches `open` (the link is live), or `{ ok: false }` on logout, attempt
+ * exhaustion, or a connect/pairing-code failure. Never rejects.
+ */
+export declare function runPairing(deps: PairingRunDeps): Promise<PairingResult>;
+//# sourceMappingURL=pairing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/pairing.ts"],"names":[],"mappings":"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"}

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",