@qwickapps/server 1.7.1 → 1.8.0

package/src/plugins/api-keys/api-keys-plugin.ts

@@ -23,22 +23,25 @@ import {
   CreateApiKeySchema,
   UpdateApiKeySchema,
 } from './types.js';
+import { hasPostgres, getPostgres } from '../postgres-plugin.js';
+import { postgresApiKeyStore } from './stores/index.js';
 
 // Store instance for helper access
 let currentStore: ApiKeyStore | null = null;
 
 /**
- * Create the API Keys plugin
+ * Create the API Keys plugin with smart defaults
+ *
+ * Config is optional - plugin will use defaults and get dependencies from registry.
+ * Gracefully handles missing dependencies with clear log messages.
  */
-export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
-  const debug = config.debug || false;
-  // Framework automatically prefixes routes with plugin slug, so use root path
-  const apiPrefix = config.api?.prefix || '/';
-  const apiEnabled = config.api?.enabled !== false;
-
-  function log(message: string, data?: Record<string, unknown>) {
-    if (debug) {
-      console.log(`[ApiKeysPlugin] ${message}`, data || '');
+export function createApiKeysPlugin(config: Partial<ApiKeysPluginConfig> = {}): Plugin {
+  function log(message: string, data?: Record<string, unknown>, isError = false) {
+    const prefix = '[ApiKeysPlugin]';
+    if (isError) {
+      console.error(`${prefix} ${message}`, data || '');
+    } else if (config.debug) {
+      console.log(`${prefix} ${message}`, data || '');
     }
   }
 
@@ -48,15 +51,113 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
     version: '1.0.0',
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
-      log('Starting API keys plugin');
+      const logger = registry.getLogger('api-keys');
 
       // Check for users plugin dependency
       if (!registry.hasPlugin('users')) {
-        throw new Error('API Keys plugin requires Users plugin to be loaded first');
+        logger.warn('Users plugin not loaded! API Keys plugin disabled.');
+        registry.registerHealthCheck({
+          name: 'api-keys-store',
+          type: 'custom',
+          check: async () => ({
+            healthy: false,
+            details: {
+              error: 'Users plugin not available',
+              state: 'disabled',
+            },
+          }),
+        });
+        return;
       }
 
+      // Check for postgres in registry
+      if (!hasPostgres()) {
+        logger.warn('No Database! API Keys plugin disabled.');
+        registry.registerHealthCheck({
+          name: 'api-keys-store',
+          type: 'custom',
+          check: async () => ({
+            healthy: false,
+            details: {
+              error: 'PostgreSQL not available',
+              state: 'disabled',
+            },
+          }),
+        });
+        return;
+      }
+
+      // Smart defaults - get dependencies from registry
+      const store = config.store ?? postgresApiKeyStore({
+        pool: () => getPostgres().getPool(),
+        autoCreateTables: true,
+      });
+
+      const debug = config.debug ?? false;
+      const apiPrefix = config.api?.prefix ?? '/api-keys';
+      const apiEnabled = config.api?.enabled ?? true;
+
+      log('Starting API keys plugin');
+
       // Initialize the store (creates tables and RLS policies if needed)
-      await config.store.initialize();
+      const initResult = await store.initialize();
+
+      if (!initResult.success) {
+        logger.error('API keys store initialization failed', { error: initResult.error });
+
+        // If migration is required, register maintenance actions
+        if (initResult.requiresMaintenance) {
+          registry.registerMaintenance({
+            pluginId: 'api-keys',
+            error: initResult.error || 'Store initialization failed',
+            actions: [
+              {
+                id: 'truncate-api-keys-table',
+                name: 'Clear API Keys Table',
+                description: 'Delete all API keys from the database. This allows the migration to proceed by removing old data.',
+                destructive: true,
+                handler: async () => {
+                  try {
+                    const pool = getPostgres().getPool();
+                    await pool.query('TRUNCATE TABLE "public"."api_keys" CASCADE');
+                    logger.info('API keys table truncated successfully');
+                    return {
+                      success: true,
+                      message: 'API keys table cleared. Plugin will retry initialization.',
+                    };
+                  } catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error('Failed to truncate API keys table', { error: errorMessage });
+                    return {
+                      success: false,
+                      error: `Failed to truncate table: ${errorMessage}`,
+                    };
+                  }
+                },
+              },
+            ],
+            recommendedAction: 'truncate-api-keys-table',
+          });
+
+          logger.warn('API keys plugin requires maintenance - registered recovery actions');
+        }
+
+        // Register unhealthy health check
+        registry.registerHealthCheck({
+          name: 'api-keys-store',
+          type: 'custom',
+          check: async () => ({
+            healthy: false,
+            details: {
+              error: initResult.error || 'Initialization failed',
+              requiresMaintenance: initResult.requiresMaintenance,
+            },
+          }),
+        });
+
+        return;  // Don't continue startup
+      }
+
       log('API keys store initialized');
 
       // Initialize optional Phase 2 stores
@@ -71,7 +172,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
       }
 
       // Store reference for helper access
-      currentStore = config.store;
+      currentStore = store;
 
       // Register health check
       registry.registerHealthCheck({
@@ -117,7 +218,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
               };
 
               // Create the API key
-              const apiKey = await config.store.create(params);
+              const apiKey = await store.create(params);
 
               // Return the key with plaintext (ONLY time plaintext is accessible)
               res.status(201).json({
@@ -152,7 +253,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
                 return res.status(401).json({ error: 'Authentication required' });
               }
 
-              const keys = await config.store.list(userId);
+              const keys = await store.list(userId);
 
               // Remove sensitive fields from response
               const sanitized = keys.map(key => ({
@@ -191,7 +292,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
               }
 
               const { id } = req.params;
-              const key = await config.store.get(userId, id);
+              const key = await store.get(userId, id);
 
               if (!key) {
                 return res.status(404).json({ error: 'API key not found' });
@@ -244,7 +345,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
               const { id } = req.params;
               const params: UpdateApiKeyParams = validation.data;
 
-              const updated = await config.store.update(userId, id, params);
+              const updated = await store.update(userId, id, params);
 
               if (!updated) {
                 return res.status(404).json({ error: 'API key not found' });
@@ -287,7 +388,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
               }
 
               const { id } = req.params;
-              const deleted = await config.store.delete(userId, id);
+              const deleted = await store.delete(userId, id);
 
               if (!deleted) {
                 return res.status(404).json({ error: 'API key not found' });
@@ -357,7 +458,7 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
                 const { id: keyId } = req.params;
 
                 // Verify key belongs to user
-                const key = await config.store.get(userId, keyId);
+                const key = await store.get(userId, keyId);
                 if (!key) {
                   return res.status(404).json({ error: 'API key not found' });
                 }

package/src/plugins/api-keys/index.ts

@@ -31,6 +31,7 @@ export type {
   UpdateApiKeyParams,
   PostgresApiKeyStoreConfig,
   ApiKeysApiConfig,
+  StoreInitializationResult,
 } from './types.js';
 
 // Zod schemas
@@ -48,8 +49,5 @@ export { postgresApiKeyStore } from './stores/index.js';
 // Middleware
 export { bearerTokenAuth } from './middleware/index.js';
 
-// UI Components
-export { ApiKeysStatusWidget } from './ApiKeysStatusWidget.js';
-export type { ApiKeysStatusWidgetProps } from './ApiKeysStatusWidget.js';
-export { ApiKeysManagementPage } from './ApiKeysManagementPage.js';
-export type { ApiKeysManagementPageProps } from './ApiKeysManagementPage.js';
+// UI Components are exported from main package index (@qwickapps/server)
+// Do NOT export here to avoid loading UI dependencies when importing plugins

package/src/plugins/api-keys/stores/postgres-store.ts

@@ -21,6 +21,7 @@ import type {
   UpdateApiKeyParams,
   ApiKey,
   ApiKeyWithPlaintext,
+  StoreInitializationResult,
 } from '../types.js';
 
 // Pool interface (from pg package)
@@ -239,82 +240,104 @@ export function postgresApiKeyStore(config: PostgresApiKeyStoreConfig): ApiKeySt
   return {
     name: 'postgres',
 
-    async initialize(): Promise<void> {
-      if (!autoCreateTables) return;
+    async initialize(): Promise<StoreInitializationResult> {
+      if (!autoCreateTables) {
+        return { success: true };
+      }
 
-      const pool = getPool();
+      try {
+        const pool = getPool();
 
-      // Create table with foreign key to users
-      await pool.query(`
-        CREATE TABLE IF NOT EXISTS ${tableFullName} (
-          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-          user_id UUID NOT NULL REFERENCES "public"."users"(id) ON DELETE CASCADE,
-          name VARCHAR(255) NOT NULL,
-          key_hash VARCHAR(64) NOT NULL,
-          key_prefix VARCHAR(12) NOT NULL,
-          key_type VARCHAR(10) NOT NULL CHECK (key_type IN ('m2m', 'pat')),
-          scopes TEXT[] NOT NULL DEFAULT '{}',
-          last_used_at TIMESTAMPTZ,
-          expires_at TIMESTAMPTZ,
-          is_active BOOLEAN NOT NULL DEFAULT true,
-          created_at TIMESTAMPTZ DEFAULT NOW(),
-          updated_at TIMESTAMPTZ DEFAULT NOW()
-        );
+        // Create table with foreign key to users
+        await pool.query(`
+          CREATE TABLE IF NOT EXISTS ${tableFullName} (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            user_id UUID NOT NULL REFERENCES "public"."users"(id) ON DELETE CASCADE,
+            name VARCHAR(255) NOT NULL,
+            key_hash VARCHAR(64) NOT NULL,
+            key_prefix VARCHAR(12) NOT NULL,
+            key_type VARCHAR(10) NOT NULL CHECK (key_type IN ('m2m', 'pat')),
+            scopes TEXT[] NOT NULL DEFAULT '{}',
+            last_used_at TIMESTAMPTZ,
+            expires_at TIMESTAMPTZ,
+            is_active BOOLEAN NOT NULL DEFAULT true,
+            created_at TIMESTAMPTZ DEFAULT NOW(),
+            updated_at TIMESTAMPTZ DEFAULT NOW()
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
+          CREATE INDEX IF NOT EXISTS idx_${tableName}_key_prefix ON ${tableFullName}(key_prefix);
+          CREATE INDEX IF NOT EXISTS idx_${tableName}_key_hash ON ${tableFullName}(key_hash);
+        `);
 
-        CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
-        CREATE INDEX IF NOT EXISTS idx_${tableName}_key_prefix ON ${tableFullName}(key_prefix);
-        CREATE INDEX IF NOT EXISTS idx_${tableName}_key_hash ON ${tableFullName}(key_hash);
-      `);
-
-      // Migration: Add user_id column if it doesn't exist (for existing installations)
-      await pool.query(`
-        DO $$
-        DECLARE
-          row_count INTEGER;
-        BEGIN
-          IF NOT EXISTS (
-            SELECT 1 FROM information_schema.columns
-            WHERE table_schema = '${schema}'
-            AND table_name = '${tableName}'
-            AND column_name = 'user_id'
-          ) THEN
-            -- Check if table has data
-            EXECUTE 'SELECT COUNT(*) FROM ${tableFullName}' INTO row_count;
-
-            IF row_count > 0 THEN
-              -- If table has data, cannot add NOT NULL column
-              -- This requires manual migration or data cleanup
-              RAISE EXCEPTION 'Cannot add user_id column: table ${tableFullName} contains % rows. Please migrate data or clear the table first.', row_count;
-            ELSE
-              -- Table is empty, safe to add NOT NULL column
+        // Migration: Check if table needs user_id column migration
+        const needsMigration = await pool.query(`
+          SELECT
+            NOT EXISTS (
+              SELECT 1 FROM information_schema.columns
+              WHERE table_schema = '${schema}'
+              AND table_name = '${tableName}'
+              AND column_name = 'user_id'
+            ) AS missing_column,
+            (SELECT COUNT(*) FROM ${tableFullName}) AS row_count
+        `);
+
+        const { missing_column, row_count } = needsMigration.rows[0] as { missing_column: boolean; row_count: number };
+
+        if (missing_column) {
+          if (row_count > 0) {
+            // Table has data but is missing user_id column - requires maintenance
+            logger.warn(
+              `Table ${tableFullName} has ${row_count} rows but is missing user_id column. ` +
+              `Requires maintenance action to migrate or clear data.`
+            );
+            return {
+              success: false,
+              error: `Table ${tableFullName} contains ${row_count} rows without user_id column. Migration required.`,
+              requiresMaintenance: true,
+            };
+          } else {
+            // Table is empty, safe to add NOT NULL column
+            await pool.query(`
               ALTER TABLE ${tableFullName}
               ADD COLUMN user_id UUID NOT NULL REFERENCES "public"."users"(id) ON DELETE CASCADE;
 
               CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
-            END IF;
-          END IF;
-        END $$;
-      `);
-
-      // Enable RLS if configured
-      if (enableRLS) {
-        await pool.query(`
-          ALTER TABLE ${tableFullName} ENABLE ROW LEVEL SECURITY;
-          ALTER TABLE ${tableFullName} FORCE ROW LEVEL SECURITY;
-        `);
+            `);
+            logger.info(`Added user_id column to empty table ${tableFullName}`);
+          }
+        }
 
-        // Create or replace the RLS policy
-        await pool.query(`
-          DROP POLICY IF EXISTS "${tableName}_owner" ON ${tableFullName};
-        `);
+        // Enable RLS if configured
+        if (enableRLS) {
+          await pool.query(`
+            ALTER TABLE ${tableFullName} ENABLE ROW LEVEL SECURITY;
+            ALTER TABLE ${tableFullName} FORCE ROW LEVEL SECURITY;
+          `);
+
+          // Create or replace the RLS policy
+          await pool.query(`
+            DROP POLICY IF EXISTS "${tableName}_owner" ON ${tableFullName};
+          `);
+
+          // RLS policy: users can only access their own keys
+          await pool.query(`
+            CREATE POLICY "${tableName}_owner" ON ${tableFullName}
+              FOR ALL
+              USING (user_id::text = current_setting('app.current_user_id', true))
+              WITH CHECK (user_id::text = current_setting('app.current_user_id', true));
+          `);
+        }
 
-        // RLS policy: users can only access their own keys
-        await pool.query(`
-          CREATE POLICY "${tableName}_owner" ON ${tableFullName}
-            FOR ALL
-            USING (user_id::text = current_setting('app.current_user_id', true))
-            WITH CHECK (user_id::text = current_setting('app.current_user_id', true));
-        `);
+        logger.info(`API keys store initialized successfully (table: ${tableFullName})`);
+        return { success: true };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to initialize API keys store: ${errorMessage}`, { error });
+        return {
+          success: false,
+          error: `Database initialization failed: ${errorMessage}`,
+        };
       }
     },
 

package/src/plugins/api-keys/types.ts

@@ -140,6 +140,18 @@ export interface ApiKeyWithPlaintext extends ApiKey {
   plaintext_key: string;
 }
 
+/**
+ * Result of store initialization
+ */
+export interface StoreInitializationResult {
+  /** Whether initialization succeeded */
+  success: boolean;
+  /** Error message if initialization failed */
+  error?: string;
+  /** Additional details about what needs to be done */
+  requiresMaintenance?: boolean;
+}
+
 /**
  * API key store interface - all storage backends must implement this
  */
@@ -149,8 +161,9 @@ export interface ApiKeyStore {
 
   /**
    * Initialize the store (create tables, RLS policies, etc.)
+   * Returns initialization status instead of throwing
    */
-  initialize(): Promise<void>;
+  initialize(): Promise<StoreInitializationResult>;
 
   /**
    * Create a new API key
@@ -230,17 +243,23 @@ export interface ApiKeysApiConfig {
 
 /**
  * API keys plugin configuration
+ *
+ * All properties are optional - plugin will use smart defaults:
+ * - store: Postgres API key store using registry's postgres instance
+ * - api.prefix: '/api-keys'
+ * - api.enabled: true
+ * - debug: false
  */
 export interface ApiKeysPluginConfig {
-  /** API key storage backend */
-  store: ApiKeyStore;
+  /** API key storage backend (default: postgres API key store from registry) */
+  store?: ApiKeyStore;
   /** Plugin scope storage backend (optional, for Phase 2) */
   scopeStore?: import('./stores/plugin-scope-store.js').PluginScopeStore;
   /** Usage log storage backend (optional, for Phase 2) */
   usageStore?: import('./stores/usage-log-store.js').UsageLogStore;
   /** API configuration */
   api?: ApiKeysApiConfig;
-  /** Enable debug logging */
+  /** Enable debug logging (default: false) */
   debug?: boolean;
 }
 

package/src/plugins/auth/index.ts

@@ -65,8 +65,6 @@ export { basicAdapter } from './adapters/basic-adapter.js';
 export { supabaseAdapter } from './adapters/supabase-adapter.js';
 export { supertokensAdapter } from './adapters/supertokens-adapter.js';
 
-// UI Components
-export { AuthStatusWidget } from './AuthStatusWidget.js';
-export type { AuthStatusWidgetProps } from './AuthStatusWidget.js';
-export { AuthManagementPage } from './AuthManagementPage.js';
-export type { AuthManagementPageProps } from './AuthManagementPage.js';
+// UI Components are exported from main package index (@qwickapps/server)
+// Do NOT export here to avoid loading UI dependencies when importing plugins
+