backend-manager 5.0.201 → 5.0.203

package/CHANGELOG.md

@@ -14,6 +14,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.203] - 2026-05-13
+### Fixed
+- `Settings.resolve()` now surfaces a clear `No schema for <METHOD> request: expected <schema>/<method>.js or <schema>/index.js` error (code 500) when both the method-specific schema (e.g. `delete.js`) and the `index.js` fallback are absent. Previously the raw Node `Cannot find module .../<schema>/index.js` error propagated to consumers, leaking the require stack and surfacing the internal `/workspace/...` deploy path.
+- Schema files that exist but throw (syntax error, runtime error) are now re-thrown directly instead of being silently masked by an unintended fallback to `index.js`. The real error surfaces, making bugs in schema files debuggable.
+
+# [5.0.202] - 2026-05-12
+### Added
+- **`src/defaults/CLAUDE.md`** — new file shipped to consumer projects, marker-wrapped with `# ========== Default Values ==========` / `# ========== Custom Values ==========`. Framework section stays live-synced across `npx mgr setup` while the Custom section is preserved verbatim. Aligns BEM with EM/BXM/UJM, which already ship a consumer-facing default CLAUDE.md.
+- **`src/utils/merge-line-files.js`** — new file. Implements the line-based merge for the marker-wrapped Default/Custom sections (copied verbatim from `electron-manager`'s utility). Reusable across `.env`, `.gitignore`, `CLAUDE.md`, and any other line-based files BEM might ship in the future.
+- **`copyDefaults()` method** in `src/cli/commands/setup.js`. New defaults-shipping mechanism for BEM (which previously had no `src/defaults/` directory at all). Mirrors EM's `copyDefaults` pattern: iterates `src/defaults/**`, renames `_.foo` → `.foo`, routes files matching `MERGEABLE_BASENAMES` (`['.env', '.gitignore', 'CLAUDE.md']`) through `mergeLineBasedFiles`, copies non-mergeable files only if they don't already exist. Wired into `runSetup()` BEFORE `runTests()` so test inspections see the merged state.
+
 # [5.0.201] - 2026-05-08
 ### Changed
 - Account deletion confirmation email now includes a "Deletion details:" block with the user's account email, UID, and deletion timestamp (UTC) — matching the pattern used in the data-request download email.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.201",
+  "version": "5.0.203",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/setup.js

@@ -107,6 +107,10 @@ class SetupCommand extends BaseCommand {
     // Clean up leftover trigger files from watch command
     this.cleanupTriggerFiles();
 
+    // Copy / merge defaults into consumer project root (matches EM/BXM/UJM pattern).
+    // Runs BEFORE tests so any test that inspects scaffolded files sees the merged state.
+    this.copyDefaults();
+
     // Run all tests
     await this.runTests();
 
@@ -147,6 +151,74 @@ class SetupCommand extends BaseCommand {
     self.default.databaseRulesCore = self.default.databaseRulesWhole.match(bem_allRulesRegex)[0];
   }
 
+  // Copy default files (src/defaults/**) into the consumer project root.
+  // For files in MERGEABLE_BASENAMES, route through `mergeLineBasedFiles` so the
+  // framework's section stays live-synced while the consumer's Custom section is
+  // preserved verbatim. For non-mergeable files: copy on first setup, skip if exists.
+  //
+  // Mirrors EM's copyDefaults pattern (src/commands/setup.js in electron-manager).
+  // Same marker convention as .env/.gitignore in EM/BXM/UJM:
+  //   # ========== Default Values ==========   (framework-owned)
+  //   # ========== Custom Values ==========    (consumer-owned)
+  copyDefaults() {
+    const self = this.main;
+    const defaultsDir = path.resolve(`${__dirname}/../../defaults`);
+
+    if (!jetpack.exists(defaultsDir)) {
+      // Defaults dir is optional — older BEM versions didn't have one. If missing, skip silently.
+      return;
+    }
+
+    const { mergeLineBasedFiles } = require('../../utils/merge-line-files.js');
+    // Files routed through the marker-based merge (vs verbatim copy / skip-if-exists).
+    // .env / .gitignore aren't currently shipped by BEM but are included here so this
+    // matches the EM/BXM/UJM contract if we ever add them.
+    const MERGEABLE_BASENAMES = new Set(['.env', '.gitignore', 'CLAUDE.md']);
+
+    const files = jetpack.find(defaultsDir, { matching: '**/*', recursive: true, files: true, directories: false });
+
+    for (const src of files) {
+      const rel = path.relative(defaultsDir, src);
+      const segments = rel.split(path.sep);
+
+      // Skip "archive" directories — anything under a path segment starting with `_` and
+      // followed by a non-`.` character. Matches EM/BXM/UJM convention. The `_.env` /
+      // `_.gitignore` files are NOT skipped; their leading `_` strips on copy below.
+      if (segments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
+        continue;
+      }
+
+      // Convert leading `_.` to `.` so dotfiles ship past npm's filter.
+      const target = segments.map((part) => part.startsWith('_.') ? part.slice(1) : part).join(path.sep);
+      const dest = path.join(self.firebaseProjectPath, target);
+      const basename = path.basename(target);
+
+      if (jetpack.exists(dest)) {
+        if (MERGEABLE_BASENAMES.has(basename)) {
+          try {
+            const existing = jetpack.read(dest, 'utf8');
+            const incoming = jetpack.read(src, 'utf8');
+            const merged   = mergeLineBasedFiles(existing, incoming, basename);
+            if (merged !== existing) {
+              jetpack.write(dest, merged);
+              this.logSuccess(`Merged default → ${target}`);
+            }
+          } catch (e) {
+            this.logWarning(`Failed to merge ${target}: ${e.message}`);
+          }
+          continue;
+        }
+
+        // Non-mergeable, already exists → preserve consumer's version.
+        continue;
+      }
+
+      // First time: copy as-is.
+      jetpack.copy(src, dest);
+      this.logSuccess(`Copied default → ${target}`);
+    }
+  }
+
   cleanupTriggerFiles() {
     const self = this.main;
     const triggerFile = `${self.firebaseProjectPath}/functions/bem-reload-trigger.js`;

package/src/defaults/CLAUDE.md

@@ -0,0 +1,73 @@
+# ========== Default Values ==========
+# Backend Manager (BEM) — consumer project
+
+> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `backend-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
+
+## Framework
+
+This project consumes **Backend Manager** (BEM) — a comprehensive framework for building modern Firebase Cloud Functions backends. BEM provides a single `Manager.init(exports, {...})` bootstrap that wires built-in functions (`bm_api`, auth events, cron jobs), helper classes (Assistant, User, Analytics, Usage, Middleware, Settings, Utilities, Metadata), payment processor integrations (Stripe / PayPal), Firestore-trigger pipelines, and a deploy/emulator/watch tooling pipeline.
+
+**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
+- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/CLAUDE.md` (or `node_modules/backend-manager/CLAUDE.md`)
+
+## Quick start
+
+```bash
+cd functions
+npx mgr setup       # validate config + scaffold defaults + run checks
+npx mgr emulator    # start Firebase emulators (auth/firestore/functions/database/storage)
+npx mgr watch       # auto-reload functions on file change
+npx mgr deploy      # deploy to Firebase
+npx mgr logs        # tail Cloud Functions logs
+```
+
+All `npx mgr <cmd>` aliases — `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-manager <cmd>` work too.
+
+## Where things live
+
+- `functions/index.js` — entry point. Must call `Manager.init(exports, { ... })` to register all built-in + custom endpoints.
+- `functions/backend-manager-config.json` — BEM config: brand, projectType (`firebase` or `custom`), feature flags, rate limits, hooks.
+- `functions/.env` — secrets (BACKEND_MANAGER_KEY, third-party API keys). Gitignored.
+- `functions/service-account.json` — Firebase Admin credentials. Gitignored.
+- `functions/routes/<verb>/<path>.js` — custom routes mounted at runtime (e.g. `routes/get/hello.js` → `GET /hello`).
+- `functions/schemas/<name>.js` — schema definitions for `Manager.Settings()` validation.
+- `firebase.json` — Firebase config (hosting, rewrites, emulator ports). Some fields managed by `npx mgr setup`.
+- `.firebaserc` — Firebase project ID alias.
+- `firestore.rules` / `database.rules.json` — security rules. BEM owns a `///---backend-manager---///` block inside each; everything outside is yours.
+
+## Per-context imports
+
+```js
+// functions/index.js — the entire backend bootstrap
+const Manager = require('backend-manager');
+Manager.init(exports, {
+  projectType: 'firebase',
+  // ...your config
+});
+
+// In a custom route (functions/routes/get/hello.js):
+module.exports = async function(Manager, assistant) {
+  // assistant.req, assistant.res, assistant.user, etc.
+};
+```
+
+## Available APIs at runtime
+
+After `Manager.init()`, the Manager instance exposes factory methods:
+- `Manager.Assistant({ req, res })` — request handler with user + analytics + utility access
+- `Manager.User(data)` — user property structure + schema
+- `Manager.Analytics({ assistant })` — GA4 event tracking
+- `Manager.Usage()` — rate-limiting
+- `Manager.Middleware(req, res)` — request pipeline
+- `Manager.Settings()` — schema validation against `functions/schemas/*`
+- `Manager.Utilities()` — batch operations + helpers
+- `Manager.Metadata(doc)` — timestamps + tag helpers
+- `Manager.storage({ name })` — local JSON storage (lowdb)
+
+Auth events, payment-webhook transitions, and cron jobs are wired automatically — hook into them by exporting from `functions/hooks/<area>/<event>.js`.
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across `npx mgr setup` runs.

package/src/manager/helpers/settings.js

@@ -47,19 +47,38 @@ Settings.prototype.resolve = function (assistant, schema, settings, options) {
     const method = (assistant?.request?.method || '').toLowerCase();
     const methodFile = `${method}.js`;
     const schemaFile = options.schema.replace('.js', '');
-    let schemaPath;
 
-    // First try method-specific schema (e.g., test/get.js, test/post.js)
     const methodSchemaPath = path.resolve(options.dir, `${schemaFile}/${methodFile}`);
+    const indexSchemaPath = path.resolve(options.dir, `${schemaFile}/index.js`);
+
+    // Helper: only fall back when THIS specific file is missing.
+    // If the file exists but throws (syntax error, runtime error, etc.) we re-throw
+    // so the real problem surfaces instead of being masked by a misleading fallback.
+    const isMissingModule = (err, expectedPath) => err
+      && err.code === 'MODULE_NOT_FOUND'
+      && typeof err.message === 'string'
+      && err.message.includes(expectedPath);
 
     try {
       schema = loadSchema(assistant, methodSchemaPath);
       assistant.log(`Settings.resolve(): Loaded method-specific schema: ${schemaFile}/${methodFile}`);
-    } catch (e) {
-      // Fallback to main schema if method-specific doesn't exist
-      schemaPath = path.resolve(options.dir, `${schemaFile}/index.js`);
-      schema = loadSchema(assistant, schemaPath);
-      assistant.log(`Settings.resolve(): Method-specific schema not found, using main schema fallback`);
+    } catch (methodErr) {
+      if (!isMissingModule(methodErr, methodSchemaPath)) {
+        throw methodErr;
+      }
+
+      try {
+        schema = loadSchema(assistant, indexSchemaPath);
+        assistant.log(`Settings.resolve(): Method-specific schema not found, using main schema fallback`);
+      } catch (indexErr) {
+        if (!isMissingModule(indexErr, indexSchemaPath)) {
+          throw indexErr;
+        }
+        throw assistant.errorify(
+          `No schema for ${method.toUpperCase()} request: expected ${schemaFile}/${methodFile} or ${schemaFile}/index.js`,
+          {code: 500},
+        );
+      }
     }
   }
 

package/src/manager/libraries/disposable-domains.json

@@ -1377,6 +1377,9 @@
   "edudingy.cfd",
   "edumail.edu.pl",
   "edumail.edu.rs",
+  "edumaili.com",
+  "edumaili.edu.pl",
+  "edumaill.edu.pl",
   "edupolska.edu.pl",
   "edv.to",
   "ee1.pl",
@@ -2461,6 +2464,7 @@
   "javadmin.com",
   "javaemail.com",
   "jbsze.com",
+  "jbsze.ne",
   "jcnorris.com",
   "jdmadventures.com",
   "jdz.ro",
@@ -2909,6 +2913,7 @@
   "maileater.com",
   "mailed.in",
   "mailed.ro",
+  "mailedu.edu.pl",
   "maileimer.de",
   "maileme101.com",
   "mailer.edu.pl",
@@ -3172,6 +3177,7 @@
   "mliok.com",
   "mm.my",
   "mm5.se",
+  "mmaily.com",
   "mnode.me",
   "moakt.cc",
   "moakt.co",

package/src/utils/merge-line-files.js

@@ -0,0 +1,211 @@
+// Merge line-based files (.env, .gitignore, CLAUDE.md) on `npx mgr setup`.
+//
+// Convention (matches EM/BXM/UJM):
+//
+//   # ========== Default Values ==========
+//   # framework-managed; overwritten on every setup
+//   KEY1=
+//   KEY2="value with spaces"
+//
+//   # ========== Custom Values ==========
+//   # user's section; preserved verbatim across setups
+//   USER_SECRET="my-secret"
+//
+// Behavior:
+//   - The Default section is replaced with the new framework's defaults.
+//   - Keys that already had values (in either Default or Custom) keep those values
+//     in the same section they were in.
+//   - Keys the user added to the Default section that are NOT in the new framework's
+//     defaults migrate to the Custom section (so framework cleanups don't lose user data).
+//   - .env values are normalized to **double-quoted** form on every merge:
+//       KEY=raw-value         →   KEY="raw-value"
+//       KEY="already-quoted"  →   KEY="already-quoted"  (left alone)
+//       KEY=                  →   KEY=                  (empty stays empty/unquoted)
+//     This protects values containing spaces, #, $, or other shell-meaningful chars.
+//   - .gitignore: same logic, line-based instead of key-based (no quoting).
+//   - CLAUDE.md: same logic as .gitignore (line-based, no quoting). The markers
+//     render as visible H1 headings in markdown — that's intentional UX.
+//   - First setup (no existing file): the framework template lands as-is.
+
+const DEFAULT_MARKER = '# ========== Default Values ==========';
+const CUSTOM_MARKER  = '# ========== Custom Values ==========';
+
+function mergeLineBasedFiles(existingContent, newContent, fileName) {
+  const isEnvFile = fileName === '.env';
+
+  const existingLines = existingContent.split('\n');
+  const newLines      = newContent.split('\n');
+
+  // Parse existing into default + custom sections.
+  const { defaultLines: existingDefault, customLines: existingCustom, existingDefaultKeys, existingCustomKeys }
+    = splitSections(existingLines, isEnvFile);
+
+  // Parse new content. We only use its default section (custom is the user's domain).
+  const { defaultLines: newDefault, customLines: newCustom } = splitSections(newLines, isEnvFile);
+
+  // Build the merged default section: walk new defaults in order, substituting the
+  // user's existing value for any key they had set in either section.
+  const newDefaultKeys = new Set();
+  const mergedDefault  = [];
+  const emit = (line) => mergedDefault.push(isEnvFile ? normalizeEnvLine(line) : line);
+
+  for (const line of newDefault) {
+    const trimmed = line.trim();
+
+    if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      const key = trimmed.split('=')[0].trim();
+      if (key) {
+        newDefaultKeys.add(key);
+        if (existingDefaultKeys.has(key)) {
+          emit(findKeyLine(existingDefault, key));
+          continue;
+        }
+        if (existingCustomKeys.has(key)) {
+          // Key the user moved to custom — leave it in custom; emit empty default value.
+          emit(line);
+          continue;
+        }
+      }
+      emit(line);
+    } else if (!isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      // .gitignore / CLAUDE.md: just keep the new line.
+      mergedDefault.push(line);
+    } else {
+      // Comment / blank.
+      mergedDefault.push(line);
+    }
+  }
+
+  // User-added stuff in their Default section that the new framework doesn't know about
+  // → migrate to Custom so it's preserved without being clobbered next setup.
+  const migratedToCustom = [];
+  for (const line of existingDefault) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    if (isEnvFile) {
+      const key = trimmed.split('=')[0].trim();
+      if (key && !newDefaultKeys.has(key) && !existingCustomKeys.has(key)) {
+        migratedToCustom.push(normalizeEnvLine(line));
+      }
+    } else {
+      // .gitignore / CLAUDE.md: line not in new defaults → migrate.
+      const inNew = newLines.some((nl) => nl.trim() === trimmed);
+      if (!inNew) {
+        migratedToCustom.push(line);
+      }
+    }
+  }
+
+  // The user's Custom section is preserved verbatim — except .env values get
+  // normalized to double-quoted form so the file's quoting style is consistent.
+  const finalCustom = isEnvFile
+    ? existingCustom.map((line) => normalizeEnvLine(line))
+    : existingCustom;
+
+  const result = [];
+  result.push(DEFAULT_MARKER);
+  result.push(...mergedDefault);
+  // Insert a single blank line before CUSTOM_MARKER, but only if the merged default
+  // doesn't already end with one (otherwise we'd accumulate an extra blank line on
+  // every merge — breaking idempotency on the first re-run after a fresh `jetpack.copy`).
+  if (mergedDefault.length === 0 || mergedDefault[mergedDefault.length - 1].trim() !== '') {
+    result.push('');
+  }
+  result.push(CUSTOM_MARKER);
+  if (migratedToCustom.length > 0) {
+    result.push(...migratedToCustom);
+  }
+  result.push(...finalCustom);
+
+  return result.join('\n');
+}
+
+// Normalize a single .env line:
+//   - Comments / blanks unchanged
+//   - KEY=  (empty value) unchanged
+//   - KEY="..." (already double-quoted) unchanged
+//   - KEY=raw-value → KEY="raw-value" (with embedded " and \ escaped)
+//   - KEY='single' → KEY="single"  (canonicalize single → double)
+function normalizeEnvLine(line) {
+  if (typeof line !== 'string') return line;
+
+  // Preserve comments and blank lines verbatim.
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return line;
+
+  // Capture leading whitespace so we don't lose indentation.
+  const leadingMatch = line.match(/^(\s*)/);
+  const leading = leadingMatch ? leadingMatch[1] : '';
+
+  const eqIdx = trimmed.indexOf('=');
+  if (eqIdx < 0) return line; // no `=` — not a KEY=VALUE line
+
+  const key = trimmed.slice(0, eqIdx).trim();
+  let value = trimmed.slice(eqIdx + 1);
+
+  // Strip trailing whitespace + inline comment-after-value (rare; we only strip a # that follows a space).
+  // We do NOT strip # inside quoted values. Detect that by checking if value starts with a quote.
+  if (value.length === 0) {
+    return `${leading}${key}=`;
+  }
+
+  // Already double-quoted? Leave alone (preserves user's exact contents).
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return `${leading}${key}=${value}`;
+  }
+
+  // Single-quoted → canonicalize to double-quoted.
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    const inner = value.slice(1, -1);
+    return `${leading}${key}="${escapeForDoubleQuote(inner)}"`;
+  }
+
+  // Raw value → wrap.
+  return `${leading}${key}="${escapeForDoubleQuote(value)}"`;
+}
+
+function escapeForDoubleQuote(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function splitSections(lines, isEnvFile) {
+  const defaultLines = [];
+  const customLines  = [];
+  const existingDefaultKeys = new Set();
+  const existingCustomKeys  = new Set();
+
+  let mode = null; // null | 'default' | 'custom'
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === DEFAULT_MARKER) { mode = 'default'; continue; }
+    if (trimmed === CUSTOM_MARKER)  { mode = 'custom';  continue; }
+
+    // Lines before any marker are treated as default (legacy / fresh files).
+    if (mode === 'custom') {
+      customLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingCustomKeys.add(key);
+      }
+    } else {
+      defaultLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingDefaultKeys.add(key);
+      }
+    }
+  }
+
+  return { defaultLines, customLines, existingDefaultKeys, existingCustomKeys };
+}
+
+function findKeyLine(lines, key) {
+  const re = new RegExp(`^\\s*${key}\\s*=`);
+  for (const line of lines) {
+    if (re.test(line)) return line;
+  }
+  return `${key}=`;
+}
+
+module.exports = { mergeLineBasedFiles, normalizeEnvLine, DEFAULT_MARKER, CUSTOM_MARKER };

package/TODO-CHARGEBLAST.md

@@ -1,32 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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?