@axiom-lattice/pg-stores 1.0.66 → 1.0.68

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/pg-stores@1.0.66 build /home/runner/work/agentic/agentic/packages/pg-stores
+> @axiom-lattice/pg-stores@1.0.68 build /home/runner/work/agentic/agentic/packages/pg-stores
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/index.js     203.86 KB
-CJS dist/index.js.map 375.22 KB
-CJS ⚡️ Build success in 411ms
-ESM dist/index.mjs     198.84 KB
-ESM dist/index.mjs.map 375.06 KB
-ESM ⚡️ Build success in 434ms
+CJS dist/index.js     204.37 KB
+CJS dist/index.js.map 377.59 KB
+CJS ⚡️ Build success in 523ms
+ESM dist/index.mjs     199.35 KB
+ESM dist/index.mjs.map 377.44 KB
+ESM ⚡️ Build success in 527ms
 DTS Build start
-DTS ⚡️ Build success in 12103ms
-DTS dist/index.d.ts  47.54 KB
-DTS dist/index.d.mts 47.54 KB
+DTS ⚡️ Build success in 13443ms
+DTS dist/index.d.ts  48.13 KB
+DTS dist/index.d.mts 48.13 KB

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @axiom-lattice/pg-stores
 
+## 1.0.68
+
+### Patch Changes
+
+- Updated dependencies [176bfe8]
+  - @axiom-lattice/core@2.1.77
+
+## 1.0.67
+
+### Patch Changes
+
+- 6ff5bd5: fix issue
+- Updated dependencies [6ff5bd5]
+  - @axiom-lattice/core@2.1.76
+  - @axiom-lattice/protocols@2.1.39
+
 ## 1.0.66
 
 ### Patch Changes

package/README.md

@@ -1,341 +1,108 @@
 # @axiom-lattice/pg-stores
 
-PostgreSQL stores implementation for the Axiom Lattice framework.
+PostgreSQL store implementations for the Axiom Lattice framework.
 
-## Overview
-
-This package provides PostgreSQL-based store implementations that conform to the store interfaces. It can be used with the `StoreLatticeManager` from `@axiom-lattice/core` to register and manage PostgreSQL-based store services.
-
-## Features
-
-- **ThreadStore**: PostgreSQL implementation for thread management
-- **AssistantStore**: PostgreSQL implementation for assistant management
-- **Migration System**: Automatic schema migration with version tracking
-- **Type Safety**: Full TypeScript support with proper type definitions
-
-## Installation
-
-```bash
-pnpm add @axiom-lattice/pg-stores
-```
-
-## Prerequisites
-
-- PostgreSQL database (version 12 or higher)
-- Node.js 18 or higher
-
-## Usage
-
-### Basic Usage - Register ThreadStore
+## Quick Start
 
 ```typescript
-import { PostgreSQLThreadStore } from "@axiom-lattice/pg-stores";
-import { registerStoreLattice, getStoreLattice } from "@axiom-lattice/core";
-
-// Create and initialize ThreadStore with connection string
-const threadStore = new PostgreSQLThreadStore({
-  poolConfig: process.env.DATABASE_URL || "postgresql://localhost:5432/mydb",
-});
+import { configureStores } from "@axiom-lattice/core";
+import { createPgStoreConfig } from "@axiom-lattice/pg-stores";
+import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
 
-// Ensure initialization (migrations run automatically)
-await threadStore.initialize();
+// One connection string creates all PG stores
+const stores = createPgStoreConfig(process.env.DATABASE_URL);
 
-// Register to StoreLatticeManager
-registerStoreLattice("threads", "thread", threadStore);
-
-// Or use PoolConfig object
-const threadStore2 = new PostgreSQLThreadStore({
-  poolConfig: {
-    host: process.env.DB_HOST || "localhost",
-    port: parseInt(process.env.DB_PORT || "5432"),
-    database: process.env.DB_NAME || "mydb",
-    user: process.env.DB_USER,
-    password: process.env.DB_PASSWORD,
-  },
+// Register all stores in one call
+await configureStores({
+  ...stores,
+  checkpoint: PostgresSaver.fromConnString(process.env.DATABASE_URL),
 });
-
-await threadStore2.initialize();
-registerStoreLattice("threads", "thread", threadStore2);
 ```
 
-### Basic Usage - Register AssistantStore
-
-```typescript
-import { PostgreSQLAssistantStore } from "@axiom-lattice/pg-stores";
-import { registerStoreLattice, getStoreLattice } from "@axiom-lattice/core";
-
-// Create and initialize AssistantStore with connection string
-const assistantStore = new PostgreSQLAssistantStore({
-  poolConfig: process.env.DATABASE_URL || "postgresql://localhost:5432/mydb",
-});
-
-// Ensure initialization (migrations run automatically)
-await assistantStore.initialize();
-
-// Register to StoreLatticeManager
-registerStoreLattice("assistants", "assistant", assistantStore);
-
-// Get and use the store (with type safety)
-const storeLattice = getStoreLattice("assistants", "assistant");
-const assistantStoreInstance = storeLattice.store; // TypeScript knows this is AssistantStore
-
-// Create an assistant
-const assistant = await assistantStoreInstance.createAssistant(
-  "assistant-123",
-  {
-    name: "My Assistant",
-    description: "A helpful assistant",
-    graphDefinition: {
-      /* ... */
-    },
-  }
-);
-
-// Get all assistants
-const assistants = await assistantStoreInstance.getAllAssistants();
+## `createPgStoreConfig`
 
-// Get a specific assistant
-const foundAssistant = await assistantStoreInstance.getAssistantById(
-  "assistant-123"
-);
+Factory function that creates all PG store instances from a single connection string. Returns an object ready to spread into `configureStores()`.
 
-// Update assistant
-const updatedAssistant = await assistantStoreInstance.updateAssistant(
-  "assistant-123",
-  {
-    name: "Updated Name",
-  }
-);
-
-// Delete assistant
-await assistantStoreInstance.deleteAssistant("assistant-123");
+```typescript
+function createPgStoreConfig(connectionString: string): {
+  workspace: PostgreSQLWorkspaceStore;
+  project: PostgreSQLProjectStore;
+  eval: PostgreSQLEvalStore;
+  user: PostgreSQLUserStore;
+  tenant: PostgreSQLTenantStore;
+  userTenantLink: PostgreSQLUserTenantLinkStore;
+  channelBinding: ChannelBindingStore;
+  channelInstallation: PostgreSQLChannelInstallationStore;
+  thread: PostgreSQLThreadStore;
+  database: PostgreSQLDatabaseConfigStore;
+  metrics: PostgreSQLMetricsServerConfigStore;
+  mcp: PostgreSQLMcpServerConfigStore;
+  assistant: PostgreSQLAssistantStore;
+  workflowTracking: PostgreSQLWorkflowTrackingStore;
+  threadMessageQueue: ThreadMessageQueueStore;
+  schedule: PostgreSQLScheduleStorage;
+}
 ```
 
-// Get and use the store (with type safety)
-const storeLattice = getStoreLattice("threads", "thread");
-const threadStore = storeLattice.store; // TypeScript knows this is ThreadStore
-
-// Create a thread
-const thread = await threadStore.createThread("assistant-123", "thread-456", {
-metadata: { title: "My Thread" },
-});
-
-// Get threads by assistant
-const threads = await threadStore.getThreadsByAssistantId("assistant-123");
+Stores with `autoMigrate: true`: eval, channelBinding, channelInstallation, workflowTracking, threadMessageQueue.
+All others use `autoMigrate: false` (manual `initialize()` via `configureStores`).
 
-// Get a specific thread
-const foundThread = await threadStore.getThreadById(
-"assistant-123",
-"thread-456"
-);
+## Individual Store Usage
 
-// Update thread
-const updatedThread = await threadStore.updateThread(
-"assistant-123",
-"thread-456",
-{ metadata: { title: "Updated Title" } }
-);
-
-// Delete thread
-await threadStore.deleteThread("assistant-123", "thread-456");
-
-````
-
-### Direct Usage (Without Registration)
+If you only need specific stores, construct them directly:
 
 ```typescript
-import { PostgreSQLThreadStore } from "@axiom-lattice/pg-stores";
+import { configureStores } from "@axiom-lattice/core";
+import { PostgreSQLThreadStore, PostgreSQLAssistantStore } from "@axiom-lattice/pg-stores";
 
-// Create store instance with connection string (migrations run automatically)
-const threadStore = new PostgreSQLThreadStore({
-  poolConfig: process.env.DATABASE_URL || "postgresql://localhost:5432/mydb",
-  autoMigrate: true, // Default: true
+await configureStores({
+  thread: new PostgreSQLThreadStore({ poolConfig: process.env.DATABASE_URL }),
+  assistant: new PostgreSQLAssistantStore({ poolConfig: process.env.DATABASE_URL }),
 });
+```
 
-// Ensure initialization
-await threadStore.initialize();
-
-// When done, dispose the store to close connections
-// await threadStore.dispose();
-
-// Use the store
-const threads = await threadStore.getThreadsByAssistantId("assistant-123");
-````
-
-### Manual Migration Control
+## Available Stores
+
+| Store | Class | Description |
+|-------|-------|-------------|
+| thread | `PostgreSQLThreadStore` | Thread CRUD |
+| assistant | `PostgreSQLAssistantStore` | Assistant CRUD |
+| skill | `PostgreSQLSkillStore` | Skill storage |
+| workspace | `PostgreSQLWorkspaceStore` | Workspace management |
+| project | `PostgreSQLProjectStore` | Project management |
+| database | `PostgreSQLDatabaseConfigStore` | DB connection configs |
+| metrics | `PostgreSQLMetricsServerConfigStore` | Metrics server configs |
+| mcp | `PostgreSQLMcpServerConfigStore` | MCP server configs |
+| user | `PostgreSQLUserStore` | User storage |
+| tenant | `PostgreSQLTenantStore` | Tenant storage |
+| userTenantLink | `PostgreSQLUserTenantLinkStore` | User-tenant links |
+| threadMessageQueue | `ThreadMessageQueueStore` | Message queue persistence |
+| workflowTracking | `PostgreSQLWorkflowTrackingStore` | Workflow run tracking |
+| eval | `PostgreSQLEvalStore` | Evaluation storage |
+| channelInstallation | `PostgreSQLChannelInstallationStore` | Channel installations |
+| channelBinding | `ChannelBindingStore` | Sender-to-agent bindings |
+| schedule | `PostgreSQLScheduleStorage` | Scheduled task persistence |
+
+## Constructor Options
+
+All stores accept the same options pattern:
 
 ```typescript
-import { PostgreSQLThreadStore } from "@axiom-lattice/pg-stores";
-
-// Create store without auto-migration
-const threadStore = new PostgreSQLThreadStore({
-  poolConfig: process.env.DATABASE_URL || "postgresql://localhost:5432/mydb",
-  autoMigrate: false,
-});
-
-// Manually run migrations when ready
-await threadStore.initialize();
+interface StoreOptions {
+  poolConfig: string | PoolConfig;  // Connection string or PoolConfig object
+  autoMigrate?: boolean;            // Run migrations automatically (default: true)
+}
 ```
 
 ## Migration System
 
-The package includes a migration system that automatically:
-
-1. Creates the `lattice_schema_migrations` table to track applied migrations
-2. Applies pending migrations in order
-3. Tracks migration versions to prevent duplicate applications
-
-### How Migrations Work
-
-Migrations run automatically when you create a store instance (unless `autoMigrate: false`):
+Each store manages its own schema migrations via `MigrationManager`. Migrations run during `initialize()`.
 
 ```typescript
-// Migrations run automatically on initialization
-const threadStore = new PostgreSQLThreadStore({
+// Manual control
+const store = new PostgreSQLThreadStore({
   poolConfig: process.env.DATABASE_URL,
-  autoMigrate: true, // Default: true
+  autoMigrate: false,
 });
-
-await threadStore.initialize(); // Migrations are applied here
+await store.initialize(); // Migrations applied here
 ```
-
-### Migration Structure
-
-Migrations are defined with:
-
-- **version**: Sequential version number (must be unique)
-- **name**: Descriptive migration name
-- **up**: Migration function to apply changes (creates/modifies tables)
-- **down**: Optional rollback function (for undoing migrations)
-
-### Using MigrationManager Directly
-
-For more control, you can use `MigrationManager` directly:
-
-```typescript
-import { Pool } from "pg";
-import { MigrationManager } from "@axiom-lattice/pg-stores";
-import { createThreadsTable } from "@axiom-lattice/pg-stores";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const migrationManager = new MigrationManager(pool);
-
-// Register migrations
-migrationManager.register(createThreadsTable);
-
-// Apply pending migrations
-await migrationManager.migrate();
-
-// Check current version
-const version = await migrationManager.getCurrentVersion();
-
-// Rollback last migration (if down migration exists)
-await migrationManager.rollback();
-```
-
-### Current Migrations
-
-- **ThreadStore Version 1**: `create_threads_table` - Creates the threads table with indexes
-- **AssistantStore Version 1**: `create_assistants_table` - Creates the assistants table with indexes
-
-For detailed migration usage, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md).
-
-## Database Schema
-
-### lattice_threads Table
-
-```sql
-CREATE TABLE lattice_threads (
-  id VARCHAR(255) NOT NULL,
-  assistant_id VARCHAR(255) NOT NULL,
-  metadata JSONB DEFAULT '{}',
-  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  PRIMARY KEY (id, assistant_id)
-);
-
-CREATE INDEX idx_lattice_threads_assistant_id ON lattice_threads(assistant_id);
-CREATE INDEX idx_lattice_threads_created_at ON lattice_threads(created_at DESC);
-```
-
-### lattice_assistants Table
-
-```sql
-CREATE TABLE lattice_assistants (
-  id VARCHAR(255) PRIMARY KEY,
-  name VARCHAR(255) NOT NULL,
-  description TEXT,
-  graph_definition JSONB NOT NULL,
-  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_lattice_assistants_name ON lattice_assistants(name);
-CREATE INDEX idx_lattice_assistants_created_at ON lattice_assistants(created_at DESC);
-```
-
-## Configuration
-
-The PostgreSQL store can be configured via:
-
-1. **Constructor options**: Pass `poolConfig` (connection string or PoolConfig object) and `autoMigrate` directly
-2. **Environment variables**:
-   - `DATABASE_URL` - PostgreSQL connection string (recommended)
-   - `DB_HOST` - Database host (if using PoolConfig object)
-   - `DB_PORT` - Database port (if using PoolConfig object)
-   - `DB_USER` - Database user (if using PoolConfig object)
-   - `DB_PASSWORD` - Database password (if using PoolConfig object)
-   - `DB_NAME` - Database name (if using PoolConfig object)
-
-### PoolConfig Options
-
-You can pass either:
-
-- **Connection string**: `"postgresql://user:password@host:port/database"`
-- **PoolConfig object**: `{ host, port, database, user, password, ... }` (see [pg PoolConfig](https://node-postgres.com/api/pool) for all options)
-
-## API Reference
-
-### ThreadStore Interface
-
-```typescript
-interface ThreadStore {
-  getThreadsByAssistantId(assistantId: string): Promise<Thread[]>;
-  getThreadById(
-    assistantId: string,
-    threadId: string
-  ): Promise<Thread | undefined>;
-  createThread(
-    assistantId: string,
-    threadId: string,
-    data: CreateThreadRequest
-  ): Promise<Thread>;
-  updateThread(
-    assistantId: string,
-    threadId: string,
-    updates: Partial<CreateThreadRequest>
-  ): Promise<Thread | null>;
-  deleteThread(assistantId: string, threadId: string): Promise<boolean>;
-  hasThread(assistantId: string, threadId: string): Promise<boolean>;
-}
-```
-
-### AssistantStore Interface
-
-```typescript
-interface AssistantStore {
-  getAllAssistants(): Promise<Assistant[]>;
-  getAssistantById(id: string): Promise<Assistant | undefined>;
-  createAssistant(id: string, data: CreateAssistantRequest): Promise<Assistant>;
-  updateAssistant(
-    id: string,
-    updates: Partial<CreateAssistantRequest>
-  ): Promise<Assistant | null>;
-  deleteAssistant(id: string): Promise<boolean>;
-  hasAssistant(id: string): Promise<boolean>;
-}
-```
-
-## License
-
-MIT