Add trial, purchase handlers (#934)

NiloCK · web-flow · commit a26b4f28b04e · 2025-10-22T23:39:32.000-03:00
- **add config loading from window.__SKUILDER_CONFIG__**
- **bump: version 0.1.13-10**
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "type": "module",
   "description": "CLI scaffolding tool for vue-skuilder projects",
   "bin": {
diff --git a/packages/client/package.json b/packages/client/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
diff --git a/packages/common-ui/RUNTIME_CONFIG.md b/packages/common-ui/RUNTIME_CONFIG.md
@@ -0,0 +1,83 @@
+# Runtime Configuration
+
+## Overview
+
+The `common-ui` library supports runtime configuration through a global `window.__SKUILDER_CONFIG__` object. This is necessary because library code is pre-built and cannot access build-time environment variables from consuming applications.
+
+## Configuration Priority
+
+Configuration values are resolved in this order:
+1. **Build-time env vars** (`import.meta.env.VITE_*`) - Only works if the consuming app's bundler processes the library code
+2. **Runtime config** (`window.__SKUILDER_CONFIG__`) - Always works, set by consuming app at startup
+3. **Fallback** - Empty string or default values
+
+## Usage in Consuming Apps
+
+Set `window.__SKUILDER_CONFIG__` **before** importing any `@vue-skuilder` packages:
+
+```typescript
+// In your main.ts / main.js - BEFORE imports
+window.__SKUILDER_CONFIG__ = {
+  apiBase: '/express',  // API base path for auth/backend calls
+  // Add other runtime config here as needed
+};
+
+// Now import vue-skuilder packages
+import { useAuthStore } from '@vue-skuilder/common-ui';
+```
+
+## Available Configuration
+
+### `apiBase` (string)
+
+Base path for API calls to the Express backend.
+
+- **Default**: `''` (empty string, uses relative paths)
+- **Example**: `'/express'` - prepends `/express` to all auth API calls
+- **Used by**: `authAPI.ts` service functions
+
+**Example**:
+```typescript
+window.__SKUILDER_CONFIG__ = {
+  apiBase: '/express',
+};
+
+// Results in calls like:
+// - /express/auth/send-verification
+// - /express/auth/verify
+// - /express/auth/status
+```
+
+## Debugging
+
+All services that use runtime config will log their configuration source and resolved values:
+
+```
+[authAPI] getApiBase() called
+[authAPI]   source: window.__SKUILDER_CONFIG__.apiBase
+[authAPI]   result: /express
+```
+
+## TypeScript Support
+
+The global type declaration is included in the library:
+
+```typescript
+declare global {
+  interface Window {
+    __SKUILDER_CONFIG__?: {
+      apiBase?: string;
+      [key: string]: any;
+    };
+  }
+}
+```
+
+## Adding New Config Values
+
+When adding new runtime config values:
+
+1. Add the property to the `Window.__SKUILDER_CONFIG__` interface
+2. Document it in this file
+3. Add appropriate logging when the value is accessed
+4. Consider build-time env var as primary source, runtime config as fallback
diff --git a/packages/common-ui/package.json b/packages/common-ui/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "main": "./dist/common-ui.umd.js",
   "module": "./dist/common-ui.es.js",
   "types": "./dist/index.d.ts",
diff --git a/packages/common-ui/src/services/authAPI.ts b/packages/common-ui/src/services/authAPI.ts
@@ -1,19 +1,46 @@
 /**
  * Authentication API service for interacting with Express backend auth endpoints.
- * Uses configurable API base path from environment or falls back to relative paths.
+ * Uses configurable API base path from environment or runtime config.
  */
 
-// Get API base path from environment, defaulting to empty string for relative paths
+// Global runtime configuration (set by consuming app)
+declare global {
+  interface Window {
+    __SKUILDER_CONFIG__?: {
+      apiBase?: string;
+      [key: string]: any;
+    };
+  }
+}
+
+// Get API base path: check env first, then runtime config, then fallback to empty
 const getApiBase = (): string => {
+  let source = 'fallback (empty string)';
+  let result = '';
+
+  // Try import.meta.env first (build-time, only works in consuming app builds)
   if (typeof import.meta !== 'undefined' && import.meta.env) {
     const base = import.meta.env.VITE_API_BASE_URL;
     if (base) {
-      // Remove trailing slash if present, ensure leading slash
       const cleaned = base.replace(/\/$/, '');
-      return cleaned.startsWith('/') ? cleaned : `/${cleaned}`;
+      result = cleaned.startsWith('/') ? cleaned : `/${cleaned}`;
+      source = 'import.meta.env.VITE_API_BASE_URL';
     }
   }
-  return '';
+
+  // Fallback to runtime config (works in library builds)
+  if (!result && typeof window !== 'undefined' && window.__SKUILDER_CONFIG__?.apiBase) {
+    const base = window.__SKUILDER_CONFIG__.apiBase;
+    const cleaned = base.replace(/\/$/, '');
+    result = cleaned.startsWith('/') ? cleaned : `/${cleaned}`;
+    source = 'window.__SKUILDER_CONFIG__.apiBase';
+  }
+
+  console.log('[authAPI] getApiBase() called');
+  console.log('[authAPI]   source:', source);
+  console.log('[authAPI]   result:', result);
+
+  return result;
 };
 
 export interface AuthResponse {
diff --git a/packages/common/package.json b/packages/common/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
diff --git a/packages/courseware/package.json b/packages/courseware/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "type": "module",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.mjs",
diff --git a/packages/db/package.json b/packages/db/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
diff --git a/packages/edit-ui/package.json b/packages/edit-ui/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "main": "./dist/edit-ui.umd.js",
   "module": "./dist/edit-ui.es.js",
   "types": "./dist/index.d.ts",
diff --git a/packages/express/.env.development b/packages/express/.env.development
@@ -9,3 +9,7 @@ COUCHDB_PASSWORD=password
 NODE_ENV=platform
 
 VERSION=localdev
+
+# Shared secret for payment webhook authorization (Stripe → /express/permissions)
+# Must match PERMISSIONS_SECRET in business backend .env
+PERMISSIONS_SECRET=dev-permissions-secret-12345
diff --git a/packages/express/package.json b/packages/express/package.json
@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "description": "an API",
   "main": "dist/index.js",
   "type": "module",
diff --git a/packages/express/src/routes/auth.ts b/packages/express/src/routes/auth.ts
@@ -289,4 +289,175 @@ router.post('/reset-password', (req: Request, res: Response) => {
   })();
 });
 
+/**
+ * POST /auth/initialize-trial
+ * Initialize trial entitlement for newly created user
+ * Called by frontend immediately after CouchDB account creation
+ *
+ * Body params:
+ *   - username: string (required) - CouchDB username
+ *   - origin: string (optional) - Frontend origin URL (e.g., 'letterspractice.com') for courseId inference
+ *   - courseId: string (optional) - Explicit courseId, if not provided inferred from origin
+ */
+router.post('/initialize-trial', (req: Request, res: Response) => {
+  void (async () => {
+    try {
+      const { username, origin, courseId: explicitCourseId } = req.body;
+
+      if (!username) {
+        return res.status(400).json({ ok: false, error: 'Username required' });
+      }
+
+      // Infer courseId from origin if not explicitly provided
+      let courseId = explicitCourseId;
+      if (!courseId && origin) {
+        // Generic origin-to-courseId conversion (e.g., 'example.com' → 'example-com')
+        // Consuming apps can override by passing explicit courseId
+        courseId = origin.replace(/\./g, '-').replace(/:/g, '-').toLowerCase();
+      }
+
+      // Require courseId to be provided via explicit param or origin
+      if (!courseId) {
+        return res.status(400).json({
+          ok: false,
+          error: 'courseId or origin required to initialize trial'
+        });
+      }
+
+      // Find user in _users db (should exist since just created via CouchDB)
+      const userDoc = await findUserByUsername(username);
+      if (!userDoc) {
+        return res.status(404).json({ ok: false, error: 'User not found' });
+      }
+
+      // Initialize entitlements if not present
+      if (!userDoc.entitlements) {
+        userDoc.entitlements = {};
+      }
+
+      // Don't overwrite if entitlement already exists (idempotent)
+      if (userDoc.entitlements[courseId]) {
+        logger.info(`Trial already initialized for ${username} on ${courseId} - skipping`);
+        return res.json({
+          ok: true,
+          message: 'Trial already initialized',
+          entitlement: userDoc.entitlements[courseId]
+        });
+      }
+
+      // Calculate expiration: 30 days from now
+      const now = new Date();
+      const expiresDate = new Date(now);
+      expiresDate.setDate(expiresDate.getDate() + 30);
+
+      // Create trial entitlement
+      userDoc.entitlements[courseId] = {
+        status: 'trial',
+        registrationDate: now.toISOString(),
+        purchaseDate: "not-yet",
+        expires: expiresDate.toISOString(),
+      };
+
+      await updateUserDoc(userDoc);
+
+      logger.info(`Trial initialized for ${username} on ${courseId} - expires ${expiresDate.toISOString()}`);
+
+      res.json({
+        ok: true,
+        entitlement: userDoc.entitlements[courseId]
+      });
+
+    } catch (error) {
+      logger.error('Error initializing trial:', error);
+      res.status(500).json({
+        ok: false,
+        error: 'Failed to initialize trial',
+      });
+    }
+  })();
+});
+
+/**
+ * POST /auth/permissions
+ * Grant or update course permissions for a user (called by payment webhooks)
+ *
+ * Body params:
+ *   - userId: string (required) - CouchDB username
+ *   - courseId: string (required) - Course identifier
+ *   - action: 'grant_access' (required)
+ *   - provider: string (optional) - 'stripe', 'manual', etc.
+ *   - metadata: object (optional) - Additional payment metadata
+ */
+router.post('/permissions', (req: Request, res: Response) => {
+  void (async () => {
+    try {
+      // Verify authorization
+      const authHeader = req.headers.authorization;
+      const expectedAuth = `Bearer ${process.env.PERMISSIONS_SECRET}`;
+
+      if (!authHeader || authHeader !== expectedAuth) {
+        logger.warn('Unauthorized permissions request');
+        return res.status(401).json({ ok: false, error: 'Unauthorized' });
+      }
+
+      const { userId, courseId, action, provider } = req.body;
+
+      // Validate required fields
+      if (!userId || !courseId || !action) {
+        return res.status(400).json({
+          ok: false,
+          error: 'Missing required fields: userId, courseId, action'
+        });
+      }
+
+      if (action !== 'grant_access') {
+        return res.status(400).json({
+          ok: false,
+          error: 'Invalid action. Only "grant_access" is supported.'
+        });
+      }
+
+      // Find user in _users db
+      const userDoc = await findUserByUsername(userId);
+      if (!userDoc) {
+        logger.error(`Permissions request for non-existent user: ${userId}`);
+        return res.status(404).json({ ok: false, error: 'User not found' });
+      }
+
+      // Initialize entitlements if not present
+      if (!userDoc.entitlements) {
+        userDoc.entitlements = {};
+      }
+
+      // Get existing entitlement (preserve registrationDate if exists)
+      const existingEntitlement = userDoc.entitlements[courseId];
+
+      // Update to paid status
+      userDoc.entitlements[courseId] = {
+        status: 'paid',
+        registrationDate: existingEntitlement?.registrationDate || new Date().toISOString(),
+        purchaseDate: new Date().toISOString(),
+        // No expires field for paid users
+      };
+
+      // Save to _users db
+      await updateUserDoc(userDoc);
+
+      logger.info(`Granted ${courseId} access to user ${userId} via ${provider || 'unknown'}`);
+
+      res.json({
+        ok: true,
+        message: `Access granted to ${courseId} for user ${userId}`
+      });
+
+    } catch (error) {
+      logger.error('Error granting permissions:', error);
+      res.status(500).json({
+        ok: false,
+        error: 'Failed to grant permissions',
+      });
+    }
+  })();
+});
+
 export default router;
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@vue-skuilder/mcp",
-  "version": "0.1.13-9",
+  "version": "0.1.13-10",
   "type": "module",
   "exports": {
     ".": {
diff --git a/packages/platform-ui/package.json b/packages/platform-ui/package.json
diff --git a/packages/standalone-ui/package.json b/packages/standalone-ui/package.json
diff --git a/packages/studio-ui/package.json b/packages/studio-ui/package.json
