@pineliner/odb-client 1.0.0

package/src/service/service-client.ts

@@ -0,0 +1,316 @@
+/**
+ * Service Client - High-level client for managing tenant databases via ODB-Lite Tenant API
+ *
+ * This client provides automatic database provisioning and management for multi-tenant applications.
+ * It handles:
+ * - Automatic database creation on first use
+ * - Database hash caching for performance
+ * - Tenant API integration with ODB-Lite
+ * - Query execution via ODB-Lite's query API
+ *
+ * @example
+ * ```typescript
+ * const service = new ServiceClient({
+ *   baseUrl: 'http://localhost:8671',
+ *   apiKey: 'odblite_tenant_key'
+ * });
+ *
+ * // Automatically creates database if it doesn't exist
+ * const dbHash = await service.ensureDatabaseForTenant('wallet', 'tenant-123');
+ *
+ * // Execute queries
+ * const result = await service.query(dbHash, 'SELECT * FROM wallets', []);
+ * ```
+ */
+
+export interface ODBLiteDatabase {
+  hash: string;
+  name: string;
+  tenantId: string;
+  nodeId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ODBLiteNode {
+  nodeId: string;
+  url: string;
+  status: string;
+  lastHealthCheck: string;
+}
+
+export interface ServiceClientConfig {
+  /** Base URL of ODB-Lite server (e.g., http://localhost:8671) */
+  baseUrl: string;
+  /** Tenant API key for authentication */
+  apiKey: string;
+}
+
+/**
+ * Service Client for managing tenant databases in ODB-Lite
+ *
+ * This is a higher-level client that sits on top of the base ODB client.
+ * It provides automatic database provisioning and management for services
+ * that need per-tenant database isolation.
+ */
+export class ServiceClient {
+  private apiUrl: string;
+  private apiKey: string;
+  private databaseCache: Map<string, string>; // cacheKey -> databaseHash
+
+  constructor(config: ServiceClientConfig) {
+    this.apiUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.databaseCache = new Map();
+  }
+
+  /**
+   * Get or create a database for a tenant
+   *
+   * This is the main method used by services. It will:
+   * 1. Check the cache for an existing database hash
+   * 2. Query ODB-Lite to see if the database exists
+   * 3. Create the database if it doesn't exist
+   * 4. Cache and return the database hash
+   *
+   * @param prefix - Database name prefix (e.g., 'wallet', 'tracking')
+   * @param tenantId - Tenant identifier
+   * @returns Database hash for querying
+   *
+   * @example
+   * ```typescript
+   * const hash = await service.ensureDatabaseForTenant('wallet', 'tenant-123');
+   * // Returns hash for database named 'wallet_tenant-123'
+   * ```
+   */
+  async ensureDatabaseForTenant(prefix: string, tenantId: string): Promise<string> {
+    const cacheKey = `${prefix}_${tenantId}`;
+    console.log(`📊 Ensuring database for ${cacheKey}`);
+
+    // Check cache first
+    const cached = this.databaseCache.get(cacheKey);
+    if (cached) {
+      console.log(`✅ Found cached database hash: ${cached}`);
+      return cached;
+    }
+
+    try {
+      // Check if database already exists
+      console.log(`🔍 Checking if database exists: ${cacheKey}`);
+      const databases = await this.listDatabases();
+      const existing = databases.find(db => db.name === cacheKey);
+
+      if (existing) {
+        console.log(`✅ Database already exists: ${cacheKey} (${existing.hash})`);
+        this.databaseCache.set(cacheKey, existing.hash);
+        return existing.hash;
+      }
+
+      // Create new database
+      console.log(`🆕 Creating new database: ${cacheKey}`);
+      const nodes = await this.listNodes();
+      console.log(`📡 Available nodes: ${nodes.length}`);
+
+      if (nodes.length === 0) {
+        throw new Error('No available nodes to create database');
+      }
+
+      // Use first healthy node
+      const node = nodes.find(n => n.status === 'healthy') || nodes[0];
+      if (!node) {
+        throw new Error('No available nodes to create database');
+      }
+      console.log(`🎯 Using node: ${node.nodeId}`);
+
+      const database = await this.createDatabase(cacheKey, node.nodeId);
+      console.log(`✅ Database created successfully: ${database.hash}`);
+
+      this.databaseCache.set(cacheKey, database.hash);
+      return database.hash;
+    } catch (error: any) {
+      console.error(`❌ Error ensuring database for ${cacheKey}:`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * List all databases owned by this tenant
+   *
+   * Queries ODB-Lite's tenant API to get all databases accessible with the current API key.
+   *
+   * @returns Array of database objects
+   */
+  async listDatabases(): Promise<ODBLiteDatabase[]> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/databases`, {
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to list databases');
+    }
+
+    return result.databases;
+  }
+
+  /**
+   * Create a new database
+   *
+   * @param name - Database name (should be unique)
+   * @param nodeId - ID of the node to host the database
+   * @returns Created database object with hash
+   */
+  async createDatabase(name: string, nodeId: string): Promise<ODBLiteDatabase> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/databases`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ name, nodeId }),
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to create database');
+    }
+
+    return result.database;
+  }
+
+  /**
+   * Get database details by hash
+   *
+   * @param hash - Database hash
+   * @returns Database object
+   */
+  async getDatabase(hash: string): Promise<ODBLiteDatabase> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/databases/${hash}`, {
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to get database');
+    }
+
+    return result.database;
+  }
+
+  /**
+   * Delete a database
+   *
+   * @param hash - Database hash to delete
+   */
+  async deleteDatabase(hash: string): Promise<void> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/databases/${hash}`, {
+      method: 'DELETE',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to delete database');
+    }
+
+    // Remove from cache
+    for (const [key, cachedHash] of this.databaseCache.entries()) {
+      if (cachedHash === hash) {
+        this.databaseCache.delete(key);
+        break;
+      }
+    }
+  }
+
+  /**
+   * List available nodes
+   *
+   * @returns Array of node objects
+   */
+  async listNodes(): Promise<ODBLiteNode[]> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/nodes`, {
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to list nodes');
+    }
+
+    return result.nodes;
+  }
+
+  /**
+   * Execute a query on a specific database
+   *
+   * This is a low-level query method. For most use cases, you should use
+   * the full ODB client (`odblite()` function) instead, which provides
+   * template tag support and better ergonomics.
+   *
+   * @param databaseHash - Hash of the database to query
+   * @param sql - SQL query string
+   * @param params - Query parameters
+   * @returns Query result
+   */
+  async query<T = any>(databaseHash: string, sql: string, params: any[] = []): Promise<T> {
+    const response = await fetch(`${this.apiUrl}/query/${databaseHash}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ sql, params }),
+    });
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Query failed');
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Clear the database hash cache
+   *
+   * Useful when database mappings have changed or for testing.
+   */
+  clearCache(): void {
+    this.databaseCache.clear();
+  }
+
+  /**
+   * Get cached database hash for a specific tenant (if exists)
+   *
+   * @param prefix - Database name prefix
+   * @param tenantId - Tenant identifier
+   * @returns Cached hash or undefined
+   */
+  getCachedHash(prefix: string, tenantId: string): string | undefined {
+    const cacheKey = `${prefix}_${tenantId}`;
+    return this.databaseCache.get(cacheKey);
+  }
+
+  /**
+   * Pre-cache a database hash
+   *
+   * Useful when you know the mapping ahead of time and want to avoid
+   * the initial lookup.
+   *
+   * @param prefix - Database name prefix
+   * @param tenantId - Tenant identifier
+   * @param hash - Database hash
+   */
+  setCachedHash(prefix: string, tenantId: string, hash: string): void {
+    const cacheKey = `${prefix}_${tenantId}`;
+    this.databaseCache.set(cacheKey, hash);
+  }
+}

package/src/types.ts

@@ -0,0 +1,127 @@
+// Core types for the ODBLite client
+export interface ODBLiteConfig {
+  baseUrl: string;
+  apiKey: string;
+  databaseId?: string;
+  timeout?: number;
+  retries?: number;
+}
+
+export interface QueryResult<T = any> {
+  rows: T[];
+  rowsAffected: number;
+  executionTime: number;
+  databaseName?: string;
+}
+
+export interface ODBLiteResponse<T = any> {
+  success: boolean;
+  data?: T[];
+  rows?: T[];
+  rowsAffected?: number;
+  executionTime?: number;
+  dbId?: string;
+  databaseName?: string;
+  error?: string;
+}
+
+// Template string SQL types
+export interface SQLFragment {
+  text: string;
+  values: any[];
+}
+
+export interface PreparedQuery {
+  sql: string;
+  params: any[];
+}
+
+// Transaction types - uses same callable pattern as main sql function
+export interface Transaction {
+  // Primary call signatures - context-aware like main sql function
+  <T = any>(sql: TemplateStringsArray, ...values: any[]): Promise<QueryResult<T>>;
+  <T = any>(input: any): SQLFragment; // For tx(object), tx(array), etc.
+
+  // Utility methods
+  raw(text: string): string;
+  identifier(name: string): string;
+
+  // Additional query methods for compatibility
+  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+  execute<T = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<T>>;
+
+  // Savepoint support (postgres.js style)
+  savepoint<T = any>(callback: (sql: Transaction) => Promise<T>): Promise<T>;
+
+  // Transaction control
+  rollback(): Promise<void>;
+  commit(): Promise<void>;
+}
+
+// Transaction callback function type
+export type TransactionCallback<T = any> = (sql: Transaction) => Promise<T> | T | Promise<T[]> | T[];
+
+// Transaction mode type
+export type TransactionMode = 'read write' | 'read only' | string;
+
+// Connection interface similar to postgres.js
+export interface ODBLiteConnection {
+  // Template string queries (postgres.js style)
+  sql<T = any>(sql: TemplateStringsArray, ...values: any[]): Promise<QueryResult<T>>;
+
+  // Raw query method
+  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+
+  // Transaction support
+  begin(): Promise<Transaction>;
+
+  // Health check
+  ping(): Promise<boolean>;
+
+  // Close connection
+  end(): Promise<void>;
+
+  // Configuration
+  config: ODBLiteConfig;
+}
+
+// Helper types for PostgreSQL-like features
+export type PrimitiveType = string | number | boolean | null | Date | Buffer;
+export type QueryParameter = PrimitiveType | PrimitiveType[];
+
+// Row result types
+export interface Row {
+  [column: string]: any;
+}
+
+// Error types
+export class ODBLiteError extends Error {
+  constructor(
+    message: string,
+    public code?: string,
+    public query?: string,
+    public params?: any[]
+  ) {
+    super(message);
+    this.name = 'ODBLiteError';
+  }
+}
+
+export class ConnectionError extends ODBLiteError {
+  constructor(message: string, public originalError?: Error) {
+    super(message, 'CONNECTION_ERROR');
+    this.name = 'ConnectionError';
+  }
+}
+
+export class QueryError extends ODBLiteError {
+  constructor(
+    message: string,
+    query?: string,
+    params?: any[],
+    public originalError?: Error
+  ) {
+    super(message, 'QUERY_ERROR', query, params);
+    this.name = 'QueryError';
+  }
+}