backend-manager 5.0.193 → 5.0.194

package/CHANGELOG.md

@@ -14,6 +14,15 @@ 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.194] - 2026-04-08
+### Fixed
+- Fix email template data merge: caller's `settings.data` is now deep-merged at root of template data tree, removing the broken `data.` prefix indirection that caused empty order confirmation emails since 5.0.185
+### Added
+- `preview` as a top-level setting on `email.send()` (alongside `subject`)
+- `logs:read` CLI: `--search`, `--order`, `--filter` flags and increased default limit to 300
+### Changed
+- Email templates now access caller data at root (`{{order.id}}`, `{{body.message}}`) instead of under `data.*`
+
 # [5.0.192] - 2026-04-02
 ### Added
 - Setup test to create `hooks/auth/` and `hooks/cron/daily/` directories in consumer projects during `npx bm setup`

package/CLAUDE.md

@@ -736,6 +736,8 @@ The forwarding URL is: `http://localhost:{hostingPort}/backend-manager/payments/
 
 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 ...` / `npx bm ...`) 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.
+
 ### Firestore Commands
 
 ```bash
@@ -763,24 +765,63 @@ npx bm auth:set-claims <uid-or-email> '<json>'       # Set custom claims
 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`.
 
 ```bash
-npx bm logs:read                                     # Read last 1h of logs (default: 50 entries)
+npx bm logs:read                                     # Read last 1h of logs (default: 300 entries, newest first)
 npx bm logs:read --fn bm_api                         # Filter by function name
 npx bm logs:read --fn bm_api --severity ERROR        # Filter by severity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
 npx bm logs:read --since 2d --limit 100              # Custom time range and limit
+npx bm logs:read --search "72.134.242.25"            # Search textPayload for a string (IP, email, error, etc.)
+npx bm logs:read --fn bm_authBeforeCreate --search "ian@example.com" --since 7d  # Combined filters
+npx bm logs:read --order asc                         # Oldest first (default: desc/newest first)
+npx bm logs:read --filter 'jsonPayload.level="error"'  # Raw gcloud filter passthrough
 npx bm logs:tail                                     # Stream live logs
 npx bm 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 bm serve`) or `functions/emulator.log` (from `npx bm test`) directly — they are plain text files, not gcloud.
+
 | Flag | Description | Default | Commands |
 |------|-------------|---------|----------|
-| `--fn <name>` | Filter by Cloud Function name | all | both |
-| `--severity <level>` | Minimum severity level | all | both |
+| `--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 | `50` | 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`
+
 ### Shared Flags
 
 | Flag | Description |

package/TODO-2.md

@@ -23,6 +23,26 @@ waht about when they request a cancel
 Read cancellation-requested.js
 The category is order/cancellation-requested (line 13).
 
+----
+add a dedicated BEM JSON field for usage to reset
+  * this way we can have clear LIMITS with their definitions like
+  * [
+    {
+      name: 'credits'
+      reset: true,
+    },
+    {
+      name: 'agents',
+      reset: false,
+    }
+  ]
+  * mirrors: [
+    {
+      collection: 'agents',
+      fields: ['usage.credits.daily', 'runs.replies.daily],
+    }
+  ]
+
 ---
 MIRROR settigns in BEM JSON so that usage reset can properly get MIRRED DOCS liek slapform forms or chatsy agents DOCS
 

package/package.json

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

package/src/cli/commands/logs.js

@@ -56,11 +56,12 @@ class LogsCommand extends BaseCommand {
 
   /**
    * Fetch historical logs.
-   * Usage: npx bm logs:read [--fn bm_api] [--severity ERROR] [--since 1h] [--limit 300]
+   * Usage: npx bm logs:read [--fn bm_api] [--severity ERROR] [--since 1h] [--limit 300] [--search "text"] [--order desc] [--filter 'raw gcloud filter']
    */
   async read(projectId, argv) {
     const filter = this.buildFilter(argv);
     const limit = parseInt(argv.limit, 10) || 300;
+    const order = argv.order || 'desc';
 
     const cmd = [
       'gcloud', 'logging', 'read',
@@ -68,7 +69,7 @@ class LogsCommand extends BaseCommand {
       `--project=${projectId}`,
       `--limit=${limit}`,
       '--format=json',
-      '--order=asc',
+      `--order=${order}`,
     ].filter(Boolean).join(' ');
 
     // Set up log file in the project directory
@@ -83,7 +84,7 @@ class LogsCommand extends BaseCommand {
       const output = execSync(cmd, {
         encoding: 'utf8',
         maxBuffer: 10 * 1024 * 1024, // 10MB
-        timeout: 30000,
+        timeout: 60000,
       });
 
       const entries = JSON.parse(output || '[]');
@@ -233,6 +234,16 @@ class LogsCommand extends BaseCommand {
       parts.push(`severity>=${argv.severity.toUpperCase()}`);
     }
 
+    // Text search filter (searches textPayload)
+    if (argv.search) {
+      parts.push(`textPayload:"${argv.search}"`);
+    }
+
+    // Raw filter passthrough (appended as-is)
+    if (argv.filter) {
+      parts.push(argv.filter);
+    }
+
     // Timestamp filter (read only, not tail)
     if (!options.excludeTimestamp) {
       const since = argv.since || '1h';

package/src/manager/libraries/email/transactional/index.js

@@ -142,6 +142,8 @@ Transactional.prototype.build = async function (settings) {
     throw errorWithCode('Parameter subject is required', 400);
   }
 
+  const preview = settings.preview || settings?.data?.email?.preview || null;
+
   const templateId = TEMPLATES[settings.template] || settings.template || TEMPLATES['default'];
 
   // Resolve sender category
@@ -176,7 +178,7 @@ Transactional.prototype.build = async function (settings) {
   const unsubSig = crypto.createHmac('sha256', process.env.UNSUBSCRIBE_HMAC_KEY).update(to[0].email.toLowerCase()).digest('hex');
   const unsubscribeUrl = `${Manager.project.websiteUrl}/portal/email-preferences?email=${encode(to[0].email)}&asmId=${encode(groupId)}&templateId=${encode(templateId)}&sig=${unsubSig}`;
 
-  // Build signoff
+  // Build signoff defaults
   const signoff = settings?.data?.signoff || {};
   signoff.type = signoff.type || 'team';
 
@@ -188,12 +190,12 @@ Transactional.prototype.build = async function (settings) {
     signoff.urlText = signoff.urlText || '@ianwieds';
   }
 
-  // Build dynamic template data defaults
+  // Build dynamic template data — system-generated defaults
   const dynamicTemplateData = {
     email: {
       id: Manager.require('uuid').v4(),
       subject,
-      preview: null,
+      preview,
       body: null,
       unsubscribeUrl,
       categories,
@@ -209,18 +211,20 @@ Transactional.prototype.build = async function (settings) {
     signoff,
     brand: brandData,
     user: userProperties,
-    data: {},
   };
 
-  // Deep-merge caller's data on top so they can override any field
-  // (e.g. email.preview, email.subject, personalization.name, data.body.*, etc.)
+  // Deep-merge caller's data on top of defaults.
+  // This is the single template data tree — everything the template can access.
+  // Callers can override any field (email.preview, signoff.type, etc.)
+  // and add custom data (order.*, body.*, abandonedCart.*, etc.) at the root.
+  // Templates access all fields at the root: {{order.id}}, {{email.preview}}, {{brand.name}}.
   if (settings.data) {
     _.merge(dynamicTemplateData, settings.data);
   }
 
-  // Process markdown in body fields (after merge so all data paths are resolved)
-  if (dynamicTemplateData.data?.body?.message) {
-    dynamicTemplateData.data.body.message = md.render(dynamicTemplateData.data.body.message);
+  // Process markdown in body fields (after merge so caller data is resolved)
+  if (dynamicTemplateData.body?.message) {
+    dynamicTemplateData.body.message = md.render(dynamicTemplateData.body.message);
   }
   if (dynamicTemplateData.email?.body) {
     dynamicTemplateData.email.body = md.render(dynamicTemplateData.email.body);
@@ -235,8 +239,8 @@ Transactional.prototype.build = async function (settings) {
     utm: settings.utm,
   };
 
-  if (dynamicTemplateData.data?.body?.message) {
-    dynamicTemplateData.data.body.message = tagLinks(dynamicTemplateData.data.body.message, utmOptions);
+  if (dynamicTemplateData.body?.message) {
+    dynamicTemplateData.body.message = tagLinks(dynamicTemplateData.body.message, utmOptions);
   }
   if (dynamicTemplateData.email?.body) {
     dynamicTemplateData.email.body = tagLinks(dynamicTemplateData.email.body, utmOptions);