backend-manager 5.0.188 → 5.0.190

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.188",
+  "version": "5.0.190",
   "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.';
@@ -12,6 +13,23 @@ const MAX_SIGNUPS_PER_DAY = 2;
  * Why not create user doc here?
  * - Admin SDK (used for tests) does NOT trigger beforeUserCreated
  * - on-create fires for ALL user creations, making it more reliable
+ *
+ * Available parameters (1st gen):
+ *
+ * user (AuthUserRecord):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (AuthEventContext):
+ *   ipAddress, userAgent, locale, eventId, eventType, authType, resource, timestamp,
+ *   additionalUserInfo: { providerId, profile, username, isNewUser, recaptchaScore, email, phoneNumber },
+ *   credential: { providerId, signInMethod, claims, idToken, accessToken, refreshToken, expirationTime, secret } | null,
+ *   emailType, smsType, params
+ *
+ * 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.
  */
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   const startTime = Date.now();
@@ -54,8 +72,8 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   usage.increment('signups');
   await usage.update();
 
-  assistant.log(`beforeCreate: Rate limit passed for ${ipAddress}, allowing user creation (${Date.now() - startTime}ms)`);
+  // Run consumer hook (can throw HttpsError to block signup)
+  await runAuthHook('before-create', { Manager, assistant, user, context, libraries });
 
-  // Allow user creation to proceed
-  // User doc will be created by on-create.js
+  assistant.log(`beforeCreate: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
 };

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

@@ -6,7 +6,26 @@
  *
  * TODO: Add mailer.sync(uid) here with 1x/day rate limit to keep marketing
  * contact data (name, country, subscription fields) fresh between sessions.
+ *
+ * Available parameters (1st gen):
+ *
+ * user (AuthUserRecord):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (AuthEventContext):
+ *   ipAddress, userAgent, locale, eventId, eventType, authType, resource, timestamp,
+ *   additionalUserInfo: { providerId, profile, username, isNewUser, recaptchaScore, email, phoneNumber },
+ *   credential: { providerId, signInMethod, claims, idToken, accessToken, refreshToken, expirationTime, secret } | null,
+ *   emailType, smsType, params
+ *
+ * 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;
@@ -43,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,5 +1,4 @@
-const MAX_RETRIES = 3;
-const RETRY_DELAY_MS = 1000;
+const { retryWrite, runAuthHook, MAX_RETRIES } = require('./utils.js');
 
 /**
  * onCreate - Create user doc
@@ -16,12 +15,23 @@ const RETRY_DELAY_MS = 1000;
  *
  * Non-critical work (welcome emails, marketing contact) is handled
  * by the user/signup endpoint, which the frontend calls after account creation.
+ *
+ * Available parameters (1st gen):
+ *
+ * user (UserRecord — firebase-admin):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime, lastRefreshTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (EventContext — NOT AuthEventContext, no ipAddress/userAgent/locale):
+ *   eventId, eventType, timestamp, resource: { service, name }, params
  */
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   const startTime = Date.now();
   const { admin } = libraries;
 
-  assistant.log(`onCreate: ${user.uid}`, { email: user.email });
+  assistant.log(`onCreate: ${user.uid} (${user.email})`, user, context);
 
   // Skip anonymous users
   if (user.providerData?.every(p => p.providerId === 'anonymous')) {
@@ -66,9 +76,9 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
 
   // Write user doc with retry
   try {
-    await retryWrite(assistant, async () => {
+    await retryWrite(assistant, 'onCreate', async () => {
       await admin.firestore().doc(`users/${user.uid}`).set(userRecord);
-    }, MAX_RETRIES, RETRY_DELAY_MS);
+    });
 
     assistant.log(`onCreate: Successfully created user doc for ${user.uid} (${Date.now() - startTime}ms)`);
   } catch (error) {
@@ -77,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);
+  });
 };
 
 /**
@@ -102,28 +117,3 @@ function extractProviderName(user) {
     last: parts.slice(1).join(' ') || null,
   };
 }
-
-/**
- * Retry a function up to maxRetries times with exponential backoff
- */
-async function retryWrite(assistant, fn, maxRetries, delayMs) {
-  let lastError;
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      await fn();
-      return; // Success
-    } catch (error) {
-      lastError = error;
-      assistant.error(`onCreate: Write attempt ${attempt}/${maxRetries} failed:`, error);
-
-      if (attempt < maxRetries) {
-        const delay = delayMs * Math.pow(2, attempt - 1); // Exponential backoff: 1s, 2s, 4s
-        assistant.log(`onCreate: Retrying in ${delay}ms...`);
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-
-  throw lastError; // All retries failed
-}

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

@@ -1,5 +1,4 @@
-const MAX_RETRIES = 3;
-const RETRY_DELAY_MS = 1000;
+const { retryWrite, runAuthHook, MAX_RETRIES } = require('./utils.js');
 
 /**
  * onDelete - Delete user doc
@@ -11,12 +10,23 @@ const RETRY_DELAY_MS = 1000;
  * - Checks if user doc exists before attempting delete
  * - Retries up to 3 times with exponential backoff on failure
  * - Logs timing for performance monitoring
+ *
+ * Available parameters (1st gen):
+ *
+ * user (UserRecord — firebase-admin):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime, lastRefreshTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (EventContext — NOT AuthEventContext, no ipAddress/userAgent/locale):
+ *   eventId, eventType, timestamp, resource: { service, name }, params
  */
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   const startTime = Date.now();
   const { admin } = libraries;
 
-  assistant.log(`onDelete: ${user.uid}`, { email: user.email });
+  assistant.log(`onDelete: ${user.uid} (${user.email})`, user, context);
 
   // Check if user doc exists before attempting delete
   const existingDoc = await admin.firestore().doc(`users/${user.uid}`)
@@ -33,9 +43,9 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
 
   // Delete user doc with retry
   try {
-    await retryWrite(assistant, async () => {
+    await retryWrite(assistant, 'onDelete', async () => {
       await admin.firestore().doc(`users/${user.uid}`).delete();
-    }, MAX_RETRIES, RETRY_DELAY_MS);
+    });
 
     assistant.log(`onDelete: Successfully deleted user doc for ${user.uid}`);
   } catch (error) {
@@ -60,30 +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)`);
 };
-
-/**
- * Retry a function up to maxRetries times with exponential backoff
- */
-async function retryWrite(assistant, fn, maxRetries, delayMs) {
-  let lastError;
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      await fn();
-      return; // Success
-    } catch (error) {
-      lastError = error;
-      assistant.error(`onDelete: Write attempt ${attempt}/${maxRetries} failed:`, error);
-
-      if (attempt < maxRetries) {
-        const delay = delayMs * Math.pow(2, attempt - 1); // Exponential backoff: 1s, 2s, 4s
-        assistant.log(`onDelete: Retrying in ${delay}ms...`);
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-
-  throw lastError; // All retries failed
-}

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

@@ -0,0 +1,74 @@
+const jetpack = require('fs-jetpack');
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+
+/**
+ * Retry a function up to maxRetries times with exponential backoff
+ */
+async function retryWrite(assistant, tag, fn) {
+  let lastError;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      await fn();
+      return; // Success
+    } catch (error) {
+      lastError = error;
+      assistant.error(`${tag}: Write attempt ${attempt}/${MAX_RETRIES} failed:`, error);
+
+      if (attempt < MAX_RETRIES) {
+        const delay = RETRY_DELAY_MS * Math.pow(2, attempt - 1); // Exponential backoff: 1s, 2s, 4s
+        assistant.log(`${tag}: Retrying in ${delay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError; // All retries failed
+}
+
+/**
+ * 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);