backend-manager 5.0.189 → 5.0.191

package/CLAUDE.md

@@ -65,24 +65,32 @@ src/
           stripe.js                   # Stripe SDK init, fetchResource, toUnified*, resolvePriceId
           paypal.js                   # PayPal fetchResource, toUnified* (custom_id parsing)
           test.js                     # Test processor (delegates to Stripe shapes)
-    functions/core/                   # Built-in functions
+    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
-      events/
-        auth/                         # Auth event handlers
-        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
-      cron/
-        daily.js                      # Daily cron runner
-        daily/{job}.js                # Individual cron jobs
+        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
@@ -142,6 +150,11 @@ functions/
     {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
@@ -416,6 +429,80 @@ Job.prototype.main = function () {
 module.exports = Job;
 ```
 
+### 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));
+};
+```
+
 ## Common Operations
 
 ### Authenticate User
@@ -482,7 +569,9 @@ Manager.handlers.bm_api = function (mod, position) {
 | Schemas | `schemas/{name}/` | `index.js` or `{method}.js` |
 | API Commands | `actions/api/{category}/` | `{action}.js` |
 | Auth Events | `events/auth/` | `{event}.js` |
-| Cron Jobs | `cron/daily/` or `hooks/cron/daily/` | `{job}.js` |
+| Auth Hooks (consumer) | `hooks/auth/` | `{event}.js` |
+| Cron Jobs (BEM) | `events/cron/daily/` | `{job}.js` |
+| Cron Jobs (consumer) | `hooks/cron/daily/` | `{job}.js` |
 
 ## Admin Post Route
 
@@ -1302,6 +1391,12 @@ marketing: {
 | Rate limiting | `src/manager/helpers/usage.js` |
 | User properties + schema | `src/manager/helpers/user.js` |
 | Batch utilities | `src/manager/helpers/utilities.js` |
+| Auth: before-create | `src/manager/events/auth/before-create.js` |
+| Auth: before-signin | `src/manager/events/auth/before-signin.js` |
+| Auth: on-create | `src/manager/events/auth/on-create.js` |
+| Auth: on-delete | `src/manager/events/auth/on-delete.js` |
+| Auth: shared utilities | `src/manager/events/auth/utils.js` |
+| Cron runner | `src/manager/events/cron/runner.js` |
 | Main API handler | `src/manager/functions/core/actions/api.js` |
 | Config template | `templates/backend-manager-config.json` |
 | CLI entry | `src/cli/index.js` |

package/TODO-2.md

@@ -23,6 +23,9 @@ waht about when they request a cancel
 Read cancellation-requested.js
 The category is order/cancellation-requested (line 13).
 
+---
+MIRROR settigns in BEM JSON so that usage reset can properly get MIRRED DOCS liek slapform forms or chatsy agents DOCS
+
 ---
 GHOSTII REVAMP
 * better logic for generating posts. better model? claude?

package/package.json

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

package/src/manager/events/auth/before-create.js

@@ -1,4 +1,5 @@
 const { isDisposable } = require('../../libraries/email/validation.js');
+const { runAuthHook } = require('./utils.js');
 
 const ERROR_TOO_MANY_ATTEMPTS = 'Unable to create account at this time. Please try again later.';
 const ERROR_DISPOSABLE_EMAIL = 'This email domain is not allowed. Please use a different email address.';
@@ -71,5 +72,8 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   usage.increment('signups');
   await usage.update();
 
+  // Run consumer hook (can throw HttpsError to block signup)
+  await runAuthHook('before-create', { Manager, assistant, user, context, libraries });
+
   assistant.log(`beforeCreate: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
 };

package/src/manager/events/auth/before-signin.js

@@ -24,6 +24,8 @@
  * Note: recaptchaScore requires reCAPTCHA Enterprise (Google Cloud level), NOT the Firebase SMS fraud toggle.
  * Note: credential tokens (idToken, accessToken, refreshToken) require opt-in via BlockingOptions.
  */
+const { runAuthHook } = require('./utils.js');
+
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   const startTime = Date.now();
   const { admin } = libraries;
@@ -60,5 +62,8 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
     assistant.log(`beforeSignIn: Updated user activity`);
   }
 
+  // Run consumer hook (can throw HttpsError to block sign-in)
+  await runAuthHook('before-signin', { Manager, assistant, user, context, libraries });
+
   assistant.log(`beforeSignIn: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
 };

package/src/manager/events/auth/on-create.js

@@ -1,4 +1,4 @@
-const { retryWrite, MAX_RETRIES } = require('./utils.js');
+const { retryWrite, runAuthHook, MAX_RETRIES } = require('./utils.js');
 
 /**
  * onCreate - Create user doc
@@ -87,6 +87,11 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
     // Don't reject - the user was already created in Auth
     // The user/signup endpoint will handle creating the doc if it's missing
   }
+
+  // Run consumer hook (non-blocking — errors logged but don't fail)
+  await runAuthHook('on-create', { Manager, assistant, user, context, libraries }).catch(e => {
+    assistant.error('onCreate: Consumer hook error:', e);
+  });
 };
 
 /**

package/src/manager/events/auth/on-delete.js

@@ -1,4 +1,4 @@
-const { retryWrite, MAX_RETRIES } = require('./utils.js');
+const { retryWrite, runAuthHook, MAX_RETRIES } = require('./utils.js');
 
 /**
  * onDelete - Delete user doc
@@ -70,5 +70,10 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
     uuid: user.uid,
   }).event('user_delete', {});
 
+  // Run consumer hook (non-blocking — errors logged but don't fail)
+  await runAuthHook('on-delete', { Manager, assistant, user, context, libraries }).catch(e => {
+    assistant.error('onDelete: Consumer hook error:', e);
+  });
+
   assistant.log(`onDelete: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
 };

package/src/manager/events/auth/utils.js

@@ -1,3 +1,5 @@
+const jetpack = require('fs-jetpack');
+
 const MAX_RETRIES = 3;
 const RETRY_DELAY_MS = 1000;
 
@@ -26,4 +28,47 @@ async function retryWrite(assistant, tag, fn) {
   throw lastError; // All retries failed
 }
 
-module.exports = { retryWrite, MAX_RETRIES };
+/**
+ * Run consumer auth hooks from hooks/auth/{eventName}.js
+ *
+ * Similar to how cron discovers hooks at hooks/cron/{schedule}/*.js,
+ * auth hooks are discovered at hooks/auth/{eventName}.js in the consumer project.
+ *
+ * For blocking functions (before-create, before-signin):
+ *   - Hook can throw HttpsError to block the operation
+ *   - Hook runs AFTER BEM's core checks (disposable email, rate limiting, etc.)
+ *
+ * For trigger functions (on-create, on-delete):
+ *   - Hook errors are logged but don't block the operation
+ *
+ * Hook signature:
+ *   module.exports = async ({ Manager, assistant, user, context, libraries }) => { ... }
+ *
+ * Consumer project structure:
+ *   functions/
+ *     hooks/
+ *       auth/
+ *         before-create.js   — runs after BEM checks, can block signup
+ *         before-signin.js   — runs after BEM signin logic, can block signin
+ *         on-create.js       — runs after BEM creates user doc
+ *         on-delete.js       — runs after BEM deletes user doc
+ */
+async function runAuthHook(eventName, args) {
+  const { Manager, assistant } = args;
+  const hookPath = `${Manager.cwd}/hooks/auth/${eventName}.js`;
+
+  // Check if hook file exists
+  if (!jetpack.exists(hookPath)) {
+    return;
+  }
+
+  assistant.log(`${eventName}: Running consumer hook @ ${hookPath}`);
+
+  // Load and execute — passes the same args object the BEM handler received
+  const hook = require(hookPath);
+  await hook(args);
+
+  assistant.log(`${eventName}: Consumer hook completed`);
+}
+
+module.exports = { retryWrite, runAuthHook, MAX_RETRIES };

package/src/manager/functions/core/actions/api/admin/cron.js

@@ -22,7 +22,7 @@ Module.prototype.main = function () {
     }
 
     // Run the cron job
-    Manager._process((new (require(`../../../cron/${payload.data.payload.id}.js`))()).init(Manager, { context: {}, }))
+    Manager._process((new (require(`${Manager.rootDirectory}/events/cron/${payload.data.payload.id}.js`))()).init(Manager, { context: {}, }))
     .then((res) => {
       return resolve({data: res});
     })

package/src/manager/index.js

@@ -14,8 +14,8 @@ const util = require('util');
 const core = './functions/core';
 const wrappers = './functions/wrappers';
 const _legacy = './functions/_legacy';
-const cron = path.resolve(__dirname, './cron');
 const events = path.resolve(__dirname, './events');
+const cron = path.resolve(events, './cron');
 
 const BEM_CONFIG_TEMPLATE_PATH = path.resolve(__dirname, '../../templates/backend-manager-config.json');
 const BEM_PACKAGE = require('../../package.json');

package/src/manager/libraries/abandoned-cart-config.js

@@ -2,7 +2,7 @@
  * Abandoned cart reminder configuration (SSOT)
  *
  * Used by:
- * - cron/frequent/abandoned-carts.js (processing reminders)
+ * - events/cron/frequent/abandoned-carts.js (processing reminders)
  * - Client-side checkout page (creating cart doc with first delay)
  */
 module.exports = {

package/src/manager/routes/admin/cron/post.js

@@ -22,7 +22,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   assistant.log('Running cron job:', settings.id);
 
   // Run the cron job
-  const cronPath = require('path').resolve(__dirname, `../../../cron/${settings.id}.js`);
+  const cronPath = `${Manager.rootDirectory}/events/cron/${settings.id}.js`;
   const cronHandler = require(cronPath);
   const result = await cronHandler({ Manager, assistant, context: {}, libraries: Manager.libraries }).catch(e => e);