@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/profiles/types.ts

@@ -0,0 +1,338 @@
+/**
+ * Profiles Plugin Types
+ *
+ * Type definitions for generic multi-profile management with age support.
+ * Supports child profiles for QwickBot, player profiles for gaming, etc.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Content filter levels for age-appropriate content
+ */
+export type ContentFilterLevel = 'strict' | 'moderate' | 'minimal' | 'none';
+
+/**
+ * Age groups for categorization
+ */
+export type AgeGroup = 'child' | 'teen' | 'adult';
+
+/**
+ * Profile record in the database
+ */
+export interface Profile {
+  /** Primary key - UUID */
+  id: string;
+  /** Organization ID for multi-tenant isolation */
+  org_id?: string;
+  /** Owner/parent user ID */
+  user_id: string;
+  /** Profile name */
+  name: string;
+  /** Avatar identifier or URL */
+  avatar?: string;
+
+  // Age-based features
+  /** Birth date for precise age calculation */
+  birth_date?: Date;
+  /** Static age (if birth_date not provided) */
+  age?: number;
+  /** Computed age group (child, teen, adult) */
+  age_group?: AgeGroup;
+
+  // Content/access control
+  /** Content filter level */
+  content_filter_level: ContentFilterLevel;
+
+  // Time restrictions
+  /** Daily time limit in minutes (null = no limit) */
+  daily_time_limit_minutes?: number;
+  /** Allowed hours start (null = no restriction) */
+  allowed_hours_start?: string;
+  /** Allowed hours end (null = no restriction) */
+  allowed_hours_end?: string;
+
+  // Status
+  /** Whether profile is active */
+  is_active: boolean;
+  /** Whether this is the default profile for the user */
+  is_default: boolean;
+
+  // Extensibility
+  /** App-specific metadata */
+  metadata: Record<string, unknown>;
+
+  /** When the profile was created */
+  created_at: Date;
+  /** When the profile was last updated */
+  updated_at: Date;
+  /** Soft delete timestamp */
+  deleted_at?: Date;
+}
+
+/**
+ * Profile creation payload
+ */
+export interface CreateProfileInput {
+  /** Organization ID */
+  org_id?: string;
+  /** Owner user ID */
+  user_id: string;
+  /** Profile name */
+  name: string;
+  /** Avatar identifier or URL */
+  avatar?: string;
+  /** Birth date for age calculation */
+  birth_date?: Date;
+  /** Static age (if birth_date not provided) */
+  age?: number;
+  /** Content filter level (default: 'moderate') */
+  content_filter_level?: ContentFilterLevel;
+  /** Daily time limit in minutes */
+  daily_time_limit_minutes?: number;
+  /** Allowed hours start (HH:MM format) */
+  allowed_hours_start?: string;
+  /** Allowed hours end (HH:MM format) */
+  allowed_hours_end?: string;
+  /** Whether this is the default profile */
+  is_default?: boolean;
+  /** App-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Profile update payload
+ */
+export interface UpdateProfileInput {
+  /** Profile name */
+  name?: string;
+  /** Avatar identifier or URL */
+  avatar?: string;
+  /** Birth date for age calculation */
+  birth_date?: Date | null;
+  /** Static age */
+  age?: number | null;
+  /** Content filter level */
+  content_filter_level?: ContentFilterLevel;
+  /** Daily time limit in minutes (null to remove) */
+  daily_time_limit_minutes?: number | null;
+  /** Allowed hours start (null to remove) */
+  allowed_hours_start?: string | null;
+  /** Allowed hours end (null to remove) */
+  allowed_hours_end?: string | null;
+  /** Whether profile is active */
+  is_active?: boolean;
+  /** Whether this is the default profile */
+  is_default?: boolean;
+  /** App-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Profile search parameters
+ */
+export interface ProfileSearchParams {
+  /** Organization ID filter */
+  org_id?: string;
+  /** User ID filter */
+  user_id?: string;
+  /** Age group filter */
+  age_group?: AgeGroup;
+  /** Active status filter */
+  is_active?: boolean;
+  /** Search query (searches name) */
+  query?: string;
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Items per page */
+  limit?: number;
+  /** Sort field */
+  sortBy?: 'name' | 'created_at' | 'age';
+  /** Sort direction */
+  sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Paginated profile list response
+ */
+export interface ProfileListResponse {
+  profiles: Profile[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+/**
+ * Time restriction check result
+ */
+export interface TimeRestrictionResult {
+  /** Whether access is allowed right now */
+  allowed: boolean;
+  /** Reason if not allowed */
+  reason?: string;
+  /** Minutes remaining today (if has limit) */
+  minutes_remaining?: number;
+  /** When restriction ends (if currently restricted) */
+  available_at?: Date;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Profile store interface - all storage backends must implement this
+ */
+export interface ProfileStore {
+  /** Store name (e.g., 'postgres', 'memory') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get a profile by ID
+   */
+  getById(id: string): Promise<Profile | null>;
+
+  /**
+   * Create a new profile
+   */
+  create(input: CreateProfileInput): Promise<Profile>;
+
+  /**
+   * Update an existing profile
+   */
+  update(id: string, input: UpdateProfileInput): Promise<Profile | null>;
+
+  /**
+   * Soft delete a profile
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Search/list profiles
+   */
+  search(params: ProfileSearchParams): Promise<ProfileListResponse>;
+
+  /**
+   * List profiles for a user
+   */
+  listByUser(userId: string): Promise<Profile[]>;
+
+  /**
+   * Get the default profile for a user
+   */
+  getDefaultProfile(userId: string): Promise<Profile | null>;
+
+  /**
+   * Count profiles for a user
+   */
+  getProfileCount(userId: string): Promise<number>;
+
+  /**
+   * Get profiles by age group
+   */
+  getByAgeGroup(userId: string, ageGroup: AgeGroup): Promise<Profile[]>;
+
+  /**
+   * Set a profile as default (unsets others)
+   */
+  setDefaultProfile(profileId: string, userId: string): Promise<boolean>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * PostgreSQL profile store configuration
+ */
+export interface PostgresProfileStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** Profiles table name (default: 'profiles') */
+  tableName?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * Age thresholds for categorization
+ */
+export interface AgeThresholds {
+  /** Maximum age for 'child' (default: 12) */
+  child: number;
+  /** Maximum age for 'teen' (default: 17) */
+  teen: number;
+}
+
+/**
+ * API configuration
+ */
+export interface ProfilesApiConfig {
+  /** API route prefix (default: '/profiles') */
+  prefix?: string;
+  /** Enable CRUD endpoints */
+  crud?: boolean;
+}
+
+/**
+ * Profiles plugin configuration
+ */
+export interface ProfilesPluginConfig {
+  /** Profile storage backend */
+  store: ProfileStore;
+  /** Maximum profiles per user (default: 10) */
+  maxProfilesPerUser?: number;
+  /** Default content filter level (default: 'moderate') */
+  defaultFilterLevel?: ContentFilterLevel;
+  /** Age thresholds for categorization */
+  ageThresholds?: AgeThresholds;
+  /** API configuration */
+  api?: ProfilesApiConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// App-specific Metadata Types (examples)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * QwickBot profile metadata (stored in metadata field)
+ */
+export interface QwickBotProfileMetadata {
+  /** Voice ID for text-to-speech */
+  voice_id?: string;
+  /** Avatar style identifier */
+  avatar_style?: string;
+  /** Personality prompt for AI */
+  personality_prompt?: string;
+  /** User's interests */
+  interests?: string[];
+}
+
+/**
+ * Gaming profile metadata (stored in metadata field)
+ */
+export interface GamingProfileMetadata {
+  /** Gamer tag */
+  gamer_tag?: string;
+  /** Avatar URL */
+  avatar_url?: string;
+  /** Allowed game ratings (E, E10+, T, M) */
+  allowed_ratings?: string[];
+  /** Preferred genres */
+  preferred_genres?: string[];
+}

package/src/plugins/rate-limit/__tests__/rate-limit-plugin.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Rate Limit Plugin Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { RateLimitStore, RateLimitCache, CachedLimit, StoredLimit, IncrementOptions } from '../types.js';
+import { RateLimitService } from '../rate-limit-service.js';
+import { createSlidingWindowStrategy } from '../strategies/sliding-window.js';
+import { createFixedWindowStrategy } from '../strategies/fixed-window.js';
+import { createTokenBucketStrategy } from '../strategies/token-bucket.js';
+
+// Mock store implementation
+function createMockStore(): RateLimitStore {
+  const records = new Map<string, StoredLimit>();
+
+  return {
+    name: 'mock',
+
+    async initialize(): Promise<void> {
+      // No-op
+    },
+
+    async get(key: string): Promise<StoredLimit | null> {
+      return records.get(key) || null;
+    },
+
+    async increment(key: string, options: IncrementOptions): Promise<StoredLimit> {
+      const now = new Date();
+      const windowMs = options.windowMs;
+      const windowStart = new Date(now.getTime() - (now.getTime() % windowMs));
+      const windowEnd = new Date(windowStart.getTime() + windowMs);
+
+      const existing = records.get(key);
+      if (existing && existing.windowStart.getTime() === windowStart.getTime()) {
+        existing.count += options.amount || 1;
+        existing.updatedAt = now;
+        return existing;
+      }
+
+      const newRecord: StoredLimit = {
+        id: `mock-${Date.now()}`,
+        key,
+        count: options.amount || 1,
+        maxRequests: options.maxRequests,
+        windowMs: options.windowMs,
+        windowStart,
+        windowEnd,
+        strategy: options.strategy,
+        userId: options.userId,
+        tenantId: options.tenantId,
+        ipAddress: options.ipAddress,
+        createdAt: now,
+        updatedAt: now,
+      };
+      records.set(key, newRecord);
+      return newRecord;
+    },
+
+    async clear(key: string): Promise<boolean> {
+      return records.delete(key);
+    },
+
+    async cleanup(): Promise<number> {
+      const now = Date.now();
+      let deleted = 0;
+      for (const [key, record] of records) {
+        if (record.windowEnd.getTime() < now) {
+          records.delete(key);
+          deleted++;
+        }
+      }
+      return deleted;
+    },
+
+    async shutdown(): Promise<void> {
+      records.clear();
+    },
+  };
+}
+
+// Mock cache implementation
+function createMockCache(): RateLimitCache {
+  const cache = new Map<string, { value: CachedLimit; expiresAt: number }>();
+
+  return {
+    name: 'mock',
+
+    async get(key: string): Promise<CachedLimit | null> {
+      const entry = cache.get(key);
+      if (!entry) return null;
+      if (entry.expiresAt <= Date.now()) {
+        cache.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+
+    async set(key: string, value: CachedLimit, ttlMs: number): Promise<void> {
+      cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+    },
+
+    async increment(key: string, amount = 1): Promise<number | null> {
+      const entry = cache.get(key);
+      if (!entry || entry.expiresAt <= Date.now()) return null;
+      entry.value.count += amount;
+      return entry.value.count;
+    },
+
+    async delete(key: string): Promise<boolean> {
+      return cache.delete(key);
+    },
+
+    isAvailable(): boolean {
+      return true;
+    },
+
+    async shutdown(): Promise<void> {
+      cache.clear();
+    },
+  };
+}
+
+describe('RateLimitService', () => {
+  let store: RateLimitStore;
+  let cache: RateLimitCache;
+  let service: RateLimitService;
+
+  beforeEach(() => {
+    store = createMockStore();
+    cache = createMockCache();
+    service = new RateLimitService({
+      store,
+      cache,
+      defaults: {
+        windowMs: 60000,
+        maxRequests: 100,
+        strategy: 'sliding-window',
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await store.shutdown();
+    await cache.shutdown();
+  });
+
+  describe('checkLimit', () => {
+    it('should return not limited for first request', async () => {
+      const status = await service.checkLimit('test:key', { increment: false });
+
+      expect(status.limited).toBe(false);
+      expect(status.current).toBe(0);
+      expect(status.limit).toBe(100);
+      expect(status.remaining).toBe(100);
+    });
+
+    it('should use provided options over defaults', async () => {
+      const status = await service.checkLimit('test:key', {
+        maxRequests: 50,
+        windowMs: 30000,
+        increment: false,
+      });
+
+      expect(status.limit).toBe(50);
+    });
+  });
+
+  describe('incrementLimit', () => {
+    it('should increment the counter', async () => {
+      const status1 = await service.incrementLimit('test:key');
+      expect(status1.current).toBe(1);
+      expect(status1.remaining).toBe(99);
+
+      const status2 = await service.incrementLimit('test:key');
+      expect(status2.current).toBe(2);
+      expect(status2.remaining).toBe(98);
+    });
+
+    it('should return limited when max reached', async () => {
+      // Set low limit for testing
+      for (let i = 0; i < 5; i++) {
+        await service.incrementLimit('test:key', { maxRequests: 5 });
+      }
+
+      const status = await service.incrementLimit('test:key', { maxRequests: 5 });
+      expect(status.limited).toBe(true);
+      expect(status.remaining).toBe(0);
+    });
+  });
+
+  describe('isLimited', () => {
+    it('should return false when not limited', async () => {
+      const limited = await service.isLimited('test:key');
+      expect(limited).toBe(false);
+    });
+
+    it('should return true when limited', async () => {
+      // Exhaust the limit
+      for (let i = 0; i < 5; i++) {
+        await service.incrementLimit('test:key', { maxRequests: 5 });
+      }
+
+      const limited = await service.isLimited('test:key', { maxRequests: 5 });
+      expect(limited).toBe(true);
+    });
+  });
+
+  describe('clearLimit', () => {
+    it('should clear the limit', async () => {
+      // Create some limits
+      await service.incrementLimit('test:key');
+      await service.incrementLimit('test:key');
+
+      // Verify exists
+      const beforeStatus = await service.checkLimit('test:key', { increment: false });
+      expect(beforeStatus.current).toBeGreaterThan(0);
+
+      // Clear
+      await service.clearLimit('test:key');
+
+      // Verify cleared
+      const afterStatus = await service.checkLimit('test:key', { increment: false });
+      expect(afterStatus.current).toBe(0);
+    });
+  });
+});
+
+describe('Strategies', () => {
+  describe('Sliding Window', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createSlidingWindowStrategy();
+      expect(strategy.name).toBe('sliding-window');
+    });
+  });
+
+  describe('Fixed Window', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createFixedWindowStrategy();
+      expect(strategy.name).toBe('fixed-window');
+    });
+  });
+
+  describe('Token Bucket', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createTokenBucketStrategy();
+      expect(strategy.name).toBe('token-bucket');
+    });
+  });
+});
+
+describe('Types', () => {
+  it('should export all required types', async () => {
+    // This test verifies that the types module compiles correctly
+    const types = await import('../types.js');
+    expect(types).toBeDefined();
+  });
+});

package/src/plugins/rate-limit/cleanup.ts

@@ -0,0 +1,117 @@
+/**
+ * Rate Limit Cleanup Job
+ *
+ * Periodically removes expired rate limit records from the database.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { RateLimitStore } from './types.js';
+
+/**
+ * Cleanup job configuration
+ */
+export interface CleanupJobConfig {
+  /** Store to clean up */
+  store: RateLimitStore;
+
+  /** Cleanup interval in milliseconds (default: 300000 = 5 min) */
+  intervalMs?: number;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Cleanup job state
+ */
+export interface CleanupJob {
+  /** Start the cleanup job */
+  start(): void;
+
+  /** Stop the cleanup job */
+  stop(): void;
+
+  /** Run cleanup immediately */
+  runNow(): Promise<number>;
+
+  /** Check if job is running */
+  isRunning(): boolean;
+}
+
+/**
+ * Create a cleanup job
+ *
+ * @param config Cleanup configuration
+ * @returns CleanupJob instance
+ */
+export function createCleanupJob(config: CleanupJobConfig): CleanupJob {
+  const {
+    store,
+    intervalMs = 300000, // 5 minutes default
+    debug = false,
+  } = config;
+
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+  let isRunningCleanup = false;
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[RateLimitCleanup] ${message}`, data || '');
+    }
+  }
+
+  async function runCleanup(): Promise<number> {
+    if (isRunningCleanup) {
+      log('Cleanup already in progress, skipping');
+      return 0;
+    }
+
+    isRunningCleanup = true;
+    try {
+      log('Starting cleanup');
+      const startTime = Date.now();
+      const deletedCount = await store.cleanup();
+      const duration = Date.now() - startTime;
+
+      log('Cleanup complete', { deletedCount, durationMs: duration });
+      return deletedCount;
+    } catch (error) {
+      console.error('[RateLimitCleanup] Error during cleanup:', error);
+      return 0;
+    } finally {
+      isRunningCleanup = false;
+    }
+  }
+
+  return {
+    start() {
+      if (intervalId) {
+        log('Cleanup job already running');
+        return;
+      }
+
+      log('Starting cleanup job', { intervalMs });
+      intervalId = setInterval(runCleanup, intervalMs);
+
+      // Run initial cleanup after a short delay
+      setTimeout(runCleanup, 10000);
+    },
+
+    stop() {
+      if (intervalId) {
+        log('Stopping cleanup job');
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    },
+
+    async runNow(): Promise<number> {
+      return runCleanup();
+    },
+
+    isRunning(): boolean {
+      return intervalId !== null;
+    },
+  };
+}