@axiom-lattice/gateway 2.1.52 → 2.1.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/gateway",
-  "version": "2.1.52",
+  "version": "2.1.54",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -25,6 +25,7 @@
     "@fastify/swagger": "^9.5.1",
     "@fastify/swagger-ui": "^5.2.3",
     "@fastify/websocket": "^11.0.1",
+    "@larksuiteoapi/node-sdk": "^1.47.0",
     "@langchain/core": "1.1.30",
     "@langchain/langgraph": "1.0.4",
     "@supabase/supabase-js": "^2.49.1",
@@ -38,10 +39,10 @@
     "pg": "^8.11.0",
     "redis": "^5.0.1",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "2.1.46",
-    "@axiom-lattice/pg-stores": "1.0.36",
-    "@axiom-lattice/protocols": "2.1.24",
-    "@axiom-lattice/queue-redis": "1.0.23"
+    "@axiom-lattice/core": "2.1.48",
+    "@axiom-lattice/pg-stores": "1.0.38",
+    "@axiom-lattice/protocols": "2.1.26",
+    "@axiom-lattice/queue-redis": "1.0.25"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/channel-installations.test.ts

@@ -0,0 +1,199 @@
+import { FastifyInstance } from "fastify";
+import fastify from "fastify";
+import { registerChannelInstallationRoutes } from "../routes/channel-installations";
+
+// Set DATABASE_URL before importing controller
+process.env.DATABASE_URL = "postgres://test:test@localhost:5432/test";
+
+// Mock the store
+const mockGetInstallationsByTenant = jest.fn();
+const mockGetInstallationById = jest.fn();
+const mockCreateInstallation = jest.fn();
+const mockUpdateInstallation = jest.fn();
+const mockDeleteInstallation = jest.fn();
+
+jest.mock("@axiom-lattice/pg-stores", () => ({
+  PostgreSQLChannelInstallationStore: jest.fn().mockImplementation(() => ({
+    getInstallationsByTenant: mockGetInstallationsByTenant,
+    getInstallationById: mockGetInstallationById,
+    createInstallation: mockCreateInstallation,
+    updateInstallation: mockUpdateInstallation,
+    deleteInstallation: mockDeleteInstallation,
+  })),
+}));
+
+describe("Channel Installation API", () => {
+  let app: FastifyInstance;
+
+  beforeEach(() => {
+    // Reset mocks
+    mockGetInstallationsByTenant.mockReset();
+    mockGetInstallationById.mockReset();
+    mockCreateInstallation.mockReset();
+    mockUpdateInstallation.mockReset();
+    mockDeleteInstallation.mockReset();
+
+    app = fastify();
+    registerChannelInstallationRoutes(app);
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe("GET /api/channel-installations", () => {
+    it("should return list of installations for tenant", async () => {
+      mockGetInstallationsByTenant.mockResolvedValueOnce([
+        {
+          id: "install-1",
+          tenantId: "tenant-a",
+          channel: "lark",
+          name: "Test Installation",
+          config: {
+            appId: "cli_test",
+            appSecret: "secret",
+            assistantId: "assistant-1",
+            mappingMode: "hybrid",
+          },
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      ]);
+
+      const response = await app.inject({
+        method: "GET",
+        url: "/api/channel-installations",
+        headers: {
+          "x-tenant-id": "tenant-a",
+        },
+      });
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toHaveProperty("records");
+      expect(body.data).toHaveProperty("total");
+      expect(body.data.records).toHaveLength(1);
+    });
+
+    it("should filter by channel type", async () => {
+      const response = await app.inject({
+        method: "GET",
+        url: "/api/channel-installations?channel=lark",
+        headers: {
+          "x-tenant-id": "tenant-a",
+        },
+      });
+
+      expect(response.statusCode).toBe(200);
+    });
+  });
+
+  describe("GET /api/channel-installations/:installationId", () => {
+    it("should return installation by id", async () => {
+      const response = await app.inject({
+        method: "GET",
+        url: "/api/channel-installations/install-1",
+        headers: {
+          "x-tenant-id": "tenant-a",
+        },
+      });
+
+      // Will return 404 since mock returns null, but route is accessible
+      expect([200, 404]).toContain(response.statusCode);
+    });
+  });
+
+  describe("POST /api/channel-installations", () => {
+    it("should create new installation", async () => {
+      mockCreateInstallation.mockResolvedValueOnce({
+        id: "new-install-id",
+        tenantId: "tenant-a",
+        channel: "lark",
+        name: "Test Lark Installation",
+        config: {
+          appId: "cli_test",
+          appSecret: "secret",
+          assistantId: "assistant-1",
+          mappingMode: "hybrid",
+        },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      });
+
+      const response = await app.inject({
+        method: "POST",
+        url: "/api/channel-installations",
+        headers: {
+          "x-tenant-id": "tenant-a",
+          "content-type": "application/json",
+        },
+        payload: {
+          channel: "lark",
+          name: "Test Lark Installation",
+          config: {
+            appId: "cli_test",
+            appSecret: "secret",
+            assistantId: "assistant-1",
+            mappingMode: "hybrid",
+          },
+        },
+      });
+
+      expect(response.statusCode).toBe(201);
+      const body = JSON.parse(response.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toHaveProperty("id");
+    });
+
+    it("should validate required fields", async () => {
+      const response = await app.inject({
+        method: "POST",
+        url: "/api/channel-installations",
+        headers: {
+          "x-tenant-id": "tenant-a",
+          "content-type": "application/json",
+        },
+        payload: {
+          // Missing channel and config
+        },
+      });
+
+      expect(response.statusCode).toBe(400);
+    });
+  });
+
+  describe("PUT /api/channel-installations/:installationId", () => {
+    it("should update installation", async () => {
+      const response = await app.inject({
+        method: "PUT",
+        url: "/api/channel-installations/install-1",
+        headers: {
+          "x-tenant-id": "tenant-a",
+          "content-type": "application/json",
+        },
+        payload: {
+          name: "Updated Name",
+        },
+      });
+
+      // Will return 404 since mock returns null, but route is accessible
+      expect([200, 404]).toContain(response.statusCode);
+    });
+  });
+
+  describe("DELETE /api/channel-installations/:installationId", () => {
+    it("should delete installation", async () => {
+      const response = await app.inject({
+        method: "DELETE",
+        url: "/api/channel-installations/install-1",
+        headers: {
+          "x-tenant-id": "tenant-a",
+        },
+      });
+
+      // Will return 404 since mock returns null, but route is accessible
+      expect([200, 404]).toContain(response.statusCode);
+    });
+  });
+});

package/src/channels/__tests__/routes.test.ts

@@ -0,0 +1,71 @@
+import fastify from "fastify";
+import { registerChannelRoutes } from "../routes";
+
+describe("registerChannelRoutes", () => {
+  const envBackup = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...envBackup };
+  });
+
+  it("registers the lark route dynamically", async () => {
+    const app = fastify();
+    registerChannelRoutes(app, {
+      lark: {
+        getInstallationConfig: jest.fn().mockResolvedValue({
+          installationId: "install-1",
+          tenantId: "tenant-a",
+          assistantId: "assistant-a",
+          appId: "cli_app_1",
+          appSecret: "secret",
+          verificationToken: "token-1",
+          mappingMode: "hybrid",
+        }),
+        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("skips lark route registration when lark config is disabled", async () => {
+    process.env.LARK_ENABLED = "false";
+
+    const app = fastify();
+    registerChannelRoutes(app);
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/channels/lark/installations/install-1/events",
+      payload: {},
+    });
+
+    expect(response.statusCode).toBe(404);
+
+    await app.close();
+  });
+});

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