@qwickapps/server 1.1.9 → 1.3.0

package/src/plugins/users/stores/postgres-store.ts

@@ -0,0 +1,225 @@
+/**
+ * PostgreSQL User Store
+ *
+ * User storage implementation using PostgreSQL.
+ * Requires the 'pg' package to be installed.
+ *
+ * Note: Ban management is handled by the separate Bans Plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  UserStore,
+  User,
+  CreateUserInput,
+  UpdateUserInput,
+  UserSearchParams,
+  UserListResponse,
+  PostgresUserStoreConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * Create a PostgreSQL user store
+ *
+ * @param config Configuration including a pg Pool instance
+ * @returns UserStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresUserStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresUserStore({ pool });
+ * ```
+ */
+export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
+  const {
+    pool: poolOrFn,
+    usersTable = 'users',
+    schema = 'public',
+    autoCreateTables = true,
+  } = config;
+
+  // Helper to get pool (supports lazy initialization via function)
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    return pool as PgPool;
+  };
+
+  const usersTableFull = `"${schema}"."${usersTable}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      // Create users table
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${usersTableFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          email VARCHAR(255) NOT NULL UNIQUE,
+          name VARCHAR(255),
+          external_id VARCHAR(255),
+          provider VARCHAR(50),
+          picture TEXT,
+          metadata JSONB DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          last_login_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${usersTable}_email ON ${usersTableFull}(email);
+        CREATE INDEX IF NOT EXISTS idx_${usersTable}_external_id ON ${usersTableFull}(external_id, provider);
+      `);
+    },
+
+    async getById(id: string): Promise<User | null> {
+      const result = await getPool().query(`SELECT * FROM ${usersTableFull} WHERE id = $1`, [id]);
+      return (result.rows[0] as User) || null;
+    },
+
+    async getByEmail(email: string): Promise<User | null> {
+      const result = await getPool().query(`SELECT * FROM ${usersTableFull} WHERE LOWER(email) = LOWER($1)`, [
+        email,
+      ]);
+      return (result.rows[0] as User) || null;
+    },
+
+    async getByExternalId(externalId: string, provider: string): Promise<User | null> {
+      const result = await getPool().query(
+        `SELECT * FROM ${usersTableFull} WHERE external_id = $1 AND provider = $2`,
+        [externalId, provider]
+      );
+      return (result.rows[0] as User) || null;
+    },
+
+    async create(input: CreateUserInput): Promise<User> {
+      const result = await getPool().query(
+        `INSERT INTO ${usersTableFull} (email, name, external_id, provider, picture, metadata)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         RETURNING *`,
+        [
+          input.email.toLowerCase(),
+          input.name,
+          input.external_id,
+          input.provider,
+          input.picture,
+          JSON.stringify(input.metadata || {}),
+        ]
+      );
+      return result.rows[0] as User;
+    },
+
+    async update(id: string, input: UpdateUserInput): Promise<User | null> {
+      const updates: string[] = [];
+      const values: unknown[] = [];
+      let paramIndex = 1;
+
+      if (input.name !== undefined) {
+        updates.push(`name = $${paramIndex++}`);
+        values.push(input.name);
+      }
+      if (input.picture !== undefined) {
+        updates.push(`picture = $${paramIndex++}`);
+        values.push(input.picture);
+      }
+      if (input.metadata !== undefined) {
+        updates.push(`metadata = $${paramIndex++}`);
+        values.push(JSON.stringify(input.metadata));
+      }
+
+      if (updates.length === 0) {
+        return this.getById(id);
+      }
+
+      updates.push(`updated_at = NOW()`);
+      values.push(id);
+
+      const result = await getPool().query(
+        `UPDATE ${usersTableFull} SET ${updates.join(', ')} WHERE id = $${paramIndex} RETURNING *`,
+        values
+      );
+      return (result.rows[0] as User) || null;
+    },
+
+    async delete(id: string): Promise<boolean> {
+      const result = await getPool().query(`DELETE FROM ${usersTableFull} WHERE id = $1`, [id]);
+      return (result.rowCount ?? 0) > 0;
+    },
+
+    async search(params: UserSearchParams): Promise<UserListResponse> {
+      const {
+        query,
+        provider,
+        page = 1,
+        limit = 20,
+        sortBy = 'created_at',
+        sortOrder = 'desc',
+      } = params;
+
+      const conditions: string[] = [];
+      const values: unknown[] = [];
+      let paramIndex = 1;
+
+      if (query) {
+        conditions.push(`(LOWER(email) LIKE $${paramIndex} OR LOWER(name) LIKE $${paramIndex})`);
+        values.push(`%${query.toLowerCase()}%`);
+        paramIndex++;
+      }
+
+      if (provider) {
+        conditions.push(`provider = $${paramIndex}`);
+        values.push(provider);
+        paramIndex++;
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+      // Validate sort column to prevent SQL injection
+      const validSortColumns = ['email', 'name', 'created_at', 'last_login_at'];
+      const sortColumn = validSortColumns.includes(sortBy) ? sortBy : 'created_at';
+      const sortDir = sortOrder === 'asc' ? 'ASC' : 'DESC';
+
+      const offset = (page - 1) * limit;
+
+      // Get total count
+      const countResult = await getPool().query(
+        `SELECT COUNT(*) FROM ${usersTableFull} ${whereClause}`,
+        values
+      );
+      const total = parseInt((countResult.rows[0] as { count: string }).count, 10);
+
+      // Get users
+      const result = await getPool().query(
+        `SELECT * FROM ${usersTableFull} ${whereClause}
+         ORDER BY ${sortColumn} ${sortDir}
+         LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`,
+        [...values, limit, offset]
+      );
+
+      return {
+        users: result.rows as User[],
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      };
+    },
+
+    async updateLastLogin(id: string): Promise<void> {
+      await getPool().query(`UPDATE ${usersTableFull} SET last_login_at = NOW() WHERE id = $1`, [id]);
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/users/types.ts

@@ -0,0 +1,209 @@
+/**
+ * Users Plugin Types
+ *
+ * Type definitions for user identity management.
+ * Storage-agnostic - supports any database through the UserStore interface.
+ *
+ * Note: Ban management is handled by the separate Bans Plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * User record in the database
+ */
+export interface User {
+  /** Primary key - UUID */
+  id: string;
+  /** User's email address (unique) */
+  email: string;
+  /** User's display name */
+  name?: string;
+  /** External provider ID (e.g., Auth0 sub) */
+  external_id?: string;
+  /** Provider name (e.g., 'auth0', 'supabase') */
+  provider?: string;
+  /** Profile picture URL */
+  picture?: string;
+  /** Additional metadata (JSON) */
+  metadata?: Record<string, unknown>;
+  /** When the user was created */
+  created_at: Date;
+  /** When the user was last updated */
+  updated_at: Date;
+  /** When the user last logged in */
+  last_login_at?: Date;
+}
+
+/**
+ * User creation payload
+ */
+export interface CreateUserInput {
+  email: string;
+  name?: string;
+  external_id?: string;
+  provider?: string;
+  picture?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User update payload
+ */
+export interface UpdateUserInput {
+  name?: string;
+  picture?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User search parameters
+ */
+export interface UserSearchParams {
+  /** Search query (searches email and name) */
+  query?: string;
+  /** Filter by provider */
+  provider?: string;
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Items per page */
+  limit?: number;
+  /** Sort field */
+  sortBy?: 'email' | 'name' | 'created_at' | 'last_login_at';
+  /** Sort direction */
+  sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Paginated user list response
+ */
+export interface UserListResponse {
+  users: User[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+/**
+ * User store interface - all storage backends must implement this
+ */
+export interface UserStore {
+  /** Store name (e.g., 'postgres', 'memory') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get a user by ID
+   */
+  getById(id: string): Promise<User | null>;
+
+  /**
+   * Get a user by email
+   */
+  getByEmail(email: string): Promise<User | null>;
+
+  /**
+   * Get a user by external ID
+   */
+  getByExternalId(externalId: string, provider: string): Promise<User | null>;
+
+  /**
+   * Create a new user
+   */
+  create(input: CreateUserInput): Promise<User>;
+
+  /**
+   * Update an existing user
+   */
+  update(id: string, input: UpdateUserInput): Promise<User | null>;
+
+  /**
+   * Delete a user
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Search/list users
+   */
+  search(params: UserSearchParams): Promise<UserListResponse>;
+
+  /**
+   * Update last login timestamp
+   */
+  updateLastLogin(id: string): Promise<void>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL user store configuration
+ * Note: Import Pool type from 'pg' when using this store
+ */
+export interface PostgresUserStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** Users table name (default: 'users') */
+  usersTable?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * User sync configuration
+ */
+export interface UserSyncConfig {
+  /** Enable sync */
+  enabled: boolean;
+  /** Create local user on first login */
+  onFirstLogin?: boolean;
+  /** Fields to sync from external provider */
+  syncFields?: Array<'email' | 'name' | 'picture'>;
+}
+
+/**
+ * API configuration
+ */
+export interface UsersApiConfig {
+  /** API route prefix (default: '/api/users') */
+  prefix?: string;
+  /** Enable CRUD endpoints */
+  crud?: boolean;
+  /** Enable search endpoint */
+  search?: boolean;
+}
+
+/**
+ * UI configuration
+ */
+export interface UsersUiConfig {
+  /** Enable UI pages */
+  enabled: boolean;
+  /** UI page path (default: '/users') */
+  page?: string;
+}
+
+/**
+ * Users plugin configuration
+ */
+export interface UsersPluginConfig {
+  /** User storage backend */
+  store: UserStore;
+  /** Sync configuration (optional) */
+  sync?: UserSyncConfig;
+  /** API configuration */
+  api?: UsersApiConfig;
+  /** UI configuration */
+  ui?: UsersUiConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}

package/src/plugins/users/users-plugin.ts

@@ -0,0 +1,281 @@
+/**
+ * Users Plugin
+ *
+ * User identity management plugin for @qwickapps/server.
+ * Provides CRUD operations, search, and user lookup functionality.
+ *
+ * Note: Ban management is handled by the separate Bans Plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  UsersPluginConfig,
+  UserStore,
+  User,
+  CreateUserInput,
+  UpdateUserInput,
+  UserSearchParams,
+} from './types.js';
+
+// Store instance for helper access
+let currentStore: UserStore | null = null;
+
+/**
+ * Create the Users plugin
+ */
+export function createUsersPlugin(config: UsersPluginConfig): Plugin {
+  const debug = config.debug || false;
+  // Routes are mounted under /api by the control panel, so don't include /api in prefix
+  const apiPrefix = config.api?.prefix || '/users';
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[UsersPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'users',
+    name: 'Users',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      log('Starting users plugin');
+
+      // Initialize the store (creates tables if needed)
+      await config.store.initialize();
+      log('Users plugin migrations complete');
+
+      // Store reference for helper access
+      currentStore = config.store;
+
+      // Register health check
+      registry.registerHealthCheck({
+        name: 'users-store',
+        type: 'custom',
+        check: async () => {
+          try {
+            // Simple health check - try to search with limit 1
+            await config.store.search({ limit: 1 });
+            return { healthy: true };
+          } catch {
+            return { healthy: false };
+          }
+        },
+      });
+
+      // Add API routes if enabled
+      if (config.api?.crud !== false) {
+        // List/Search users
+        registry.addRoute({
+          method: 'get',
+          path: apiPrefix,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const params: UserSearchParams = {
+                query: req.query.q as string,
+                provider: req.query.provider as string,
+                page: parseInt(req.query.page as string) || 1,
+                limit: Math.min(parseInt(req.query.limit as string) || 20, 100),
+                sortBy: (req.query.sortBy as UserSearchParams['sortBy']) || 'created_at',
+                sortOrder: (req.query.sortOrder as UserSearchParams['sortOrder']) || 'desc',
+              };
+
+              const result = await config.store.search(params);
+              res.json(result);
+            } catch (error) {
+              console.error('[UsersPlugin] Search error:', error);
+              res.status(500).json({ error: 'Failed to search users' });
+            }
+          },
+        });
+
+        // Get user by ID
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const user = await config.store.getById(req.params.id);
+              if (!user) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Get user error:', error);
+              res.status(500).json({ error: 'Failed to get user' });
+            }
+          },
+        });
+
+        // Create user
+        registry.addRoute({
+          method: 'post',
+          path: apiPrefix,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input: CreateUserInput = {
+                email: req.body.email,
+                name: req.body.name,
+                external_id: req.body.external_id,
+                provider: req.body.provider,
+                picture: req.body.picture,
+                metadata: req.body.metadata,
+              };
+
+              if (!input.email) {
+                return res.status(400).json({ error: 'Email is required' });
+              }
+
+              // Check if user already exists
+              const existing = await config.store.getByEmail(input.email);
+              if (existing) {
+                return res.status(409).json({ error: 'User with this email already exists' });
+              }
+
+              const user = await config.store.create(input);
+              res.status(201).json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Create user error:', error);
+              res.status(500).json({ error: 'Failed to create user' });
+            }
+          },
+        });
+
+        // Update user
+        registry.addRoute({
+          method: 'put',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input: UpdateUserInput = {
+                name: req.body.name,
+                picture: req.body.picture,
+                metadata: req.body.metadata,
+              };
+
+              const user = await config.store.update(req.params.id, input);
+              if (!user) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Update user error:', error);
+              res.status(500).json({ error: 'Failed to update user' });
+            }
+          },
+        });
+
+        // Delete user
+        registry.addRoute({
+          method: 'delete',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const deleted = await config.store.delete(req.params.id);
+              if (!deleted) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.status(204).send();
+            } catch (error) {
+              console.error('[UsersPlugin] Delete user error:', error);
+              res.status(500).json({ error: 'Failed to delete user' });
+            }
+          },
+        });
+      }
+
+      log('Users plugin started');
+    },
+
+    async onStop(): Promise<void> {
+      log('Stopping users plugin');
+      await config.store.shutdown();
+      currentStore = null;
+      log('Users plugin stopped');
+    },
+  };
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Get the current user store instance
+ */
+export function getUserStore(): UserStore | null {
+  return currentStore;
+}
+
+/**
+ * Get a user by ID
+ */
+export async function getUserById(id: string): Promise<User | null> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+  return currentStore.getById(id);
+}
+
+/**
+ * Get a user by email
+ */
+export async function getUserByEmail(email: string): Promise<User | null> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+  return currentStore.getByEmail(email);
+}
+
+/**
+ * Find or create a user from auth provider data
+ */
+export async function findOrCreateUser(data: {
+  email: string;
+  name?: string;
+  external_id: string;
+  provider: string;
+  picture?: string;
+}): Promise<User> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+
+  // Try to find by external ID first
+  let user = await currentStore.getByExternalId(data.external_id, data.provider);
+  if (user) {
+    await currentStore.updateLastLogin(user.id);
+    return user;
+  }
+
+  // Try to find by email
+  user = await currentStore.getByEmail(data.email);
+  if (user) {
+    // Update with external ID if not set
+    if (!user.external_id) {
+      await currentStore.update(user.id, {});
+    }
+    await currentStore.updateLastLogin(user.id);
+    return user;
+  }
+
+  // Create new user
+  user = await currentStore.create({
+    email: data.email,
+    name: data.name,
+    external_id: data.external_id,
+    provider: data.provider,
+    picture: data.picture,
+  });
+
+  return user;
+}