@vex-chat/libvex 1.0.2 → 2.0.0

package/src/__tests__/harness/platform-transports.ts

@@ -0,0 +1,17 @@
+/**
+ * Test logger for integration tests.
+ */
+import type { Logger } from "../../transport/types.js";
+
+export const testLogger: Logger = {
+    debug(_m: string) {},
+    error(m: string) {
+        console.error(`[test] ${m}`);
+    },
+    info(m: string) {
+        console.log(`[test] ${m}`);
+    },
+    warn(m: string) {
+        console.warn(`[test] ${m}`);
+    },
+};

package/src/__tests__/harness/poison-node-imports.ts

@@ -0,0 +1,108 @@
+import type { Plugin } from "vite";
+
+/**
+ * Vite plugin that catches Node builtin imports AND Node-only globals
+ * in library source (src/) during transformation.
+ *
+ * Vitest runs in Node where builtins resolve natively and globals like
+ * Buffer/process exist — so tests pass even when the code would crash
+ * in a browser or Tauri webview. This plugin catches those at transform
+ * time, which vitest does invoke.
+ *
+ * Uses Node's own builtinModules list — no manual maintenance needed.
+ */
+import { builtinModules } from "node:module";
+
+const nodeBuiltins = new Set([
+    ...builtinModules,
+    ...builtinModules.map((m) => `node:${m}`),
+]);
+
+// Node-only globals that don't exist in browsers/Tauri/RN.
+// \bBuffer\b won't match ArrayBuffer or SharedArrayBuffer (no word boundary).
+const NODE_GLOBALS = ["Buffer", "process", "__dirname", "__filename"];
+
+// Matches: import ... from "events"  or  import ... from 'node:os'
+// Also: export ... from "events"
+const IMPORT_RE = /(?:import|export)\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
+// Matches: await import("events")
+const DYNAMIC_IMPORT_RE = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+type Violation = { kind: "global" | "import"; line: number; name: string };
+
+export function poisonNodeImports(): Plugin {
+    return {
+        enforce: "pre",
+        name: "poison-node-imports",
+        transform(code: string, id: string) {
+            // Only check library source — not tests or dependencies
+            if (!id.includes("/src/")) return null;
+            if (id.includes("__tests__")) return null;
+            if (id.includes("node_modules")) return null;
+            if (isNodeOnlyFile(id)) return null;
+
+            const violations = findViolations(code);
+            if (violations.length === 0) return null;
+
+            const file = id.replace(/^.*\/src\//, "src/");
+            const msgs = violations
+                .map((v) => `  line ${String(v.line)}: ${v.name} (${v.kind})`)
+                .join("\n");
+            throw new Error(
+                `[platform-guard] Node-only code in ${file}:\n${msgs}\n` +
+                    `These would crash in browser/RN/Tauri. Use browser-safe alternatives or dynamic imports.`,
+            );
+        },
+    };
+}
+
+function findViolations(code: string): Violation[] {
+    const results: Violation[] = [];
+    const lines = code.split("\n");
+    const strippedLines = stripComments(code).split("\n");
+
+    // Check imports against the original code (comments don't affect import syntax)
+    for (let i = 0; i < lines.length; i++) {
+        const lineText = lines[i];
+        for (const re of [IMPORT_RE, DYNAMIC_IMPORT_RE]) {
+            re.lastIndex = 0;
+            let match;
+            while ((match = re.exec(lineText ?? "")) !== null) {
+                const mod = match[1]?.replace(/\.js$/, "").replace(/\.ts$/, "");
+                if (mod !== undefined && nodeBuiltins.has(mod)) {
+                    results.push({
+                        kind: "import",
+                        line: i + 1,
+                        name: match[1] ?? "",
+                    });
+                }
+            }
+        }
+    }
+
+    // Check globals against comment-stripped code
+    for (let i = 0; i < strippedLines.length; i++) {
+        const lineText = strippedLines[i] ?? "";
+        for (const g of NODE_GLOBALS) {
+            const re = new RegExp(`\\b${g}\\b`);
+            if (re.test(lineText)) {
+                results.push({ kind: "global", line: i + 1, name: g });
+            }
+        }
+    }
+
+    return results;
+}
+
+function isNodeOnlyFile(id: string): boolean {
+    // These files are only loaded via dynamic import on the Node path.
+    if (id.includes("/storage/node")) return true;
+    if (id.includes("/utils/createLogger")) return true;
+    return false;
+}
+
+/** Strip comments to avoid false positives on globals in JSDoc / inline comments. */
+function stripComments(code: string): string {
+    // Remove single-line comments, but not URLs (://), and multi-line comments
+    return code.replace(/\/\/(?!:).*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+}

package/src/__tests__/harness/shared-suite.ts

@@ -0,0 +1,446 @@
+/**
+ * Shared integration test body. Called by each platform entry file
+ * with a different adapter factory.
+ *
+ * Runs register → login → connect → send/receive DM against a real spire.
+ */
+
+import type { ClientOptions, Message } from "../../index.js";
+import type { Storage } from "../../Storage.js";
+import type { Logger } from "../../transport/types.js";
+
+import { Client } from "../../index.js";
+
+import { testFile, testImage } from "./fixtures.js";
+
+export function platformSuite(
+    platformName: string,
+    logger: Logger,
+    makeStorage: (SK: string, opts: ClientOptions) => Promise<Storage>,
+) {
+    describe.sequential(`platform: ${platformName}`, () => {
+        let client: Client;
+        const username = Client.randomUsername();
+        const password = "platform-test-pw";
+
+        beforeAll(async () => {
+            const SK = Client.generateSecretKey();
+            const opts: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage = await makeStorage(SK, opts);
+            client = await Client.create(SK, opts, storage);
+        });
+
+        afterAll(async () => {
+            try {
+                await client.close();
+            } catch {}
+        });
+
+        test("register", async () => {
+            const [user, err] = await client.register(username, password);
+            expect(err).toBeNull();
+            expect(user!.username).toBe(username);
+        });
+
+        test("login", async () => {
+            const result = await client.login(username, password);
+            expect(result.ok).toBe(true);
+        });
+
+        test("connect (websocket auth)", async () => {
+            await connectAndWait(client, `[${platformName}] WS auth`);
+            expect(true).toBe(true);
+        });
+
+        test("send and receive DM (self)", async () => {
+            const me = client.me.user();
+            const msgPromise = waitForMessage(
+                client,
+                (m) => m.direction === "incoming" && m.decrypted,
+                `[${platformName}] self-DM`,
+            );
+            void client.messages.send(me.userID, "platform-test");
+            const msg = await msgPromise;
+            expect(msg.message).toBe("platform-test");
+        });
+
+        test("two-user DM", async () => {
+            const SK2 = Client.generateSecretKey();
+            const opts2: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage2 = await makeStorage(SK2, opts2);
+            const client2 = await Client.create(SK2, opts2, storage2);
+            const username2 = Client.randomUsername();
+
+            try {
+                const [user2, regErr] = await client2.register(
+                    username2,
+                    "test-pw-2",
+                );
+                expect(regErr).toBeNull();
+
+                const loginErr = await client2.login(username2, "test-pw-2");
+                expect(loginErr.ok).toBe(true);
+
+                await connectAndWait(client2, "client2");
+
+                // client sends to client2, client2 receives
+                const msgPromise = waitForMessage(
+                    client2,
+                    (m) => m.direction === "incoming" && m.decrypted,
+                    `[${platformName}] two-user DM`,
+                    15_000,
+                );
+                void client.messages.send(user2!.userID, "hello from user 1");
+                const msg = await msgPromise;
+                expect(msg.message).toBe("hello from user 1");
+            } finally {
+                await client2.close().catch(() => {});
+            }
+        });
+
+        test("group messaging in channel", async () => {
+            const SK2 = Client.generateSecretKey();
+            const opts2: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage2 = await makeStorage(SK2, opts2);
+            const client2 = await Client.create(SK2, opts2, storage2);
+            const username2 = Client.randomUsername();
+
+            try {
+                // Register + login + connect user2
+                await client2.register(username2, "test-pw-2");
+                await client2.login(username2, "test-pw-2");
+                await connectAndWait(client2, "client2");
+
+                // user1 creates server + channel
+                const server = await client.servers.create("test-server");
+                expect(server).toBeTruthy();
+                const channels = await client.channels.retrieve(
+                    server.serverID,
+                );
+                expect(channels.length).toBeGreaterThan(0);
+                const channel = channels[0];
+                if (!channel) throw new Error("No channel found");
+
+                // user1 creates invite, user2 redeems it
+                const invite = await client.invites.create(
+                    server.serverID,
+                    "1h",
+                );
+                expect(invite).toBeTruthy();
+                await client2.invites.redeem(invite.inviteID);
+
+                // user1 sends group message, user2 receives it
+                const msgPromise = waitForMessage(
+                    client2,
+                    (m) =>
+                        m.direction === "incoming" &&
+                        m.decrypted &&
+                        m.group === channel.channelID,
+                    "group message receive",
+                    15_000,
+                );
+                void client.messages.group(channel.channelID, "hello channel");
+                const msg = await msgPromise;
+                expect(msg.message).toBe("hello channel");
+
+                // Cleanup
+                await client.servers.delete(server.serverID);
+            } finally {
+                await client2.close().catch(() => {});
+            }
+        });
+
+        test("loginWithDeviceKey (auto-login)", async () => {
+            // Simulate app restart: create a new Client with the same
+            // device key, authenticate without password.
+            const deviceKey = client.getKeys().private;
+            const deviceID = client.me.device().deviceID;
+            const opts2: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage2 = await makeStorage(deviceKey, opts2);
+            const client2 = await Client.create(deviceKey, opts2, storage2);
+
+            try {
+                const authErr = await client2.loginWithDeviceKey(deviceID);
+                expect(authErr).toBeNull();
+
+                await connectAndWait(client2, "device-key");
+
+                // Same user, same identity
+                expect(client2.me.user().userID).toBe(client.me.user().userID);
+                expect(client2.me.user().username).toBe(username);
+            } finally {
+                await client2.close().catch(() => {});
+            }
+        });
+
+        test("server CRUD", async () => {
+            const permissions = await client.permissions.retrieve();
+            expect(permissions).toEqual([]);
+
+            const server = await client.servers.create("Test Server");
+            const serverList = await client.servers.retrieve();
+            expect(serverList.some((s) => s.serverID === server.serverID)).toBe(
+                true,
+            );
+
+            const byID = await client.servers.retrieveByID(server.serverID);
+            expect(byID?.serverID).toBe(server.serverID);
+
+            await client.servers.delete(server.serverID);
+            const afterDelete = await client.servers.retrieve();
+            expect(
+                afterDelete.some((s) => s.serverID === server.serverID),
+            ).toBe(false);
+        });
+
+        test("channel CRUD", async () => {
+            const server = await client.servers.create("Channel Test Server");
+            const channel = await client.channels.create(
+                "Test Channel",
+                server.serverID,
+            );
+
+            const byID = await client.channels.retrieveByID(channel.channelID);
+            expect(byID?.channelID).toBe(channel.channelID);
+
+            await client.channels.delete(channel.channelID);
+            const channels = await client.channels.retrieve(server.serverID);
+            expect(
+                channels.some((c) => c.channelID === channel.channelID),
+            ).toBe(false);
+            // Default channel still exists
+            expect(channels.length).toBe(1);
+
+            await client.servers.delete(server.serverID);
+        });
+
+        test("invite create + redeem", async () => {
+            const server = await client.servers.create("Invite Test Server");
+            const invite = await client.invites.create(server.serverID, "1h");
+            expect(invite).toBeTruthy();
+            expect(invite.serverID).toBe(server.serverID);
+
+            await client.invites.redeem(invite.inviteID);
+            await client.servers.delete(server.serverID);
+        });
+
+        test("message history retrieve + delete", async () => {
+            const me = client.me.user();
+
+            // Send a message and wait for it
+            const msgPromise = waitForMessage(
+                client,
+                (m) => m.direction === "incoming" && m.decrypted,
+                "history DM",
+            );
+            void client.messages.send(me.userID, "history-test");
+            await msgPromise;
+
+            const history = await client.messages.retrieve(me.userID);
+            expect(history.length).toBeGreaterThan(0);
+
+            await client.messages.delete(me.userID);
+            const afterDelete = await client.messages.retrieve(me.userID);
+            expect(afterDelete.length).toBe(0);
+        });
+
+        // TODO: multi-device fan-out requires sender to query fresh device
+        // list before sending. Currently the sender caches one device and
+        // the message only reaches device1.
+        test.todo("multi-device message sync", async () => {
+            const SK2 = Client.generateSecretKey();
+            const opts2: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage2 = await makeStorage(SK2, opts2);
+            const device2 = await Client.create(SK2, opts2, storage2);
+
+            // Sender: separate user
+            const SK3 = Client.generateSecretKey();
+            const opts3: ClientOptions = {
+                dbLogLevel: "error",
+                inMemoryDb: true,
+                logger,
+                logLevel: "error",
+                ...apiUrlOverrideFromEnv(),
+            };
+            const storage3 = await makeStorage(SK3, opts3);
+            const sender = await Client.create(SK3, opts3, storage3);
+            const senderName = Client.randomUsername();
+
+            try {
+                // Register device2 under same account
+                await device2.login(username, password);
+                await connectAndWait(device2, "device2");
+
+                // Register + connect sender
+                await sender.register(senderName, "sender-pw");
+                await sender.login(senderName, "sender-pw");
+                await connectAndWait(sender, "sender");
+
+                const targetUserID = client.me.user().userID;
+
+                // Both devices listen for the incoming DM
+                const received = { device1: false, device2: false };
+
+                const waitForBoth = new Promise<void>((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        reject(
+                            new Error(
+                                `multi-device sync timed out (d1=${String(received.device1)}, d2=${String(received.device2)})`,
+                            ),
+                        );
+                    }, 15_000);
+                    const check = () => {
+                        if (received.device1 && received.device2) {
+                            clearTimeout(timer);
+                            resolve();
+                        }
+                    };
+
+                    client.on("message", (msg: Message) => {
+                        if (
+                            msg.direction === "incoming" &&
+                            msg.decrypted &&
+                            msg.message === "sync-test"
+                        ) {
+                            received.device1 = true;
+                            check();
+                        }
+                    });
+                    device2.on("message", (msg: Message) => {
+                        if (
+                            msg.direction === "incoming" &&
+                            msg.decrypted &&
+                            msg.message === "sync-test"
+                        ) {
+                            received.device2 = true;
+                            check();
+                        }
+                    });
+                });
+
+                void sender.messages.send(targetUserID, "sync-test");
+                await waitForBoth;
+
+                expect(received.device1).toBe(true);
+                expect(received.device2).toBe(true);
+            } finally {
+                await device2.close().catch(() => {});
+                await sender.close().catch(() => {});
+            }
+        });
+
+        test("file upload + download", async () => {
+            const [details, key] = await client.files.create(testFile);
+            expect(details.fileID).toBeTruthy();
+
+            const fetched = await client.files.retrieve(details.fileID, key);
+            expect(fetched).toBeTruthy();
+            expect(new Uint8Array(fetched!.data)).toEqual(testFile);
+        });
+
+        test("emoji upload", async () => {
+            const server = await client.servers.create("Emoji Test Server");
+            const emoji = await client.emoji.create(
+                testImage,
+                "testmoji",
+                server.serverID,
+            );
+            expect(emoji).toBeTruthy();
+
+            const list = await client.emoji.retrieveList(server.serverID);
+            expect(list.some((e) => e.emojiID === emoji!.emojiID)).toBe(true);
+
+            await client.servers.delete(server.serverID);
+        });
+
+        test("avatar upload", async () => {
+            await client.me.setAvatar(testImage);
+            expect(true).toBe(true);
+        });
+    });
+}
+
+function apiUrlOverrideFromEnv():
+    | Pick<ClientOptions, "host" | "unsafeHttp">
+    | undefined {
+    const raw = process.env["API_URL"]?.trim();
+    if (!raw) return undefined;
+    if (/^https?:\/\//i.test(raw)) {
+        const u = new URL(raw);
+        return { host: u.host, unsafeHttp: u.protocol === "http:" };
+    }
+    return { host: raw, unsafeHttp: true };
+}
+
+function connectAndWait(
+    c: Client,
+    label: string,
+    timeout = 10_000,
+): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} connect timed out`));
+        }, timeout);
+        const onConnected = () => {
+            clearTimeout(timer);
+            c.off("connected", onConnected);
+            resolve();
+        };
+        c.on("connected", onConnected);
+        c.connect().catch((err: unknown) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+
+async function waitForMessage(
+    c: Client,
+    predicate: (m: Message) => boolean,
+    label: string,
+    timeout = 10_000,
+): Promise<Message> {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} message timed out`));
+        }, timeout);
+        const onMsg = (msg: Message) => {
+            if (predicate(msg)) {
+                clearTimeout(timer);
+                c.off("message", onMsg);
+                resolve(msg);
+            }
+        };
+        c.on("message", onMsg);
+    });
+}

package/src/__tests__/platform-browser.test.ts

@@ -0,0 +1,19 @@
+import type { ClientOptions } from "../index.js";
+
+import { MemoryStorage } from "./harness/memory-storage.js";
+import { browserTestAdapters } from "./harness/platform-transports.js";
+// Browser platform test — covers Tauri, Expo/RN, and web.
+// Runs with the poison plugin (vitest.config.browser.ts) which catches
+// Node builtins and globals at compile time. Uses MemoryStorage (no
+// Node SQLite) and BrowserTestWS (Uint8Array binary).
+import { platformSuite } from "./harness/shared-suite.js";
+
+platformSuite(
+    "browser",
+    browserTestAdapters,
+    async (SK: string, _opts: ClientOptions) => {
+        const storage = new MemoryStorage(SK);
+        await storage.init();
+        return storage;
+    },
+);

package/src/__tests__/platform-node.test.ts

@@ -0,0 +1,10 @@
+import type { ClientOptions } from "../index.js";
+
+import { createNodeStorage } from "../storage/node.js";
+
+import { testLogger } from "./harness/platform-transports.js";
+import { platformSuite } from "./harness/shared-suite.js";
+
+platformSuite("node", testLogger, (SK: string, _opts: ClientOptions) =>
+    Promise.resolve(createNodeStorage(":memory:", SK)),
+);

package/src/codec.ts

@@ -0,0 +1,68 @@
+/**
+ * Type-safe codec factory for msgpack encode/decode with optional Zod validation.
+ *
+ * Usage:
+ *   import { MailWSSchema } from "@vex-chat/types";
+ *   const MailCodec = createCodec(MailWSSchema);
+ *
+ *   // SDK/Apps (trusted internal) — fast, typed, no Zod overhead:
+ *   const msg = MailCodec.decode(data);
+ *
+ *   // Spire (trust boundary) — validates at runtime:
+ *   const msg = MailCodec.decodeSafe(data);
+ */
+
+import type { z } from "zod/v4";
+
+import { Packr } from "msgpackr";
+
+const _packr = new Packr({ moreTypes: false, useRecords: false });
+
+/**
+ * Creates a type-safe codec for msgpack encode/decode.
+ *
+ * @param schema - A Zod schema to validate against
+ * @returns An object with encode, decode, encodeSafe, and decodeSafe methods
+ */
+export function createCodec<T extends z.ZodType>(schema: T) {
+    type Msg = z.infer<T>;
+    return {
+        /** Decode msgpack data — typed but not validated. Fast path for SDK. */
+        decode: (data: Uint8Array): Msg => schema.parse(decode(data)) as Msg,
+
+        /** Decode + validate with Zod. Safe path for trust boundaries (Spire). */
+        decodeSafe: (data: Uint8Array): Msg =>
+            schema.parse(decode(data)) as Msg,
+
+        /** Encode to msgpack — typed but not validated. */
+        encode: (msg: Msg): Uint8Array => encode(msg),
+
+        /** Validate + encode. Ensures outgoing messages match the schema. */
+        encodeSafe: (msg: Msg): Uint8Array => {
+            schema.parse(msg);
+            return encode(msg);
+        },
+    };
+}
+
+function decode(data: Uint8Array): unknown {
+    return _packr.decode(data) as unknown;
+}
+
+/**
+ * Encode a value to msgpack. Returns a fresh Uint8Array copy
+ * (not a subarray of the internal pool buffer) to avoid browser
+ * XMLHttpRequest.send() corruption (axios issue #4068).
+ */
+function encode(value: unknown): Uint8Array {
+    const packed = _packr.encode(value);
+    return new Uint8Array(
+        packed.buffer.slice(
+            packed.byteOffset,
+            packed.byteOffset + packed.byteLength,
+        ),
+    );
+}
+
+/** Raw msgpack encode/decode without schema validation. */
+export const msgpack = { decode, encode };