@ketrics/sdk-backend 0.2.0

package/dist/database-errors.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Ketrics SDK - Database Error Classes
+ *
+ * Provides typed errors for database operations in tenant applications.
+ *
+ * Error Hierarchy:
+ * - DatabaseError (base)
+ *   - DatabaseNotFoundError
+ *   - DatabaseAccessDeniedError
+ *   - DatabaseConnectionError
+ *   - DatabaseQueryError
+ *   - DatabaseTransactionError
+ *
+ * Security Note: Error messages MUST NOT expose internal details like:
+ * - Connection strings or credentials
+ * - Tenant IDs
+ * - Internal database names
+ * - AWS account information
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseTransactionError = exports.DatabaseQueryError = exports.DatabaseConnectionError = exports.DatabaseAccessDeniedError = exports.DatabaseNotFoundError = exports.DatabaseError = void 0;
+exports.isDatabaseError = isDatabaseError;
+exports.isDatabaseErrorType = isDatabaseErrorType;
+// ============================================================================
+// Base Error Class
+// ============================================================================
+/**
+ * Base error class for all Database errors
+ *
+ * All Database errors extend this class and include:
+ * - databaseCode: The database code that caused the error
+ * - operation: The operation that failed
+ * - timestamp: When the error occurred
+ */
+class DatabaseError extends Error {
+    constructor(databaseCode, operation, message) {
+        super(message);
+        this.name = this.constructor.name;
+        this.databaseCode = databaseCode;
+        this.operation = operation;
+        this.timestamp = new Date();
+        // Maintains proper stack trace for where error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Serialize error for logging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            databaseCode: this.databaseCode,
+            operation: this.operation,
+            timestamp: this.timestamp.toISOString(),
+        };
+    }
+}
+exports.DatabaseError = DatabaseError;
+// ============================================================================
+// Specific Error Classes
+// ============================================================================
+/**
+ * Error thrown when a database is not found
+ *
+ * Thrown when DatabaseConnection.connect() is called with a database code
+ * that doesn't exist in the tenant's namespace.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const db = await ketrics.DatabaseConnection.connect('unknown-db');
+ * } catch (error) {
+ *   if (error instanceof ketrics.DatabaseNotFoundError) {
+ *     console.log(`Database '${error.databaseCode}' not found`);
+ *   }
+ * }
+ * ```
+ */
+class DatabaseNotFoundError extends DatabaseError {
+    constructor(databaseCode) {
+        super(databaseCode, 'connect', `Database '${databaseCode}' not found`);
+    }
+}
+exports.DatabaseNotFoundError = DatabaseNotFoundError;
+/**
+ * Error thrown when application does not have access to a database
+ *
+ * Thrown when DatabaseConnection.connect() is called for a database that exists
+ * but the executing application has not been granted access.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const db = await ketrics.DatabaseConnection.connect('restricted-db');
+ * } catch (error) {
+ *   if (error instanceof ketrics.DatabaseAccessDeniedError) {
+ *     console.log(`No access to database '${error.databaseCode}'`);
+ *   }
+ * }
+ * ```
+ */
+class DatabaseAccessDeniedError extends DatabaseError {
+    constructor(databaseCode) {
+        super(databaseCode, 'connect', `Application does not have access to database '${databaseCode}'`);
+    }
+}
+exports.DatabaseAccessDeniedError = DatabaseAccessDeniedError;
+/**
+ * Error thrown when a database connection cannot be established
+ *
+ * Thrown when the database connection cannot be established due to
+ * network issues, authentication failures, or server unavailability.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const db = await ketrics.DatabaseConnection.connect('main-db');
+ * } catch (error) {
+ *   if (error instanceof ketrics.DatabaseConnectionError) {
+ *     console.log(`Connection failed: ${error.reason}`);
+ *   }
+ * }
+ * ```
+ */
+class DatabaseConnectionError extends DatabaseError {
+    constructor(databaseCode, reason) {
+        super(databaseCode, 'connect', `Failed to connect to database '${databaseCode}': ${reason}`);
+        this.reason = reason;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            reason: this.reason,
+        };
+    }
+}
+exports.DatabaseConnectionError = DatabaseConnectionError;
+/**
+ * Error thrown when a database query fails
+ *
+ * Thrown when a SQL query fails to execute due to syntax errors,
+ * constraint violations, or other database-level errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await db.query('SELECT * FROM nonexistent_table');
+ * } catch (error) {
+ *   if (error instanceof ketrics.DatabaseQueryError) {
+ *     console.log(`Query failed: ${error.reason}`);
+ *   }
+ * }
+ * ```
+ */
+class DatabaseQueryError extends DatabaseError {
+    constructor(databaseCode, reason, sql) {
+        super(databaseCode, 'query', `Query failed: ${reason}`);
+        this.reason = reason;
+        // Only include SQL if it's safe (no sensitive data)
+        if (sql && sql.length <= 200) {
+            this.sql = sql;
+        }
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            reason: this.reason,
+            ...(this.sql && { sql: this.sql }),
+        };
+    }
+}
+exports.DatabaseQueryError = DatabaseQueryError;
+/**
+ * Error thrown when a database transaction fails
+ *
+ * Thrown when a transaction fails to commit or encounters an error
+ * during execution that requires rollback.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await db.transaction(async (tx) => {
+ *     await tx.execute('INSERT INTO users VALUES (...)');
+ *     throw new Error('Simulated failure');
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ketrics.DatabaseTransactionError) {
+ *     console.log(`Transaction failed: ${error.reason}`);
+ *     console.log(`Rolled back: ${error.rolledBack}`);
+ *   }
+ * }
+ * ```
+ */
+class DatabaseTransactionError extends DatabaseError {
+    constructor(databaseCode, reason, rolledBack = true) {
+        super(databaseCode, 'transaction', `Transaction failed${rolledBack ? ' (rolled back)' : ''}: ${reason}`);
+        this.reason = reason;
+        this.rolledBack = rolledBack;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            reason: this.reason,
+            rolledBack: this.rolledBack,
+        };
+    }
+}
+exports.DatabaseTransactionError = DatabaseTransactionError;
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if an error is a DatabaseError
+ *
+ * @param error - The error to check
+ * @returns True if the error is a DatabaseError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const db = await ketrics.DatabaseConnection.connect('main-db');
+ * } catch (error) {
+ *   if (isDatabaseError(error)) {
+ *     console.log(`Database error: ${error.databaseCode}`);
+ *   }
+ * }
+ * ```
+ */
+function isDatabaseError(error) {
+    return error instanceof DatabaseError;
+}
+/**
+ * Type guard to check if an error is a specific DatabaseError type
+ *
+ * @param error - The error to check
+ * @param errorClass - The error class to check against
+ * @returns True if the error is an instance of the specified class
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const db = await ketrics.DatabaseConnection.connect('main-db');
+ * } catch (error) {
+ *   if (isDatabaseErrorType(error, DatabaseNotFoundError)) {
+ *     console.log('Database not found');
+ *   } else if (isDatabaseErrorType(error, DatabaseAccessDeniedError)) {
+ *     console.log('Access denied');
+ *   }
+ * }
+ * ```
+ */
+function isDatabaseErrorType(error, errorClass) {
+    return error instanceof errorClass;
+}
+//# sourceMappingURL=database-errors.js.map

package/dist/database-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-errors.js","sourceRoot":"","sources":["../src/database-errors.ts"],"names":[],"mappings":"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"}

package/dist/databases.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Ketrics SDK - Database Interfaces
+ *
+ * Provides type definitions for accessing external database connections
+ * from tenant applications.
+ *
+ * Usage in tenant code:
+ * ```typescript
+ * // Connect to a database
+ * const db = await ketrics.DatabaseConnection.connect('main-db');
+ *
+ * // Query data
+ * const result = await db.query('SELECT * FROM users WHERE id = ?', [1]);
+ * console.log(result.rows);
+ *
+ * // Execute statement
+ * await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+ *
+ * // Transaction
+ * await db.transaction(async (tx) => {
+ *   await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 1]);
+ *   await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 2]);
+ * });
+ *
+ * // Close connection
+ * await db.close();
+ * ```
+ */
+/**
+ * Database Query Result
+ *
+ * Result from executing a SELECT query.
+ */
+export interface DatabaseQueryResult<T = unknown> {
+    /** Result rows */
+    rows: T[];
+    /** Number of rows returned */
+    rowCount: number;
+    /** Affected rows (for INSERT/UPDATE/DELETE) */
+    affectedRows?: number;
+}
+/**
+ * Database Execute Result
+ *
+ * Result from executing an INSERT, UPDATE, or DELETE statement.
+ */
+export interface DatabaseExecuteResult {
+    /** Number of affected rows */
+    affectedRows: number;
+    /** Insert ID (if applicable) */
+    insertId?: number | string;
+}
+/**
+ * Database Connection Interface
+ *
+ * Interface for executing SQL queries against external databases.
+ * Use `DatabaseConnection.connect()` to obtain an instance.
+ *
+ * @example
+ * ```typescript
+ * const db = await ketrics.DatabaseConnection.connect('main-db');
+ * try {
+ *   const result = await db.query<User>('SELECT * FROM users WHERE id = ?', [1]);
+ *   console.log(result.rows);
+ * } finally {
+ *   await db.close();
+ * }
+ * ```
+ */
+export interface IDatabaseConnection {
+    /** Database code (read-only) */
+    readonly code: string;
+    /** Granted permissions for this database (read-only) */
+    readonly permissions: ReadonlySet<string>;
+    /**
+     * Execute a SELECT query
+     *
+     * @param sql - SQL query string with parameter placeholders
+     * @param params - Optional array of parameter values
+     * @returns Query result with rows and row count
+     * @throws DatabaseQueryError if query fails
+     *
+     * @example
+     * ```typescript
+     * const result = await db.query('SELECT * FROM users WHERE age > ?', [18]);
+     * console.log(result.rows);     // [{ id: 1, name: 'John', age: 25 }, ...]
+     * console.log(result.rowCount); // 10
+     * ```
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<DatabaseQueryResult<T>>;
+    /**
+     * Execute an INSERT, UPDATE, or DELETE statement
+     *
+     * @param sql - SQL statement string with parameter placeholders
+     * @param params - Optional array of parameter values
+     * @returns Execute result with affected row count
+     * @throws DatabaseQueryError if statement fails
+     *
+     * @example
+     * ```typescript
+     * const result = await db.execute(
+     *   'INSERT INTO users (name, email) VALUES (?, ?)',
+     *   ['John', 'john@example.com']
+     * );
+     * console.log(result.affectedRows); // 1
+     * console.log(result.insertId);     // 123
+     * ```
+     */
+    execute(sql: string, params?: unknown[]): Promise<DatabaseExecuteResult>;
+    /**
+     * Execute operations within a transaction
+     *
+     * The transaction automatically commits if the function completes successfully,
+     * or rolls back if an error is thrown.
+     *
+     * @param fn - Async function that receives a transaction connection
+     * @returns Result of the transaction function
+     * @throws DatabaseTransactionError if transaction fails
+     *
+     * @example
+     * ```typescript
+     * await db.transaction(async (tx) => {
+     *   await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 1]);
+     *   await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 2]);
+     * });
+     * ```
+     */
+    transaction<T>(fn: (tx: IDatabaseConnection) => Promise<T>): Promise<T>;
+    /**
+     * Close the database connection
+     *
+     * Returns the connection to the pool for reuse.
+     * Always close connections when done to prevent pool exhaustion.
+     *
+     * @example
+     * ```typescript
+     * const db = await ketrics.DatabaseConnection.connect('main-db');
+     * try {
+     *   // Use database...
+     * } finally {
+     *   await db.close();
+     * }
+     * ```
+     */
+    close(): Promise<void>;
+}
+/**
+ * @deprecated Use `ketrics.DatabaseConnection.connect()` instead
+ *
+ * Legacy interface - maintained for backward compatibility.
+ * New code should use `ketrics.DatabaseConnection.connect()`.
+ */
+export interface DatabaseManager {
+    /**
+     * @deprecated Use `ketrics.DatabaseConnection.connect()` instead
+     *
+     * Connect to a database by code
+     *
+     * @param databaseCode - Database code (e.g., "main-db", "analytics-db")
+     * @returns DatabaseConnection or null if no permission
+     * @throws Error if database server not found or connection fails
+     */
+    connect(databaseCode: string): Promise<IDatabaseConnection | null>;
+}
+//# sourceMappingURL=databases.d.ts.map

package/dist/databases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.d.ts","sourceRoot":"","sources":["../src/databases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,kBAAkB;IAClB,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEzE;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAExE;;;;;;;;;;;;;;;OAeG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACpE"}

package/dist/databases.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Ketrics SDK - Database Interfaces
+ *
+ * Provides type definitions for accessing external database connections
+ * from tenant applications.
+ *
+ * Usage in tenant code:
+ * ```typescript
+ * // Connect to a database
+ * const db = await ketrics.DatabaseConnection.connect('main-db');
+ *
+ * // Query data
+ * const result = await db.query('SELECT * FROM users WHERE id = ?', [1]);
+ * console.log(result.rows);
+ *
+ * // Execute statement
+ * await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+ *
+ * // Transaction
+ * await db.transaction(async (tx) => {
+ *   await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 1]);
+ *   await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 2]);
+ * });
+ *
+ * // Close connection
+ * await db.close();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=databases.js.map

package/dist/databases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.js","sourceRoot":"","sources":["../src/databases.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}