backend-manager 5.0.203 → 5.1.0

package/TODO-CHARGEBLAST.md

@@ -0,0 +1,32 @@
+As for the AMEX enrollment, AMEX alerts are not supported on Stripe/Shopify. To enable them, you’ll need a dedicated AMEX MID and a payment orchestrator to route all AMEX transactions through that dedicated MID. Using a dedicated AMEX MID allows for a dispute rate of up to 5%, so routing all AMEX traffic through it will significantly reduce your dispute rate on Stripe.
+
+06:44 PM
+For Discover,
+
+In order to enroll in Discover coverage, you will need to do the following:
+
+First, provide us with details about your business below:
+- Merchant Legal Name:
+- Merchant DBA Name:
+- Merchant Registered Street Address:
+- City:
+- Country:
+- State/Province:
+- ZIP/Postal Code:
+
+Second, you must request from your payment processor’s support for a few pieces of information. To do so, please follow the steps below and send them the email template below.
+
+""I am enrolling for Discover Ethoca Alerts via my third-party vendor, Chargeblast. I need my 15-Digit Discover SE number. Can you please provide these pieces of information to me ASAP? Let me know if you need any additional info from me. Please feel free to provide me with these pieces of information piecemeal.”
+
+06:44 PM
+For AMEX If you’d like to proceed with obtaining a dedicated AMEX MID, we’d be happy to arrange an introduction for you.
+
+06:45 PM
+Avatar of Zander
+Zander
+Are we still connected?
+
+06:56 PM
+Avatar of Zander
+Zander
+Since this chat has been inactive, I’ll close it for now. If you have more questions, feel free to contact us at any time. Have a great day ahead!

package/TODO-email-auth.md

@@ -0,0 +1,14 @@
+https://github.com/disposable-email-domains/disposable-email-domains?tab=readme-ov-file
+https://www.npmjs.com/package/disposable-domains
+https://github.com/tompec/disposable-email-domains
+
+Two repos:
+
+Repo	Domains	Approach
+disposable-email-domains/disposable-email-domains	5,359	Curated, conservative, high confidence
+ivolo/disposable-email-domains	121,569	Aggressive, aggregated from many sources, more false positives
+Our current list has 854 — so even the smaller curated list is 6x larger.
+
+For our use case (currently only used to skip marketing sync, not blocking signups), I'd recommend the 5,359 curated list — it's comprehensive enough without being overly aggressive. And if we ever do use it for blocking signups, the false positive risk is much lower.
+
+Want to swap to that one?

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` |