@axiom-lattice/pg-stores 1.0.37 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,8 +21,8 @@
   "license": "MIT",
   "dependencies": {
     "pg": "^8.16.3",
-    "@axiom-lattice/protocols": "2.1.25",
-    "@axiom-lattice/core": "2.1.47"
+    "@axiom-lattice/protocols": "2.1.26",
+    "@axiom-lattice/core": "2.1.49"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",

package/src/__tests__/ChannelIdentityMappingStore.test.ts

@@ -0,0 +1,219 @@
+import { ChannelIdentityMappingStore } from "../stores/ChannelIdentityMappingStore";
+
+const mockQuery = jest.fn();
+
+jest.mock("pg", () => ({
+  Pool: jest.fn().mockImplementation(() => ({
+    query: mockQuery,
+  })),
+}));
+
+describe("ChannelIdentityMappingStore", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("creates and retrieves a mapping by external subject key", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "mapping-1",
+          channel: "lark",
+          channel_app_id: "cli_app_1",
+          tenant_id: "tenant-a",
+          assistant_id: "assistant-a",
+          mapping_mode: "hybrid",
+          external_subject_type: "user",
+          external_subject_key:
+            "lark:cli_app_1:tenant:tenant-a:assistant:assistant-a:user:ou_xxx",
+          lark_open_id: "ou_xxx",
+          lark_chat_id: "oc_yyy",
+          lark_message_id: "om_1",
+          thread_id: "thread-1",
+          created_at: new Date("2026-04-10T00:00:00.000Z"),
+          updated_at: new Date("2026-04-10T00:00:00.000Z"),
+          last_activity_at: new Date("2026-04-10T00:00:00.000Z"),
+        },
+      ],
+    });
+
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "mapping-1",
+          channel: "lark",
+          channel_app_id: "cli_app_1",
+          tenant_id: "tenant-a",
+          assistant_id: "assistant-a",
+          mapping_mode: "hybrid",
+          external_subject_type: "user",
+          external_subject_key:
+            "lark:cli_app_1:tenant:tenant-a:assistant:assistant-a:user:ou_xxx",
+          lark_open_id: "ou_xxx",
+          lark_chat_id: "oc_yyy",
+          lark_message_id: "om_1",
+          thread_id: "thread-1",
+          created_at: new Date("2026-04-10T00:00:00.000Z"),
+          updated_at: new Date("2026-04-10T00:00:00.000Z"),
+          last_activity_at: new Date("2026-04-10T00:00:00.000Z"),
+        },
+      ],
+    });
+
+    const created = await store.createMapping({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+      externalSubjectType: "user",
+      externalSubjectKey:
+        "lark:cli_app_1:tenant:tenant-a:assistant:assistant-a:user:ou_xxx",
+      larkOpenId: "ou_xxx",
+      larkChatId: "oc_yyy",
+      larkMessageId: "om_1",
+      threadId: "thread-1",
+    });
+
+    const found = await store.getMappingBySubject({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      externalSubjectKey:
+        "lark:cli_app_1:tenant:tenant-a:assistant:assistant-a:user:ou_xxx",
+    });
+
+    expect(created.threadId).toBe("thread-1");
+    expect(found?.threadId).toBe("thread-1");
+  });
+
+  it("returns completed when a duplicate inbound receipt is already completed", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rows: [{ source: "inserted", status: "processing" }] });
+    mockQuery.mockResolvedValueOnce({ rows: [{ source: "existing", status: "completed" }] });
+
+    const first = await store.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_1",
+      tenantId: "tenant-a",
+    });
+
+    const second = await store.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_1",
+      tenantId: "tenant-a",
+    });
+
+    expect(first).toEqual({ accepted: true, status: "processing" });
+    expect(second).toEqual({ accepted: false, status: "completed" });
+  });
+
+  it("claims a new inbound receipt with processing status", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rows: [{ source: "inserted", status: "processing" }] });
+
+    const result = await store.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_processing_1",
+      tenantId: "tenant-a",
+    });
+
+    expect(result).toEqual({ accepted: true, status: "processing" });
+  });
+
+  it("allows retry when an inbound receipt was previously marked failed", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rows: [{ source: "retried", status: "processing" }] });
+
+    const result = await store.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_failed_1",
+      tenantId: "tenant-a",
+    });
+
+    expect(result).toEqual({ accepted: true, status: "processing" });
+  });
+
+  it("rejects a receipt that is already processing", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rows: [{ source: "existing", status: "processing" }] });
+
+    const result = await store.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_processing_1",
+      tenantId: "tenant-a",
+    });
+
+    expect(result).toEqual({ accepted: false, status: "processing" });
+  });
+
+  it("marks an inbound receipt as failed", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rowCount: 1 });
+
+    await store.markInboundReceiptFailed({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_failed_1",
+      tenantId: "tenant-a",
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringContaining("SET status = 'failed'"),
+      ["lark", "cli_app_1", "om_failed_1", "tenant-a"],
+    );
+  });
+
+  it("marks an inbound receipt as completed", async () => {
+    const store = new ChannelIdentityMappingStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({ rowCount: 1 });
+
+    await store.markInboundReceiptCompleted({
+      channel: "lark",
+      channelAppId: "cli_app_1",
+      externalMessageId: "om_done_1",
+      tenantId: "tenant-a",
+      threadId: "thread-1",
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringContaining("UPDATE channel_inbound_message_receipts"),
+      ["thread-1", "lark", "cli_app_1", "om_done_1", "tenant-a"],
+    );
+  });
+});

package/src/__tests__/PostgreSQLChannelInstallationStore.test.ts

@@ -0,0 +1,54 @@
+import { PostgreSQLChannelInstallationStore } from "../stores/PostgreSQLChannelInstallationStore";
+
+const mockQuery = jest.fn();
+
+jest.mock("pg", () => ({
+  Pool: jest.fn().mockImplementation(() => ({
+    query: mockQuery,
+  })),
+}));
+
+jest.mock("@axiom-lattice/core", () => ({
+  encrypt: (value: string) => `enc:${value}`,
+  decrypt: (value: string) => value.replace(/^enc:/, ""),
+}));
+
+describe("PostgreSQLChannelInstallationStore", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("retrieves and decrypts an installation by id", async () => {
+    const store = new PostgreSQLChannelInstallationStore({
+      poolConfig: "postgres://test:test@localhost:5432/test",
+      autoMigrate: false,
+    });
+
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "install-1",
+          tenant_id: "tenant-a",
+          channel: "lark",
+          name: "Tenant A Lark",
+          config: {
+            appId: "cli_app_1",
+            appSecret: "enc:secret",
+            verificationToken: "enc:token-1",
+            encryptKey: "enc:encrypt-key",
+            assistantId: "assistant-a",
+            mappingMode: "hybrid",
+          },
+          created_at: new Date("2026-04-10T00:00:00.000Z"),
+          updated_at: new Date("2026-04-10T00:00:00.000Z"),
+        },
+      ],
+    });
+
+    const installation = await store.getInstallationById("install-1");
+
+    expect(installation?.tenantId).toBe("tenant-a");
+    expect(installation?.config.appSecret).toBe("secret");
+    expect(installation?.config.verificationToken).toBe("token-1");
+  });
+});

package/src/index.ts

@@ -39,7 +39,11 @@ export * from "./migrations/project_migrations";
 export * from "./migrations/user_migrations";
 export * from "./migrations/tenant_migrations";
 export * from "./migrations/thread_message_queue_migrations";
+export * from "./migrations/channel_identity_mapping_migration";
+export * from "./migrations/channel_installation_migrations";
 export * from "./stores/ThreadMessageQueueStore";
+export * from "./stores/ChannelIdentityMappingStore";
+export * from "./stores/PostgreSQLChannelInstallationStore";
 
 // Re-export for convenience
 export { PostgreSQLThreadStore } from "./stores/PostgreSQLThreadStore";
@@ -54,6 +58,8 @@ export { PostgreSQLProjectStore } from "./stores/PostgreSQLProjectStore";
 export { PostgreSQLUserStore } from "./stores/PostgreSQLUserStore";
 export { PostgreSQLTenantStore } from "./stores/PostgreSQLTenantStore";
 export { PostgreSQLUserTenantLinkStore } from "./stores/PostgreSQLUserTenantLinkStore";
+export { ChannelIdentityMappingStore } from "./stores/ChannelIdentityMappingStore";
+export { PostgreSQLChannelInstallationStore } from "./stores/PostgreSQLChannelInstallationStore";
 
 // Re-export types from protocols
 export type {
@@ -76,6 +82,11 @@ export type {
   UpdateDatabaseConfigRequest,
   DatabaseConfig,
   DatabaseType,
+  ChannelInstallationStore,
+  ChannelInstallation,
+  CreateChannelInstallationRequest,
+  UpdateChannelInstallationRequest,
+  LarkChannelInstallationConfig,
   MetricsServerConfigStore,
   MetricsServerConfigEntry,
   CreateMetricsServerConfigRequest,

package/src/migrations/channel_identity_mapping_migration.ts

@@ -0,0 +1,59 @@
+import { PoolClient } from "pg";
+import { Migration } from "./migration";
+
+export const createChannelIdentityMappingTables: Migration = {
+  version: 20,
+  name: "create_channel_identity_mapping_tables",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS channel_identity_mappings (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        channel VARCHAR(50) NOT NULL,
+        channel_app_id VARCHAR(255) NOT NULL,
+        tenant_id VARCHAR(255) NOT NULL,
+        assistant_id VARCHAR(255) NOT NULL,
+        mapping_mode VARCHAR(20) NOT NULL CHECK (mapping_mode IN ('user', 'group', 'hybrid')),
+        external_subject_type VARCHAR(20) NOT NULL CHECK (external_subject_type IN ('user', 'chat')),
+        external_subject_key VARCHAR(512) NOT NULL,
+        lark_open_id VARCHAR(255),
+        lark_chat_id VARCHAR(255) NOT NULL,
+        lark_message_id VARCHAR(255),
+        thread_id VARCHAR(255) NOT NULL,
+        created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        last_activity_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE (channel, channel_app_id, tenant_id, assistant_id, external_subject_key)
+      )
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_channel_identity_lookup
+      ON channel_identity_mappings(channel, channel_app_id, tenant_id, assistant_id, external_subject_key)
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_channel_identity_thread
+      ON channel_identity_mappings(thread_id, tenant_id)
+    `);
+
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS channel_inbound_message_receipts (
+        channel VARCHAR(50) NOT NULL,
+        channel_app_id VARCHAR(255) NOT NULL,
+        external_message_id VARCHAR(255) NOT NULL,
+        tenant_id VARCHAR(255) NOT NULL,
+        status VARCHAR(20) NOT NULL DEFAULT 'processing' CHECK (status IN ('processing', 'completed', 'failed')),
+        thread_id VARCHAR(255),
+        created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (channel, channel_app_id, external_message_id)
+      )
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query("DROP TABLE IF EXISTS channel_inbound_message_receipts");
+    await client.query("DROP INDEX IF EXISTS idx_channel_identity_thread");
+    await client.query("DROP INDEX IF EXISTS idx_channel_identity_lookup");
+    await client.query("DROP TABLE IF EXISTS channel_identity_mappings");
+  },
+};

package/src/migrations/channel_installation_migrations.ts

@@ -0,0 +1,31 @@
+import { PoolClient } from "pg";
+import { Migration } from "./migration";
+
+export const createChannelInstallationsTable: Migration = {
+  version: 21,
+  name: "create_channel_installations_table",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS lattice_channel_installations (
+        id UUID PRIMARY KEY,
+        tenant_id VARCHAR(255) NOT NULL,
+        channel VARCHAR(50) NOT NULL,
+        name VARCHAR(255),
+        config JSONB NOT NULL,
+        created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_channel_installations_tenant_channel
+      ON lattice_channel_installations(tenant_id, channel)
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query(
+      "DROP INDEX IF EXISTS idx_channel_installations_tenant_channel",
+    );
+    await client.query("DROP TABLE IF EXISTS lattice_channel_installations");
+  },
+};