@qwickapps/server 1.2.0 → 1.3.0

package/src/plugins/entitlements/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Entitlements Plugin
+ *
+ * User entitlement management for @qwickapps/server.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Main plugin
+export { createEntitlementsPlugin } from './entitlements-plugin.js';
+
+// Helper functions
+export {
+  getEntitlementSource,
+  isSourceReadonly,
+  getEntitlements,
+  refreshEntitlements,
+  hasEntitlement,
+  hasAnyEntitlement,
+  hasAllEntitlements,
+  grantEntitlement,
+  revokeEntitlement,
+  setEntitlements,
+  getAvailableEntitlements,
+  getEntitlementStats,
+  invalidateEntitlementCache,
+  storeExternalIdMapping,
+  invalidateByExternalId,
+  // Middleware
+  requireEntitlement,
+  requireAnyEntitlement,
+  requireAllEntitlements,
+} from './entitlements-plugin.js';
+
+// Sources
+export { postgresEntitlementSource } from './sources/index.js';
+
+// Types
+export type {
+  EntitlementSource,
+  EntitlementResult,
+  EntitlementDefinition,
+  EntitlementsPluginConfig,
+  EntitlementCallbacks,
+  EntitlementsCacheConfig,
+  EntitlementsApiConfig,
+  PostgresEntitlementSourceConfig,
+  UserEntitlement,
+  CachedEntitlements,
+  EntitlementStats,
+} from './types.js';

package/src/plugins/entitlements/sources/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Entitlement Sources
+ *
+ * Export all available entitlement source implementations.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresEntitlementSource } from './postgres-source.js';

package/src/plugins/entitlements/sources/postgres-source.ts

@@ -0,0 +1,253 @@
+/**
+ * PostgreSQL Entitlement Source
+ *
+ * Entitlement storage implementation using PostgreSQL.
+ * Stores user entitlements and entitlement definitions.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  EntitlementSource,
+  EntitlementDefinition,
+  EntitlementStats,
+  PostgresEntitlementSourceConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * Create a PostgreSQL entitlement source
+ *
+ * @param config Configuration including a pg Pool instance or a function that returns one
+ * @returns EntitlementSource implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresEntitlementSource } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const source = postgresEntitlementSource({ pool });
+ *
+ * // Or with lazy initialization:
+ * const source = postgresEntitlementSource({ pool: () => getPostgres().getPool() });
+ * ```
+ */
+export function postgresEntitlementSource(config: PostgresEntitlementSourceConfig): EntitlementSource {
+  const {
+    pool: poolOrFn,
+    tableName = 'user_entitlements',
+    definitionsTable = 'entitlement_definitions',
+    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 entitlementsTable = `"${schema}"."${tableName}"`;
+  const defsTable = `"${schema}"."${definitionsTable}"`;
+
+  return {
+    name: 'postgres',
+    description: 'PostgreSQL local entitlements',
+    readonly: false,
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      // Create entitlement definitions table (catalog of available entitlements)
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${defsTable} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          name VARCHAR(255) NOT NULL UNIQUE,
+          category VARCHAR(100),
+          description TEXT,
+          created_at TIMESTAMPTZ DEFAULT NOW()
+        );
+      `);
+
+      // Create user entitlements table (many-to-many style)
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${entitlementsTable} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID,
+          email VARCHAR(255) NOT NULL,
+          entitlement VARCHAR(255) NOT NULL,
+          granted_at TIMESTAMPTZ DEFAULT NOW(),
+          granted_by VARCHAR(255),
+          expires_at TIMESTAMPTZ,
+          metadata JSONB DEFAULT '{}',
+          UNIQUE(email, entitlement)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_email ON ${entitlementsTable}(LOWER(email));
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${entitlementsTable}(user_id) WHERE user_id IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_entitlement ON ${entitlementsTable}(entitlement);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_expires_at ON ${entitlementsTable}(expires_at) WHERE expires_at IS NOT NULL;
+      `);
+    },
+
+    async getEntitlements(identifier: string): Promise<string[]> {
+      const email = identifier.toLowerCase();
+
+      const result = await getPool().query(
+        `SELECT entitlement FROM ${entitlementsTable}
+         WHERE LOWER(email) = $1
+         AND (expires_at IS NULL OR expires_at > NOW())
+         ORDER BY entitlement`,
+        [email]
+      );
+
+      return result.rows.map((row) => (row as { entitlement: string }).entitlement);
+    },
+
+    async getAllAvailable(): Promise<EntitlementDefinition[]> {
+      const result = await getPool().query(
+        `SELECT id, name, category, description FROM ${defsTable}
+         ORDER BY category NULLS LAST, name`
+      );
+
+      return result.rows as EntitlementDefinition[];
+    },
+
+    async getUsersWithEntitlement(
+      entitlement: string,
+      options: { limit?: number; offset?: number } = {}
+    ): Promise<{ emails: string[]; total: number }> {
+      const { limit = 50, offset = 0 } = options;
+
+      // Get total count
+      const countResult = await getPool().query(
+        `SELECT COUNT(DISTINCT email) FROM ${entitlementsTable}
+         WHERE entitlement = $1
+         AND (expires_at IS NULL OR expires_at > NOW())`,
+        [entitlement]
+      );
+      const total = parseInt((countResult.rows[0] as { count: string }).count, 10);
+
+      // Get emails
+      const result = await getPool().query(
+        `SELECT DISTINCT email FROM ${entitlementsTable}
+         WHERE entitlement = $1
+         AND (expires_at IS NULL OR expires_at > NOW())
+         ORDER BY email
+         LIMIT $2 OFFSET $3`,
+        [entitlement, limit, offset]
+      );
+
+      return {
+        emails: result.rows.map((row) => (row as { email: string }).email),
+        total,
+      };
+    },
+
+    async addEntitlement(identifier: string, entitlement: string, grantedBy?: string): Promise<void> {
+      const email = identifier.toLowerCase();
+
+      // Use ON CONFLICT to handle duplicates (update granted_at if re-granting)
+      await getPool().query(
+        `INSERT INTO ${entitlementsTable} (email, entitlement, granted_by)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (email, entitlement) DO UPDATE SET
+           granted_at = NOW(),
+           granted_by = EXCLUDED.granted_by,
+           expires_at = NULL`,
+        [email, entitlement, grantedBy || 'system']
+      );
+
+      // Auto-create definition if it doesn't exist
+      await getPool().query(
+        `INSERT INTO ${defsTable} (name)
+         VALUES ($1)
+         ON CONFLICT (name) DO NOTHING`,
+        [entitlement]
+      );
+    },
+
+    async removeEntitlement(identifier: string, entitlement: string): Promise<void> {
+      const email = identifier.toLowerCase();
+
+      await getPool().query(
+        `DELETE FROM ${entitlementsTable}
+         WHERE LOWER(email) = $1 AND entitlement = $2`,
+        [email, entitlement]
+      );
+    },
+
+    async setEntitlements(identifier: string, entitlements: string[]): Promise<void> {
+      const email = identifier.toLowerCase();
+      const pool = getPool();
+
+      // Start a transaction
+      await pool.query('BEGIN');
+
+      try {
+        // Remove all existing entitlements for this email
+        await pool.query(
+          `DELETE FROM ${entitlementsTable} WHERE LOWER(email) = $1`,
+          [email]
+        );
+
+        // Insert new entitlements
+        if (entitlements.length > 0) {
+          const values = entitlements
+            .map((_, i) => `($1, $${i + 2}, 'system')`)
+            .join(', ');
+
+          await pool.query(
+            `INSERT INTO ${entitlementsTable} (email, entitlement, granted_by)
+             VALUES ${values}`,
+            [email, ...entitlements]
+          );
+
+          // Auto-create definitions for any new entitlements
+          for (const ent of entitlements) {
+            await pool.query(
+              `INSERT INTO ${defsTable} (name)
+               VALUES ($1)
+               ON CONFLICT (name) DO NOTHING`,
+              [ent]
+            );
+          }
+        }
+
+        await pool.query('COMMIT');
+      } catch (error) {
+        await pool.query('ROLLBACK');
+        throw error;
+      }
+    },
+
+    async getStats(): Promise<EntitlementStats> {
+      const result = await getPool().query(
+        `SELECT
+           COUNT(DISTINCT email) as users_with_entitlements,
+           COUNT(DISTINCT entitlement) as total_entitlements
+         FROM ${entitlementsTable}
+         WHERE expires_at IS NULL OR expires_at > NOW()`
+      );
+
+      const row = result.rows[0] as {
+        users_with_entitlements: string;
+        total_entitlements: string;
+      };
+
+      return {
+        usersWithEntitlements: parseInt(row.users_with_entitlements, 10) || 0,
+        totalEntitlements: parseInt(row.total_entitlements, 10) || 0,
+      };
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/entitlements/types.ts

@@ -0,0 +1,256 @@
+/**
+ * Entitlements Plugin Types
+ *
+ * Type definitions for entitlement management.
+ * Entitlements are string-based tags (e.g., 'pro', 'enterprise', 'feature:analytics').
+ * Sources can be local (PostgreSQL) or remote (Keap, Stripe, etc.).
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Entitlement definition - describes an available entitlement
+ */
+export interface EntitlementDefinition {
+  /** Unique ID (UUID for Postgres, tag ID for external sources) */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Category for grouping (optional) */
+  category?: string;
+  /** Description (optional) */
+  description?: string;
+}
+
+/**
+ * Result from entitlement lookup
+ */
+export interface EntitlementResult {
+  /** Identifier used for lookup (email) */
+  identifier: string;
+  /** Array of entitlement strings (tag names) */
+  entitlements: string[];
+  /** Source that provided the entitlements */
+  source: 'cache' | string;
+  /** When the data was cached (ISO string) */
+  cachedAt?: string;
+  /** When the cache expires (ISO string) */
+  expiresAt?: string;
+  /** Per-source breakdown (when multiple sources) */
+  bySource?: Record<string, string[]>;
+  /** Additional metadata from source */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User entitlement record (for writable sources)
+ */
+export interface UserEntitlement {
+  /** Record ID */
+  id: string;
+  /** User ID (optional, for linking to users table) */
+  user_id?: string;
+  /** User email (always present) */
+  email: string;
+  /** Entitlement name/tag */
+  entitlement: string;
+  /** When granted */
+  granted_at: Date;
+  /** Who granted it */
+  granted_by?: string;
+  /** When it expires (null = permanent) */
+  expires_at?: Date;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * EntitlementSource interface - adapter pattern for pluggable sources
+ *
+ * Identifier is typically email, but sources may support other identifiers
+ * (e.g., Keap contact ID). The plugin normalizes to email for caching.
+ */
+export interface EntitlementSource {
+  /** Unique source name (e.g., 'postgres', 'keap') */
+  name: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  /** Whether this source is read-only (no add/remove operations) */
+  readonly?: boolean;
+
+  /**
+   * Initialize the source (create tables, establish connections, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get entitlements for an identifier
+   * @param identifier Email or other identifier
+   * @returns Array of entitlement strings (tag names)
+   */
+  getEntitlements(identifier: string): Promise<string[]>;
+
+  /**
+   * Get all available entitlements that can be assigned
+   * Optional - returns empty array if not implemented
+   */
+  getAllAvailable?(): Promise<EntitlementDefinition[]>;
+
+  /**
+   * Search for users with a specific entitlement
+   * Optional - for sources that support reverse lookup
+   */
+  getUsersWithEntitlement?(entitlement: string, options?: {
+    limit?: number;
+    offset?: number;
+  }): Promise<{ emails: string[]; total: number }>;
+
+  /**
+   * Add an entitlement to a user
+   * @throws Error if source is read-only
+   */
+  addEntitlement?(identifier: string, entitlement: string, grantedBy?: string): Promise<void>;
+
+  /**
+   * Remove an entitlement from a user
+   * @throws Error if source is read-only
+   */
+  removeEntitlement?(identifier: string, entitlement: string): Promise<void>;
+
+  /**
+   * Bulk set entitlements for a user (replaces all existing)
+   * Optional - for sources that support batch operations
+   */
+  setEntitlements?(identifier: string, entitlements: string[]): Promise<void>;
+
+  /**
+   * Shutdown the source (close connections, cleanup)
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Check if the source is healthy (optional)
+   * Used for health checks without making expensive API calls.
+   * If not implemented, health check will assume healthy if initialized.
+   */
+  isHealthy?(): Promise<boolean>;
+
+  /**
+   * Get statistics about entitlements (optional)
+   * Used for dashboard widgets showing user counts with entitlements.
+   */
+  getStats?(): Promise<EntitlementStats>;
+}
+
+/**
+ * Statistics about entitlements from a source
+ */
+export interface EntitlementStats {
+  /** Total users with at least one entitlement */
+  usersWithEntitlements: number;
+  /** Total number of unique entitlements/tags */
+  totalEntitlements?: number;
+  /** Additional source-specific stats */
+  [key: string]: unknown;
+}
+
+/**
+ * Entitlement callbacks
+ */
+export interface EntitlementCallbacks {
+  /** Called when entitlements are fetched */
+  onFetch?: (identifier: string, entitlements: string[], source: string) => Promise<void>;
+  /** Called when entitlements change */
+  onChange?: (identifier: string, added: string[], removed: string[]) => Promise<void>;
+  /** Called when an entitlement is granted */
+  onGrant?: (identifier: string, entitlement: string, grantedBy?: string) => Promise<void>;
+  /** Called when an entitlement is revoked */
+  onRevoke?: (identifier: string, entitlement: string) => Promise<void>;
+}
+
+/**
+ * Cache configuration for entitlements
+ */
+export interface EntitlementsCacheConfig {
+  /** Enable caching (default: true) */
+  enabled?: boolean;
+  /** Cache instance name from cache plugin (default: 'default') */
+  instanceName?: string;
+  /** Cache key prefix (default: 'entitlements:') */
+  keyPrefix?: string;
+  /** TTL in seconds for cached entitlements (default: 300) */
+  ttl?: number;
+  /** TTL for identifier mappings, e.g., contactId -> email (default: ttl * 2) */
+  mappingTtl?: number;
+}
+
+/**
+ * API configuration for entitlements
+ */
+export interface EntitlementsApiConfig {
+  /** API route prefix (default: '/entitlements'). Note: routes are mounted under /api by control panel */
+  prefix?: string;
+  /** Enable API endpoints (default: true) */
+  enabled?: boolean;
+  /** Enable write endpoints (grant/revoke) - only works with writable source */
+  enableWrite?: boolean;
+}
+
+/**
+ * Entitlements plugin configuration
+ */
+export interface EntitlementsPluginConfig {
+  /** Primary entitlement source */
+  source: EntitlementSource;
+
+  /** Additional sources to query (results are merged) */
+  additionalSources?: EntitlementSource[];
+
+  /** Cache configuration */
+  cache?: EntitlementsCacheConfig;
+
+  /** Callbacks for entitlement events */
+  callbacks?: EntitlementCallbacks;
+
+  /** API configuration */
+  api?: EntitlementsApiConfig;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * PostgreSQL entitlement source configuration
+ */
+export interface PostgresEntitlementSourceConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** User entitlements table name (default: 'user_entitlements') */
+  tableName?: string;
+  /** Entitlement definitions table (default: 'entitlement_definitions') */
+  definitionsTable?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * Cached entitlements structure (stored in Redis)
+ */
+export interface CachedEntitlements {
+  /** Email (normalized lowercase) */
+  email: string;
+  /** Combined entitlements from all sources */
+  entitlements: string[];
+  /** Per-source breakdown */
+  bySource: Record<string, string[]>;
+  /** When cached (ISO string) */
+  cachedAt: string;
+  /** When expires (ISO string) */
+  expiresAt: string;
+  /** Cache version for invalidation */
+  version: number;
+}

package/src/plugins/frontend-app-plugin.ts

@@ -13,7 +13,8 @@
 import express from 'express';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import type { ControlPanelPlugin, FrontendAppConfig } from '../core/types.js';
+import type { Plugin, PluginConfig, PluginRegistry } from '../core/plugin-registry.js';
+import type { FrontendAppConfig } from '../core/types.js';
 import { createRouteGuard } from '../core/guards.js';
 
 export interface FrontendAppPluginConfig {
@@ -27,25 +28,32 @@ export interface FrontendAppPluginConfig {
     heading?: string;
     description?: string;
     links?: Array<{ label: string; url: string }>;
+    /** URL path to the logo icon (SVG, PNG, etc.) */
+    logoIconUrl?: string;
     branding?: {
-      logo?: string;
       primaryColor?: string;
     };
   };
   /** Route guard configuration */
   guard?: FrontendAppConfig['mount']['guard'];
+  /** Product name for default landing page */
+  productName?: string;
+  /** Mount path for control panel link */
+  mountPath?: string;
 }
 
 /**
  * Create a frontend app plugin that handles the root path
  */
-export function createFrontendAppPlugin(config: FrontendAppPluginConfig): ControlPanelPlugin {
+export function createFrontendAppPlugin(config: FrontendAppPluginConfig): Plugin {
   return {
-    name: 'frontend-app',
-    order: 0, // Run first to capture root path
+    id: 'frontend-app',
+    name: 'Frontend App Plugin',
+    version: '1.0.0',
 
-    async onInit(context) {
-      const { app, logger } = context;
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      const logger = registry.getLogger('frontend-app');
+      const app = registry.getApp();
 
       // Apply guard if configured
       if (config.guard && config.guard.type !== 'none') {
@@ -95,16 +103,20 @@ export function createFrontendAppPlugin(config: FrontendAppPluginConfig): Contro
       logger.info(`Frontend app: Serving default welcome page`);
       app.get('/', (_req, res) => {
         const html = generateLandingPageHtml({
-          title: context.config.productName,
-          heading: `Welcome to ${context.config.productName}`,
+          title: config.productName || 'QwickApps Server',
+          heading: `Welcome to ${config.productName || 'QwickApps Server'}`,
           description: 'Your application is running.',
           links: [
-            { label: 'Control Panel', url: context.config.mountPath || '/cpanel' },
+            { label: 'Control Panel', url: config.mountPath || '/cpanel' },
           ],
         });
         res.type('html').send(html);
       });
     },
+
+    async onStop(): Promise<void> {
+      // Nothing to cleanup
+    },
   };
 }
 
@@ -143,7 +155,7 @@ function generateLandingPageHtml(config: NonNullable<FrontendAppPluginConfig['la
       max-width: 600px;
       padding: 2rem;
     }
-    ${config.branding?.logo ? `
+    ${config.logoIconUrl ? `
     .logo {
       width: 80px;
       height: 80px;
@@ -198,7 +210,7 @@ function generateLandingPageHtml(config: NonNullable<FrontendAppPluginConfig['la
 </head>
 <body>
   <div class="container">
-    ${config.branding?.logo ? `<img src="${config.branding.logo}" alt="Logo" class="logo">` : ''}
+    ${config.logoIconUrl ? `<img src="${config.logoIconUrl}" alt="Logo" class="logo">` : ''}
     <h1>${config.heading || config.title}</h1>
     ${config.description ? `<p>${config.description}</p>` : ''}
     ${linksHtml ? `<div class="links">${linksHtml}</div>` : ''}