@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/subscriptions/types.ts

@@ -0,0 +1,355 @@
+/**
+ * Subscriptions Plugin Types
+ *
+ * Type definitions for subscription tier management and feature entitlements.
+ * Supports Stripe integration for paid subscriptions.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Subscription status
+ */
+export type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'trialing' | 'inactive';
+
+/**
+ * Subscription tier definition (admin-managed)
+ */
+export interface SubscriptionTier {
+  /** Primary key - UUID */
+  id: string;
+  /** URL-safe identifier (e.g., 'free', 'premium', 'family') */
+  slug: string;
+  /** Display name */
+  name: string;
+  /** Description */
+  description?: string;
+  /** Monthly price in cents (null = free) */
+  price_monthly_cents?: number;
+  /** Yearly price in cents (null = free or monthly only) */
+  price_yearly_cents?: number;
+  /** Stripe price ID for monthly billing */
+  stripe_price_id_monthly?: string;
+  /** Stripe price ID for yearly billing */
+  stripe_price_id_yearly?: string;
+  /** Whether this tier is active (available for new subscriptions) */
+  is_active: boolean;
+  /** Sort order for display */
+  sort_order: number;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+  /** When the tier was created */
+  created_at: Date;
+  /** When the tier was last updated */
+  updated_at: Date;
+}
+
+/**
+ * Feature entitlement per tier
+ */
+export interface SubscriptionEntitlement {
+  /** Primary key - UUID */
+  id: string;
+  /** Tier this entitlement belongs to */
+  tier_id: string;
+  /** Feature code (e.g., 'ai_messages_daily', 'vision_calls_daily') */
+  feature_code: string;
+  /** Limit value (-1 = unlimited, null = disabled, positive = limit) */
+  limit_value?: number;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * User subscription record
+ */
+export interface UserSubscription {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID */
+  user_id: string;
+  /** Tier ID */
+  tier_id: string;
+  /** Stripe customer ID */
+  stripe_customer_id?: string;
+  /** Stripe subscription ID */
+  stripe_subscription_id?: string;
+  /** Subscription status */
+  status: SubscriptionStatus;
+  /** Current billing period start */
+  current_period_start?: Date;
+  /** Current billing period end */
+  current_period_end?: Date;
+  /** Whether to cancel at period end */
+  cancel_at_period_end: boolean;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+  /** When the subscription was created */
+  created_at: Date;
+  /** When the subscription was last updated */
+  updated_at: Date;
+}
+
+/**
+ * User subscription with tier details
+ */
+export interface UserSubscriptionWithTier extends UserSubscription {
+  tier: SubscriptionTier;
+}
+
+/**
+ * Feature limit check result
+ */
+export interface FeatureLimitResult {
+  /** Whether the feature is available */
+  available: boolean;
+  /** Limit value (-1 = unlimited) */
+  limit?: number;
+  /** Current usage (if tracked) */
+  current?: number;
+  /** Remaining quota (if tracked) */
+  remaining?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Input Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Tier creation payload
+ */
+export interface CreateTierInput {
+  slug: string;
+  name: string;
+  description?: string;
+  price_monthly_cents?: number;
+  price_yearly_cents?: number;
+  stripe_price_id_monthly?: string;
+  stripe_price_id_yearly?: string;
+  is_active?: boolean;
+  sort_order?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Tier update payload
+ */
+export interface UpdateTierInput {
+  name?: string;
+  description?: string;
+  price_monthly_cents?: number;
+  price_yearly_cents?: number;
+  stripe_price_id_monthly?: string;
+  stripe_price_id_yearly?: string;
+  is_active?: boolean;
+  sort_order?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Entitlement creation payload
+ */
+export interface CreateEntitlementInput {
+  tier_id: string;
+  feature_code: string;
+  limit_value?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User subscription creation payload
+ */
+export interface CreateUserSubscriptionInput {
+  user_id: string;
+  tier_id: string;
+  stripe_customer_id?: string;
+  stripe_subscription_id?: string;
+  status?: SubscriptionStatus;
+  current_period_start?: Date;
+  current_period_end?: Date;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User subscription update payload
+ */
+export interface UpdateUserSubscriptionInput {
+  tier_id?: string;
+  stripe_customer_id?: string;
+  stripe_subscription_id?: string;
+  status?: SubscriptionStatus;
+  current_period_start?: Date;
+  current_period_end?: Date;
+  cancel_at_period_end?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Subscriptions store interface
+ */
+export interface SubscriptionsStore {
+  /** Store name (e.g., 'postgres') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, etc.)
+   */
+  initialize(): Promise<void>;
+
+  // Tiers
+  /**
+   * Create a subscription tier
+   */
+  createTier(input: CreateTierInput): Promise<SubscriptionTier>;
+
+  /**
+   * Get tier by ID
+   */
+  getTierById(id: string): Promise<SubscriptionTier | null>;
+
+  /**
+   * Get tier by slug
+   */
+  getTierBySlug(slug: string): Promise<SubscriptionTier | null>;
+
+  /**
+   * List all tiers
+   */
+  listTiers(activeOnly?: boolean): Promise<SubscriptionTier[]>;
+
+  /**
+   * Update a tier
+   */
+  updateTier(id: string, input: UpdateTierInput): Promise<SubscriptionTier | null>;
+
+  /**
+   * Delete a tier (soft delete)
+   */
+  deleteTier(id: string): Promise<boolean>;
+
+  // Entitlements
+  /**
+   * Create an entitlement
+   */
+  createEntitlement(input: CreateEntitlementInput): Promise<SubscriptionEntitlement>;
+
+  /**
+   * Get entitlements for a tier
+   */
+  getEntitlementsByTier(tierId: string): Promise<SubscriptionEntitlement[]>;
+
+  /**
+   * Update an entitlement
+   */
+  updateEntitlement(id: string, limitValue: number | null): Promise<SubscriptionEntitlement | null>;
+
+  /**
+   * Delete an entitlement
+   */
+  deleteEntitlement(id: string): Promise<boolean>;
+
+  /**
+   * Set multiple entitlements for a tier (upsert)
+   */
+  setTierEntitlements(tierId: string, entitlements: Array<{ feature_code: string; limit_value?: number }>): Promise<void>;
+
+  // User Subscriptions
+  /**
+   * Create a user subscription
+   */
+  createUserSubscription(input: CreateUserSubscriptionInput): Promise<UserSubscription>;
+
+  /**
+   * Get user subscription by ID
+   */
+  getUserSubscriptionById(id: string): Promise<UserSubscription | null>;
+
+  /**
+   * Get active subscription for a user
+   */
+  getActiveSubscription(userId: string): Promise<UserSubscriptionWithTier | null>;
+
+  /**
+   * Get subscription by Stripe subscription ID
+   */
+  getByStripeSubscriptionId(stripeSubId: string): Promise<UserSubscription | null>;
+
+  /**
+   * Update user subscription
+   */
+  updateUserSubscription(id: string, input: UpdateUserSubscriptionInput): Promise<UserSubscription | null>;
+
+  /**
+   * Cancel subscription (sets cancel_at_period_end)
+   */
+  cancelSubscription(id: string): Promise<boolean>;
+
+  /**
+   * Get feature limit for a user
+   */
+  getFeatureLimit(userId: string, featureCode: string): Promise<number | null>;
+
+  /**
+   * Check if user has a feature
+   */
+  hasFeature(userId: string, featureCode: string): Promise<boolean>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * PostgreSQL subscriptions store configuration
+ */
+export interface PostgresSubscriptionsStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one */
+  pool: unknown | (() => unknown);
+  /** Tiers table name (default: 'subscription_tiers') */
+  tiersTable?: string;
+  /** Entitlements table name (default: 'subscription_entitlements') */
+  entitlementsTable?: string;
+  /** User subscriptions table name (default: 'user_subscriptions') */
+  userSubscriptionsTable?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * API configuration
+ */
+export interface SubscriptionsApiConfig {
+  /** API route prefix (default: '/subscriptions') */
+  prefix?: string;
+  /** Enable tier management endpoints */
+  tierManagement?: boolean;
+  /** Enable user subscription endpoints */
+  userSubscriptions?: boolean;
+}
+
+/**
+ * Subscriptions plugin configuration
+ */
+export interface SubscriptionsPluginConfig {
+  /** Subscriptions storage backend */
+  store: SubscriptionsStore;
+  /** Default tier slug for new users (default: 'free') */
+  defaultTierSlug?: string;
+  /** Whether to auto-create default subscription for new users */
+  autoCreateDefaultSubscription?: boolean;
+  /** API configuration */
+  api?: SubscriptionsApiConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}

package/src/plugins/usage/__tests__/usage-plugin.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Usage Plugin Tests
+ *
+ * Unit tests for the usage tracking plugin including:
+ * - Plugin lifecycle
+ * - Daily/monthly usage tracking
+ * - Increment and check limits
+ * - Cleanup operations
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  createUsagePlugin,
+  getUsageStore,
+  getDailyUsage,
+  incrementUsage,
+  checkUsageLimit,
+  getDailyUsageSummary,
+  resetUsage,
+} from '../usage-plugin.js';
+import type { UsageStore, DailyUsage, MonthlyUsage } from '../types.js';
+import type { PluginRegistry } from '../../../core/plugin-registry.js';
+
+// Mock the subscriptions plugin (usage plugin depends on it for limits)
+vi.mock('../../subscriptions/subscriptions-plugin.js', () => ({
+  getFeatureLimit: vi.fn().mockResolvedValue(-1), // unlimited by default
+  hasFeature: vi.fn().mockResolvedValue(true),
+}));
+
+import { getFeatureLimit } from '../../subscriptions/subscriptions-plugin.js';
+
+describe('Usage Plugin', () => {
+  // Mock usage data
+  const mockDailyUsage: DailyUsage = {
+    id: 'usage-id-123',
+    user_id: 'user-123',
+    feature_code: 'ai_messages',
+    date: new Date().toISOString().split('T')[0],
+    count: 10,
+    metadata: {},
+    created_at: new Date(),
+    updated_at: new Date(),
+  };
+
+  const mockMonthlyUsage: MonthlyUsage = {
+    id: 'monthly-id-123',
+    user_id: 'user-123',
+    feature_code: 'ai_messages',
+    year_month: new Date().toISOString().substring(0, 7),
+    count: 300,
+    metadata: {},
+    created_at: new Date(),
+    updated_at: new Date(),
+  };
+
+  // Mock store factory
+  const createMockStore = (): UsageStore => ({
+    name: 'mock',
+    initialize: vi.fn().mockResolvedValue(undefined),
+    getDailyUsage: vi.fn().mockResolvedValue(mockDailyUsage),
+    getMonthlyUsage: vi.fn().mockResolvedValue(mockMonthlyUsage),
+    incrementDaily: vi.fn().mockResolvedValue(11),
+    getAllDailyUsage: vi.fn().mockResolvedValue([mockDailyUsage]),
+    getAllMonthlyUsage: vi.fn().mockResolvedValue([mockMonthlyUsage]),
+    resetDailyUsage: vi.fn().mockResolvedValue(undefined),
+    cleanupOldDaily: vi.fn().mockResolvedValue(100),
+    cleanupOldMonthly: vi.fn().mockResolvedValue(12),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+  });
+
+  // Mock registry factory
+  const createMockRegistry = (): PluginRegistry =>
+    ({
+      hasPlugin: vi.fn().mockReturnValue(false),
+      getPlugin: vi.fn().mockReturnValue(null),
+      listPlugins: vi.fn().mockReturnValue([]),
+      addRoute: vi.fn(),
+      addMenuItem: vi.fn(),
+      addPage: vi.fn(),
+      addWidget: vi.fn(),
+      getRoutes: vi.fn().mockReturnValue([]),
+      getMenuItems: vi.fn().mockReturnValue([]),
+      getPages: vi.fn().mockReturnValue([]),
+      getWidgets: vi.fn().mockReturnValue([]),
+      getConfig: vi.fn().mockReturnValue({}),
+      setConfig: vi.fn().mockResolvedValue(undefined),
+      subscribe: vi.fn().mockReturnValue(() => {}),
+      emit: vi.fn(),
+      registerHealthCheck: vi.fn(),
+      getApp: vi.fn().mockReturnValue({} as any),
+      getRouter: vi.fn().mockReturnValue({} as any),
+      getLogger: vi.fn().mockReturnValue({
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      }),
+    }) as unknown as PluginRegistry;
+
+  let mockStore: UsageStore;
+  let mockRegistry: PluginRegistry;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStore = createMockStore();
+    mockRegistry = createMockRegistry();
+  });
+
+  afterEach(async () => {
+    // Clean up
+    const store = getUsageStore();
+    if (store) {
+      const plugin = createUsagePlugin({ store: mockStore });
+      await plugin.onStop?.();
+    }
+  });
+
+  describe('createUsagePlugin', () => {
+    it('should create a plugin with correct id', () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      expect(plugin.id).toBe('usage');
+    });
+
+    it('should create a plugin with correct name', () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      expect(plugin.name).toBe('Usage');
+    });
+
+    it('should create a plugin with version', () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      expect(plugin.version).toBe('1.0.0');
+    });
+  });
+
+  describe('onStart', () => {
+    it('should initialize store on start', async () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockStore.initialize).toHaveBeenCalled();
+    });
+
+    it('should register health check', async () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockRegistry.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'usage-store',
+          type: 'custom',
+        })
+      );
+    });
+  });
+
+  describe('onStop', () => {
+    it('should shutdown store', async () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+      await plugin.onStop?.();
+
+      expect(mockStore.shutdown).toHaveBeenCalled();
+    });
+
+    it('should clear store reference', async () => {
+      const plugin = createUsagePlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+      await plugin.onStop?.();
+
+      expect(getUsageStore()).toBeNull();
+    });
+  });
+
+  describe('helper functions', () => {
+    describe('getUsageStore', () => {
+      it('should return null when plugin not started', () => {
+        expect(getUsageStore()).toBeNull();
+      });
+
+      it('should return store when plugin started', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        expect(getUsageStore()).toBe(mockStore);
+      });
+    });
+
+    describe('getDailyUsage', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(
+          getDailyUsage('user-id', 'ai_messages')
+        ).rejects.toThrow('Usage plugin not initialized');
+      });
+
+      it('should return daily usage count', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        const result = await getDailyUsage('user-123', 'ai_messages');
+        expect(result).toBe(10); // count from mockDailyUsage
+      });
+
+      it('should return 0 when no usage', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.getDailyUsage as any).mockResolvedValue(null);
+
+        const result = await getDailyUsage('user-123', 'unused_feature');
+        expect(result).toBe(0);
+      });
+    });
+
+    describe('incrementUsage', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(
+          incrementUsage('user-id', 'ai_messages')
+        ).rejects.toThrow('Usage plugin not initialized');
+      });
+
+      it('should increment and return result', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        const result = await incrementUsage('user-123', 'ai_messages');
+
+        expect(result.allowed).toBe(true);
+        expect(result.current_count).toBeDefined();
+        expect(mockStore.incrementDaily).toHaveBeenCalled();
+      });
+
+      it('should increment by custom amount', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.incrementDaily as any).mockResolvedValue(15);
+
+        const result = await incrementUsage('user-123', 'ai_messages', 5);
+
+        expect(result.allowed).toBe(true);
+        expect(result.current_count).toBe(15);
+      });
+    });
+
+    describe('checkUsageLimit', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(
+          checkUsageLimit('user-id', 'ai_messages', 50)
+        ).rejects.toThrow('Usage plugin not initialized');
+      });
+
+      it('should return usage limit result', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        // Reset mock to return -1 (unlimited)
+        (getFeatureLimit as any).mockResolvedValue(-1);
+
+        const result = await checkUsageLimit('user-123', 'ai_messages', -1);
+
+        // Should return a result object with usage info
+        expect(result).toHaveProperty('allowed');
+        expect(result).toHaveProperty('current_count');
+        expect(result).toHaveProperty('limit');
+      });
+    });
+
+    describe('resetUsage', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(
+          resetUsage('user-id', 'ai_messages')
+        ).rejects.toThrow('Usage plugin not initialized');
+      });
+
+      it('should reset usage', async () => {
+        const plugin = createUsagePlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        await resetUsage('user-123', 'ai_messages');
+
+        expect(mockStore.resetDailyUsage).toHaveBeenCalledWith(
+          'user-123',
+          'ai_messages'
+        );
+      });
+    });
+  });
+});

package/src/plugins/usage/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Usage Plugin
+ *
+ * Usage tracking with daily/monthly counters.
+ * Exports all usage-related functionality.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Main plugin
+export {
+  createUsagePlugin,
+  getUsageStore,
+  getDailyUsage,
+  incrementUsage,
+  checkUsageLimit,
+  getFeatureUsageStatus,
+  getDailyUsageSummary,
+  resetUsage,
+  getRemainingQuota,
+  canUseFeature,
+} from './usage-plugin.js';
+
+// Types
+export type {
+  DailyUsage,
+  MonthlyUsage,
+  UsageIncrementResult,
+  UsageStatus,
+  UsageSummary,
+  UsageStore,
+  UsagePluginConfig,
+  UsageApiConfig,
+  UsageCleanupConfig,
+  PostgresUsageStoreConfig,
+} from './types.js';
+
+// Stores
+export { postgresUsageStore } from './stores/index.js';

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

@@ -0,0 +1,9 @@
+/**
+ * Usage Stores
+ *
+ * Export all usage storage implementations.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresUsageStore } from './postgres-store.js';