@kodelyth/tlon 2026.5.39 → 2026.5.42

package/src/urbit/send.ts

@@ -0,0 +1,228 @@
+import { scot, da } from "@urbit/aura";
+import {
+  createMessageReceiptFromOutboundResults,
+  type MessageReceiptPartKind,
+} from "klaw/plugin-sdk/channel-message";
+import { markdownToStory, createImageBlock, isImageUrl, type Story } from "./story.js";
+
+export type TlonPokeApi = {
+  poke: (params: { app: string; mark: string; json: unknown }) => Promise<unknown>;
+};
+
+type SendTextParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  toShip: string;
+  text: string;
+};
+
+type SendStoryParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  toShip: string;
+  story: Story;
+  kind?: MessageReceiptPartKind;
+};
+
+function createTlonSendReceipt(params: {
+  messageId: string;
+  conversationId: string;
+  kind: MessageReceiptPartKind;
+}) {
+  return createMessageReceiptFromOutboundResults({
+    results: [
+      {
+        channel: "tlon",
+        messageId: params.messageId,
+        conversationId: params.conversationId,
+      },
+    ],
+    threadId: params.conversationId,
+    kind: params.kind,
+  });
+}
+
+export async function sendDm({ api, fromShip, toShip, text }: SendTextParams) {
+  const story: Story = markdownToStory(text);
+  return sendDmWithStory({ api, fromShip, toShip, story, kind: "text" });
+}
+
+export async function sendDmWithStory({
+  api,
+  fromShip,
+  toShip,
+  story,
+  kind = "unknown",
+}: SendStoryParams) {
+  const sentAt = Date.now();
+  const idUd = scot("ud", da.fromUnix(sentAt));
+  const id = `${fromShip}/${idUd}`;
+
+  const delta = {
+    add: {
+      memo: {
+        content: story,
+        author: fromShip,
+        sent: sentAt,
+      },
+      kind: null,
+      time: null,
+    },
+  };
+
+  const action = {
+    ship: toShip,
+    diff: { id, delta },
+  };
+
+  await api.poke({
+    app: "chat",
+    mark: "chat-dm-action",
+    json: action,
+  });
+
+  return {
+    channel: "tlon",
+    messageId: id,
+    receipt: createTlonSendReceipt({ messageId: id, conversationId: toShip, kind }),
+  };
+}
+
+type SendGroupParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  hostShip: string;
+  channelName: string;
+  text: string;
+  replyToId?: string | null;
+};
+
+type SendGroupStoryParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  hostShip: string;
+  channelName: string;
+  story: Story;
+  replyToId?: string | null;
+  kind?: MessageReceiptPartKind;
+};
+
+export async function sendGroupMessage({
+  api,
+  fromShip,
+  hostShip,
+  channelName,
+  text,
+  replyToId,
+}: SendGroupParams) {
+  const story: Story = markdownToStory(text);
+  return sendGroupMessageWithStory({
+    api,
+    fromShip,
+    hostShip,
+    channelName,
+    story,
+    replyToId,
+    kind: "text",
+  });
+}
+
+export async function sendGroupMessageWithStory({
+  api,
+  fromShip,
+  hostShip,
+  channelName,
+  story,
+  replyToId,
+  kind = "unknown",
+}: SendGroupStoryParams) {
+  const sentAt = Date.now();
+
+  // Format reply ID as @ud (with dots) - required for Tlon to recognize thread replies
+  let formattedReplyId = replyToId;
+  if (replyToId && /^\d+$/.test(replyToId)) {
+    try {
+      // scot('ud', n) formats a number as @ud with dots
+      formattedReplyId = scot("ud", BigInt(replyToId));
+    } catch {
+      // Fall back to raw ID if formatting fails
+    }
+  }
+
+  const action = {
+    channel: {
+      nest: `chat/${hostShip}/${channelName}`,
+      action: formattedReplyId
+        ? {
+            // Thread reply - needs post wrapper around reply action
+            // ReplyActionAdd takes Memo: {content, author, sent} - no kind/blob/meta
+            post: {
+              reply: {
+                id: formattedReplyId,
+                action: {
+                  add: {
+                    content: story,
+                    author: fromShip,
+                    sent: sentAt,
+                  },
+                },
+              },
+            },
+          }
+        : {
+            // Regular post
+            post: {
+              add: {
+                content: story,
+                author: fromShip,
+                sent: sentAt,
+                kind: "/chat",
+                blob: null,
+                meta: null,
+              },
+            },
+          },
+    },
+  };
+
+  await api.poke({
+    app: "channels",
+    mark: "channel-action-1",
+    json: action,
+  });
+
+  const messageId = `${fromShip}/${sentAt}`;
+  return {
+    channel: "tlon",
+    messageId,
+    receipt: createTlonSendReceipt({
+      messageId,
+      conversationId: `${hostShip}/${channelName}`,
+      kind,
+    }),
+  };
+}
+
+/**
+ * Build a story with text and optional media (image)
+ */
+export function buildMediaStory(text: string | undefined, mediaUrl: string | undefined): Story {
+  const story: Story = [];
+  const cleanText = text?.trim() ?? "";
+  const cleanUrl = mediaUrl?.trim() ?? "";
+
+  // Add text content if present
+  if (cleanText) {
+    story.push(...markdownToStory(cleanText));
+  }
+
+  // Add image block if URL looks like an image
+  if (cleanUrl && isImageUrl(cleanUrl)) {
+    story.push(createImageBlock(cleanUrl, ""));
+  } else if (cleanUrl) {
+    // For non-image URLs, add as a link
+    story.push({ inline: [{ link: { href: cleanUrl, content: cleanUrl } }] });
+  }
+
+  return story.length > 0 ? story : [{ inline: [""] }];
+}

package/src/urbit/sse-client.test.ts

@@ -0,0 +1,234 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { urbitFetch } from "./fetch.js";
+import { UrbitSSEClient } from "./sse-client.js";
+
+// Mock urbitFetch to avoid real network calls
+vi.mock("./fetch.js", () => ({
+  urbitFetch: vi.fn(),
+}));
+
+// Mock channel-ops to avoid real channel operations
+vi.mock("./channel-ops.js", () => ({
+  ensureUrbitChannelOpen: vi.fn().mockResolvedValue(undefined),
+  pokeUrbitChannel: vi.fn().mockResolvedValue(undefined),
+  scryUrbitPath: vi.fn().mockResolvedValue({}),
+}));
+
+function requireFirstMockCall(calls: readonly unknown[][], label: string): unknown[] {
+  const call = calls.at(0);
+  if (!call) {
+    throw new Error(`Expected ${label} call`);
+  }
+  return call;
+}
+
+describe("UrbitSSEClient", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("subscribe", () => {
+    it("sends subscriptions added after connect", async () => {
+      const mockUrbitFetch = vi.mocked(urbitFetch);
+      mockUrbitFetch.mockResolvedValue({
+        response: { ok: true, status: 200 } as unknown as Response,
+        finalUrl: "https://example.com",
+        release: vi.fn().mockResolvedValue(undefined),
+      });
+
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+      // Simulate connected state
+      (client as { isConnected: boolean }).isConnected = true;
+
+      await client.subscribe({
+        app: "chat",
+        path: "/dm/~zod",
+        event: () => {},
+      });
+
+      expect(mockUrbitFetch).toHaveBeenCalledTimes(1);
+      const callArgs = requireFirstMockCall(mockUrbitFetch.mock.calls, "urbit fetch")[0] as
+        | Parameters<typeof urbitFetch>[0]
+        | undefined;
+      if (!callArgs) {
+        throw new Error("Expected urbit fetch arguments");
+      }
+      expect(callArgs.path).toContain("/~/channel/");
+      expect(callArgs.init?.method).toBe("PUT");
+
+      const body = JSON.parse(callArgs.init?.body as string);
+      expect(body).toHaveLength(1);
+      expect(body[0]).toEqual({
+        id: 1,
+        action: "subscribe",
+        ship: "example",
+        app: "chat",
+        path: "/dm/~zod",
+      });
+    });
+
+    it("queues subscriptions before connect", async () => {
+      const mockUrbitFetch = vi.mocked(urbitFetch);
+
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+      // Not connected yet
+
+      await client.subscribe({
+        app: "chat",
+        path: "/dm/~zod",
+        event: () => {},
+      });
+
+      // Should not call urbitFetch since not connected
+      expect(mockUrbitFetch).not.toHaveBeenCalled();
+      // But subscription should be queued
+      expect(client.subscriptions).toHaveLength(1);
+      expect(client.subscriptions[0]).toEqual({
+        id: 1,
+        action: "subscribe",
+        ship: "example",
+        app: "chat",
+        path: "/dm/~zod",
+      });
+    });
+  });
+
+  describe("updateCookie", () => {
+    it("normalizes cookie when updating", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+
+      // Cookie with extra parts that should be stripped
+      client.updateCookie("urbauth-~zod=456; Path=/; HttpOnly");
+
+      expect(client.cookie).toBe("urbauth-~zod=456");
+    });
+
+    it("handles simple cookie values", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+
+      client.updateCookie("urbauth-~zod=newvalue");
+
+      expect(client.cookie).toBe("urbauth-~zod=newvalue");
+    });
+  });
+
+  describe("reconnection", () => {
+    it("has autoReconnect enabled by default", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+      expect(client.autoReconnect).toBe(true);
+    });
+
+    it("can disable autoReconnect via options", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+        autoReconnect: false,
+      });
+      expect(client.autoReconnect).toBe(false);
+    });
+
+    it("stores onReconnect callback", () => {
+      const onReconnect = vi.fn();
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+        onReconnect,
+      });
+      expect(client.onReconnect).toBe(onReconnect);
+    });
+
+    it("resets reconnect attempts on successful connect", async () => {
+      const mockUrbitFetch = vi.mocked(urbitFetch);
+
+      // Mock a response that returns a readable stream
+      const mockStream = new ReadableStream({
+        start(controller) {
+          controller.close();
+        },
+      });
+
+      mockUrbitFetch.mockResolvedValue({
+        response: {
+          ok: true,
+          status: 200,
+          body: mockStream,
+        } as unknown as Response,
+        finalUrl: "https://example.com",
+        release: vi.fn().mockResolvedValue(undefined),
+      });
+
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+        autoReconnect: false, // Disable to prevent reconnect loop
+      });
+      client.reconnectAttempts = 5;
+
+      await client.connect();
+
+      expect(client.reconnectAttempts).toBe(0);
+    });
+  });
+
+  describe("event acking", () => {
+    it("logs malformed SSE JSON with an owned parser error", () => {
+      const logger = { error: vi.fn() };
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+        logger,
+      });
+
+      client.processEvent("id: 1\ndata: {not json");
+
+      expect(logger.error).toHaveBeenCalledWith(
+        "Error parsing SSE event: Error: Tlon Urbit SSE event was malformed JSON",
+      );
+    });
+
+    it("tracks lastHeardEventId and ackThreshold", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+
+      // Access private properties for testing
+      const lastHeardEventId = (client as unknown as { lastHeardEventId: number }).lastHeardEventId;
+      const ackThreshold = (client as unknown as { ackThreshold: number }).ackThreshold;
+
+      expect(lastHeardEventId).toBe(-1);
+      expect(ackThreshold).toBeGreaterThan(0);
+    });
+  });
+
+  describe("constructor", () => {
+    it("generates unique channel ID", () => {
+      const client1 = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+      const client2 = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+
+      expect(client1.channelId).not.toBe(client2.channelId);
+    });
+
+    it("normalizes cookie in constructor", () => {
+      const client = new UrbitSSEClient(
+        "https://example.com",
+        "urbauth-~zod=123; Path=/; HttpOnly",
+      );
+
+      expect(client.cookie).toBe("urbauth-~zod=123");
+    });
+
+    it("sets default reconnection parameters", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123");
+
+      expect(client.maxReconnectAttempts).toBe(10);
+      expect(client.reconnectDelay).toBe(1000);
+      expect(client.maxReconnectDelay).toBe(30000);
+    });
+
+    it("allows overriding reconnection parameters", () => {
+      const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+        maxReconnectAttempts: 5,
+        reconnectDelay: 500,
+        maxReconnectDelay: 10000,
+      });
+
+      expect(client.maxReconnectAttempts).toBe(5);
+      expect(client.reconnectDelay).toBe(500);
+      expect(client.maxReconnectDelay).toBe(10000);
+    });
+  });
+});