backend-manager 5.0.38 → 5.0.39

package/.claude/settings.local.json

@@ -1,8 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "Bash(rg:*)"
+      "Bash(rg:*)",
+      "Bash(mkdir:*)"
     ],
     "deny": []
   }
-}
+}

package/.gitignore FROM BEM TEMPALTE

@@ -0,0 +1,74 @@
+# ========== Default Values ==========
+# macOS
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+firebase-debug.log*
+
+# Firebase cache
+.firebase/
+
+# Firebase config
+# Uncomment this if you'd like others to create their own Firebase project.
+# For a team working on the same Firebase project(s), it is recommended to leave
+# it commented so all members can deploy to the same project(s) in .firebaserc.
+.firebaserc
+functions/service-account*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+
+# ========== Custom Values ==========
+# Add your custom ignore patterns below this line
+# ...

package/CLAUDE.md

@@ -384,19 +384,112 @@ Manager.handlers.bm_api = function (mod, position) {
 
 ## Testing
 
+### Running Tests
 ```bash
-# Run all tests
-npm test
-
-# Test files are in test/
-test/
-  cli-commands.test.js
-  usage.js
-  user.js
-  payment-resolver/
-  ai/
+# Option 1: Two terminals
+npx bm emulators  # Terminal 1 - keeps emulators running
+npx bm test       # Terminal 2 - runs tests
+
+# Option 2: Single command (auto-starts emulators)
+npx bm test
+```
+
+### Filtering Tests
+```bash
+npx bm test rules/             # Run rules tests (both BEM and project)
+npx bm test bem:rules/         # Only BEM's rules tests
+npx bm test project:rules/     # Only project's rules tests
+npx bm test user/ admin/       # Multiple paths
+```
+
+### Test Locations
+- **BEM core tests:** `test/`
+- **Project tests:** `functions/test/bem/`
+
+Use `bem:` or `project:` prefix to filter by source.
+
+### Test Types
+
+| Type | Use When | Behavior |
+|------|----------|----------|
+| Standalone | Single logical test | Runs once |
+| Suite (`type: 'suite'`) | Sequential dependent tests | Shared state, stops on failure |
+| Group (`type: 'group'`) | Multiple independent tests | Continues on failure |
+
+### Standalone Test
+```javascript
+module.exports = {
+  description: 'Test name',
+  auth: 'none',  // none, user, admin, premium-active, premium-expired
+  timeout: 10000,
+  async run({ http, assert, accounts, firestore, state, waitFor }) { },
+  async cleanup({ ... }) { },  // Optional
+};
 ```
 
+### Suite (Sequential with Shared State)
+```javascript
+module.exports = {
+  description: 'Suite name',
+  type: 'suite',
+  tests: [
+    { name: 'step-1', async run({ state }) { state.value = 'shared'; } },
+    { name: 'step-2', async run({ state }) { /* state.value available */ } },
+  ],
+};
+```
+
+### Group (Independent Tests)
+```javascript
+module.exports = {
+  description: 'Group name',
+  type: 'group',
+  tests: [
+    { name: 'test-1', auth: 'admin', async run({ http, assert }) { } },
+    { name: 'test-2', auth: 'none', async run({ http, assert }) { } },
+  ],
+};
+```
+
+### Context Object
+| Property | Description |
+|----------|-------------|
+| `http` | HTTP client (`http.command()`, `http.as('admin').command()`) |
+| `assert` | Assertion helpers (see below) |
+| `accounts` | Test accounts `{ basic, admin, premium-active, ... }` |
+| `firestore` | Direct DB access (`get`, `set`, `delete`, `exists`) |
+| `state` | Shared state (suites only) |
+| `waitFor` | Polling helper `waitFor(condition, timeout, interval)` |
+
+### Assert Methods
+```javascript
+assert.ok(value, message)                      // Truthy
+assert.equal(a, b, message)                    // Strict equality
+assert.notEqual(a, b, message)                 // Not equal
+assert.deepEqual(a, b, message)                // Deep equality
+assert.match(value, /regex/, message)          // Regex match
+assert.isSuccess(response, message)            // Response success
+assert.isError(response, code, message)        // Response error with code
+assert.hasProperty(obj, 'path.to.prop', msg)   // Property exists
+assert.propertyEquals(obj, 'path', value, msg) // Property value
+assert.isType(value, 'string', message)        // Type check
+assert.contains(array, value, message)         // Array includes
+assert.inRange(value, min, max, message)       // Number range
+assert.fail(message)                           // Explicit fail
+```
+
+### Auth Levels
+`none`, `user`/`basic`, `admin`, `premium-active`, `premium-expired`
+
+### Key Test Files
+| File | Purpose |
+|------|---------|
+| `src/test/runner.js` | Test runner |
+| `test/` | BEM core tests |
+| `src/test/utils/assertions.js` | Assert helpers |
+| `src/test/utils/http-client.js` | HTTP client |
+| `src/test/test-accounts.js` | Test account definitions |
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs

package/README.md

@@ -359,7 +359,7 @@ The main API endpoint accepts commands in the format `category:action`:
 | `general` | `generate-uuid`, `send-email`, `fetch-post` |
 | `handler` | `create-post` |
 | `firebase` | `get-providers` |
-| `test` | `authenticate`, `create-test-accounts`, `webhook`, `lab`, `redirect` |
+| `test` | `authenticate`, `webhook`, `lab`, `redirect` |
 | `special` | `setup-electron-manager-client` |
 
 ### Auth Events
@@ -737,7 +737,8 @@ npx backend-manager <command>
 | `bem setup` | Run Firebase project setup and validation |
 | `bem serve` | Start local Firebase emulator |
 | `bem deploy` | Deploy functions to Firebase |
-| `bem test` | Run test suite |
+| `bem test [paths...]` | Run integration tests |
+| `bem emulators` | Start Firebase emulators (keep-alive mode) |
 | `bem version`, `bem v` | Show BEM version |
 | `bem clear` | Clear cache and temp files |
 | `bem install`, `bem i` | Install BEM (local or production) |
@@ -747,14 +748,11 @@ npx backend-manager <command>
 
 ## Environment Variables
 
+Set these in your `functions/.env` file:
+
 | Variable | Description |
 |----------|-------------|
-| `FIREBASE_CONFIG` | Firebase project config (auto-set by Firebase) |
-| `RUNTIME_CONFIG` | BEM runtime config (JSON5 format) |
 | `BACKEND_MANAGER_KEY` | Admin authentication key |
-| `ENVIRONMENT` | `'production'` or `'development'` |
-| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |
-| `HCAPTCHA_SECRET` | hCaptcha secret for usage validation |
 
 ## Response Headers
 
@@ -764,6 +762,106 @@ BEM attaches metadata to responses:
 bm-properties: {"code":200,"tag":"functionName/executionId","usage":{...},"schema":{...}}
 ```
 
+## Testing
+
+BEM includes an integration test framework that runs against Firebase emulators.
+
+### Running Tests
+
+```bash
+# Option 1: Two terminals (recommended for development)
+npx bm emulators  # Terminal 1 - keeps emulators running
+npx bm test       # Terminal 2 - runs tests
+
+# Option 2: Single command (auto-starts emulators, shuts down after)
+npx bm test
+```
+
+### Filtering Tests
+
+```bash
+npx bm test rules/             # Run rules tests (both BEM and project)
+npx bm test bem:rules/         # Only BEM's rules tests
+npx bm test project:rules/     # Only project's rules tests
+npx bm test user/ admin/       # Multiple paths
+```
+
+### Test Locations
+
+- **BEM core tests:** `test/`
+- **Project tests:** `functions/test/bem/`
+
+Use `bem:` or `project:` prefix to filter by source.
+
+### Writing Tests
+
+**Suite** - Sequential tests with shared state (stops on first failure):
+
+```javascript
+// test/functions/user/sign-up.js
+module.exports = {
+  description: 'User signup flow with affiliate tracking',
+  type: 'suite',
+  tests: [
+    {
+      name: 'verify-referrer-exists',
+      async run({ firestore, assert, state, accounts }) {
+        state.referrerUid = accounts.referrer.uid;
+        const doc = await firestore.get(`users/${state.referrerUid}`);
+        assert.ok(doc, 'Referrer should exist');
+      },
+    },
+    {
+      name: 'call-user-signup-with-affiliate',
+      async run({ http, assert, state }) {
+        const response = await http.as('referred').command('user:sign-up', {
+          attribution: { affiliate: { code: 'TESTREF' } },
+        });
+        assert.isSuccess(response);
+      },
+    },
+  ],
+};
+```
+
+**Group** - Independent tests (continues even if one fails):
+
+```javascript
+// test/functions/admin/firestore-write.js
+module.exports = {
+  description: 'Admin Firestore write operation',
+  type: 'group',
+  tests: [
+    {
+      name: 'admin-auth-succeeds',
+      auth: 'admin',
+      async run({ http, assert }) {
+        const response = await http.command('admin:firestore-write', {
+          path: '_test/doc',
+          document: { test: 'value' },
+        });
+        assert.isSuccess(response);
+      },
+    },
+    {
+      name: 'unauthenticated-rejected',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.command('admin:firestore-write', {
+          path: '_test/doc',
+          document: { test: 'value' },
+        });
+        assert.isError(response, 401);
+      },
+    },
+  ],
+};
+```
+
+**Auth levels:** `none`, `user`/`basic`, `admin`, `premium-active`, `premium-expired`
+
+See `CLAUDE.md` for complete test API documentation.
+
 ## Final Words
 
 If you are still having difficulty, we would love for you to post a question to [the Backend Manager issues page](https://github.com/itw-creative-works/backend-manager/issues). It is much easier to answer questions that include your code and relevant files! So if you can provide them, we'd be extremely grateful (and more likely to help you find the answer!)

package/REFACTOR-BEM-API.md

@@ -0,0 +1,72 @@
+We need to do a pretty significatn refactor of our BEM API now.
+
+Since that was orignally implemented, I built a much better process for hading incoming http requests. That is, the route/schema system found here:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/assistant.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/middleware.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/settings.js
+
+You can see an example of it in our consuming project:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/index.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/routes/example/index.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/schemas/example/index.js
+
+We built a single unified bem_api function that handles all http requests in a single place, and then routes them, see here:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/index.js
+.https.onRequest(async (req, res) => self._process((new (require(`${core}/actions/api.js`))()).init(self, { req: req, res: res, })));
+
+We should refactor this system to USE THE NEW ROUTE/SCHEMA SYSTEM rather than the old way of doing things. This will make it much easier to maintain and extend in the future.
+
+We can start with a simple one like:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/functions/core/actions/api/general/generate-uuid.js
+
+and once we perfect that we can move on to the others.
+
+For each BEM refactor, we should create a route and a schema for the expected input. As you can see, BEM APIs epect a command and payload in the body, requiring it to be a POST operation. I would like to rebuild this system to be more proper, so that each BEM api can be GET, POST, etc as appropriate.
+
+Previously:
+request('/backend-manager', {
+  method: 'POST',
+  body: {
+    command: 'generate-uuid',
+    payload: { ... }
+  }
+})
+
+but i think it owud be more intuitive if going forward we just had endpoints like:
+request('/backend-manager/general:uuid', {
+  method: 'POST',
+  body: { ... }
+})
+OR
+request('/backend-manager/general/uuid', {
+  method: 'POST',
+  body: { ... }
+})
+
+Im not sure how we can do this to be backwards compatible with existing BEM API consumers, but it does need to be backwards compatible.
+
+If you look at the firebase.json in the consuming project we can see that
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/firebase.json
+{
+  "source": "/backend-manager",
+  "function": "bm_api"
+},
+
+So maybe we could make it:
+{
+  "source": "/backend-manager/**",
+  "function": "bm_api"
+},
+and then parse the route inside the bem_api function to determine which route/schema to use, falling back to the old system if the route is just /backend-manager with a "command" in the body, and then use the new route/schema system if the path is /backend-manager/something?
+
+Either way, i think we need a minimal intermediary step where we determine which one to use based on the incoming request and then either just route to the old one or route to the new "middleware", "settings", route/schema system
+
+I would like each new route to have a great name clearly indicating its purpose, the method should be appropriate for the action (GET for fetches, POST for creates, etc) and the schema should be well defined for each route.
+
+Since we can build this new API system however we want, i also expect you to rewrite and refactor the BEM api endppints to be kickass, modern, and well designed.
+
+
+
+
+
+

package/REFACTOR-MIDDLEWARE.md

@@ -0,0 +1,62 @@
+MIDDLEWARE REFACTOR
+We have a system where we handle incoming requests using a route/schema system found here:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/assistant.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/middleware.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/helpers/settings.js
+
+You can see an example of it in our consuming project:
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/index.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/routes/example/index.js
+/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-backend/functions/schemas/example/index.js
+
+I have some ideas iw as thinking about and id like to know your thoughts:
+* new design so that each route is modern JS that does a single export instead of exportting a class with an init() and a main() method.
+* schema system currently uses the user's plan when designing the schma like
+module.exports = function (assistant) {
+  return {
+    // DEFAULTS
+    ['defaults']: {
+      key: {
+        types: ['string'],
+        value: undefined,
+        default: '',
+        required: false,
+        min: 0,
+        max: 2048,
+      },
+    },
+
+    // Premium plan
+    ['premium']: {
+      key: {
+        types: ['string'],
+        value: undefined,
+        default: 'premium-default',
+        required: false,
+        min: 0,
+        max: 4096,
+      },
+    }
+  };
+}
+
+however it hink we should instead eliminate the toplevel plan/default system and code each plan changes into the individual keys like:
+  const schema = {
+    id: {
+      types: ['string'],
+      value: () => assistant.Manager.Utilities().randomId(),
+      required: false,
+    },
+    feature: {
+      types: ['string'],
+      default: '',
+      required: true,
+      min: 1,
+      max: 4,
+    },
+  };
+
+  // Adjust schema based on plan
+  if (assistant.user.plan === 'premium') {
+    schema.feature.max = 8;
+  }

package/REFACTOR-PAYMENT.md

@@ -0,0 +1,61 @@
+PAYMETN SYSTEM REFACTOR
+Question
+Propose a schema for storing user's subscription data in their firestore user document. Currently the user looks like this
+users/{uid}
+{
+  auth: {
+    uid: string,
+    email: string,
+  },
+  roles: {
+    admin: boolean,
+  },
+  ... (other stuff that is not really relevant)
+}
+I will be using a variety of payment processors including Stripe and PayPal, so I need a flexible way to store subscription data that can work with multiple providers.
+Before inserting the subscription data, we wil need to receive the processor webhooks.
+We will be keeping track of the subcsription data in the user doc AS WELL AS a dedicated subscription doc where we can have more information
+Thus, the user doc doesnt need to contain the entire subscription Object, just enough to grant the user access to premium features in the backend or frontend as well as display important info in the user's account page like next billing date, plan name, status, anything else that is important.
+Also, since we will be checking subscription status often, I thought it would be nice to store 2 main objects:
+1. the original subscirpiton object from the payment provider, unmodified
+2. a unified and standardized subscription object that we define, so that when checking subscription status we dont have to deal with the differences between payment providers (both for displaying info and for checking status/plan/etc to grant access when making requests or on the frontend)
+We could store BOTH in both the user doc and the subscription doc, or only store the unified object in the user doc and both in the subscription doc.
+
+For our standardized Object, we should be able to get the current plan and whether the subscription is active or not EXTREMELY easily. LIke a single if statement, allowing us to grant access if if the user is premium or whatever.
+
+However, i would like it to be flexible enough so that we can show something like:
+  - User is on premium plan and paid up --> grant access to premium features, show "You are Premium and your next billing date is X"
+  - User is on premium plan but payment failed --> restrict access to premium features, show "Your payment failed, please update your payment method"
+  - User was on premium plan but cancelled --> restrict access to premium features, show "You WERE premium but it was cancelled so now youre on Free plan"
+  - User was on premium plan but cancellation is pending --> grant access to premium features, show "You are Premium until X date when your plan will be cancelled"
+  - User is on trial --> grant access to premium features, show "You are on a free trial that ends on X date"
+So essentially we need a way to be able to determine all of these different scenarios EASILY (SINGLE IF STATEMENT)
+
+I know all payment proivders are different and ahve different concepts of how exaclty a subscirption is active, cancelled, past due, trialing, etc but we need to come up with a unified way of representing this data in our standardized object so that we can easily check status and display info regardless of payment provider.
+
+Like, i i think stripe you can "cancel at period end" and thus the sub will not actually be cancelled until the end of the billing period, but paypal might be slightly different.
+
+BEM API ENDPOINTS
+* For our payment system to work, we shoudl implemnt some BEM API endpoints to create, listen for webhooks, and manage subscriptions.
+* anytime there is an aciton that handles multiple payment providers, we should have the entryppoint import a file for each provider, where each provider handles the request in its own way, but STILL STANDARDIZED and similar across all providers.
+
+backend-manager/payments/intent
+* handle creating payment intents or equivalent in other providers
+* various checks like
+  * is the user currently subscribed? if so block
+  * is the user allowed to have a trial (havent had one before)? if not block their trial
+  * validate their gcaptcha token. block if invalid or missing
+  * create the payment intent or equivalent at "payments-intents/{id}" in firestore
+
+backend-manager/payments/webhook (or something similar)
+* handle receiving webhooks from payment providers to update subscription status
+* different file for processing each paymnt processor (returning some comon things like the event id)
+* various checks like
+  * verify the webhook by checking the querystring for the BEM token (same as .env BACKEND_MANAGER_KEY)
+  * check for payment-webhooks/{id} doc to see if we already processed this webhook (id is provided by the payment provider in the webhook payload)
+  * Immediately save the raw webhook data to "payments-webhooks/{id}" in firestore so we can return a 200 as soon as possible. THe webhook will be processed in a firestore function trigger onWrite for that doc (status === pending)
+
+Firestore trigger for payments-webhooks/{id}
+* process the webhook data and update the user's subscription data in both their user doc and their subscription doc
+* various checks like
+  * if status === completed, do nothing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.38",
+  "version": "5.0.39",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -8,13 +8,6 @@
     "bm": "./bin/bem"
   },
   "scripts": {
-    "_test": "npm run prepare && ./node_modules/mocha/bin/mocha test/ --recursive --timeout=10000",
-    "test": "./node_modules/mocha/bin/mocha test/ --recursive --timeout=10000",
-    "test:cli": "./node_modules/mocha/bin/mocha test/cli-commands.test.js --timeout=10000",
-    "test:usage": "./node_modules/mocha/bin/mocha test/usage.js --timeout=10000",
-    "test:payment-resolver": "./node_modules/mocha/bin/mocha test/payment-resolver/index.js --timeout=10000",
-    "test:user": "./node_modules/mocha/bin/mocha test/user.js --timeout=10000",
-    "test:ai": "./node_modules/mocha/bin/mocha test/ai/index.js --timeout=10000",
     "start": "node src/manager/index.js",
     "prepare": "node -e \"require('prepare-package')()\"",
     "prepare:watch": "nodemon -w ./src -e '*' --exec 'npm run prepare'"
@@ -22,6 +15,13 @@
   "engines": {
     "node": "22"
   },
+  "projectScripts": {
+    "start": "npx bm setup && npx bm serve",
+    "deploy": "npx bm setup && npx bm deploy",
+    "emulators": "npx bm setup && npx bm emulators",
+    "test": "npx bm setup && npx bm test",
+    "setup": "npx bm setup"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/itw-creative-works/backend-manager.git"
@@ -43,7 +43,7 @@
     "replace": {}
   },
   "dependencies": {
-    "@firebase/rules-unit-testing": "^2.0.7",
+    "@firebase/rules-unit-testing": "^5.0.0",
     "@google-cloud/storage": "^7.16.0",
     "@octokit/rest": "^19.0.13",
     "@sendgrid/mail": "^7.7.0",
@@ -67,7 +67,7 @@
     "lowdb": "^1.0.0",
     "mailchimp-api-v3": "^1.15.0",
     "mime-types": "^2.1.35",
-    "mocha": "^8.4.0",
+    "mocha": "^11.7.5",
     "moment": "^2.30.1",
     "nanoid": "^3.3.11",
     "node-fetch": "^2.7.0",

package/src/cli/cli-refactored.js

@@ -10,8 +10,10 @@ const InstallCommand = require('./commands/install');
 const ServeCommand = require('./commands/serve');
 const DeployCommand = require('./commands/deploy');
 const TestCommand = require('./commands/test');
+const EmulatorsCommand = require('./commands/emulators');
 const CleanCommand = require('./commands/clean');
 const IndexesCommand = require('./commands/indexes');
+const WatchCommand = require('./commands/watch');
 
 function Main() {}
 
@@ -92,11 +94,23 @@ Main.prototype.process = async function (args) {
     return await cmd.execute();
   }
 
+  // Emulators (keep-alive mode)
+  if (self.options['emulators'] || self.options['emulator']) {
+    const cmd = new EmulatorsCommand(self);
+    return await cmd.execute();
+  }
+
   // Clean
   if (self.options['clean:npm']) {
     const cmd = new CleanCommand(self);
     return await cmd.execute();
   }
+
+  // Watch (trigger hot reload when BEM source changes)
+  if (self.options['watch']) {
+    const cmd = new WatchCommand(self);
+    return await cmd.execute();
+  }
 };
 
 // Test method for setup command