@qwickapps/server 1.2.0 → 1.3.1

package/src/plugins/users/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Users Plugin Index
+ *
+ * User identity management plugin.
+ * For ban management, use the separate Bans Plugin which depends on this plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Main plugin
+export {
+  createUsersPlugin,
+  getUserStore,
+  getUserById,
+  getUserByEmail,
+  findOrCreateUser,
+  buildUserInfo,
+} from './users-plugin.js';
+
+// Types
+export type {
+  UsersPluginConfig,
+  UserStore,
+  User,
+  CreateUserInput,
+  UpdateUserInput,
+  UserSearchParams,
+  UserListResponse,
+  PostgresUserStoreConfig,
+  UserSyncConfig,
+  UsersApiConfig,
+  UsersUiConfig,
+  UserInfo,
+  UserSyncInput,
+} from './types.js';
+
+// Stores
+export { postgresUserStore } from './stores/index.js';

package/src/plugins/users/stores/index.ts

@@ -0,0 +1,7 @@
+/**
+ * User Stores Index
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresUserStore } from './postgres-store.js';

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,247 @@
+/**
+ * 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;
+}
+
+/**
+ * Comprehensive user information aggregated from multiple plugins.
+ * Used by /users/:id/info and /users/sync endpoints.
+ */
+export interface UserInfo {
+  /** Core user data from users plugin */
+  user: User;
+  /** User's entitlements (if entitlements plugin loaded) */
+  entitlements?: string[];
+  /** User's preferences (if preferences plugin loaded) */
+  preferences?: Record<string, unknown>;
+  /** Active ban info (if bans plugin loaded, null if not banned) */
+  ban?: {
+    id: string;
+    reason: string;
+    banned_at: Date;
+    expires_at?: Date;
+  } | null;
+  /** User's roles (if roles plugin loaded - future) */
+  roles?: string[];
+}
+
+/**
+ * Input for POST /users/sync endpoint
+ */
+export interface UserSyncInput {
+  /** User's email address */
+  email: string;
+  /** External provider ID (e.g., Auth0 user_id) */
+  external_id: string;
+  /** Provider name (e.g., 'auth0', 'google') */
+  provider: string;
+  /** User's display name (optional) */
+  name?: string;
+  /** Profile picture URL (optional) */
+  picture?: string;
+}