@masons/agent-network 0.1.5

package/dist/config.js

@@ -0,0 +1,245 @@
+/**
+ * Config & runtime bridge — mediates shared state between channel.ts and tools.ts.
+ *
+ * Read/write separation architecture:
+ * - **Reads**: `initToolConfig(ctx.cfg)` injects Host-provided config into
+ *   module-level variables. Tools read from these vars via guard functions.
+ * - **Writes**: 3 fs functions write to `openclaw.json`, signaling the Host
+ *   (Gateway monitors file changes for hot-reload / restart).
+ * - **Runtime**: `initConnectorClient(client)` injects the live WebSocket
+ *   client after connection is established. Conversation tools read it via
+ *   `requireConnectorClient()`.
+ *
+ * `ctx.cfg` is the Host's authoritative value for this process lifecycle.
+ * Plugin does not re-parse the config file for reads.
+ *
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_API_HOST, } from "./platform-client.js";
+// ---------------------------------------------------------------------------
+// Module-level state (lifecycle-scoped — set by initToolConfig, read by tools)
+// ---------------------------------------------------------------------------
+// Initialize with defaults so setup tools work BEFORE startAccount() runs.
+// On first install (no credentials), startAccount() never runs because
+// listAccountIds() returns []. But the LLM setup tools (mstp_setup_init etc.)
+// still need apiHost to call the Platform API. Without this default, tools
+// throw "Channel must be started first" on first run.
+// Config state (from Host's openclaw.json — set by initToolConfig)
+let platformConfig = { apiHost: DEFAULT_API_HOST };
+let storedApiKey = null;
+let storedPendingTarget = null;
+// Runtime state (live connection — set by startAccount, cleared by stopAccount)
+let storedConnectorClient = null;
+// ---------------------------------------------------------------------------
+// Config navigation — shared between channel.ts and config.ts
+// ---------------------------------------------------------------------------
+/**
+ * Extract the `channels["agent-network"]` section from the full OpenClaw config.
+ *
+ * OpenClaw Gateway passes the ENTIRE config (all of openclaw.json) to
+ * channel adapter methods and startAccount(). This helper navigates to
+ * the MSTP-specific section.
+ *
+ */
+export function extractMstpConfig(cfg) {
+    const channels = cfg.channels;
+    if (!channels)
+        return null;
+    const section = channels["agent-network"];
+    if (typeof section !== "object" || section === null)
+        return null;
+    return section;
+}
+// ---------------------------------------------------------------------------
+// Config injection (called by startAccount() in channel.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Inject Host-provided config into module-level variables.
+ *
+ * Called by `startAccount()` each time Gateway starts or hot-reloads.
+ * Ensures tools always read the Host's current config values.
+ */
+export function initToolConfig(cfg) {
+    const mstpCfg = extractMstpConfig(cfg);
+    platformConfig = {
+        apiHost: typeof mstpCfg?.apiHost === "string" ? mstpCfg.apiHost : DEFAULT_API_HOST,
+    };
+    // Extract API key from channels["agent-network"].accounts.default.token
+    const accounts = mstpCfg?.accounts;
+    const defaultAccount = accounts?.default;
+    storedApiKey =
+        typeof defaultAccount?.token === "string" ? defaultAccount.token : null;
+    storedPendingTarget =
+        typeof mstpCfg?.pendingTarget === "string" ? mstpCfg.pendingTarget : null;
+}
+// ---------------------------------------------------------------------------
+// ConnectorClient injection (called by startAccount() after connect)
+// ---------------------------------------------------------------------------
+/**
+ * Inject the live ConnectorClient after WebSocket connection is established.
+ *
+ * Called by `startAccount()` AFTER `client.connect()` resolves — ensures
+ * tools never receive a client with a null WebSocket.
+ *
+ * Phase 1 supports a single account. The double-init guard makes this
+ * assumption explicit: a second call without `clearConnectorClient()` throws.
+ */
+export function initConnectorClient(client) {
+    if (storedConnectorClient !== null) {
+        throw new Error("ConnectorClient already initialized. Multi-account not yet supported.");
+    }
+    storedConnectorClient = client;
+}
+/**
+ * Clear the stored ConnectorClient reference.
+ *
+ * Called by `stopAccount()` before disconnecting — prevents tools from
+ * operating on a disconnected client.
+ */
+export function clearConnectorClient() {
+    storedConnectorClient = null;
+}
+// ---------------------------------------------------------------------------
+// Guard functions (used by tools — fail-fast if not initialized)
+// ---------------------------------------------------------------------------
+/**
+ * Get platform config. Always returns a valid config — defaults are set
+ * at module load time, and overwritten by `initToolConfig()` when
+ * `startAccount()` runs.
+ *
+ * This ensures setup tools work on first install (before credentials
+ * exist and before `startAccount()` has run).
+ */
+export function requirePlatformConfig() {
+    return platformConfig;
+}
+/**
+ * Get stored API key. Throws if no credentials are configured.
+ */
+export function requireApiKey() {
+    if (!storedApiKey) {
+        throw new Error("No API key configured. Complete MSTP setup first.");
+    }
+    return storedApiKey;
+}
+/**
+ * Get pending connection target handle, or null if none.
+ */
+export function getPendingTarget() {
+    return storedPendingTarget;
+}
+/**
+ * Get the live ConnectorClient. Throws if not initialized.
+ *
+ * Note: The returned client may be in a reconnecting state (WebSocket
+ * temporarily null after a drop). Callers must handle `false` returns
+ * from send methods (`sendMessage`, `createSession`, `endSession`).
+ */
+export function requireConnectorClient() {
+    if (!storedConnectorClient) {
+        throw new Error("Not connected to the agent network. Wait for the connection to be established.");
+    }
+    return storedConnectorClient;
+}
+// ---------------------------------------------------------------------------
+// Config path resolution
+// ---------------------------------------------------------------------------
+function getConfigPath() {
+    const base = process.env.OPENCLAW_HOME || join(homedir(), ".openclaw");
+    return join(base, "openclaw.json");
+}
+// ---------------------------------------------------------------------------
+// Internal read/write helpers
+// ---------------------------------------------------------------------------
+async function readConfig() {
+    try {
+        const raw = await readFile(getConfigPath(), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {}; // File doesn't exist yet
+    }
+}
+async function persistConfig(config) {
+    const configPath = getConfigPath();
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+/**
+ * Get or create the `channels["agent-network"]` section in config.
+ */
+function ensureMstpSection(config) {
+    if (typeof config.channels !== "object" || config.channels === null) {
+        config.channels = {};
+    }
+    const channels = config.channels;
+    if (typeof channels["agent-network"] !== "object" ||
+        channels["agent-network"] === null) {
+        channels["agent-network"] = {};
+    }
+    return channels["agent-network"];
+}
+/**
+ * Write credentials + apiHost to `openclaw.json`.
+ *
+ * Atomic: credentials and apiHost are written in a single operation
+ * to avoid partial-write race conditions.
+ */
+export async function writeCredentials(creds, apiHost) {
+    const config = await readConfig();
+    const mstp = ensureMstpSection(config);
+    mstp.enabled = true;
+    // Write accounts.default
+    if (typeof mstp.accounts !== "object" || mstp.accounts === null) {
+        mstp.accounts = {};
+    }
+    const accounts = mstp.accounts;
+    accounts.default = {
+        connectorUrl: creds.connectorUrl,
+        token: creds.token,
+    };
+    // Write apiHost if provided
+    if (apiHost) {
+        mstp.apiHost = apiHost;
+    }
+    await persistConfig(config);
+}
+/**
+ * Write pending connection target handle.
+ *
+ * Reserved for future use: web-initiated connection flows where a target
+ * handle is pre-set before the plugin starts.
+ */
+export async function writeTargetHandle(handle) {
+    const config = await readConfig();
+    const mstp = ensureMstpSection(config);
+    mstp.pendingTarget = handle;
+    await persistConfig(config);
+}
+/**
+ * Clear pending connection target from config file AND module-level variable.
+ *
+ * This is a deliberate exception to the read/write separation pattern:
+ * we also update `storedPendingTarget` in memory to avoid stale reads
+ * within the same session (since `initToolConfig()` only runs at startup).
+ */
+export async function clearTargetHandle() {
+    const config = await readConfig();
+    const mstp = ensureMstpSection(config);
+    delete mstp.pendingTarget;
+    await persistConfig(config);
+    // Update module-level var — deliberate exception to read/write separation
+    storedPendingTarget = null;
+}
+// ---------------------------------------------------------------------------
+// Test-only reset (prefix _ = internal)
+// ---------------------------------------------------------------------------
+/** @internal Reset module state for test isolation. */
+export function _resetForTesting() {
+    platformConfig = { apiHost: DEFAULT_API_HOST };
+    storedApiKey = null;
+    storedPendingTarget = null;
+    storedConnectorClient = null;
+}

package/dist/connector-client.d.ts

@@ -0,0 +1,65 @@
+import { EventEmitter } from "node:events";
+import { type MessageReceivedEvent, type SessionCreatedEvent, type SessionEndedEvent } from "./types.js";
+type ConnectorClientEvents = {
+    session_created: (event: SessionCreatedEvent) => void;
+    message_received: (event: MessageReceivedEvent) => void;
+    session_ended: (event: SessionEndedEvent) => void;
+    session_error: (sessionId: string, message: string) => void;
+    error: (error: Error) => void;
+    connected: () => void;
+    disconnected: () => void;
+};
+export declare class ConnectorClient extends EventEmitter {
+    private readonly url;
+    private readonly token;
+    private ws;
+    private intentionalClose;
+    private backoffMs;
+    private alreadyConnectedRetries;
+    private reconnectTimer;
+    private registerResolve;
+    private registerReject;
+    private registerTimer;
+    constructor(url: string, token: string);
+    connect(): Promise<void>;
+    disconnect(): void;
+    createSession(target: string, opts?: {
+        secret?: string;
+        metadata?: Record<string, unknown>;
+    }): {
+        requestId: string;
+        sent: boolean;
+    };
+    sendMessage(sessionId: string, content: string, opts?: {
+        contentType?: string;
+        metadata?: Record<string, unknown>;
+    }): boolean;
+    endSession(sessionId: string, reason?: string): boolean;
+    on<K extends keyof ConnectorClientEvents>(event: K, listener: ConnectorClientEvents[K]): this;
+    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once<K extends keyof ConnectorClientEvents>(event: K, listener: ConnectorClientEvents[K]): this;
+    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    off<K extends keyof ConnectorClientEvents>(event: K, listener: ConnectorClientEvents[K]): this;
+    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    emit<K extends keyof ConnectorClientEvents>(event: K, ...args: Parameters<ConnectorClientEvents[K]>): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    private doConnect;
+    private sendRegister;
+    private startRegisterTimeout;
+    private resolveRegister;
+    private rejectRegister;
+    private handleMessage;
+    private handleRegisterAck;
+    private handleSessionCreated;
+    private handleErrorEvent;
+    private handleClose;
+    private handleError;
+    private scheduleReconnect;
+    private calculateBackoff;
+    private nextExponentialBackoff;
+    private clearReconnectTimer;
+    private cleanupConnection;
+    private send;
+}
+export {};
+//# sourceMappingURL=connector-client.d.ts.map

package/dist/connector-client.d.ts.map

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

package/dist/connector-client.js

@@ -0,0 +1,288 @@
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+import { CURRENT_PROTOCOL_VERSION, isErrorEvent, isMessageReceived, isRegisterAck, isSessionCreated, isSessionEnded, REGISTER_ACK_TIMEOUT_MS, } from "./types.js";
+// --- Reconnection constants ---
+const BACKOFF_INITIAL_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+const ALREADY_CONNECTED_RETRY_MS = 2_000;
+const ALREADY_CONNECTED_MAX_RETRIES = 30;
+// --- ConnectorClient ---
+export class ConnectorClient extends EventEmitter {
+    url;
+    token;
+    ws = null;
+    intentionalClose = false;
+    backoffMs = BACKOFF_INITIAL_MS;
+    alreadyConnectedRetries = 0;
+    reconnectTimer = null;
+    registerResolve = null;
+    registerReject = null;
+    registerTimer = null;
+    constructor(url, token) {
+        super();
+        this.url = url;
+        this.token = token;
+    }
+    // --- Public API ---
+    connect() {
+        if (this.ws) {
+            return Promise.reject(new Error("Already connecting or connected"));
+        }
+        this.intentionalClose = false;
+        return this.doConnect();
+    }
+    disconnect() {
+        this.intentionalClose = true;
+        this.clearReconnectTimer();
+        const wsToClose = this.ws;
+        this.cleanupConnection();
+        if (wsToClose &&
+            (wsToClose.readyState === WebSocket.OPEN ||
+                wsToClose.readyState === WebSocket.CONNECTING)) {
+            wsToClose.close(1000, "Client disconnect");
+        }
+    }
+    createSession(target, opts) {
+        const requestId = randomUUID();
+        const event = {
+            event: "CREATE_SESSION",
+            requestId,
+            target,
+            secret: opts?.secret,
+            metadata: opts?.metadata,
+        };
+        const sent = this.send(event);
+        return { requestId, sent };
+    }
+    sendMessage(sessionId, content, opts) {
+        const event = {
+            event: "SEND_MESSAGE",
+            sessionId,
+            content,
+            contentType: opts?.contentType,
+            metadata: opts?.metadata,
+        };
+        return this.send(event);
+    }
+    endSession(sessionId, reason) {
+        const event = {
+            event: "END_SESSION",
+            sessionId,
+            reason,
+        };
+        return this.send(event);
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    // --- Connection lifecycle ---
+    doConnect() {
+        return new Promise((resolve, reject) => {
+            this.registerResolve = resolve;
+            this.registerReject = reject;
+            const ws = new WebSocket(this.url, { handshakeTimeout: 10_000 });
+            this.ws = ws;
+            ws.on("open", () => {
+                this.sendRegister();
+                this.startRegisterTimeout();
+            });
+            ws.on("message", this.handleMessage);
+            ws.on("close", this.handleClose);
+            ws.on("error", this.handleError);
+        });
+    }
+    sendRegister() {
+        const event = {
+            event: "REGISTER",
+            token: this.token,
+            protocolVersion: CURRENT_PROTOCOL_VERSION,
+        };
+        this.send(event);
+    }
+    startRegisterTimeout() {
+        this.registerTimer = setTimeout(() => {
+            this.rejectRegister(new Error("REGISTER_ACK timeout"));
+            this.ws?.close(4000, "Register timeout");
+        }, REGISTER_ACK_TIMEOUT_MS);
+    }
+    resolveRegister() {
+        if (this.registerTimer) {
+            clearTimeout(this.registerTimer);
+            this.registerTimer = null;
+        }
+        if (this.registerResolve) {
+            this.registerResolve();
+            this.registerResolve = null;
+            this.registerReject = null;
+        }
+    }
+    rejectRegister(err) {
+        if (this.registerTimer) {
+            clearTimeout(this.registerTimer);
+            this.registerTimer = null;
+        }
+        if (this.registerReject) {
+            this.registerReject(err);
+            this.registerResolve = null;
+            this.registerReject = null;
+        }
+    }
+    // --- Message handling ---
+    handleMessage = (data) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(data.toString());
+        }
+        catch {
+            this.emit("error", new Error("Received non-JSON message from Connector"));
+            return;
+        }
+        if (isRegisterAck(parsed)) {
+            this.handleRegisterAck(parsed);
+            return;
+        }
+        if (isSessionCreated(parsed)) {
+            this.handleSessionCreated(parsed);
+            return;
+        }
+        if (isMessageReceived(parsed)) {
+            this.emit("message_received", parsed);
+            return;
+        }
+        if (isSessionEnded(parsed)) {
+            this.emit("session_ended", parsed);
+            return;
+        }
+        if (isErrorEvent(parsed)) {
+            this.handleErrorEvent(parsed);
+            return;
+        }
+        // Unknown event type — silently ignore (forward compatibility)
+    };
+    handleRegisterAck(ack) {
+        if (ack.status === "ok") {
+            this.backoffMs = BACKOFF_INITIAL_MS;
+            this.alreadyConnectedRetries = 0;
+            this.resolveRegister();
+            this.emit("connected");
+        }
+        else {
+            const reason = ack.reason ?? "Unknown registration error";
+            // "Unsupported protocol version" — do not reconnect
+            if (reason === "Unsupported protocol version") {
+                this.intentionalClose = true;
+                this.rejectRegister(new Error(reason));
+                this.emit("error", new Error(reason));
+                this.ws?.close(4001, reason);
+                return;
+            }
+            // "Already connected" — track retries for short backoff
+            if (reason === "Already connected") {
+                this.alreadyConnectedRetries++;
+            }
+            this.rejectRegister(new Error(reason));
+            this.ws?.close(4001, reason);
+        }
+    }
+    handleSessionCreated(event) {
+        this.emit("session_created", event);
+    }
+    handleErrorEvent(event) {
+        // (1) Route by sessionId — session-scoped error
+        if (event.sessionId) {
+            this.emit("session_error", event.sessionId, event.message);
+            return;
+        }
+        // (2) Global error (includes requestId-only errors from failed CREATE_SESSION)
+        this.emit("error", new Error(event.message));
+    }
+    // --- Connection close ---
+    handleClose = () => {
+        const wasRegistering = this.registerReject !== null;
+        this.cleanupConnection();
+        if (wasRegistering) {
+            // Connection closed during REGISTER — check for special retry logic
+            // (handled by rejectRegister which was already called if ACK error came first)
+            if (this.registerReject) {
+                this.rejectRegister(new Error("Connection closed during registration"));
+            }
+        }
+        // "disconnected" is emitted on every close, including intermediate closes
+        // during reconnect cycles. This is intentional — channel adapter uses this
+        // to clear stale session state before a fresh REGISTER re-creates sessions.
+        this.emit("disconnected");
+        if (!this.intentionalClose) {
+            this.scheduleReconnect();
+        }
+    };
+    handleError = (err) => {
+        // WebSocket errors are followed by a close event, so just emit
+        this.emit("error", err);
+    };
+    // --- Reconnection ---
+    scheduleReconnect() {
+        this.clearReconnectTimer();
+        const delay = this.calculateBackoff();
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.doConnect().catch(() => {
+                // connect rejection is expected during reconnect — handled by close event
+            });
+        }, delay);
+    }
+    calculateBackoff() {
+        // "Already connected" — short fixed retry with limit
+        if (this.alreadyConnectedRetries > 0) {
+            if (this.alreadyConnectedRetries >= ALREADY_CONNECTED_MAX_RETRIES) {
+                // Exceeded max retries, fall back to normal exponential backoff
+                this.alreadyConnectedRetries = 0;
+                return this.nextExponentialBackoff();
+            }
+            return ALREADY_CONNECTED_RETRY_MS;
+        }
+        return this.nextExponentialBackoff();
+    }
+    nextExponentialBackoff() {
+        const jitter = 1 + Math.random() * 0.3;
+        const delay = Math.min(this.backoffMs * jitter, BACKOFF_MAX_MS);
+        this.backoffMs = Math.min(this.backoffMs * 2, BACKOFF_MAX_MS);
+        return delay;
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    // --- Cleanup ---
+    cleanupConnection() {
+        if (this.ws) {
+            this.ws.off("message", this.handleMessage);
+            this.ws.off("close", this.handleClose);
+            this.ws.off("error", this.handleError);
+            this.ws = null;
+        }
+        if (this.registerTimer) {
+            clearTimeout(this.registerTimer);
+            this.registerTimer = null;
+        }
+    }
+    // --- Helpers ---
+    send(event) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(event));
+            return true;
+        }
+        return false;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/** Unambiguous characters: A-H J-N P-Z 2-9 (excludes I/O/1/0) */
+export declare const SETUP_CODE_CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export declare const SETUP_CODE_LENGTH = 8;
+export declare const SETUP_CODE_TTL_MS: number;
+export declare const AUTHORIZED_TOKEN_TTL_MS: number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AACrE,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAChD,eAAO,MAAM,uBAAuB,QAAiB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,5 @@
+/** Unambiguous characters: A-H J-N P-Z 2-9 (excludes I/O/1/0) */
+export const SETUP_CODE_CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export const SETUP_CODE_LENGTH = 8;
+export const SETUP_CODE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+export const AUTHORIZED_TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AUTHORIZED_TOKEN_TTL_MS, SETUP_CODE_CHARSET, SETUP_CODE_LENGTH, SETUP_CODE_TTL_MS, } from "./constants.js";
+export type { MstpAccount } from "./config-schema.js";
+export type { ErrorEvent, MessageReceivedEvent, RegisterAckEvent, SessionCreatedEvent, SessionEndedEvent, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAIxB,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Main entry point for @masons/agent-network.
+//
+// This file MUST NOT import modules that depend on Node.js-only packages (ws,
+// etc.) because some consumers import from here in Next.js builds that include
+// client bundles.
+//
+// The OpenClaw Plugin entry is in ./plugin.ts (loaded via openclaw.extensions).
+// The ConnectorClient and protocol types are available via dedicated sub-exports.
+// --- Shared constants ---
+export { AUTHORIZED_TOKEN_TTL_MS, SETUP_CODE_CHARSET, SETUP_CODE_LENGTH, SETUP_CODE_TTL_MS, } from "./constants.js";