backend-manager 5.0.202 → 5.1.0

package/docs/admin-post-route.md

@@ -0,0 +1,24 @@
+# Admin Post Route
+
+The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, upload, and body rewriting.
+
+## Image Processing Flow
+
+1. Receives markdown body with external image URLs (e.g., `![alt](https://images.unsplash.com/...)`)
+2. Extracts all `![alt](url)` patterns from the body using regex
+3. Downloads each image and uploads it to `src/assets/images/blog/post-{id}/` on GitHub
+4. **Rewrites the body** to replace external URLs with `@post/{filename}` format
+5. The `@post/` prefix is resolved at Jekyll build time by `jekyll-uj-powertools` to the full path
+
+## Key Details
+
+- Image filenames are derived from `hyphenate(alt_text)` + downloaded extension
+- Header image (`headerImageURL`) is uploaded but NOT rewritten in the body (it's in frontmatter)
+- Failed image downloads are skipped — the original external URL stays in the body
+- The `extractImages()` function returns a URL mapping used for body rewriting
+
+## Files
+
+- `src/manager/routes/admin/post/post.js` — POST handler (create)
+- `src/manager/routes/admin/post/put.js` — PUT handler (edit)
+- `src/manager/routes/admin/post/templates/post.html` — Post template

package/docs/ai-library.md

@@ -0,0 +1,23 @@
+# AI Library
+
+`Manager.AI(assistant).request({ provider, model, messages, ... })` is the unified entry for all AI calls. Provider-agnostic surface — same options shape, same return shape.
+
+| Provider | Default model | Notes |
+|---|---|---|
+| `openai` | `gpt-5-mini` | Better at structured JSON via JSON schema |
+| `anthropic` | `claude-sonnet-4-6` | Better at SVG illustrations and creative output |
+
+Return shape (same for all providers): `{ content, output, tokens, raw }`.
+
+`options.response: 'json'` triggers JSON parsing — both providers strip fences and parse with JSON5 for robustness. `options.schema` enforces structure on OpenAI (real JSON schema) and is injected into the system prompt on Anthropic.
+
+API keys: `BACKEND_MANAGER_OPENAI_API_KEY`, `BACKEND_MANAGER_ANTHROPIC_API_KEY` (process.env or config).
+
+The legacy `src/manager/libraries/openai.js` is a thin compatibility shim that re-exports the OpenAI provider class — existing callers using `new OpenAI(assistant, key)` still work unchanged.
+
+| File | Purpose |
+|---|---|
+| `src/manager/libraries/ai/index.js` | Unified `AI` class (dispatches by provider) |
+| `src/manager/libraries/ai/providers/openai.js` | OpenAI provider (original `openai.js` content) |
+| `src/manager/libraries/ai/providers/anthropic.js` | Anthropic provider (Claude Messages API) |
+| `src/manager/libraries/openai.js` | Back-compat shim → providers/openai.js |

package/docs/architecture.md

@@ -0,0 +1,31 @@
+# Architecture
+
+## Manager Class
+
+The core `Manager` class (in `src/manager/index.js`) extends EventEmitter and orchestrates all functionality:
+- Initializes Firebase Admin SDK
+- Sets up built-in Cloud Functions (`bm_api`, auth events, cron)
+- Provides factory methods for helper classes
+- Manages configuration from multiple sources
+
+## Dual-Mode Support
+
+BEM supports two deployment modes:
+- **Firebase Functions** (`projectType: 'firebase'`): Cloud Functions with Firebase triggers
+- **Custom Server** (`projectType: 'custom'`): Express server for non-Firebase deployments
+
+## Helper Factory Pattern
+
+All helpers are accessed via factory methods on the Manager instance:
+
+```javascript
+Manager.Assistant({ req, res })  // Request handler
+Manager.User(data)               // User properties
+Manager.Analytics({ assistant }) // GA4 events
+Manager.Usage()                  // Rate limiting
+Manager.Middleware(req, res)     // Request pipeline
+Manager.Settings()               // Schema validation
+Manager.Utilities()              // Batch operations
+Manager.Metadata(doc)            // Timestamps/tags
+Manager.storage({ name })        // Local JSON storage (lowdb)
+```

package/docs/auth-hooks.md

@@ -0,0 +1,74 @@
+# Auth Hooks (Consumer Project)
+
+Auth hooks let consumer projects inject custom logic into BEM's auth event lifecycle. BEM runs its core handler first, then looks for a matching hook at `hooks/auth/{event-name}.js`.
+
+| Hook | File | Behavior |
+|------|------|----------|
+| `before-create` | `hooks/auth/before-create.js` | Runs after BEM's disposable email + rate limit checks. **Can throw `HttpsError` to block signup.** |
+| `before-signin` | `hooks/auth/before-signin.js` | Runs after BEM's activity update. **Can throw `HttpsError` to block sign-in.** |
+| `on-create` | `hooks/auth/on-create.js` | Runs after BEM creates the user doc. **Non-blocking** — errors are caught and logged. |
+| `on-delete` | `hooks/auth/on-delete.js` | Runs after BEM deletes the user doc. **Non-blocking** — errors are caught and logged. |
+
+Hook signature (same as BEM's internal handlers):
+
+```javascript
+module.exports = async ({ Manager, assistant, user, context, libraries }) => {
+  // user: AuthUserRecord (uid, email, providerData, etc.)
+  // context: AuthEventContext for blocking functions (ipAddress, userAgent, additionalUserInfo)
+  //          EventContext for triggers (eventId, eventType, timestamp — no IP/userAgent)
+  // libraries: { admin, functions, ... }
+};
+```
+
+## Blocking hook example (before-create)
+
+```javascript
+// hooks/auth/before-create.js — Only allow Google OAuth signups
+const ENFORCE = true;
+
+const ALLOWED_PROVIDERS = ['google.com'];
+
+module.exports = async ({ assistant, user, context, libraries }) => {
+  if (!ENFORCE) { return; }
+
+  const { functions } = libraries;
+  const provider = context.additionalUserInfo?.providerId;
+
+  if (!ALLOWED_PROVIDERS.includes(provider)) {
+    assistant.error(`hook/before-create: Blocked provider '${provider}' for ${user.email}`);
+    throw new functions.auth.HttpsError('permission-denied', 'Please sign up with Google.');
+  }
+};
+```
+
+## Non-blocking hook example (on-create)
+
+```javascript
+// hooks/auth/on-create.js — Auto-delete spam referrals
+const powertools = require('node-powertools');
+
+const ENFORCE = true;
+const BLOCKED_AFFILIATE_CODES = ['iLvQjmvm'];
+
+module.exports = async ({ Manager, assistant, user, context, libraries }) => {
+  if (!ENFORCE) { return; }
+
+  const { admin } = libraries;
+  const uid = user.uid;
+
+  // Poll until signup route attaches attribution.affiliate.code
+  let referredBy = null;
+
+  await powertools.poll(async () => {
+    const userDoc = await admin.firestore().doc(`users/${uid}`).get().catch(() => null);
+    if (!userDoc?.exists) { return true; }
+    referredBy = userDoc.data()?.attribution?.affiliate?.code;
+    return !!referredBy;
+  }, { interval: 10000, timeout: 60000 }).catch(() => {});
+
+  if (!referredBy || !BLOCKED_AFFILIATE_CODES.includes(referredBy)) { return; }
+
+  // Delete spam account (triggers on-delete for cleanup)
+  await admin.auth().deleteUser(uid).catch(e => assistant.error('Delete failed:', e));
+};
+```

package/docs/cli-firestore-auth.md

@@ -0,0 +1,59 @@
+# CLI: Firestore & Auth Commands
+
+Quick commands for reading/writing Firestore and managing Auth users directly from the terminal. Works in any BEM consumer project (requires `functions/service-account.json` for production, or `--emulator` for local).
+
+**IMPORTANT: All CLI commands (`npx mgr ...`) MUST be run from the consumer project's `functions/` subdirectory** (e.g., `cd /path/to/my-project/functions && npx mgr ...`). The `mgr` binary lives in `functions/node_modules/.bin/` — running from the project root or any other directory will fail.
+
+For log commands, see [docs/cli-logs.md](cli-logs.md).
+
+## Firestore Commands
+
+```bash
+npx mgr firestore:get <path>                          # Read a document
+npx mgr firestore:set <path> '<json>'                 # Write/merge a document
+npx mgr firestore:set <path> '<json>' --no-merge      # Overwrite a document entirely
+npx mgr firestore:query <collection>                  # Query a collection (default limit 25)
+  --where "field==value"                              #   Filter (repeatable for AND)
+  --orderBy "field:desc"                              #   Sort
+  --limit N                                           #   Limit results
+npx mgr firestore:delete <path>                       # Delete a document (prompts for confirmation)
+```
+
+## Auth Commands
+
+```bash
+npx mgr auth:get <uid-or-email>                       # Get user by UID or email (auto-detected via @)
+npx mgr auth:list [--limit N] [--page-token T]        # List users (default 100)
+npx mgr auth:delete <uid-or-email>                    # Delete user (prompts for confirmation)
+npx mgr auth:set-claims <uid-or-email> '<json>'       # Set custom claims
+```
+
+## Shared Flags
+
+| Flag | Description |
+|------|-------------|
+| `--emulator` | Target local emulator instead of production |
+| `--force` | Skip confirmation on destructive operations |
+| `--raw` | Compact JSON output (for piping to `jq` etc.) |
+
+## Examples
+
+```bash
+# Read a user document from production
+npx mgr firestore:get users/abc123
+
+# Write to emulator
+npx mgr firestore:set users/test123 '{"name":"Test User"}' --emulator
+
+# Query with filters
+npx mgr firestore:query users --where "subscription.status==active" --limit 10
+
+# Look up auth user by email
+npx mgr auth:get user@example.com
+
+# Set admin claims
+npx mgr auth:set-claims user@example.com '{"admin":true}'
+
+# Delete from emulator (no confirmation needed)
+npx mgr firestore:delete users/test123 --emulator
+```

package/docs/cli-logs.md

@@ -0,0 +1,67 @@
+# CLI: Logs Commands
+
+Fetch or stream Cloud Function logs from Google Cloud Logging. Requires `gcloud` CLI installed and authenticated. Auto-resolves the project ID from `service-account.json`, `.firebaserc`, or `GCLOUD_PROJECT`.
+
+> All `npx mgr ...` commands must be run from the consumer project's `functions/` subdirectory. See [docs/cli-firestore-auth.md](cli-firestore-auth.md) for the explanation.
+
+## Commands
+
+```bash
+npx mgr logs:read                                     # Read last 1h of logs (default: 300 entries, newest first)
+npx mgr logs:read --fn bm_api                         # Filter by function name
+npx mgr logs:read --fn bm_api --severity ERROR        # Filter by severity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+npx mgr logs:read --since 2d --limit 100              # Custom time range and limit
+npx mgr logs:read --search "72.134.242.25"            # Search textPayload for a string (IP, email, error, etc.)
+npx mgr logs:read --fn bm_authBeforeCreate --search "ian@example.com" --since 7d  # Combined filters
+npx mgr logs:read --order asc                         # Oldest first (default: desc/newest first)
+npx mgr logs:read --filter 'jsonPayload.level="error"'  # Raw gcloud filter passthrough
+npx mgr logs:tail                                     # Stream live logs
+npx mgr logs:tail --fn bm_paymentsWebhookOnWrite      # Stream filtered live logs
+```
+
+Both commands save output to `functions/logs.log` (overwritten on each run). `logs:read` saves raw JSON; `logs:tail` streams text.
+
+**Cloud Logs vs Local Logs:** These commands query **production** Google Cloud Logging. For **local/dev** logs, read `functions/serve.log` (from `npx mgr serve`) or `functions/emulator.log` (from `npx mgr test`) directly — they are plain text files, not gcloud.
+
+## Flags
+
+| Flag | Description | Default | Commands |
+|------|-------------|---------|----------|
+| `--fn <name>` | Filter by Cloud Function name (see table below) | all | both |
+| `--severity <level>` | Minimum severity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | all | both |
+| `--search <text>` | Search textPayload for a substring (IP, email, uid, error message) | none | both |
+| `--filter <expr>` | Raw gcloud logging filter expression (appended to built-in filters) | none | both |
+| `--since <duration>` | Time range (`30m`, `1h`, `2d`, `1w`) | `1h` | read only |
+| `--limit <n>` | Max entries | `300` | read only |
+| `--order <dir>` | Sort order: `asc` (oldest first) or `desc` (newest first) | `desc` | read only |
+| `--interval <sec>` | Polling interval in seconds | `5` | tail only |
+| `--raw` | Output raw JSON | false | both |
+
+## `--fn` Function Name Reference
+
+The `--fn` flag uses the **deployed Cloud Function name**, not the route path.
+
+**BEM built-in functions (always deployed):**
+
+| Function name | Type | Description |
+|---------------|------|-------------|
+| `bm_api` | HTTPS | Main API router — all consumer routes (GET/POST/PUT/DELETE) go through this |
+| `bm_authBeforeCreate` | Auth blocking | Before user creation: disposable email blocking, IP rate limiting, consumer hooks |
+| `bm_authBeforeSignIn` | Auth blocking | Before sign-in: consumer hooks |
+| `bm_authOnCreate` | Auth event | After user creation: user doc setup |
+| `bm_authOnDelete` | Auth event | After user deletion |
+| `bm_paymentsWebhookOnWrite` | Firestore trigger | Processes payment webhooks |
+| `bm_paymentsDisputeOnWrite` | Firestore trigger | Processes payment disputes |
+| `bm_notificationsOnWrite` | Firestore trigger | Sends push notifications |
+| `bm_cronDaily` | Scheduled | Daily cron (midnight UTC) |
+| `bm_cronFrequent` | Scheduled | Frequent cron (every 10 min) |
+
+**Consumer-defined functions** use the export name from `functions/index.js` (e.g., `exports.items = ...` → `--fn items`).
+
+**Quick lookup — which function to query:**
+- API route errors → `--fn bm_api`
+- Signup/auth blocked → `--fn bm_authBeforeCreate`
+- Sign-in issues → `--fn bm_authBeforeSignIn`
+- User doc not created → `--fn bm_authOnCreate`
+- Payment not processing → `--fn bm_paymentsWebhookOnWrite`
+- Cron job issues → `--fn bm_cronDaily` or `--fn bm_cronFrequent`

package/docs/code-patterns.md

@@ -0,0 +1,67 @@
+# Code Patterns
+
+## Short-Circuit Returns
+
+Use early returns instead of nested conditionals:
+
+```javascript
+// CORRECT
+function handler(data) {
+  if (!data) {
+    return assistant.errorify('Missing data', { code: 400 });
+  }
+
+  // Main logic here
+  return assistant.respond({ success: true });
+}
+
+// INCORRECT
+function handler(data) {
+  if (data) {
+    // Main logic here
+    return assistant.respond({ success: true });
+  }
+}
+```
+
+## Logical Operators on New Lines
+
+Place operators at the start of continuation lines:
+
+```javascript
+// CORRECT
+const isValid = hasPermission
+  || isAdmin
+  || isOwner;
+
+// INCORRECT
+const isValid = hasPermission ||
+  isAdmin ||
+  isOwner;
+```
+
+## Firestore Document Access
+
+Use shorthand `.doc()` path:
+
+```javascript
+// CORRECT
+admin.firestore().doc('users/abc123')
+
+// INCORRECT
+admin.firestore().collection('users').doc('abc123')
+```
+
+## Template Strings for Requires
+
+```javascript
+// CORRECT
+require(`${functionsDir}/node_modules/backend-manager`)
+
+// INCORRECT
+require(functionsDir + '/node_modules/backend-manager')
+```
+
+## Prefer fs-jetpack
+
+Use `fs-jetpack` over `fs` or `fs-extra` for file operations.

package/docs/common-operations.md

@@ -0,0 +1,64 @@
+# Common Operations
+
+Inside-the-handler patterns for the most frequent operations. See [docs/routes.md](routes.md) for the route file structure itself.
+
+## Authenticate User
+
+```javascript
+const user = await assistant.authenticate();
+if (!user.authenticated) {
+  return assistant.errorify('Authentication required', { code: 401 });
+}
+```
+
+## Read/Write Firestore
+
+```javascript
+const { admin } = Manager.libraries;
+
+// Read
+const doc = await admin.firestore().doc('users/abc123').get();
+const data = doc.data();
+
+// Write
+await admin.firestore().doc('users/abc123').set({ field: 'value' }, { merge: true });
+```
+
+## Handle Errors
+
+```javascript
+// Send error response
+assistant.errorify('Something went wrong', { code: 500, sentry: true });
+
+// Or throw to reject
+return reject(assistant.errorify('Bad request', { code: 400 }));
+```
+
+## Send Response
+
+```javascript
+// Success
+assistant.respond({ success: true, data: result });
+
+// With custom status
+assistant.respond({ created: true }, { code: 201 });
+
+// Redirect
+assistant.respond('https://example.com', { code: 302 });
+```
+
+## Use Hooks (Consumer Project)
+
+```javascript
+Manager.handlers.bm_api = function (mod, position) {
+  const assistant = mod.assistant;
+  const command = assistant.request.data.command;
+
+  return new Promise(async function(resolve, reject) {
+    if (position === 'pre' && command === 'user:sign-up') {
+      // Before sign-up logic
+    }
+    return resolve();
+  });
+};
+```

package/docs/directory-structure.md

@@ -0,0 +1,119 @@
+# Directory Structure
+
+## BEM Library (this repo)
+
+```
+src/
+  manager/
+    index.js                          # Main Manager class
+    helpers/                          # Helper classes
+      assistant.js                    # Request/response handling
+      user.js                         # User property structure + schema
+      analytics.js                    # GA4 integration
+      usage.js                        # Rate limiting
+      middleware.js                   # Request pipeline
+      settings.js                     # Schema validation
+      utilities.js                    # Batch operations
+      metadata.js                     # Timestamps/tags
+    libraries/
+      payment/                        # Shared payment utilities
+        order-id.js                   # Order ID generation (XXXX-XXXX-XXXX)
+        processors/                   # Payment processor libraries
+          stripe.js                   # Stripe SDK init, fetchResource, toUnified*, resolvePriceId
+          paypal.js                   # PayPal fetchResource, toUnified* (custom_id parsing)
+          test.js                     # Test processor (delegates to Stripe shapes)
+    events/                             # All event-driven code
+      auth/                             # Auth event handlers (hookable)
+        before-create.js                # Disposable email blocking + IP rate limiting
+        before-signin.js                # Activity update + sign-in analytics
+        on-create.js                    # User doc creation
+        on-delete.js                    # User doc deletion + marketing cleanup
+        utils.js                        # Shared utilities (retryWrite, runAuthHook)
+      cron/                             # Cron job runners
+        runner.js                       # Shared cron job runner (BEM + consumer hooks)
+        daily.js                        # Daily cron entry point
+        daily/{job}.js                  # Individual daily cron jobs
+        frequent.js                     # Frequent cron entry point
+        frequent/{job}.js               # Individual frequent cron jobs
+      firestore/                        # Firestore triggers
+        payments-webhooks/              # Webhook processing pipeline
+          on-write.js                   # Orchestrator: fetch→transform→transition→write
+          analytics.js                  # Payment analytics tracking (GA4, Meta, TikTok)
+          transitions/                  # State transition detection + handlers
+            index.js                    # Transition detection logic
+            send-email.js               # Shared email helper for handlers
+            subscription/               # Subscription transition handlers
+            one-time/                   # One-time payment transition handlers
+    functions/core/                     # Built-in functions
+      actions/
+        api.js                          # Main bm_api handler
+        api/{category}/{action}.js      # API command handlers
+    routes/                           # Built-in routes
+      admin/
+        post/                         # POST /admin/post - Create blog posts via GitHub
+          post.js                     # Extracts images, uploads to GitHub, rewrites body to @post/ format
+          put.js                      # PUT /admin/post - Edit existing posts
+          templates/
+            post.html                 # Post frontmatter template
+      payments/
+        intent/                       # POST /payments/intent
+          post.js                     # Intent creation orchestrator
+          processors/                 # Per-processor intent creators
+            stripe.js                 # Stripe Checkout Session creation
+            paypal.js                 # PayPal subscription + one-time order creation
+            test.js                   # Test processor (auto-fires webhooks)
+        webhook/                      # POST /payments/webhook
+          post.js                     # Webhook ingestion + Firestore write
+          processors/                 # Per-processor webhook parsers
+            stripe.js                 # Stripe event parsing + categorization
+            paypal.js                 # PayPal event parsing + categorization
+            test.js                   # Test processor (delegates to Stripe)
+        cancel/                       # POST /payments/cancel
+          processors/
+            stripe.js                 # Stripe cancel_at_period_end
+            paypal.js                 # PayPal subscription cancel
+            test.js                   # Test cancel (writes webhook doc)
+        refund/                       # POST /payments/refund
+          processors/
+            stripe.js                 # Stripe refund + immediate cancel
+            paypal.js                 # PayPal refund + cancel
+            test.js                   # Test refund (writes webhook doc)
+        portal/                       # POST /payments/portal
+          processors/
+            stripe.js                 # Stripe billing portal URL
+            paypal.js                 # PayPal management URL
+    schemas/                          # Built-in schemas
+  cli/
+    index.js                          # CLI entry point
+    commands/                         # CLI commands
+  test/
+    test-accounts.js                  # Test account definitions (static + journey)
+templates/
+  backend-manager-config.json         # Config template
+```
+
+## Consumer Project Structure
+
+```
+functions/
+  index.js                            # Manager.init() + custom functions
+  backend-manager-config.json         # App configuration
+  service-account.json                # Firebase credentials
+  routes/
+    {endpoint}/
+      index.js                        # All methods handler
+      get.js                          # GET handler
+      post.js                         # POST handler
+  schemas/
+    {endpoint}/
+      index.js                        # Schema definition
+  hooks/
+    auth/
+      before-create.js                # Custom pre-signup checks (can block)
+      before-signin.js                # Custom pre-signin checks (can block)
+      on-create.js                    # Post-signup side effects (non-blocking)
+      on-delete.js                    # Post-deletion side effects (non-blocking)
+    cron/
+      daily/
+        {job}.js                      # Custom daily jobs
+```

package/docs/environment-detection.md

@@ -0,0 +1,7 @@
+# Environment Detection
+
+```javascript
+assistant.isDevelopment()  // true when ENVIRONMENT !== 'production' or in emulator
+assistant.isProduction()   // true when ENVIRONMENT === 'production'
+assistant.isTesting()      // true when running tests (via npx mgr test)
+```

package/docs/file-naming.md

@@ -0,0 +1,11 @@
+# File Naming Conventions
+
+| Type | Location | Naming |
+|------|----------|--------|
+| Routes | `routes/{name}/` | `index.js` or `{method}.js` |
+| Schemas | `schemas/{name}/` | `index.js` or `{method}.js` |
+| API Commands | `actions/api/{category}/` | `{action}.js` |
+| Auth Events | `events/auth/` | `{event}.js` |
+| Auth Hooks (consumer) | `hooks/auth/` | `{event}.js` |
+| Cron Jobs (BEM) | `events/cron/daily/` | `{job}.js` |
+| Cron Jobs (consumer) | `hooks/cron/daily/` | `{job}.js` |