@axiom-lattice/gateway 2.1.53 → 2.1.55

package/src/channels/lark/README.md

@@ -0,0 +1,187 @@
+# Lark Channel Ingress
+
+This module adds Feishu/Lark message ingress to the existing `@axiom-lattice/gateway` service.
+
+## What It Supports
+
+- inbound Lark event callbacks
+- URL verification challenge
+- plain and encrypted callback payloads
+- v1 and v2 verification token extraction
+- text-message parsing
+- thread mapping to existing Axiom threads
+- reactive text replies sent through the official Lark SDK
+
+## Current Scope
+
+This is the MVP scope:
+
+- one gateway deployment can handle multiple tenant-scoped Lark installations
+- only text messages are supported
+- only reactive replies are supported
+- identity mapping is persisted in PostgreSQL
+
+## Environment Variables
+
+Required when `LARK_ENABLED=true`:
+
+```bash
+LARK_ENABLED=true
+
+DATABASE_URL=postgresql://user:pass@localhost:5432/axiom_lattice
+```
+
+Lark app credentials are no longer loaded from global environment variables. They are stored per installation in PostgreSQL.
+
+## Route
+
+The webhook route is mounted on the existing gateway service:
+
+```text
+POST /api/channels/lark/installations/:installationId/events
+```
+
+## Start The Gateway
+
+Development:
+
+```bash
+pnpm --filter @axiom-lattice/gateway dev
+```
+
+Production:
+
+```bash
+pnpm --filter @axiom-lattice/gateway build
+pnpm --filter @axiom-lattice/gateway start
+```
+
+## Feishu/Lark Console Setup
+
+In the Feishu developer console:
+
+1. Create or open an enterprise self-built app.
+2. Go to the event subscription / callback configuration page.
+3. Set the request URL to:
+
+```text
+https://your-domain.com/api/channels/lark/installations/<installationId>/events
+```
+
+4. Create a matching installation record in PostgreSQL for that tenant. The installation config must include:
+
+- appId
+- appSecret
+- Verification Token
+- Encrypt Key
+- assistantId
+- mappingMode
+
+5. Configure the same values in the Feishu console:
+
+- Verification Token
+- Encrypt Key
+
+6. Subscribe to the message event:
+
+```text
+im.message.receive_v1
+```
+
+## Callback Handling
+
+This implementation handles the normal Feishu event callback flow, not the message-card callback signature flow.
+
+Supported verification behavior:
+
+- v1 callback token: `body.token`
+- v2 callback token: `body.header.token`
+- encrypted envelope: `body.encrypt`
+
+If the callback is encrypted, the gateway decrypts it before:
+
+- checking the verification token
+- handling URL verification
+- parsing the event body
+
+## Identity Mapping
+
+The mapping mode controls how Lark conversations map to Axiom threads.
+
+### `user`
+
+- one Lark user maps to one Axiom thread
+- useful for personal assistant behavior
+
+### `group`
+
+- one Lark chat maps to one Axiom thread
+- useful for shared team assistant behavior
+
+### `hybrid`
+
+- direct chats use user isolation
+- group chats use group isolation
+
+This is the recommended default because it matches normal user expectations.
+
+Each installation also binds the request to:
+
+- one tenant
+- one default assistant
+- optional workspace and project IDs
+
+## Message Flow
+
+```text
+Lark callback
+-> gateway route
+-> decrypt / verify
+-> parse text event
+-> claim inbound receipt
+-> resolve or create thread mapping
+-> run assistant on existing gateway/core pipeline
+-> aggregate assistant text
+-> send reply through official Lark SDK
+```
+
+## Local Debugging
+
+To test locally, the Feishu callback URL must be reachable from Feishu.
+
+Typical options:
+
+- a public dev domain
+- an internal network tunnel
+
+Example callback URL:
+
+```text
+https://your-tunnel.example.com/api/channels/lark/installations/<installationId>/events
+```
+
+## What To Check When It Fails
+
+1. `LARK_ENABLED` is set to `true`
+2. `DATABASE_URL` is set and reachable
+3. the installation record exists in `lattice_channel_installations`
+4. the installation `appId` / `appSecret` are correct
+5. the installation `verificationToken` matches the Feishu console value
+6. the installation `encryptKey` matches the Feishu console value
+7. the callback URL is publicly reachable
+8. the Feishu app is subscribed to `im.message.receive_v1`
+
+## Data Written
+
+This module writes to PostgreSQL tables created by the gateway migration path:
+
+- `lattice_channel_installations`
+- `channel_identity_mappings`
+- `channel_inbound_message_receipts`
+
+## Known Limits
+
+- text only
+- one default assistant per installation
+- no proactive outbound messaging workflow yet
+- no card/file/image handling yet

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

@@ -0,0 +1,23 @@
+import { MessageChunkTypes } from "@axiom-lattice/protocols";
+import { aggregateLarkReply } from "../aggregator";
+
+describe("aggregateLarkReply", () => {
+  it("joins ai chunks for the requested message id", () => {
+    const result = aggregateLarkReply("msg-1", [
+      { type: MessageChunkTypes.AI, data: { id: "msg-1", content: "Hel" } },
+      { type: MessageChunkTypes.AI, data: { id: "msg-2", content: "skip" } },
+      { type: MessageChunkTypes.TOOL, data: { id: "msg-1", content: "ignore" } },
+      { type: MessageChunkTypes.AI, data: { id: "msg-1", content: "lo" } },
+    ]);
+
+    expect(result).toBe("Hello");
+  });
+
+  it("returns an empty string when no ai content exists for the message", () => {
+    const result = aggregateLarkReply("msg-1", [
+      { type: MessageChunkTypes.MESSAGE_COMPLETED, data: { id: "msg-1" } },
+    ]);
+
+    expect(result).toBe("");
+  });
+});

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" }),
+      },
+    });
+  });
+});