@firstperson/firstperson 2026.1.33

package/src/config-schema.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { FirstPersonConfigSchema } from "./config-schema.js";
+
+describe("FirstPersonConfigSchema", () => {
+  it("validates a valid config", () => {
+    const config = {
+      enabled: true,
+      token: "fp_token_123",
+      relayUrl: "wss://chat.firstperson.ai",
+      dmPolicy: "pairing" as const,
+      allowFrom: ["device-1", "device-2"],
+    };
+
+    const result = FirstPersonConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts empty config", () => {
+    const result = FirstPersonConfigSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts partial config", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      token: "fp_token_123",
+      dmPolicy: "allowlist",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects invalid dmPolicy", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      dmPolicy: "invalid_policy",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects invalid relayUrl", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      relayUrl: "not-a-valid-url",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty token", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      token: "",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects unknown keys (strict mode)", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      token: "fp_token_123",
+      unknownField: "should fail",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts allowFrom with numbers", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      allowFrom: [123, "device-1", 456],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts wildcard in allowFrom", () => {
+    const result = FirstPersonConfigSchema.safeParse({
+      allowFrom: ["*"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("validates all dmPolicy options", () => {
+    const policies = ["pairing", "allowlist", "open", "disabled"] as const;
+    for (const policy of policies) {
+      const result = FirstPersonConfigSchema.safeParse({ dmPolicy: policy });
+      expect(result.success).toBe(true);
+    }
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const FirstPersonConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    token: z.string().min(1).optional(),
+    relayUrl: z.string().url().optional(),
+    dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  })
+  .strict();
+
+export type FirstPersonConfigInput = z.infer<typeof FirstPersonConfigSchema>;

package/src/relay-client.test.ts

@@ -0,0 +1,452 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import type { Logger } from "./relay-client.js";
+
+// Mock WebSocket
+const mockWsInstances: MockWebSocket[] = [];
+
+class MockWebSocket {
+  static OPEN = 1;
+  static CLOSED = 3;
+
+  readyState = MockWebSocket.OPEN;
+  url: string;
+  private handlers: Record<string, Function[]> = {};
+
+  constructor(url: string) {
+    this.url = url;
+    mockWsInstances.push(this);
+  }
+
+  on(event: string, handler: Function) {
+    if (!this.handlers[event]) {
+      this.handlers[event] = [];
+    }
+    this.handlers[event].push(handler);
+  }
+
+  send = vi.fn();
+
+  close() {
+    this.readyState = MockWebSocket.CLOSED;
+    this.emit("close", 1000, "");
+  }
+
+  emit(event: string, ...args: unknown[]) {
+    const handlers = this.handlers[event] || [];
+    for (const handler of handlers) {
+      handler(...args);
+    }
+  }
+}
+
+vi.mock("ws", () => ({
+  default: MockWebSocket,
+}));
+
+describe("relay-client", () => {
+  let sendTextMessage: typeof import("./relay-client.js").sendTextMessage;
+  let startRelayConnection: typeof import("./relay-client.js").startRelayConnection;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    mockWsInstances.length = 0;
+
+    const mod = await import("./relay-client.js");
+    sendTextMessage = mod.sendTextMessage;
+    startRelayConnection = mod.startRelayConnection;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("sendTextMessage", () => {
+    it("creates temporary connection when no active connection", async () => {
+      const promise = sendTextMessage({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        to: "device-123",
+        text: "Hello, world!",
+      });
+
+      // Wait for WebSocket to be created
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+
+      // Simulate connection open
+      ws.emit("open");
+
+      // Check message was sent
+      expect(ws.send).toHaveBeenCalledWith(
+        expect.stringContaining('"type":"message"')
+      );
+      expect(ws.send).toHaveBeenCalledWith(
+        expect.stringContaining('"to":"device-123"')
+      );
+      expect(ws.send).toHaveBeenCalledWith(
+        expect.stringContaining('"text":"Hello, world!"')
+      );
+
+      // Simulate acknowledgment
+      ws.emit("message", Buffer.from(JSON.stringify({ type: "message_sent" })));
+
+      const result = await promise;
+      expect(result.chatId).toBe("device-123");
+      expect(result.messageId).toMatch(/^msg_\d+_[a-z0-9]+$/);
+    });
+
+    it("includes replyTo when provided", async () => {
+      const promise = sendTextMessage({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        to: "device-123",
+        text: "Reply text",
+        replyTo: "original-msg-id",
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      expect(ws.send).toHaveBeenCalledWith(
+        expect.stringContaining('"replyTo":"original-msg-id"')
+      );
+
+      ws.emit("message", Buffer.from(JSON.stringify({ type: "ack" })));
+      await promise;
+    });
+
+    it("handles relay error response", async () => {
+      const promise = sendTextMessage({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        to: "device-123",
+        text: "Hello",
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+      ws.emit(
+        "message",
+        Buffer.from(JSON.stringify({ type: "error", error: "Device not found" }))
+      );
+
+      await expect(promise).rejects.toThrow("Device not found");
+    });
+
+    it("handles WebSocket error", async () => {
+      const promise = sendTextMessage({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        to: "device-123",
+        text: "Hello",
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("error", new Error("Connection refused"));
+
+      await expect(promise).rejects.toThrow("Connection refused");
+    });
+
+    it("encodes token in URL", async () => {
+      sendTextMessage({
+        relayUrl: "wss://relay.example.com",
+        token: "token with spaces",
+        to: "device-123",
+        text: "Hello",
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      expect(ws.url).toContain("token=token%20with%20spaces");
+    });
+  });
+
+  describe("startRelayConnection", () => {
+    it("connects and calls onConnected callback", async () => {
+      const onConnected = vi.fn();
+      const onDisconnected = vi.fn();
+      const onMessage = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected,
+        onDisconnected,
+        onMessage,
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      expect(onConnected).toHaveBeenCalledTimes(1);
+    });
+
+    it("handles incoming messages", async () => {
+      const onConnected = vi.fn();
+      const onDisconnected = vi.fn();
+      const onMessage = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected,
+        onDisconnected,
+        onMessage,
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      const incomingMessage = {
+        type: "message",
+        from: "device-456",
+        text: "Hello from device",
+        messageId: "msg-123",
+        timestamp: "2026-01-31T12:00:00Z",
+      };
+
+      ws.emit("message", Buffer.from(JSON.stringify(incomingMessage)));
+
+      await vi.waitFor(() => expect(onMessage).toHaveBeenCalled());
+
+      expect(onMessage).toHaveBeenCalledWith({
+        messageId: "msg-123",
+        deviceId: "device-456",
+        text: "Hello from device",
+        timestamp: "2026-01-31T12:00:00Z",
+      });
+    });
+
+    it("responds to ping with pong", async () => {
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected: vi.fn(),
+        onMessage: vi.fn(),
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+      ws.emit("message", Buffer.from(JSON.stringify({ type: "ping" })));
+
+      expect(ws.send).toHaveBeenCalledWith(JSON.stringify({ type: "pong" }));
+    });
+
+    it("closes connection on abort signal", async () => {
+      const onDisconnected = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected,
+        onMessage: vi.fn(),
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      controller.abort();
+
+      expect(ws.readyState).toBe(MockWebSocket.CLOSED);
+    });
+
+    it("masks token in log messages", async () => {
+      const logger: Logger = {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "secret-token-12345",
+        accountId: "default",
+        abortSignal: controller.signal,
+        log: logger,
+        onConnected: vi.fn(),
+        onDisconnected: vi.fn(),
+        onMessage: vi.fn(),
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      // Check that token is masked in logs
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining("token=***")
+      );
+      expect(logger.info).not.toHaveBeenCalledWith(
+        expect.stringContaining("secret-token-12345")
+      );
+    });
+
+    it("generates message ID when not provided", async () => {
+      const onMessage = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected: vi.fn(),
+        onMessage,
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      // Message without messageId
+      ws.emit(
+        "message",
+        Buffer.from(
+          JSON.stringify({
+            type: "message",
+            from: "device-456",
+            text: "Hello",
+          })
+        )
+      );
+
+      await vi.waitFor(() => expect(onMessage).toHaveBeenCalled());
+
+      const call = onMessage.mock.calls[0][0];
+      expect(call.messageId).toMatch(/^msg_\d+$/);
+    });
+
+    it("ignores messages without required fields", async () => {
+      const onMessage = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected: vi.fn(),
+        onMessage,
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      // Message missing 'text' field
+      ws.emit(
+        "message",
+        Buffer.from(
+          JSON.stringify({
+            type: "message",
+            from: "device-456",
+          })
+        )
+      );
+
+      // Message missing 'from' field
+      ws.emit(
+        "message",
+        Buffer.from(
+          JSON.stringify({
+            type: "message",
+            text: "Hello",
+          })
+        )
+      );
+
+      // Allow time for async processing
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(onMessage).not.toHaveBeenCalled();
+    });
+
+    it("ignores non-JSON messages", async () => {
+      const onMessage = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected: vi.fn(),
+        onMessage,
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      // Invalid JSON
+      ws.emit("message", Buffer.from("not valid json"));
+
+      // Allow time for async processing
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(onMessage).not.toHaveBeenCalled();
+    });
+
+    it("calls onDisconnected on close", async () => {
+      const onDisconnected = vi.fn();
+      const controller = new AbortController();
+
+      startRelayConnection({
+        relayUrl: "wss://relay.example.com",
+        token: "test-token",
+        accountId: "default",
+        abortSignal: controller.signal,
+        onConnected: vi.fn(),
+        onDisconnected,
+        onMessage: vi.fn(),
+      });
+
+      await vi.waitFor(() => expect(mockWsInstances.length).toBe(1));
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+      ws.emit("close", 1000, "Normal closure");
+
+      // After abort signal, onDisconnected is called without error
+      controller.abort();
+
+      await vi.waitFor(() => expect(onDisconnected).toHaveBeenCalled());
+    });
+  });
+});