@friggframework/core 2.0.0-next.53 → 2.0.0-next.55

package/database/encryption/encryption-schema-registry.js

@@ -109,6 +109,51 @@ function registerCustomSchema(schema) {
     );
 }
 
+/**
+ * Loads and registers custom encryption schema from appDefinition.
+ * Gracefully handles cases where appDefinition is not available.
+ *
+ * This ensures that custom encryption schemas defined in the backend's index.js
+ * are registered before any repositories attempt to encrypt data.
+ *
+ * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
+ */
+function loadCustomEncryptionSchema() {
+    try {
+        // Lazy require to avoid circular dependency issues
+        const path = require('node:path');
+        const { findNearestBackendPackageJson } = require('../../utils');
+
+        const backendPackagePath = findNearestBackendPackageJson();
+        if (!backendPackagePath) {
+            return; // No backend found, skip custom schema
+        }
+
+        const backendDir = path.dirname(backendPackagePath);
+        const backendIndexPath = path.join(backendDir, 'index.js');
+
+        const backendModule = require(backendIndexPath);
+        const appDefinition = backendModule?.Definition;
+
+        if (!appDefinition) {
+            return; // No app definition found
+        }
+
+        const customSchema = appDefinition.encryption?.schema;
+
+        if (customSchema && Object.keys(customSchema).length > 0) {
+            registerCustomSchema(customSchema);
+        }
+    } catch (error) {
+        // Silently ignore errors - custom schema is optional
+        // This handles cases like:
+        // - Backend package.json not found (tests, standalone usage)
+        // - No appDefinition defined
+        // - No custom encryption schema specified
+        logger.debug('Could not load custom encryption schema:', error.message);
+    }
+}
+
 function getEncryptedFields(modelName) {
     const coreFields = CORE_ENCRYPTION_SCHEMA[modelName]?.fields || [];
     const customFields = customSchema[modelName]?.fields || [];
@@ -136,6 +181,7 @@ module.exports = {
     hasEncryptedFields,
     getEncryptedModels,
     registerCustomSchema,
+    loadCustomEncryptionSchema,
     validateCustomSchema,
     resetCustomSchema, // For testing only
 };

package/database/prisma.js

@@ -1,7 +1,7 @@
 const {
     createEncryptionExtension,
 } = require('./encryption/prisma-encryption-extension');
-const { registerCustomSchema } = require('./encryption/encryption-schema-registry');
+const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
 const config = require('./config');
@@ -11,7 +11,7 @@ const config = require('./config');
  * Falls back to MONGO_URI if DATABASE_URL is not set
  * Infrastructure layer concern - maps legacy MONGO_URI to Prisma's expected DATABASE_URL
  * 
- * Note: This should only be called when DB_TYPE is 'mongodb'
+ * Note: This should only be called when DB_TYPE is 'mongodb' or 'documentdb'
  */
 function ensureMongoDbUrl() {
     // If DATABASE_URL is already set, use it
@@ -22,13 +22,13 @@ function ensureMongoDbUrl() {
     // Fallback to MONGO_URI for backwards compatibility with DocumentDB deployments
     if (process.env.MONGO_URI && process.env.MONGO_URI.trim()) {
         process.env.DATABASE_URL = process.env.MONGO_URI;
-        logger.debug('Using MONGO_URI as DATABASE_URL for MongoDB connection');
+        logger.debug('Using MONGO_URI as DATABASE_URL for Mongo-compatible connection');
         return;
     }
 
     // Neither is set - error
     throw new Error(
-        'DATABASE_URL or MONGO_URI environment variable must be set for MongoDB'
+        'DATABASE_URL or MONGO_URI environment variable must be set for MongoDB/DocumentDB'
     );
 }
 
@@ -59,46 +59,6 @@ function getEncryptionConfig() {
     };
 }
 
-/**
- * Loads and registers custom encryption schema from appDefinition
- * Gracefully handles cases where appDefinition is not available
- */
-function loadCustomEncryptionSchema() {
-    try {
-        // Lazy require to avoid circular dependency issues
-        const path = require('node:path');
-        const { findNearestBackendPackageJson } = require('../utils');
-
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
-        }
-
-        const backendDir = path.dirname(backendPackagePath);
-        const backendIndexPath = path.join(backendDir, 'index.js');
-
-        const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
-
-        if (!appDefinition) {
-            return; // No app definition found
-        }
-
-        const customSchema = appDefinition.encryption?.schema;
-
-        if (customSchema && Object.keys(customSchema).length > 0) {
-            registerCustomSchema(customSchema);
-        }
-    } catch (error) {
-        // Silently ignore errors - custom schema is optional
-        // This handles cases like:
-        // - Backend package.json not found (tests, standalone usage)
-        // - No appDefinition defined
-        // - No custom encryption schema specified
-        logger.debug('Could not load custom encryption schema:', error.message);
-    }
-}
-
 const prismaClientSingleton = () => {
     let PrismaClient;
 
@@ -124,7 +84,7 @@ const prismaClientSingleton = () => {
         );
     };
 
-    if (config.DB_TYPE === 'mongodb') {
+    if (config.DB_TYPE === 'mongodb' || config.DB_TYPE === 'documentdb') {
         // Ensure DATABASE_URL is set (fallback to MONGO_URI if needed)
         ensureMongoDbUrl();
         PrismaClient = loadPrismaClient('mongodb');
@@ -132,7 +92,7 @@ const prismaClientSingleton = () => {
         PrismaClient = loadPrismaClient('postgresql');
     } else {
         throw new Error(
-            `Unsupported database type: ${config.DB_TYPE}. Supported values: 'mongodb', 'postgresql'`
+            `Unsupported database type: ${config.DB_TYPE}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
         );
     }
 
@@ -205,7 +165,7 @@ async function connectPrisma() {
     // Initialize MongoDB schema - ensure all collections exist
     // Only run for MongoDB/DocumentDB (not PostgreSQL)
     // This prevents "Cannot create namespace in multi-document transaction" errors
-    if (config.DB_TYPE === 'mongodb') {
+    if (config.DB_TYPE === 'mongodb' || config.DB_TYPE === 'documentdb') {
         const { initializeMongoDBSchema } = require('./utils/mongodb-schema-init');
         await initializeMongoDBSchema();
     }

package/database/repositories/health-check-repository-documentdb.js

@@ -0,0 +1,134 @@
+const {
+    HealthCheckRepositoryInterface,
+} = require('./health-check-repository-interface');
+const {
+    toObjectId,
+    fromObjectId,
+    findOne,
+    insertOne,
+    deleteOne,
+} = require('../documentdb-utils');
+const { DocumentDBEncryptionService } = require('../documentdb-encryption-service');
+
+class HealthCheckRepositoryDocumentDB extends HealthCheckRepositoryInterface {
+    /**
+     * @param {Object} params
+     * @param {Object} params.prismaClient - Prisma client instance
+     */
+    constructor({ prismaClient }) {
+        super();
+        this.prisma = prismaClient;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    /**
+     * @returns {Promise<{readyState: number, stateName: string, isConnected: boolean}>}
+     */
+    async getDatabaseConnectionState() {
+        let isConnected = false;
+        let stateName = 'unknown';
+
+        try {
+            await this.prisma.$runCommandRaw({ ping: 1 });
+            isConnected = true;
+            stateName = 'connected';
+        } catch (error) {
+            stateName = 'disconnected';
+        }
+
+        return {
+            readyState: isConnected ? 1 : 0,
+            stateName,
+            isConnected,
+        };
+    }
+
+    /**
+     * @param {number} maxTimeMS
+     * @returns {Promise<number>} Response time in milliseconds
+     */
+    async pingDatabase(maxTimeMS = 2000) {
+        const pingStart = Date.now();
+
+        const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Database ping timeout')), maxTimeMS)
+        );
+
+        await Promise.race([
+            this.prisma.$runCommandRaw({ ping: 1 }),
+            timeoutPromise,
+        ]);
+
+        return Date.now() - pingStart;
+    }
+
+    async createCredential(credentialData) {
+        const now = new Date();
+        const document = {
+            ...credentialData,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        // Encrypt sensitive fields before insert
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'Credential',
+            document
+        );
+        const insertedId = await insertOne(this.prisma, 'Credential', encryptedDocument);
+        const created = await findOne(this.prisma, 'Credential', { _id: insertedId });
+
+        // Decrypt after read
+        const decrypted = await this.encryptionService.decryptFields(
+            'Credential',
+            created
+        );
+
+        return {
+            id: fromObjectId(decrypted._id),
+            ...decrypted,
+        };
+    }
+
+    async findCredentialById(id) {
+        const doc = await findOne(this.prisma, 'Credential', {
+            _id: toObjectId(id),
+        });
+
+        if (!doc) return null;
+
+        // Decrypt sensitive fields
+        const decrypted = await this.encryptionService.decryptFields('Credential', doc);
+
+        return {
+            id: fromObjectId(decrypted._id),
+            ...decrypted,
+        };
+    }
+
+    async getRawCredentialById(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return null;
+
+        const result = await this.prisma.$runCommandRaw({
+            find: 'Credential',
+            filter: { _id: objectId },
+        });
+
+        // Return raw document WITHOUT decryption
+        // This allows the test to verify that fields are actually encrypted in the database
+        return result?.cursor?.firstBatch?.[0] ?? null;
+    }
+
+    async deleteCredential(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return false;
+
+        const result = await deleteOne(this.prisma, 'Credential', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return deleted > 0;
+    }
+}
+
+module.exports = { HealthCheckRepositoryDocumentDB };
+

package/database/repositories/health-check-repository-factory.js

@@ -1,5 +1,6 @@
 const { HealthCheckRepositoryMongoDB } = require('./health-check-repository-mongodb');
 const { HealthCheckRepositoryPostgreSQL } = require('./health-check-repository-postgres');
+const { HealthCheckRepositoryDocumentDB } = require('./health-check-repository-documentdb');
 const config = require('../config');
 
 /**
@@ -29,9 +30,12 @@ function createHealthCheckRepository({ prismaClient } = {}) {
         case 'postgresql':
             return new HealthCheckRepositoryPostgreSQL({ prismaClient });
 
+        case 'documentdb':
+            return new HealthCheckRepositoryDocumentDB({ prismaClient });
+
         default:
             throw new Error(
-                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'postgresql'`
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
             );
     }
 }
@@ -40,4 +44,5 @@ module.exports = {
     createHealthCheckRepository,
     HealthCheckRepositoryMongoDB,
     HealthCheckRepositoryPostgreSQL,
+    HealthCheckRepositoryDocumentDB,
 };

package/database/repositories/health-check-repository-interface.js

@@ -15,72 +15,67 @@
  */
 class HealthCheckRepositoryInterface {
     /**
-     * Ping database to verify connectivity
-     *
-     * @param {number} maxTimeMS - Maximum time in milliseconds
-     * @returns {Promise<number>} Response time in milliseconds
+     * @returns {Promise<{readyState: number, stateName: string, isConnected: boolean}>}
      * @abstract
      */
-    async pingDatabase(maxTimeMS) {
-        throw new Error('Method pingDatabase must be implemented by subclass');
+    async getDatabaseConnectionState() {
+        throw new Error('Method getDatabaseConnectionState must be implemented by subclass');
     }
 
     /**
-     * Save a test document
+     * Ping database to verify connectivity
      *
-     * @param {Object} TestModel - Prisma model
-     * @param {Object} data - Data to save
-     * @returns {Promise<Object>} Saved document
+     * @param {number} maxTimeMS - Maximum time in milliseconds
+     * @returns {Promise<number>} Response time in milliseconds
      * @abstract
      */
-    async saveTestDocument(TestModel, data) {
-        throw new Error('Method saveTestDocument must be implemented by subclass');
+    async pingDatabase(maxTimeMS) {
+        throw new Error('Method pingDatabase must be implemented by subclass');
     }
 
     /**
-     * Find test document by ID
+     * Persist an encrypted credential for health verification.
+     * Implementations should rely on Prisma so encryption middleware runs.
      *
-     * @param {Object} TestModel - Prisma model
-     * @param {string|number} id - Document ID
-     * @returns {Promise<Object|null>} Document or null
+     * @param {Object} credentialData
+     * @returns {Promise<Object>} Persisted credential
      * @abstract
      */
-    async findTestDocumentById(TestModel, id) {
-        throw new Error('Method findTestDocumentById must be implemented by subclass');
+    async createCredential(credentialData) {
+        throw new Error('Method createCredential must be implemented by subclass');
     }
 
     /**
-     * Get raw document from collection
+     * Retrieve credential by ID using Prisma (decrypted).
      *
-     * @param {string} collectionName - Collection name
-     * @param {Object} filter - Filter criteria
-     * @returns {Promise<Object|null>} Raw document or null
+     * @param {string} id
+     * @returns {Promise<Object|null>}
      * @abstract
      */
-    async getRawDocumentFromCollection(collectionName, filter) {
-        throw new Error('Method getRawDocumentFromCollection must be implemented by subclass');
+    async findCredentialById(id) {
+        throw new Error('Method findCredentialById must be implemented by subclass');
     }
 
     /**
-     * Delete test document
+     * Fetch raw credential document from the database (without decryption).
      *
-     * @param {Object} TestModel - Prisma model
-     * @param {string|number} id - Document ID
-     * @returns {Promise<Object>} Deletion result
+     * @param {string} id
+     * @returns {Promise<Object|null>}
      * @abstract
      */
-    async deleteTestDocument(TestModel, id) {
-        throw new Error('Method deleteTestDocument must be implemented by subclass');
+    async getRawCredentialById(id) {
+        throw new Error('Method getRawCredentialById must be implemented by subclass');
     }
 
     /**
-     * Get database connection state
+     * Delete credential by ID.
      *
-     * @returns {Promise<Object>} Connection state info
+     * @param {string} id
+     * @returns {Promise<void>}
      * @abstract
      */
-    async getDatabaseConnectionState() {
-        throw new Error('Method getDatabaseConnectionState must be implemented by subclass');
+    async deleteCredential(id) {
+        throw new Error('Method deleteCredential must be implemented by subclass');
     }
 }
 

package/database/repositories/health-check-repository-mongodb.js

@@ -52,9 +52,7 @@ class HealthCheckRepositoryMongoDB extends HealthCheckRepositoryInterface {
             }),
             timeoutPromise
         ]);
-        
-        return Date.now() - pingStart;
-    }
+
         return Date.now() - pingStart;
     }
 

package/database/use-cases/check-database-state-use-case.js

@@ -32,7 +32,7 @@ class CheckDatabaseStateUseCase {
     /**
      * Execute check migration status
      * 
-     * @param {string} dbType - Database type (postgresql or mongodb)
+     * @param {string} dbType - Database type (postgresql, mongodb, or documentdb)
      * @param {string} stage - Deployment stage (default: 'production')
      * @returns {Promise<Object>} Migration status
      */
@@ -42,8 +42,8 @@ class CheckDatabaseStateUseCase {
             throw new ValidationError('dbType is required');
         }
 
-        if (!['postgresql', 'mongodb'].includes(dbType)) {
-            throw new ValidationError('dbType must be postgresql or mongodb');
+        if (!['postgresql', 'mongodb', 'documentdb'].includes(dbType)) {
+            throw new ValidationError('dbType must be postgresql, mongodb, or documentdb');
         }
 
         console.log(`Checking migration status for ${dbType} in ${stage}`);

package/database/use-cases/run-database-migration-use-case.js

@@ -26,7 +26,7 @@ class RunDatabaseMigrationUseCase {
      * Execute database migration
      *
      * @param {Object} params
-     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.dbType - Database type ('postgresql', 'mongodb', or 'documentdb')
      * @param {string} params.stage - Deployment stage (determines migration command)
      * @param {boolean} [params.verbose=false] - Enable verbose output
      * @returns {Promise<Object>} Migration result { success, dbType, stage, command, message }
@@ -61,19 +61,21 @@ class RunDatabaseMigrationUseCase {
                     { dbType, stage, command: migrationCommand, step: 'migrate', output: migrationResult.output }
                 );
             }
-        } else if (dbType === 'mongodb') {
+        } else if (dbType === 'mongodb' || dbType === 'documentdb') {
             migrationCommand = 'db push';
             // Use non-interactive mode for automated/Lambda environments
             migrationResult = await this.prismaRunner.runPrismaDbPush(verbose, true);
 
             if (!migrationResult.success) {
                 throw new MigrationError(
-                    `MongoDB push failed: ${migrationResult.error || 'Unknown error'}`,
+                    `Mongo-compatible push failed: ${migrationResult.error || 'Unknown error'}`,
                     { dbType, stage, command: migrationCommand, step: 'push', output: migrationResult.output }
                 );
             }
         } else {
-            throw new ValidationError(`Unsupported database type: ${dbType}. Must be 'postgresql' or 'mongodb'.`);
+            throw new ValidationError(
+                `Unsupported database type: ${dbType}. Must be 'postgresql', 'mongodb', or 'documentdb'.`
+            );
         }
 
         // Return success result

package/database/use-cases/trigger-database-migration-use-case.js

@@ -38,7 +38,7 @@ class TriggerDatabaseMigrationUseCase {
      *
      * @param {Object} params
      * @param {string} params.userId - User ID triggering the migration
-     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.dbType - Database type ('postgresql', 'mongodb', or 'documentdb')
      * @param {string} params.stage - Deployment stage (determines migration command)
      * @returns {Promise<Object>} Process info { success, processId, state, statusUrl, message }
      * @throws {ValidationError} If parameters are invalid
@@ -123,7 +123,7 @@ class TriggerDatabaseMigrationUseCase {
             throw new ValidationError('dbType must be a string');
         }
 
-        const validDbTypes = ['postgresql', 'mongodb'];
+        const validDbTypes = ['postgresql', 'mongodb', 'documentdb'];
         if (!validDbTypes.includes(dbType)) {
             throw new ValidationError(
                 `Invalid dbType: "${dbType}". Must be one of: ${validDbTypes.join(', ')}`

package/database/utils/mongodb-schema-init.js

@@ -47,9 +47,9 @@ const config = require('../config');
  * ```
  */
 async function initializeMongoDBSchema() {
-    // Only run for MongoDB
-    if (config.DB_TYPE !== 'mongodb') {
-        console.log('Schema initialization skipped - not using MongoDB');
+    // Only run for MongoDB-compatible databases
+    if (config.DB_TYPE !== 'mongodb' && config.DB_TYPE !== 'documentdb') {
+        console.log('Schema initialization skipped - not using MongoDB-compatible database');
         return;
     }
 
@@ -61,7 +61,7 @@ async function initializeMongoDBSchema() {
         );
     }
 
-    console.log('Initializing MongoDB schema - ensuring all collections exist...');
+    console.log('Initializing MongoDB-compatible schema - ensuring all collections exist...');
     const startTime = Date.now();
 
     try {
@@ -77,7 +77,7 @@ async function initializeMongoDBSchema() {
 
         const duration = Date.now() - startTime;
         console.log(
-            `MongoDB schema initialization complete - ${collections.length} collections verified (${duration}ms)`
+            `MongoDB-compatible schema initialization complete - ${collections.length} collections verified (${duration}ms)`
         );
     } catch (error) {
         console.error('Failed to initialize MongoDB schema:', error.message);

package/database/utils/prisma-runner.js

@@ -10,12 +10,17 @@ const chalk = require('chalk');
 
 /**
  * Gets the path to the Prisma schema file for the database type
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @param {string} projectRoot - Project root directory
  * @returns {string} Absolute path to schema file
  * @throws {Error} If schema file doesn't exist
  */
+function normalizeMongoCompatible(dbType) {
+    return dbType === 'documentdb' ? 'mongodb' : dbType;
+}
+
 function getPrismaSchemaPath(dbType, projectRoot = process.cwd()) {
+    const normalizedType = normalizeMongoCompatible(dbType);
     // Try multiple locations for the schema file
     // Priority order:
     // 1. Lambda layer path (where the schema actually exists in deployed Lambda)
@@ -23,10 +28,10 @@ function getPrismaSchemaPath(dbType, projectRoot = process.cwd()) {
     // 3. Parent node_modules (workspace/monorepo setup)
     const possiblePaths = [
         // Lambda layer path - this is where the schema actually exists in deployed Lambda
-        `/opt/nodejs/node_modules/generated/prisma-${dbType}/schema.prisma`,
+        `/opt/nodejs/node_modules/generated/prisma-${normalizedType}/schema.prisma`,
         // Check where Frigg is installed via npm (production scenario)
-        path.join(projectRoot, 'node_modules', '@friggframework', 'core', `prisma-${dbType}`, 'schema.prisma'),
-        path.join(projectRoot, '..', 'node_modules', '@friggframework', 'core', `prisma-${dbType}`, 'schema.prisma')
+        path.join(projectRoot, 'node_modules', '@friggframework', 'core', `prisma-${normalizedType}`, 'schema.prisma'),
+        path.join(projectRoot, '..', 'node_modules', '@friggframework', 'core', `prisma-${normalizedType}`, 'schema.prisma')
     ];
 
     for (const schemaPath of possiblePaths) {
@@ -44,7 +49,7 @@ function getPrismaSchemaPath(dbType, projectRoot = process.cwd()) {
 
 /**
  * Runs prisma generate for the specified database type
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @param {boolean} verbose - Enable verbose output
  * @returns {Promise<Object>} { success: boolean, output?: string, error?: string }
  */
@@ -53,18 +58,19 @@ async function runPrismaGenerate(dbType, verbose = false) {
         const schemaPath = getPrismaSchemaPath(dbType);
 
         // Check if Prisma client already exists (e.g., in Lambda or pre-generated)
-        const generatedClientPath = path.join(path.dirname(path.dirname(schemaPath)), 'generated', `prisma-${dbType}`, 'client.js');
+        const normalizedType = normalizeMongoCompatible(dbType);
+        const generatedClientPath = path.join(path.dirname(path.dirname(schemaPath)), 'generated', `prisma-${normalizedType}`, 'client.js');
         const isLambdaEnvironment = !!process.env.AWS_LAMBDA_FUNCTION_NAME || !!process.env.LAMBDA_TASK_ROOT;
 
         // In Lambda, also check the layer path (/opt/nodejs/node_modules)
-        const lambdaLayerClientPath = `/opt/nodejs/node_modules/generated/prisma-${dbType}/client.js`;
+        const lambdaLayerClientPath = `/opt/nodejs/node_modules/generated/prisma-${normalizedType}/client.js`;
 
         const clientExists = fs.existsSync(generatedClientPath) || (isLambdaEnvironment && fs.existsSync(lambdaLayerClientPath));
 
         if (clientExists) {
             const foundPath = fs.existsSync(generatedClientPath) ? generatedClientPath : lambdaLayerClientPath;
             if (verbose) {
-                console.log(chalk.gray(`✓ Prisma client already generated at: ${foundPath}`));
+            console.log(chalk.gray(`✓ Prisma client already generated at: ${foundPath}`));
             }
             if (isLambdaEnvironment) {
                 if (verbose) {
@@ -110,7 +116,7 @@ async function runPrismaGenerate(dbType, verbose = false) {
 
 /**
  * Checks database migration status
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @returns {Promise<Object>} { upToDate: boolean, pendingMigrations?: number, error?: string }
  */
 async function checkDatabaseState(dbType) {

package/errors/client-safe-error.js

@@ -0,0 +1,26 @@
+const { BaseError } = require('./base-error');
+
+/**
+ * ClientSafeError - An error that is safe to expose to end users
+ *
+ * Use this error class when the error message does not contain sensitive
+ * implementation details and can be safely shown to users.
+ *
+ * Examples:
+ * - "Invalid Token: Token is expired"
+ * - "User not found"
+ * - "Invalid credentials"
+ *
+ * @param {string} message - The user-safe error message
+ * @param {number} statusCode - HTTP status code (default: 400)
+ * @param {object} options - Additional error options (cause, etc.)
+ */
+class ClientSafeError extends BaseError {
+    constructor(message, statusCode = 400, options) {
+        super(message, options);
+        this.statusCode = statusCode;
+        this.isClientSafe = true;
+    }
+}
+
+module.exports = { ClientSafeError };

package/errors/fetch-error.js

@@ -61,8 +61,9 @@ class FetchError extends BaseError {
         ];
 
         super(messageParts.filter(Boolean).join('\n'));
-        
+
         this.response = response;
+        this.statusCode = response?.status;
     }
 
     static async create(options = {}) {