@qwickapps/server 1.4.0 → 1.5.0

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

@@ -0,0 +1,213 @@
+/**
+ * PostgreSQL Usage Store
+ *
+ * Usage tracking storage implementation using PostgreSQL.
+ * Tracks daily and monthly usage counters.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  UsageStore,
+  DailyUsage,
+  MonthlyUsage,
+  PostgresUsageStoreConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * Get current date in YYYY-MM-DD format
+ */
+function getCurrentDate(): string {
+  return new Date().toISOString().split('T')[0];
+}
+
+/**
+ * Get current year-month in YYYY-MM format
+ */
+function getCurrentYearMonth(): string {
+  const now = new Date();
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * Create a PostgreSQL usage store
+ */
+export function postgresUsageStore(config: PostgresUsageStoreConfig): UsageStore {
+  const {
+    pool: poolOrFn,
+    dailyTable = 'usage_daily',
+    monthlyTable = 'usage_monthly',
+    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 dailyTableFull = `"${schema}"."${dailyTable}"`;
+  const monthlyTableFull = `"${schema}"."${monthlyTable}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      // Create usage_daily table
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${dailyTableFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL,
+          feature_code VARCHAR(100) NOT NULL,
+          date DATE NOT NULL DEFAULT CURRENT_DATE,
+          count INTEGER DEFAULT 0,
+          metadata JSONB DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          UNIQUE(user_id, feature_code, date)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${dailyTable}_user_date ON ${dailyTableFull}(user_id, date);
+        CREATE INDEX IF NOT EXISTS idx_${dailyTable}_feature ON ${dailyTableFull}(feature_code);
+        CREATE INDEX IF NOT EXISTS idx_${dailyTable}_date ON ${dailyTableFull}(date);
+      `);
+
+      // Create usage_monthly table
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${monthlyTableFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL,
+          feature_code VARCHAR(100) NOT NULL,
+          year_month VARCHAR(7) NOT NULL,
+          count INTEGER DEFAULT 0,
+          metadata JSONB DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          UNIQUE(user_id, feature_code, year_month)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${monthlyTable}_user ON ${monthlyTableFull}(user_id, year_month);
+        CREATE INDEX IF NOT EXISTS idx_${monthlyTable}_feature ON ${monthlyTableFull}(feature_code);
+      `);
+    },
+
+    async getDailyUsage(userId: string, featureCode: string, date?: string): Promise<DailyUsage | null> {
+      const targetDate = date || getCurrentDate();
+      const result = await getPool().query(
+        `SELECT * FROM ${dailyTableFull}
+         WHERE user_id = $1 AND feature_code = $2 AND date = $3`,
+        [userId, featureCode, targetDate]
+      );
+      return (result.rows[0] as DailyUsage) || null;
+    },
+
+    async getMonthlyUsage(userId: string, featureCode: string, yearMonth?: string): Promise<MonthlyUsage | null> {
+      const targetMonth = yearMonth || getCurrentYearMonth();
+      const result = await getPool().query(
+        `SELECT * FROM ${monthlyTableFull}
+         WHERE user_id = $1 AND feature_code = $2 AND year_month = $3`,
+        [userId, featureCode, targetMonth]
+      );
+      return (result.rows[0] as MonthlyUsage) || null;
+    },
+
+    async incrementDaily(userId: string, featureCode: string, amount = 1, date?: string): Promise<number> {
+      const targetDate = date || getCurrentDate();
+      const yearMonth = targetDate.substring(0, 7); // Extract YYYY-MM from YYYY-MM-DD
+
+      // Increment daily usage (upsert)
+      const dailyResult = await getPool().query(
+        `INSERT INTO ${dailyTableFull} (user_id, feature_code, date, count)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (user_id, feature_code, date)
+         DO UPDATE SET count = ${dailyTableFull}.count + $4, updated_at = NOW()
+         RETURNING count`,
+        [userId, featureCode, targetDate, amount]
+      );
+
+      const newCount = (dailyResult.rows[0] as { count: number }).count;
+
+      // Also increment monthly usage
+      await getPool().query(
+        `INSERT INTO ${monthlyTableFull} (user_id, feature_code, year_month, count)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (user_id, feature_code, year_month)
+         DO UPDATE SET count = ${monthlyTableFull}.count + $4, updated_at = NOW()`,
+        [userId, featureCode, yearMonth, amount]
+      );
+
+      return newCount;
+    },
+
+    async getAllDailyUsage(userId: string, date?: string): Promise<DailyUsage[]> {
+      const targetDate = date || getCurrentDate();
+      const result = await getPool().query(
+        `SELECT * FROM ${dailyTableFull}
+         WHERE user_id = $1 AND date = $2
+         ORDER BY feature_code`,
+        [userId, targetDate]
+      );
+      return result.rows as DailyUsage[];
+    },
+
+    async getAllMonthlyUsage(userId: string, yearMonth?: string): Promise<MonthlyUsage[]> {
+      const targetMonth = yearMonth || getCurrentYearMonth();
+      const result = await getPool().query(
+        `SELECT * FROM ${monthlyTableFull}
+         WHERE user_id = $1 AND year_month = $2
+         ORDER BY feature_code`,
+        [userId, targetMonth]
+      );
+      return result.rows as MonthlyUsage[];
+    },
+
+    async resetDailyUsage(userId: string, featureCode: string, date?: string): Promise<void> {
+      const targetDate = date || getCurrentDate();
+      await getPool().query(
+        `UPDATE ${dailyTableFull}
+         SET count = 0, updated_at = NOW()
+         WHERE user_id = $1 AND feature_code = $2 AND date = $3`,
+        [userId, featureCode, targetDate]
+      );
+    },
+
+    async cleanupOldDaily(daysToKeep: number): Promise<number> {
+      // Calculate cutoff date to avoid SQL interpolation
+      const cutoffDate = new Date();
+      cutoffDate.setDate(cutoffDate.getDate() - daysToKeep);
+      const cutoffDateStr = cutoffDate.toISOString().split('T')[0];
+
+      const result = await getPool().query(
+        `DELETE FROM ${dailyTableFull} WHERE date < $1`,
+        [cutoffDateStr]
+      );
+      return result.rowCount ?? 0;
+    },
+
+    async cleanupOldMonthly(monthsToKeep: number): Promise<number> {
+      // Calculate the cutoff year-month
+      const now = new Date();
+      now.setMonth(now.getMonth() - monthsToKeep);
+      const cutoffMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+
+      const result = await getPool().query(
+        `DELETE FROM ${monthlyTableFull}
+         WHERE year_month < $1`,
+        [cutoffMonth]
+      );
+      return result.rowCount ?? 0;
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/usage/types.ts

@@ -0,0 +1,222 @@
+/**
+ * Usage Plugin Types
+ *
+ * Type definitions for usage tracking with daily/monthly counters.
+ * Integrates with subscriptions-plugin for limit enforcement.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Daily usage record
+ */
+export interface DailyUsage {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID */
+  user_id: string;
+  /** Feature code (e.g., 'ai_messages', 'vision_calls') */
+  feature_code: string;
+  /** Date (YYYY-MM-DD) */
+  date: string;
+  /** Usage count */
+  count: number;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+  /** When the record was created */
+  created_at: Date;
+  /** When the record was last updated */
+  updated_at: Date;
+}
+
+/**
+ * Monthly usage record
+ */
+export interface MonthlyUsage {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID */
+  user_id: string;
+  /** Feature code */
+  feature_code: string;
+  /** Year-month (YYYY-MM) */
+  year_month: string;
+  /** Usage count */
+  count: number;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+  /** When the record was created */
+  created_at: Date;
+  /** When the record was last updated */
+  updated_at: Date;
+}
+
+/**
+ * Usage increment result
+ */
+export interface UsageIncrementResult {
+  /** Whether the increment was allowed */
+  allowed: boolean;
+  /** Current count after increment (if allowed) */
+  current_count: number;
+  /** Limit value (-1 = unlimited) */
+  limit: number | null;
+  /** Remaining quota */
+  remaining: number | null;
+  /** When the counter resets */
+  resets_at?: Date;
+  /** Reason if not allowed */
+  reason?: string;
+}
+
+/**
+ * Usage status for a feature
+ */
+export interface UsageStatus {
+  /** Feature code */
+  feature_code: string;
+  /** Current usage count */
+  current: number;
+  /** Limit value (-1 = unlimited, null = no subscription) */
+  limit: number | null;
+  /** Remaining quota (-1 = unlimited) */
+  remaining: number | null;
+  /** When the counter resets */
+  resets_at: Date;
+  /** Percentage used (0-100, null if unlimited) */
+  percentage_used: number | null;
+}
+
+/**
+ * Usage summary for a user
+ */
+export interface UsageSummary {
+  /** User ID */
+  user_id: string;
+  /** Period (daily or monthly) */
+  period: 'daily' | 'monthly';
+  /** Period date/month */
+  period_value: string;
+  /** Usage by feature */
+  features: UsageStatus[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Usage store interface
+ */
+export interface UsageStore {
+  /** Store name (e.g., 'postgres') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get daily usage for a user and feature
+   */
+  getDailyUsage(userId: string, featureCode: string, date?: string): Promise<DailyUsage | null>;
+
+  /**
+   * Get monthly usage for a user and feature
+   */
+  getMonthlyUsage(userId: string, featureCode: string, yearMonth?: string): Promise<MonthlyUsage | null>;
+
+  /**
+   * Increment daily usage (also updates monthly)
+   */
+  incrementDaily(userId: string, featureCode: string, amount?: number, date?: string): Promise<number>;
+
+  /**
+   * Get all daily usage for a user on a date
+   */
+  getAllDailyUsage(userId: string, date?: string): Promise<DailyUsage[]>;
+
+  /**
+   * Get all monthly usage for a user
+   */
+  getAllMonthlyUsage(userId: string, yearMonth?: string): Promise<MonthlyUsage[]>;
+
+  /**
+   * Reset daily usage for a user and feature
+   */
+  resetDailyUsage(userId: string, featureCode: string, date?: string): Promise<void>;
+
+  /**
+   * Cleanup old daily records
+   */
+  cleanupOldDaily(daysToKeep: number): Promise<number>;
+
+  /**
+   * Cleanup old monthly records
+   */
+  cleanupOldMonthly(monthsToKeep: number): Promise<number>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * PostgreSQL usage store configuration
+ */
+export interface PostgresUsageStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one */
+  pool: unknown | (() => unknown);
+  /** Daily usage table name (default: 'usage_daily') */
+  dailyTable?: string;
+  /** Monthly usage table name (default: 'usage_monthly') */
+  monthlyTable?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * API configuration
+ */
+export interface UsageApiConfig {
+  /** API route prefix (default: '/usage') */
+  prefix?: string;
+  /** Enable usage endpoints */
+  enabled?: boolean;
+}
+
+/**
+ * Cleanup configuration
+ */
+export interface UsageCleanupConfig {
+  /** Days to keep daily records (default: 90) */
+  dailyRetentionDays?: number;
+  /** Months to keep monthly records (default: 24) */
+  monthlyRetentionMonths?: number;
+  /** Run cleanup on startup */
+  runOnStartup?: boolean;
+  /** Cleanup interval in hours (0 = disabled) */
+  cleanupIntervalHours?: number;
+}
+
+/**
+ * Usage plugin configuration
+ */
+export interface UsagePluginConfig {
+  /** Usage storage backend */
+  store: UsageStore;
+  /** API configuration */
+  api?: UsageApiConfig;
+  /** Cleanup configuration */
+  cleanup?: UsageCleanupConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}