@axiom-lattice/gateway 2.1.52 → 2.1.54

package/src/channels/lark/__tests__/controller.test.ts

@@ -0,0 +1,270 @@
+import type { ThreadStore } from "@axiom-lattice/protocols";
+import fastify from "fastify";
+import { createLarkEventHandler } from "../controller";
+
+const installationConfig = {
+  installationId: "install-1",
+  tenantId: "tenant-a",
+  assistantId: "assistant-a",
+  appId: "cli_app_1",
+  appSecret: "secret",
+  verificationToken: "token-1",
+  encryptKey: "encrypt-key",
+  mappingMode: "hybrid" as const,
+};
+
+describe("createLarkEventHandler", () => {
+  it("returns the challenge response during URL verification", async () => {
+    const app = fastify();
+    app.post(
+      "/api/channels/lark/installations/:installationId/events",
+      createLarkEventHandler({
+        getInstallationConfig: jest.fn().mockResolvedValue(installationConfig),
+        parseRequestBody: jest.fn().mockReturnValue({
+          type: "url_verification",
+          challenge: "challenge-token",
+          token: "token-1",
+        }),
+        verifyParsedBody: jest.fn().mockReturnValue(true),
+        parseEvent: jest.fn(),
+        claimInboundReceipt: jest.fn(),
+        markInboundReceiptCompleted: jest.fn(),
+        markInboundReceiptFailed: jest.fn(),
+        resolveThread: jest.fn(),
+        runAgentAndCollectText: jest.fn(),
+        sendTextReply: jest.fn(),
+      }),
+    );
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {
+        challenge: "challenge-token",
+        type: "url_verification",
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ challenge: "challenge-token" });
+
+    await app.close();
+  });
+
+  it("handles one direct text message end to end", async () => {
+    const app = fastify();
+    const parseEvent = jest.fn().mockReturnValue({
+      messageId: "om_1",
+      openId: "ou_1",
+      chatId: "oc_1",
+      chatType: "direct",
+      text: "hello",
+    });
+    const claimInboundReceipt = jest
+      .fn()
+      .mockResolvedValue({ accepted: true, status: "processing" });
+    const markInboundReceiptCompleted = jest.fn().mockResolvedValue(undefined);
+    const markInboundReceiptFailed = jest.fn().mockResolvedValue(undefined);
+    const resolveThread = jest.fn().mockResolvedValue({ threadId: "thread-1" });
+    const runAgentAndCollectText = jest.fn().mockResolvedValue("hi there");
+    const sendTextReply = jest.fn().mockResolvedValue(undefined);
+
+    app.post(
+      "/api/channels/lark/installations/:installationId/events",
+      createLarkEventHandler({
+        getInstallationConfig: jest.fn().mockResolvedValue(installationConfig),
+        parseRequestBody: jest.fn().mockImplementation((body) => body),
+        verifyParsedBody: jest.fn().mockReturnValue(true),
+        parseEvent,
+        claimInboundReceipt,
+        markInboundReceiptCompleted,
+        markInboundReceiptFailed,
+        resolveThread,
+        runAgentAndCollectText,
+        sendTextReply,
+      }),
+    );
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {
+        header: { event_type: "im.message.receive_v1" },
+        event: {
+          sender: { sender_id: { open_id: "ou_1" } },
+          message: {
+            message_id: "om_1",
+            chat_id: "oc_1",
+            chat_type: "p2p",
+            message_type: "text",
+            content: '{"text":"hello"}',
+          },
+        },
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(claimInboundReceipt).toHaveBeenCalledWith({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_1",
+      tenantId: "tenant-a",
+    });
+    expect(resolveThread).toHaveBeenCalled();
+    expect(runAgentAndCollectText).toHaveBeenCalledWith({
+      assistantId: "assistant-a",
+      threadId: "thread-1",
+      text: "hello",
+      tenantId: "tenant-a",
+      workspaceId: undefined,
+      projectId: undefined,
+    });
+    expect(sendTextReply).toHaveBeenCalledWith({
+      chatId: "oc_1",
+      text: "hi there",
+      config: installationConfig,
+    });
+    expect(markInboundReceiptCompleted).toHaveBeenCalledWith({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_1",
+      tenantId: "tenant-a",
+      threadId: "thread-1",
+    });
+    expect(markInboundReceiptFailed).not.toHaveBeenCalled();
+
+    await app.close();
+  });
+
+  it("short-circuits when an inbound receipt is already processing", async () => {
+    const app = fastify();
+    const parseEvent = jest.fn().mockReturnValue({
+      messageId: "om_processing",
+      openId: "ou_1",
+      chatId: "oc_1",
+      chatType: "direct",
+      text: "hello",
+    });
+    const claimInboundReceipt = jest
+      .fn()
+      .mockResolvedValue({ accepted: false, status: "processing" });
+    const resolveThread = jest.fn();
+    const runAgentAndCollectText = jest.fn();
+    const sendTextReply = jest.fn();
+
+    app.post(
+      "/api/channels/lark/installations/:installationId/events",
+      createLarkEventHandler({
+        getInstallationConfig: jest.fn().mockResolvedValue(installationConfig),
+        parseRequestBody: jest.fn().mockImplementation((body) => body),
+        verifyParsedBody: jest.fn().mockReturnValue(true),
+        parseEvent,
+        claimInboundReceipt,
+        markInboundReceiptCompleted: jest.fn(),
+        markInboundReceiptFailed: jest.fn(),
+        resolveThread,
+        runAgentAndCollectText,
+        sendTextReply,
+      }),
+    );
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {
+        header: { event_type: "im.message.receive_v1" },
+        event: {
+          sender: { sender_id: { open_id: "ou_1" } },
+          message: {
+            message_id: "om_processing",
+            chat_id: "oc_1",
+            chat_type: "p2p",
+            message_type: "text",
+            content: '{"text":"hello"}',
+          },
+        },
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ success: true, processing: true });
+    expect(resolveThread).not.toHaveBeenCalled();
+    expect(runAgentAndCollectText).not.toHaveBeenCalled();
+    expect(sendTextReply).not.toHaveBeenCalled();
+
+    await app.close();
+  });
+
+  it("rejects requests when verification fails", async () => {
+    const app = fastify();
+
+    app.post(
+      "/api/channels/lark/installations/:installationId/events",
+      createLarkEventHandler({
+        getInstallationConfig: jest.fn().mockResolvedValue(installationConfig),
+        parseRequestBody: jest.fn().mockReturnValue({ header: { token: "bad" } }),
+        verifyParsedBody: jest.fn().mockReturnValue(false),
+        parseEvent: jest.fn(),
+        claimInboundReceipt: jest.fn(),
+        markInboundReceiptCompleted: jest.fn(),
+        markInboundReceiptFailed: jest.fn(),
+        resolveThread: jest.fn(),
+        runAgentAndCollectText: jest.fn(),
+        sendTextReply: jest.fn(),
+      }),
+    );
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {
+        header: { event_type: "im.message.receive_v1" },
+      },
+    });
+
+    expect(response.statusCode).toBe(401);
+    expect(response.json()).toEqual({ success: false, message: "Invalid Lark request" });
+
+    await app.close();
+  });
+
+  it("loads installation-scoped config from the route parameter", async () => {
+    const app = fastify();
+    const getInstallationConfig = jest.fn().mockResolvedValue(installationConfig);
+
+    app.post(
+      "/api/channels/lark/installations/:installationId/events",
+      createLarkEventHandler({
+        getInstallationConfig,
+        parseRequestBody: jest.fn().mockReturnValue({
+          type: "url_verification",
+          challenge: "challenge-token",
+          token: "token-1",
+        }),
+        verifyParsedBody: jest.fn().mockReturnValue(true),
+        parseEvent: jest.fn(),
+        claimInboundReceipt: jest.fn(),
+        markInboundReceiptCompleted: jest.fn(),
+        markInboundReceiptFailed: jest.fn(),
+        resolveThread: jest.fn(),
+        runAgentAndCollectText: jest.fn(),
+        sendTextReply: jest.fn(),
+      }),
+    );
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {
+        type: "url_verification",
+        challenge: "challenge-token",
+        token: "token-1",
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(getInstallationConfig).toHaveBeenCalledWith("install-1");
+
+    await app.close();
+  });
+});

package/src/channels/lark/__tests__/mapping-service.test.ts

@@ -0,0 +1,118 @@
+import type { ThreadStore } from "@axiom-lattice/protocols";
+import { createChannelThreadMappingService } from "../mapping-service";
+
+describe("createChannelThreadMappingService", () => {
+  it("uses a user subject key for direct chats in hybrid mode", async () => {
+    const mappingStore = {
+      getMappingBySubject: jest.fn().mockResolvedValue(null),
+      createMapping: jest.fn().mockResolvedValue({ threadId: "thread-1" }),
+    };
+
+    const threadStore: Pick<ThreadStore, "createThread"> = {
+      createThread: jest.fn().mockResolvedValue({ id: "thread-1" }),
+    };
+
+    const service = createChannelThreadMappingService({
+      mappingStore,
+      threadStore,
+      uuid: () => "thread-1",
+    });
+
+    const result = await service.getOrCreateThread({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+      openId: "ou_1",
+      chatId: "oc_1",
+      chatType: "direct",
+      messageId: "om_1",
+    });
+
+    expect(mappingStore.getMappingBySubject).toHaveBeenCalledWith(
+      expect.objectContaining({
+        externalSubjectKey:
+          "lark:cli_app_1:tenant:tenant-a:assistant:assistant-a:user:ou_1",
+      }),
+    );
+    expect(result.threadId).toBe("thread-1");
+  });
+
+  it("reuses an existing mapping when one already exists", async () => {
+    const mappingStore = {
+      getMappingBySubject: jest.fn().mockResolvedValue({ threadId: "thread-existing" }),
+      createMapping: jest.fn(),
+    };
+
+    const threadStore: Pick<ThreadStore, "createThread"> = {
+      createThread: jest.fn(),
+    };
+
+    const service = createChannelThreadMappingService({
+      mappingStore,
+      threadStore,
+      uuid: () => "thread-new",
+    });
+
+    const result = await service.getOrCreateThread({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "group",
+      openId: "ou_1",
+      chatId: "oc_group_1",
+      chatType: "group",
+      messageId: "om_2",
+    });
+
+    expect(result.threadId).toBe("thread-existing");
+    expect(threadStore.createThread).not.toHaveBeenCalled();
+    expect(mappingStore.createMapping).not.toHaveBeenCalled();
+  });
+
+  it("re-reads the canonical mapping when createMapping hits a unique conflict", async () => {
+    const mappingStore = {
+      getMappingBySubject: jest
+        .fn()
+        .mockResolvedValueOnce(null)
+        .mockResolvedValueOnce({ threadId: "thread-canonical" }),
+      createMapping: jest.fn().mockRejectedValue(
+        Object.assign(new Error("duplicate key value violates unique constraint"), {
+          code: "23505",
+        }),
+      ),
+    };
+
+    const threadStore: Pick<ThreadStore, "createThread" | "deleteThread"> = {
+      createThread: jest.fn().mockResolvedValue({ id: "thread-new" }),
+      deleteThread: jest.fn().mockResolvedValue(true),
+    };
+
+    const service = createChannelThreadMappingService({
+      mappingStore,
+      threadStore,
+      uuid: () => "thread-new",
+    });
+
+    const result = await service.getOrCreateThread({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+      openId: "ou_1",
+      chatId: "oc_1",
+      chatType: "direct",
+      messageId: "om_1",
+    });
+
+    expect(result.threadId).toBe("thread-canonical");
+    expect(mappingStore.getMappingBySubject).toHaveBeenCalledTimes(2);
+    expect(threadStore.deleteThread).toHaveBeenCalledWith(
+      "tenant-a",
+      "thread-new",
+    );
+  });
+});

package/src/channels/lark/__tests__/parser.test.ts

@@ -0,0 +1,72 @@
+import { parseLarkMessageEvent } from "../parser";
+
+describe("parseLarkMessageEvent", () => {
+  it("parses a direct text message event", () => {
+    const parsed = parseLarkMessageEvent({
+      header: { event_type: "im.message.receive_v1" },
+      event: {
+        sender: { sender_id: { open_id: "ou_user_1" } },
+        message: {
+          message_id: "om_1",
+          chat_id: "oc_chat_1",
+          chat_type: "p2p",
+          message_type: "text",
+          content: '{"text":"hello"}',
+        },
+      },
+    });
+
+    expect(parsed).toEqual({
+      messageId: "om_1",
+      openId: "ou_user_1",
+      chatId: "oc_chat_1",
+      chatType: "direct",
+      text: "hello",
+    });
+  });
+
+  it("parses a group text message event", () => {
+    const parsed = parseLarkMessageEvent({
+      header: { event_type: "im.message.receive_v1" },
+      event: {
+        sender: { sender_id: { open_id: "ou_user_2" } },
+        message: {
+          message_id: "om_2",
+          chat_id: "oc_group_1",
+          chat_type: "group",
+          message_type: "text",
+          content: '{"text":"team update"}',
+        },
+      },
+    });
+
+    expect(parsed.chatType).toBe("group");
+    expect(parsed.text).toBe("team update");
+  });
+
+  it("returns null for unsupported event types", () => {
+    const parsed = parseLarkMessageEvent({
+      header: { event_type: "im.message.read_v1" },
+    });
+
+    expect(parsed).toBeNull();
+  });
+
+  it("returns null for non-text messages", () => {
+    const parsed = parseLarkMessageEvent({
+      header: { event_type: "im.message.receive_v1" },
+      event: {
+        sender: { sender_id: { open_id: "ou_user_3" } },
+        message: {
+          message_id: "om_3",
+          chat_id: "oc_chat_3",
+          chat_type: "p2p",
+          message_type: "image",
+          content: '{"image_key":"img_1"}',
+        },
+      },
+    });
+
+    expect(parsed).toBeNull();
+  });
+});

package/src/channels/lark/__tests__/sender.test.ts

@@ -0,0 +1,37 @@
+import { createLarkSender } from "../sender";
+
+describe("createLarkSender", () => {
+  it("sends a text reply through the lark sdk client", async () => {
+    const createMock = jest.fn().mockResolvedValue({ code: 0 });
+    const sdkClient = {
+      im: {
+        v1: {
+          message: {
+            create: createMock,
+          },
+        },
+      },
+    };
+
+    const sender = createLarkSender(
+      {
+        appId: "cli_app_1",
+        appSecret: "secret",
+      },
+      sdkClient as never,
+    );
+
+    await sender.sendTextReply({ chatId: "oc_1", text: "hello" });
+
+    expect(createMock).toHaveBeenCalledWith({
+      params: {
+        receive_id_type: "chat_id",
+      },
+      data: {
+        receive_id: "oc_1",
+        msg_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    });
+  });
+});

package/src/channels/lark/__tests__/verification.test.ts

@@ -0,0 +1,157 @@
+import type { FastifyRequest } from "fastify";
+import crypto from "crypto";
+import {
+  createLarkRequestVerifier,
+  decryptLarkPayload,
+  parseLarkRequestBody,
+} from "../verification";
+
+describe("createLarkRequestVerifier", () => {
+  it("accepts requests with the configured verification token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: { token: "token-1" },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("rejects requests with the wrong verification token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: { token: "token-2" },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(false);
+  });
+
+  it("accepts requests carrying lark signature headers", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {
+        "x-lark-request-timestamp": "1712730010",
+        "x-lark-signature": "signature",
+      },
+      body: {},
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("accepts v2 payloads that carry the token in header.token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: {
+        schema: "2.0",
+        header: {
+          token: "token-1",
+        },
+      },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("decrypts an encrypted lark payload", () => {
+    const encryptKey = "encrypt-key-1";
+    const payload = JSON.stringify({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+    const encrypted = encryptForTest(encryptKey, payload);
+
+    expect(decryptLarkPayload(encryptKey, encrypted)).toEqual({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+  });
+
+  it("parses encrypted payloads before token verification", () => {
+    const encryptKey = "encrypt-key-1";
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      encryptKey,
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const encrypted = encryptForTest(
+      encryptKey,
+      JSON.stringify({
+        type: "url_verification",
+        challenge: "challenge-1",
+        token: "token-1",
+      }),
+    );
+
+    const request = {
+      headers: {},
+      body: {
+        encrypt: encrypted,
+      },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+    expect(parseLarkRequestBody(request.body, encryptKey)).toEqual({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+  });
+});
+
+function encryptForTest(encryptKey: string, plaintext: string): string {
+  const key = crypto.createHash("sha256").update(encryptKey).digest();
+  const iv = Buffer.alloc(16, 1);
+  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(Buffer.from(plaintext, "utf8")),
+    cipher.final(),
+  ]);
+
+  return Buffer.concat([iv, ciphertext]).toString("base64");
+}

package/src/channels/lark/aggregator.ts

@@ -0,0 +1,16 @@
+import type { MessageChunk } from "@axiom-lattice/protocols";
+import { MessageChunkTypes } from "@axiom-lattice/protocols";
+
+export function aggregateLarkReply(
+  messageId: string,
+  chunks: MessageChunk[],
+): string {
+  return chunks
+    .filter(
+      (chunk) =>
+        chunk.type === MessageChunkTypes.AI && chunk.data.id === messageId,
+    )
+    .map((chunk) => chunk.data.content || "")
+    .join("")
+    .trim();
+}