@axiom-lattice/gateway 2.1.52 → 2.1.54

package/src/channels/lark/config.ts

@@ -0,0 +1,44 @@
+import type { LarkIngressConfig } from "./types";
+
+export function loadLarkIngressConfig(): LarkIngressConfig {
+  return {
+    enabled: process.env.LARK_ENABLED !== "false",
+    appId: process.env.LARK_APP_ID || "",
+    appSecret: process.env.LARK_APP_SECRET || "",
+    verificationToken: process.env.LARK_VERIFICATION_TOKEN,
+    encryptKey: process.env.LARK_ENCRYPT_KEY,
+    tenantId: process.env.LARK_TENANT_ID || "default",
+    assistantId: process.env.LARK_ASSISTANT_ID || "default_agent",
+    workspaceId: process.env.LARK_WORKSPACE_ID,
+    projectId: process.env.LARK_PROJECT_ID,
+    mappingMode:
+      (process.env.LARK_MAPPING_MODE as "user" | "group" | "hybrid") ||
+      "hybrid",
+  };
+}
+
+export function isLarkIngressEnabled(config: LarkIngressConfig): boolean {
+  return config.enabled;
+}
+
+export function assertLarkIngressConfig(config: LarkIngressConfig): void {
+  if (!config.enabled) {
+    return;
+  }
+
+  if (!config.appId) {
+    throw new Error("LARK_APP_ID is required when Lark ingress is enabled");
+  }
+
+  if (!config.appSecret) {
+    throw new Error("LARK_APP_SECRET is required when Lark ingress is enabled");
+  }
+
+  if (!config.tenantId) {
+    throw new Error("LARK_TENANT_ID is required when Lark ingress is enabled");
+  }
+
+  if (!config.assistantId) {
+    throw new Error("LARK_ASSISTANT_ID is required when Lark ingress is enabled");
+  }
+}

package/src/channels/lark/controller.ts

@@ -0,0 +1,189 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { parseLarkMessageEvent } from "./parser";
+import type {
+  LarkIngressConfig,
+  LarkUrlVerificationPayload,
+  ParsedLarkMessageEvent,
+} from "./types";
+
+export interface LarkEventHandlerDependencies {
+  getInstallationConfig: (
+    installationId: string,
+  ) => Promise<LarkIngressConfig | null>;
+  parseRequestBody: (
+    body: unknown,
+    encryptKey?: string,
+  ) => LarkUrlVerificationPayload;
+  verifyParsedBody: (
+    body: LarkUrlVerificationPayload,
+    config: LarkIngressConfig,
+  ) => boolean;
+  parseEvent: (payload: unknown) => ParsedLarkMessageEvent | null;
+  claimInboundReceipt: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+  }) => Promise<{ accepted: boolean; status: "processing" | "completed" }>;
+  markInboundReceiptCompleted: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+    threadId: string;
+  }) => Promise<void>;
+  markInboundReceiptFailed: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+  }) => Promise<void>;
+  resolveThread: (input: {
+    channel: string;
+    channelAppId: string;
+    tenantId: string;
+    assistantId: string;
+    mappingMode: "user" | "group" | "hybrid";
+    openId: string;
+    chatId: string;
+    chatType: "direct" | "group";
+    messageId: string;
+    workspaceId?: string;
+    projectId?: string;
+  }) => Promise<{ threadId: string }>;
+  runAgentAndCollectText: (input: {
+    tenantId: string;
+    assistantId: string;
+    threadId: string;
+    text: string;
+    workspaceId?: string;
+    projectId?: string;
+  }) => Promise<string>;
+  sendTextReply: (input: {
+    chatId: string;
+    text: string;
+    config: LarkIngressConfig;
+  }) => Promise<void>;
+}
+
+export function createLarkEventHandler(
+  dependencies: LarkEventHandlerDependencies,
+) {
+  return async function handleLarkEvent(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const installationId = (request.params as { installationId?: string })
+      ?.installationId;
+
+    if (!installationId) {
+      reply.status(400).send({ success: false, message: "Missing installationId" });
+      return;
+    }
+
+    const config = await dependencies.getInstallationConfig(installationId);
+    if (!config) {
+      reply.status(404).send({ success: false, message: "Lark installation not found" });
+      return;
+    }
+
+    const body = dependencies.parseRequestBody(
+      request.body,
+      config.encryptKey,
+    ) as LarkUrlVerificationPayload;
+
+    if (!dependencies.verifyParsedBody(body, config)) {
+      reply.status(401).send({ success: false, message: "Invalid Lark request" });
+      return;
+    }
+
+    if (body.type === "url_verification" && body.challenge) {
+      reply.status(200).send({ challenge: body.challenge });
+      return;
+    }
+
+    const parsed = dependencies.parseEvent(request.body);
+    if (!parsed) {
+      reply.status(200).send({ success: true, ignored: true });
+      return;
+    }
+
+    const receipt = await dependencies.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: config.appId,
+      externalMessageId: parsed.messageId,
+      tenantId: config.tenantId,
+    });
+
+    if (!receipt.accepted) {
+      reply.status(200).send(
+        receipt.status === "processing"
+          ? { success: true, processing: true }
+          : { success: true, duplicate: true },
+      );
+      return;
+    }
+
+    try {
+      const { threadId } = await dependencies.resolveThread({
+        channel: "lark",
+        channelAppId: config.appId,
+        tenantId: config.tenantId,
+        assistantId: config.assistantId,
+        mappingMode: config.mappingMode,
+        openId: parsed.openId,
+        chatId: parsed.chatId,
+        chatType: parsed.chatType,
+        messageId: parsed.messageId,
+        workspaceId: config.workspaceId,
+        projectId: config.projectId,
+      });
+
+      const text = await dependencies.runAgentAndCollectText({
+        tenantId: config.tenantId,
+        assistantId: config.assistantId,
+        threadId,
+        text: parsed.text,
+        workspaceId: config.workspaceId,
+        projectId: config.projectId,
+      });
+
+      await dependencies.sendTextReply({
+        chatId: parsed.chatId,
+        text,
+        config,
+      });
+
+      await dependencies.markInboundReceiptCompleted({
+        channel: "lark",
+        channelAppId: config.appId,
+        externalMessageId: parsed.messageId,
+        tenantId: config.tenantId,
+        threadId,
+      });
+
+      reply.status(200).send({ success: true, threadId });
+    } catch (error) {
+      await dependencies.markInboundReceiptFailed({
+        channel: "lark",
+        channelAppId: config.appId,
+        externalMessageId: parsed.messageId,
+        tenantId: config.tenantId,
+      });
+      throw error;
+    }
+  };
+}
+
+export const handleLarkEvent = createLarkEventHandler({
+  getInstallationConfig: async () => null,
+  parseRequestBody: (body) => (body || {}) as LarkUrlVerificationPayload,
+  verifyParsedBody: () => true,
+  parseEvent: parseLarkMessageEvent,
+  claimInboundReceipt: async () => ({ accepted: true, status: "processing" }),
+  markInboundReceiptCompleted: async () => undefined,
+  markInboundReceiptFailed: async () => undefined,
+  resolveThread: async () => ({ threadId: "" }),
+  runAgentAndCollectText: async () => "",
+  sendTextReply: async () => undefined,
+});

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

@@ -0,0 +1,138 @@
+import type { ThreadStore } from "@axiom-lattice/protocols";
+import type { ChannelIdentityMappingStore } from "@axiom-lattice/pg-stores";
+import { randomUUID } from "crypto";
+
+interface GetOrCreateThreadInput {
+  channel: string;
+  channelAppId: string;
+  tenantId: string;
+  assistantId: string;
+  mappingMode: "user" | "group" | "hybrid";
+  openId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  messageId: string;
+  workspaceId?: string;
+  projectId?: string;
+}
+
+interface ChannelThreadMappingServiceDeps {
+  mappingStore: Pick<
+    ChannelIdentityMappingStore,
+    "getMappingBySubject" | "createMapping"
+  >;
+  threadStore: Pick<ThreadStore, "createThread" | "deleteThread">;
+  uuid?: () => string;
+}
+
+export function createChannelThreadMappingService(
+  deps: ChannelThreadMappingServiceDeps,
+) {
+  return {
+    async getOrCreateThread(input: GetOrCreateThreadInput): Promise<{ threadId: string }> {
+      const externalSubjectKey = buildExternalSubjectKey(input);
+      const existing = await deps.mappingStore.getMappingBySubject({
+        channel: input.channel,
+        channelAppId: input.channelAppId,
+        tenantId: input.tenantId,
+        assistantId: input.assistantId,
+        externalSubjectKey,
+      });
+
+      if (existing) {
+        return { threadId: existing.threadId };
+      }
+
+      const threadId = (deps.uuid || randomUUID)();
+
+      await deps.threadStore.createThread(input.tenantId, input.assistantId, threadId, {
+        metadata: {
+          tenantId: input.tenantId,
+          workspaceId: input.workspaceId,
+          projectId: input.projectId,
+          channel: input.channel,
+          larkChatId: input.chatId,
+          larkOpenId: input.openId,
+        },
+      });
+
+      try {
+        await deps.mappingStore.createMapping({
+          channel: input.channel,
+          channelAppId: input.channelAppId,
+          tenantId: input.tenantId,
+          assistantId: input.assistantId,
+          mappingMode: input.mappingMode,
+          externalSubjectType:
+            resolveSubjectType(input.mappingMode, input.chatType) === "user"
+              ? "user"
+              : "chat",
+          externalSubjectKey,
+          larkOpenId: input.openId,
+          larkChatId: input.chatId,
+          larkMessageId: input.messageId,
+          threadId,
+        });
+      } catch (error) {
+        if (!isUniqueViolation(error)) {
+          throw error;
+        }
+
+        const canonical = await deps.mappingStore.getMappingBySubject({
+          channel: input.channel,
+          channelAppId: input.channelAppId,
+          tenantId: input.tenantId,
+          assistantId: input.assistantId,
+          externalSubjectKey,
+        });
+
+        if (!canonical) {
+          throw error;
+        }
+
+        await deps.threadStore.deleteThread(input.tenantId, threadId);
+
+        return { threadId: canonical.threadId };
+      }
+
+      return { threadId };
+    },
+  };
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: string }).code === "23505"
+  );
+}
+
+function buildExternalSubjectKey(input: GetOrCreateThreadInput): string {
+  const subjectType = resolveSubjectType(input.mappingMode, input.chatType);
+  const subjectValue = subjectType === "user" ? input.openId : input.chatId;
+
+  return [
+    input.channel,
+    input.channelAppId,
+    `tenant:${input.tenantId}`,
+    `assistant:${input.assistantId}`,
+    `${subjectType}:${subjectValue}`,
+  ].join(":");
+}
+
+function resolveSubjectType(
+  mappingMode: "user" | "group" | "hybrid",
+  chatType: "direct" | "group",
+): "user" | "chat" {
+  if (mappingMode === "user") {
+    return "user";
+  }
+
+  if (mappingMode === "group") {
+    return "chat";
+  }
+
+  return chatType === "direct" ? "user" : "chat";
+}

package/src/channels/lark/parser.ts

@@ -0,0 +1,68 @@
+import type { ParsedLarkMessageEvent } from "./types";
+
+interface RawLarkPayload {
+  header?: {
+    event_type?: string;
+  };
+  event?: {
+    sender?: {
+      sender_id?: {
+        open_id?: string;
+      };
+    };
+    message?: {
+      message_id?: string;
+      chat_id?: string;
+      chat_type?: string;
+      message_type?: string;
+      content?: string;
+    };
+  };
+}
+
+export function parseLarkMessageEvent(
+  payload: unknown,
+): ParsedLarkMessageEvent | null {
+  const raw = payload as RawLarkPayload;
+
+  if (raw.header?.event_type !== "im.message.receive_v1") {
+    return null;
+  }
+
+  const message = raw.event?.message;
+  const openId = raw.event?.sender?.sender_id?.open_id;
+
+  if (!message || !openId || message.message_type !== "text") {
+    return null;
+  }
+
+  const parsedContent = parseLarkTextContent(message.content);
+  if (!message.message_id || !message.chat_id || !parsedContent) {
+    return null;
+  }
+
+  return {
+    messageId: message.message_id,
+    openId,
+    chatId: message.chat_id,
+    chatType: normalizeChatType(message.chat_type),
+    text: parsedContent,
+  };
+}
+
+function parseLarkTextContent(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";
+}

package/src/channels/lark/routes.ts

@@ -0,0 +1,121 @@
+import type { FastifyInstance } from "fastify";
+import { getStoreLattice } from "@axiom-lattice/core";
+import {
+  ChannelIdentityMappingStore,
+  PostgreSQLChannelInstallationStore,
+} from "@axiom-lattice/pg-stores";
+import {
+  createLarkEventHandler,
+  type LarkEventHandlerDependencies,
+} from "./controller";
+import {
+  isLarkIngressEnabled,
+  loadLarkIngressConfig,
+} from "./config";
+import { createChannelThreadMappingService } from "./mapping-service";
+import { parseLarkMessageEvent } from "./parser";
+import { runAgentAndCollectLarkReply } from "./runner";
+import { createLarkSender } from "./sender";
+import { createLarkRequestVerifier, parseLarkRequestBody } from "./verification";
+
+export function registerLarkChannelRoutes(
+  app: FastifyInstance,
+  dependencies?: LarkEventHandlerDependencies,
+): void {
+  const config = loadLarkIngressConfig();
+  if (!dependencies && !isLarkIngressEnabled(config)) {
+    return;
+  }
+  const handlerDependencies = dependencies || createDefaultLarkDependencies();
+
+  app.post(
+    "/api/channels/lark/installations/:installationId/events",
+    createLarkEventHandler({
+      ...handlerDependencies,
+    }),
+  );
+}
+
+function createDefaultLarkDependencies(): LarkEventHandlerDependencies {
+  const installationStore = new PostgreSQLChannelInstallationStore({
+    poolConfig: getDatabaseUrl(),
+  });
+  const threadStore = getStoreLattice("default", "thread").store;
+  const mappingStore = new ChannelIdentityMappingStore({
+    poolConfig: getDatabaseUrl(),
+  });
+  const mappingService = createChannelThreadMappingService({
+    mappingStore,
+    threadStore,
+  });
+
+  return {
+    getInstallationConfig: async (installationId) => {
+      const installation = await installationStore.getInstallationById(
+        installationId,
+      );
+
+      if (!installation || installation.channel !== "lark") {
+        return null;
+      }
+
+      return {
+        enabled: true,
+        installationId: installation.id,
+        tenantId: installation.tenantId,
+        assistantId: installation.config.assistantId,
+        appId: installation.config.appId,
+        appSecret: installation.config.appSecret,
+        verificationToken: installation.config.verificationToken,
+        encryptKey: installation.config.encryptKey,
+        workspaceId: installation.config.workspaceId,
+        projectId: installation.config.projectId,
+        mappingMode: installation.config.mappingMode,
+      };
+    },
+    parseRequestBody: (body, encryptKey) => parseLarkRequestBody(body, encryptKey),
+    verifyParsedBody: (body, config) => {
+      if (!config.verificationToken) {
+        return true;
+      }
+
+      return createLarkRequestVerifier(config)({
+        body,
+      } as unknown as Parameters<ReturnType<typeof createLarkRequestVerifier>>[0]);
+    },
+    parseEvent: parseLarkMessageEvent,
+    claimInboundReceipt: (input) => mappingStore.claimInboundReceipt(input),
+    markInboundReceiptCompleted: (input) =>
+      mappingStore.markInboundReceiptCompleted(input),
+    markInboundReceiptFailed: (input) =>
+      mappingStore.markInboundReceiptFailed(input),
+    resolveThread: (input) => mappingService.getOrCreateThread(input),
+    runAgentAndCollectText: ({ tenantId, assistantId, threadId, text, workspaceId, projectId }) =>
+      runAgentAndCollectLarkReply({
+        tenantId,
+        assistantId,
+        threadId,
+        text,
+        workspaceId,
+        projectId,
+      }),
+    sendTextReply: async ({ chatId, text, config }) => {
+      const sender = createLarkSender({
+        appId: config.appId,
+        appSecret: config.appSecret,
+      });
+
+      await sender.sendTextReply({ chatId, text });
+    },
+  };
+}
+
+function getDatabaseUrl(): string {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    throw new Error("DATABASE_URL is required for Lark channel ingress");
+  }
+
+  return databaseUrl;
+}

package/src/channels/lark/runner.ts

@@ -0,0 +1,37 @@
+import { agentInstanceManager } from "@axiom-lattice/core";
+import { MessageChunkTypes } from "@axiom-lattice/protocols";
+import { aggregateLarkReply } from "./aggregator";
+
+export async function runAgentAndCollectLarkReply(input: {
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  text: string;
+  workspaceId?: string;
+  projectId?: string;
+}): Promise<string> {
+  const agent = agentInstanceManager.getAgent({
+    tenant_id: input.tenantId,
+    assistant_id: input.assistantId,
+    thread_id: input.threadId,
+    workspace_id: input.workspaceId,
+    project_id: input.projectId,
+  });
+
+  const result = await agent.addMessage({
+    input: {
+      message: input.text,
+    },
+  });
+
+  const chunks = [];
+  const stream = agent.chunkStream(result.messageId, [
+    MessageChunkTypes.MESSAGE_COMPLETED,
+  ]);
+
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+
+  return aggregateLarkReply(result.messageId, chunks);
+}

package/src/channels/lark/sender.ts

@@ -0,0 +1,58 @@
+interface LarkSenderConfig {
+  appId: string;
+  appSecret: string;
+}
+
+interface LarkSdkMessageClient {
+  im: {
+    v1: {
+      message: {
+        create(input: {
+          params: {
+            receive_id_type: "chat_id";
+          };
+          data: {
+            receive_id: string;
+            msg_type: "text";
+            content: string;
+          };
+        }): Promise<{ code?: number }>;
+      };
+    };
+  };
+}
+
+export function createLarkSender(
+  config: LarkSenderConfig,
+  client: LarkSdkMessageClient = createDefaultLarkClient(config),
+) {
+  return {
+    async sendTextReply(input: { chatId: string; text: string }): Promise<void> {
+      const response = await client.im.v1.message.create({
+        params: {
+          receive_id_type: "chat_id",
+        },
+        data: {
+          receive_id: input.chatId,
+          msg_type: "text",
+          content: JSON.stringify({ text: input.text }),
+        },
+      });
+
+      if (response.code && response.code !== 0) {
+        throw new Error("Failed to send Lark reply");
+      }
+    },
+  };
+}
+
+function createDefaultLarkClient(config: LarkSenderConfig): LarkSdkMessageClient {
+  const Lark = require("@larksuiteoapi/node-sdk") as {
+    Client: new (input: { appId: string; appSecret: string }) => unknown;
+  };
+
+  return new Lark.Client({
+    appId: config.appId,
+    appSecret: config.appSecret,
+  }) as LarkSdkMessageClient;
+}

package/src/channels/lark/types.ts

@@ -0,0 +1,33 @@
+export interface ParsedLarkMessageEvent {
+  messageId: string;
+  openId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  text: string;
+}
+
+export interface LarkUrlVerificationPayload {
+  type?: string;
+  challenge?: string;
+  token?: string;
+  schema?: string;
+  header?: {
+    token?: string;
+    event_type?: string;
+  };
+  encrypt?: string;
+}
+
+export interface LarkIngressConfig {
+  enabled: boolean;
+  installationId?: string;
+  appId: string;
+  appSecret: string;
+  verificationToken?: string;
+  encryptKey?: string;
+  tenantId: string;
+  assistantId: string;
+  workspaceId?: string;
+  projectId?: string;
+  mappingMode: "user" | "group" | "hybrid";
+}