@axiom-lattice/gateway 3.0.2 → 3.0.3

package/src/channels/lark/LarkChannelAdapter.ts

@@ -1,217 +0,0 @@
-import { z } from "zod";
-import type {
-  ChannelAdapter,
-  InboundMessage,
-  OutboundMessage,
-  ReplyTarget,
-  ChannelInstallation,
-} from "@axiom-lattice/protocols";
-import type { LarkChannelInstallationConfig } from "@axiom-lattice/protocols";
-import { parseLarkMessageEvent } from "./parser";
-import { Logger } from "../../logger/Logger";
-import * as Lark from "@larksuiteoapi/node-sdk";
-
-const logger = new Logger({ serviceName: "lattice/gateway/lark" });
-
-// ─── WS connection state ──────────────────────────────────────────────────
-
-const activeConnections = new Map<string, Lark.WSClient>();
-
-// ─── WS message parsing (shared with lark-ws) ─────────────────────────────
-
-interface LarkWSMessageEvent {
-  sender?: { sender_id?: { open_id?: string } };
-  message?: {
-    message_id?: string;
-    chat_id?: string;
-    chat_type?: string;
-    message_type?: string;
-    content?: string;
-  };
-}
-
-function parseTextContent(content: string | undefined): string | null {
-  if (!content) return null;
-  try {
-    const parsed = JSON.parse(content) as { text?: string };
-    return typeof parsed.text === "string" ? parsed.text : null;
-  } catch { return null; }
-}
-
-function normalizeChatType(chatType: string | undefined): "direct" | "group" {
-  return chatType === "p2p" ? "direct" : "group";
-}
-
-function wsEventToInbound(
-  event: LarkWSMessageEvent,
-  installationId: string,
-  tenantId: string,
-): InboundMessage | null {
-  const messageId = event.message?.message_id;
-  const chatId = event.message?.chat_id;
-  const openId = event.sender?.sender_id?.open_id;
-  if (!messageId || !chatId || !openId) return null;
-  if (event.message?.message_type !== "text") return null;
-
-  const text = parseTextContent(event.message.content);
-  if (!text) return null;
-
-  const chatType = normalizeChatType(event.message.chat_type);
-  return {
-    channel: "lark",
-    channelInstallationId: installationId,
-    tenantId,
-    sender: { id: openId, displayName: undefined },
-    content: { text, metadata: { chatId, chatType, messageId } },
-    conversation: { id: chatId, type: chatType },
-    replyTarget: {
-      adapterChannel: "lark",
-      channelInstallationId: installationId,
-      rawTarget: { chatId, messageId, chatType },
-    },
-  };
-}
-
-// ─── Adapter ──────────────────────────────────────────────────────────────
-
-export const larkConfigSchema = z.object({
-  appId: z.string(),
-  appSecret: z.string(),
-  verificationToken: z.string().optional(),
-  encryptKey: z.string().optional(),
-});
-
-export const larkChannelAdapter: ChannelAdapter<LarkChannelInstallationConfig> = {
-  channel: "lark",
-
-  configSchema: larkConfigSchema,
-
-  async receive(
-    rawPayload: unknown,
-    installation: ChannelInstallation<LarkChannelInstallationConfig>,
-  ): Promise<InboundMessage | null> {
-    const event = parseLarkMessageEvent(rawPayload);
-    if (!event) return null;
-
-    return {
-      channel: "lark",
-      channelInstallationId: installation.id,
-      tenantId: installation.tenantId,
-      sender: { id: event.openId, displayName: undefined },
-      content: {
-        text: event.text,
-        metadata: { chatId: event.chatId, chatType: event.chatType, messageId: event.messageId },
-      },
-      conversation: { id: event.chatId, type: event.chatType },
-      replyTarget: {
-        adapterChannel: "lark",
-        channelInstallationId: installation.id,
-        rawTarget: { chatId: event.chatId, messageId: event.messageId, chatType: event.chatType },
-      },
-    };
-  },
-
-  async sendReply(
-    replyTarget: ReplyTarget,
-    message: OutboundMessage,
-    installation: ChannelInstallation<LarkChannelInstallationConfig>,
-  ): Promise<void> {
-    const { createLarkSender } = await import("./sender");
-    const sender = await createLarkSender(installation.config);
-    await sender.sendTextReply({
-      chatId: replyTarget.rawTarget.chatId as string,
-      text: message.text,
-    });
-  },
-
-  resolveThreadId(message: InboundMessage, binding: unknown): string {
-    const date = new Date().toISOString().split("T")[0];
-    const chatType = message.conversation?.type === "direct" ? "dm" : "group";
-    const agentId = (binding as { agentId: string }).agentId;
-    if (chatType === "dm") {
-      return `lark:dm:${message.sender.id}:${agentId}:${date}`;
-    }
-    return `lark:group:${message.conversation?.id ?? "unknown"}:${agentId}:${date}`;
-  },
-
-  async connect(
-    installation: ChannelInstallation<LarkChannelInstallationConfig>,
-    deps?: unknown,
-  ): Promise<void> {
-    const { id: installationId, tenantId, config } = installation;
-
-    if (!config.appId || !config.appSecret) {
-      logger.warn("Lark installation missing credentials, skipping", { installationId });
-      return;
-    }
-
-    if (activeConnections.has(installationId)) {
-      logger.warn("Lark WS already connected for installation, skipping", { installationId });
-      return;
-    }
-
-    logger.info("Lark WS client starting", { installationId, tenantId });
-
-    const router = (deps as { router?: { dispatch(msg: InboundMessage): Promise<unknown> } })?.router;
-
-    const eventDispatcher = new Lark.EventDispatcher({}).register({
-      "im.message.receive_v1": async (data: LarkWSMessageEvent) => {
-        try {
-          const inbound = wsEventToInbound(data, installationId, tenantId);
-          if (!inbound) return;
-
-          logger.info("Lark WS message received", {
-            installationId,
-            senderId: inbound.sender.id,
-            chatId: data.message?.chat_id,
-          });
-
-          if (router) {
-            const result = await router.dispatch(inbound);
-            if (!(result as { success?: boolean }).success) {
-              logger.warn("Lark WS dispatch failed", {
-                installationId,
-                error: (result as { error?: { message?: string } }).error?.message,
-              });
-            }
-          }
-        } catch (err) {
-          logger.error("Lark WS event handler error", {
-            installationId,
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      },
-    });
-
-    const client = new Lark.WSClient({
-      appId: config.appId,
-      appSecret: config.appSecret,
-      loggerLevel: Lark.LoggerLevel.info,
-    });
-
-    await client.start({ eventDispatcher });
-    activeConnections.set(installationId, client);
-    logger.info("Lark WS client connected", { installationId });
-  },
-
-  async disconnect(installationId: string): Promise<void> {
-    const client = activeConnections.get(installationId);
-    if (!client) {
-      logger.warn("Lark WS not connected, nothing to disconnect", { installationId });
-      return;
-    }
-
-    logger.info("Lark WS client disconnecting", { installationId });
-    try {
-      client.close({ force: true });
-    } catch (err) {
-      logger.error("Lark WS client stop error", {
-        installationId,
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-    activeConnections.delete(installationId);
-    logger.info("Lark WS client disconnected", { installationId });
-  },
-};

package/src/channels/lark/README.md

@@ -1,187 +0,0 @@
-# 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__/controller.test.ts

@@ -1,136 +0,0 @@
-import fastify from "fastify";
-import { createLarkEventHandler } from "../controller";
-
-const installation = {
-  id: "install-1",
-  tenantId: "tenant-a",
-  channel: "lark" as const,
-  config: { appId: "cli_app_1", appSecret: "secret" },
-  enabled: true,
-  rejectWhenNoBinding: false,
-  createdAt: new Date(),
-  updatedAt: new Date(),
-};
-
-describe("createLarkEventHandler", () => {
-  it("returns 404 when installation is not found", async () => {
-    const app = fastify();
-    const handler = createLarkEventHandler({
-      installationStore: {
-        getInstallationById: jest.fn().mockResolvedValue(null),
-      } as any,
-      router: { dispatch: jest.fn() } as any,
-    });
-
-    app.post(
-      "/api/channels/lark/installations/:installationId/events",
-      handler,
-    );
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/channels/lark/installations/install-1/events",
-      payload: {},
-    });
-
-    expect(response.statusCode).toBe(404);
-    expect(response.json()).toEqual({ success: false, message: "Installation not found" });
-
-    await app.close();
-  });
-
-  it("returns 404 when installation channel is not lark", async () => {
-    const app = fastify();
-    const handler = createLarkEventHandler({
-      installationStore: {
-        getInstallationById: jest.fn().mockResolvedValue({ ...installation, channel: "slack" }),
-      } as any,
-      router: { dispatch: jest.fn() } as any,
-    });
-
-    app.post(
-      "/api/channels/lark/installations/:installationId/events",
-      handler,
-    );
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/channels/lark/installations/install-1/events",
-      payload: {},
-    });
-
-    expect(response.statusCode).toBe(404);
-
-    await app.close();
-  });
-
-  it("returns 200 for non-message events (e.g. url verification)", async () => {
-    const app = fastify();
-    const handler = createLarkEventHandler({
-      installationStore: {
-        getInstallationById: jest.fn().mockResolvedValue(installation),
-      } as any,
-      router: { dispatch: jest.fn() } as any,
-    });
-
-    app.post(
-      "/api/channels/lark/installations/:installationId/events",
-      handler,
-    );
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/channels/lark/installations/install-1/events",
-      payload: { type: "url_verification", challenge: "challenge-token" },
-    });
-
-    expect(response.statusCode).toBe(200);
-
-    await app.close();
-  });
-
-  it("dispatches valid message events via router", async () => {
-    const app = fastify();
-    const dispatch = jest.fn().mockResolvedValue({ success: true });
-
-    const handler = createLarkEventHandler({
-      installationStore: {
-        getInstallationById: jest.fn().mockResolvedValue(installation),
-      } as any,
-      router: { dispatch } as any,
-    });
-
-    app.post(
-      "/api/channels/lark/installations/:installationId/events",
-      handler,
-    );
-
-    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(dispatch).toHaveBeenCalledTimes(1);
-    expect(dispatch.mock.calls[0][0]).toMatchObject({
-      channel: "lark",
-      channelInstallationId: "install-1",
-      tenantId: "tenant-a",
-    });
-
-    await app.close();
-  });
-});

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

@@ -1,118 +0,0 @@
-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",
-    );
-  });
-});