backend-manager 5.0.127 → 5.0.129

package/CLAUDE.md

@@ -84,6 +84,12 @@ src/
         daily.js                      # Daily cron runner
         daily/{job}.js                # Individual cron jobs
     routes/                           # Built-in routes
+      admin/
+        post/                         # POST /admin/post - Create blog posts via GitHub
+          post.js                     # Extracts images, uploads to GitHub, rewrites body to @post/ format
+          put.js                      # PUT /admin/post - Edit existing posts
+          templates/
+            post.html                 # Post frontmatter template
       payments/
         intent/                       # POST /payments/intent
           post.js                     # Intent creation orchestrator
@@ -426,6 +432,28 @@ Manager.handlers.bm_api = function (mod, position) {
 | Auth Events | `events/auth/` | `{event}.js` |
 | Cron Jobs | `cron/daily/` or `hooks/cron/daily/` | `{job}.js` |
 
+## Admin Post Route
+
+The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, upload, and body rewriting.
+
+### Image Processing Flow
+1. Receives markdown body with external image URLs (e.g., `![alt](https://images.unsplash.com/...)`)
+2. Extracts all `![alt](url)` patterns from the body using regex
+3. Downloads each image and uploads it to `src/assets/images/blog/post-{id}/` on GitHub
+4. **Rewrites the body** to replace external URLs with `@post/{filename}` format
+5. The `@post/` prefix is resolved at Jekyll build time by `jekyll-uj-powertools` to the full path
+
+### Key Details
+- Image filenames are derived from `hyphenate(alt_text)` + downloaded extension
+- Header image (`headerImageURL`) is uploaded but NOT rewritten in the body (it's in frontmatter)
+- Failed image downloads are skipped — the original external URL stays in the body
+- The `extractImages()` function returns a URL mapping used for body rewriting
+
+### Files
+- `src/manager/routes/admin/post/post.js` — POST handler (create)
+- `src/manager/routes/admin/post/put.js` — PUT handler (edit)
+- `src/manager/routes/admin/post/templates/post.html` — Post template
+
 ## Testing
 
 ### Running Tests
@@ -673,6 +701,31 @@ Products can opt out of daily caps by setting `rateLimit: 'monthly'` (default is
 }
 ```
 
+### Proxy Usage (setUser + Mirrors)
+
+Sometimes usage must be billed to a different user than the one making the request (e.g., anonymous visitors consuming an agent owner's credits). Use `setUser()` to swap the target and `addMirror()` / `setMirrors()` to write usage to additional Firestore docs:
+
+```js
+// Switch usage target to the agent owner (fetches their user doc)
+await usage.setUser(ownerUid);
+
+// Also write usage data to the agent doc
+usage.addMirror(`agents/${agentId}`);
+
+// Now validate, increment, and update all operate on the owner's data
+// update() writes to users/{ownerUid} AND agents/{agentId} in parallel
+await usage.validate('credits');
+usage.increment('credits');
+await usage.update();
+```
+
+**Methods:**
+- `setUser(uid)` — async, fetches `users/{uid}` from Firestore, replaces `self.user`, sets `useUnauthenticatedStorage = false`
+- `setMirrors(paths)` — sync, overwrites the mirror array with the given paths
+- `addMirror(path)` — sync, appends a single path to the mirror array
+
+Mirrors are write-only — `update()` writes `{ usage: self.user.usage }` (merge) to each mirror path. No reads are performed on mirrors.
+
 ### Reset Schedule
 
 | Target | Frequency | What happens |

package/README.md

@@ -532,6 +532,11 @@ await usage.update();
 
 // Whitelist keys
 usage.addWhitelistKeys(['another-key']);
+
+// Proxy usage: bill a different user and mirror writes to additional docs
+await usage.setUser('owner-uid');          // Switch target user (fetches from Firestore)
+usage.addMirror('agents/agent-id');        // Also write usage to this doc on update()
+usage.setMirrors(['agents/a', 'orgs/b']); // Overwrite mirror list
 ```
 
 ### Middleware

package/package.json

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

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

@@ -15,11 +15,13 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   // Update last activity and geolocation
   const update = await admin.firestore().doc(`users/${user.uid}`)
     .set({
-      activity: {
-        lastActivity: {
+      metadata: {
+        updated: {
           timestamp: now.toISOString(),
           timestampUNIX: Math.round(now.getTime() / 1000),
         },
+      },
+      activity: {
         geolocation: {
           ip: context.ipAddress,
           language: context.locale,

package/src/manager/helpers/usage.js

@@ -23,6 +23,8 @@ function Usage(m) {
     user: '',
   }
 
+  self._mirrors = [];
+
   self.initialized = false;
 }
 
@@ -100,6 +102,39 @@ Usage.prototype.init = function (assistant, options) {
   });
 };
 
+Usage.prototype.setUser = async function (uid) {
+  const self = this;
+  const admin = self.Manager.libraries.admin;
+
+  const doc = await admin.firestore().doc(`users/${uid}`).get().catch(() => null);
+  const data = (doc && doc.exists) ? doc.data() : {};
+
+  self.user = {
+    ...data,
+    auth: { uid: uid, ...(data.auth || {}) },
+    usage: data.usage || {},
+    subscription: data.subscription || {},
+  };
+
+  self.useUnauthenticatedStorage = false;
+
+  self.log(`Usage.setUser(): Switched to user ${uid}`);
+
+  return self;
+};
+
+Usage.prototype.setMirrors = function (paths) {
+  const self = this;
+  self._mirrors = Array.isArray(paths) ? paths : [];
+  return self;
+};
+
+Usage.prototype.addMirror = function (path) {
+  const self = this;
+  self._mirrors.push(path);
+  return self;
+};
+
 Usage.prototype.validate = function (name, options) {
   const self = this;
 
@@ -357,40 +392,44 @@ Usage.prototype.update = function () {
   return new Promise(async function(resolve, reject) {
     const { admin } = Manager.libraries;
 
+    // Build the primary write promise
+    let mainWrite;
+
     // Write self.user to firestore or local if no user or if key is set
     if (self.useUnauthenticatedStorage) {
       if (self.options.unauthenticatedMode === 'firestore') {
-        admin.firestore().doc(`usage/${self.key}`)
-          .set(self.user.usage, { merge: true })
-          .then(() => {
-            self.log(`Usage.update(): Updated user.usage in firestore`, self.user.usage);
-
-            return resolve(self.user.usage);
-          })
-          .catch(e => {
-            return reject(assistant.errorify(e, {code: 500, sentry: true}));
-          });
+        mainWrite = admin.firestore().doc(`usage/${self.key}`)
+          .set(self.user.usage, { merge: true });
       } else {
         self.storage.set(`${self.paths.user}.usage`, self.user.usage).write();
 
         self.log(`Usage.update(): Updated user.usage in local storage`, self.user.usage);
 
-        return resolve(self.user.usage);
+        mainWrite = Promise.resolve();
       }
     } else {
-      admin.firestore().doc(`users/${self.user.auth.uid}`)
+      mainWrite = admin.firestore().doc(`users/${self.user.auth.uid}`)
         .set({
           usage: self.user.usage,
-        }, { merge: true })
-        .then(() => {
-          self.log(`Usage.update(): Updated user.usage in firestore`, self.user.usage);
-
-          return resolve(self.user.usage);
-        })
-        .catch(e => {
-          return reject(assistant.errorify(e, {code: 500, sentry: true}));
-        });
+        }, { merge: true });
     }
+
+    // Build mirror write promises
+    const mirrorWrites = (self._mirrors || []).map((path) => {
+      return admin.firestore().doc(path)
+        .set({ usage: self.user.usage }, { merge: true });
+    });
+
+    // Execute all writes in parallel
+    Promise.all([mainWrite, ...mirrorWrites])
+      .then(() => {
+        self.log(`Usage.update(): Updated user.usage in firestore (+ ${mirrorWrites.length} mirrors)`, self.user.usage);
+
+        return resolve(self.user.usage);
+      })
+      .catch(e => {
+        return reject(assistant.errorify(e, {code: 500, sentry: true}));
+      });
   });
 };
 

package/src/manager/helpers/user.js

@@ -66,9 +66,11 @@ const SCHEMA = {
     code: { type: 'string', default: '$randomId' },
     referrals: { type: 'array', default: [] },
   },
-  activity: {
-    lastActivity: '$timestamp:now',
+  metadata: {
     created: '$timestamp:now',
+    updated: '$timestamp:now',
+  },
+  activity: {
     geolocation: {
       ip: { type: 'string', default: null, nullable: true },
       continent: { type: 'string', default: null, nullable: true },

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

@@ -98,6 +98,11 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
     return assistant.respond(imageResult.message, { code: 400 });
   }
 
+  // Rewrite body to use @post/ prefix for extracted images
+  for (const { originalUrl, localFilename } of imageResult) {
+    settings.body = settings.body.split(originalUrl).join(`@post/${localFilename}`);
+  }
+
   // Set defaults
   const formattedContent = powertools.template(
     POST_TEMPLATE,
@@ -120,6 +125,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
 
 // Helper: Extract and upload images
 async function extractImages(assistant, octokit, settings) {
+  const urlMap = [];
 
   const matches = settings.body.matchAll(IMAGE_REGEX);
   const images = Array.from(matches).map(match => ({
@@ -138,7 +144,7 @@ async function extractImages(assistant, octokit, settings) {
   assistant.log('extractImages(): images', images);
 
   if (!images.length) {
-    return;
+    return urlMap;
   }
 
   for (let index = 0; index < images.length; index++) {
@@ -171,7 +177,14 @@ async function extractImages(assistant, octokit, settings) {
         continue;
       }
     }
+
+    // Track successfully uploaded non-header images for body rewriting
+    if (!image.header) {
+      urlMap.push({ originalUrl: image.src, localFilename: download.filename });
+    }
   }
+
+  return urlMap;
 }
 
 // Helper: Download image

package/src/manager/routes/admin/users/sync/post.js

@@ -57,12 +57,12 @@ module.exports = async ({ assistant, Manager, user, settings, analytics, librari
             uid: uid,
             email: email,
           },
-          activity: {
+          metadata: {
             created: {
               timestamp: created.toISOString(),
               timestampUNIX: Math.floor(created.getTime() / 1000),
             },
-            lastActivity: {
+            updated: {
               timestamp: activity.toISOString(),
               timestampUNIX: Math.floor(activity.getTime() / 1000),
             },

package/templates/firestore.rules

@@ -68,6 +68,7 @@ service cloud.firestore {
         || isWritingField('subscription')
         || isWritingField('affiliate')
         || isWritingField('api')
+        || isWritingField('metadata')
         || isWritingField('usage');
     }
 

package/test/routes/admin/create-post.js

@@ -0,0 +1,311 @@
+/**
+ * Test: POST /admin/post
+ * Tests the admin create post endpoint
+ * Creates blog posts via GitHub with image extraction and @post/ body rewriting
+ * Requires admin/blogger role, GitHub API key, and repo_website config
+ */
+const { Octokit } = require('@octokit/rest');
+
+module.exports = {
+  description: 'Admin create post on GitHub',
+  type: 'suite',
+  timeout: 300000, // 5 minutes total for the suite
+
+  tests: [
+    // --- Validation tests (no GitHub needed) ---
+
+    {
+      name: 'missing-title-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          url: 'test-post',
+          description: 'Test description',
+          headerImageURL: 'https://example.com/image.jpg',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 400, 'Missing title should return 400');
+      },
+    },
+
+    {
+      name: 'missing-url-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          description: 'Test description',
+          headerImageURL: 'https://example.com/image.jpg',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 400, 'Missing URL should return 400');
+      },
+    },
+
+    {
+      name: 'missing-description-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          url: 'test-post',
+          headerImageURL: 'https://example.com/image.jpg',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 400, 'Missing description should return 400');
+      },
+    },
+
+    {
+      name: 'missing-header-image-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          url: 'test-post',
+          description: 'Test description',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 400, 'Missing headerImageURL should return 400');
+      },
+    },
+
+    {
+      name: 'missing-body-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          url: 'test-post',
+          description: 'Test description',
+          headerImageURL: 'https://example.com/image.jpg',
+        });
+
+        assert.isError(response, 400, 'Missing body should return 400');
+      },
+    },
+
+    // --- Integration: create post with inline image, verify @post/ rewriting ---
+
+    {
+      name: 'create-post-rewrites-body-images',
+      auth: 'admin',
+      timeout: 120000,
+      skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE env var not set' : false,
+
+      async run({ http, assert, state, config }) {
+        if (!process.env.GITHUB_TOKEN) {
+          assert.fail('GITHUB_TOKEN env var not set');
+          return;
+        }
+
+        if (!config.githubRepoWebsite) {
+          assert.fail('githubRepoWebsite not configured');
+          return;
+        }
+
+        // Parse owner/repo for cleanup later
+        const repoMatch = config.githubRepoWebsite.match(/github\.com\/([^/]+)\/([^/]+)/);
+        if (!repoMatch) {
+          assert.fail('Could not parse githubRepoWebsite');
+          return;
+        }
+
+        state.owner = repoMatch[1];
+        state.repo = repoMatch[2];
+
+        // Use a real public .jpg for the inline image
+        const inlineImageURL = 'https://picsum.photos/id/10/200/200.jpg';
+
+        const response = await http.post('admin/post', {
+          title: 'BEM Test Create Post',
+          url: 'bem-test-create-post',
+          description: 'Test post created by BEM test suite to verify @post/ body rewriting.',
+          headerImageURL: 'https://picsum.photos/id/1/400/300.jpg',
+          body: `# BEM Test Create Post\n\nSome intro text.\n\n![Test inline image](${inlineImageURL})\n\nMore text after the image.`,
+          postPath: 'guest',
+        });
+
+        assert.isSuccess(response, 'Create post should succeed');
+        assert.hasProperty(response, 'data.id', 'Response should have post id');
+        assert.hasProperty(response, 'data.path', 'Response should have post path');
+
+        // Store for cleanup
+        state.postId = response.data.id;
+        state.postPath = `${response.data.path}/${response.data.date}-bem-test-create-post.md`;
+      },
+    },
+
+    {
+      name: 'verify-body-has-at-post-prefix',
+      auth: 'admin',
+      timeout: 30000,
+      skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE env var not set' : false,
+
+      async run({ assert, state }) {
+        if (!state.postPath) {
+          return; // Previous test didn't run
+        }
+
+        const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+        // Fetch the committed post from GitHub
+        const { data: fileData } = await octokit.rest.repos.getContent({
+          owner: state.owner,
+          repo: state.repo,
+          path: state.postPath,
+        });
+
+        const content = Buffer.from(fileData.content, 'base64').toString();
+        state.currentSha = fileData.sha;
+
+        // The body should contain @post/ prefix instead of the original external URL
+        assert.ok(
+          content.includes('@post/'),
+          'Post body should contain @post/ prefix for downloaded images',
+        );
+
+        assert.ok(
+          !content.includes('picsum.photos/id/10'),
+          'Post body should NOT contain the original external inline image URL',
+        );
+      },
+    },
+
+    // --- Auth rejection tests ---
+
+    {
+      name: 'unauthenticated-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          url: 'test-post',
+          description: 'Test description',
+          headerImageURL: 'https://example.com/image.jpg',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 401, 'Create post should fail without authentication');
+      },
+    },
+
+    {
+      name: 'non-admin-rejected',
+      auth: 'basic',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('admin/post', {
+          title: 'Test Post',
+          url: 'test-post',
+          description: 'Test description',
+          headerImageURL: 'https://example.com/image.jpg',
+          body: 'Test content',
+        });
+
+        assert.isError(response, 403, 'Create post should fail for non-admin user');
+      },
+    },
+
+    // --- Cleanup ---
+
+    {
+      name: 'cleanup',
+      auth: 'admin',
+      timeout: 60000,
+
+      async run({ state }) {
+        if (!process.env.GITHUB_TOKEN || !state.postPath) {
+          return;
+        }
+
+        const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+        // Delete the test post
+        try {
+          const { data: fileData } = await octokit.rest.repos.getContent({
+            owner: state.owner,
+            repo: state.repo,
+            path: state.postPath,
+          });
+
+          await octokit.rest.repos.deleteFile({
+            owner: state.owner,
+            repo: state.repo,
+            path: state.postPath,
+            message: '🧹 BEM test cleanup: delete create-post test',
+            sha: fileData.sha,
+          });
+        } catch (e) {
+          // File might not exist, ignore
+        }
+
+        // Delete uploaded test images
+        const imagePath = `src/assets/images/blog/post-${state.postId}/`;
+        try {
+          const { data: dirData } = await octokit.rest.repos.getContent({
+            owner: state.owner,
+            repo: state.repo,
+            path: imagePath,
+          });
+
+          // Delete each image file
+          for (const file of dirData) {
+            await octokit.rest.repos.deleteFile({
+              owner: state.owner,
+              repo: state.repo,
+              path: file.path,
+              message: `🧹 BEM test cleanup: delete test image ${file.name}`,
+              sha: file.sha,
+            });
+          }
+        } catch (e) {
+          // Directory might not exist, ignore
+        }
+
+        // Cancel any running workflows triggered by our test commits
+        try {
+          const { data: runs } = await octokit.rest.actions.listWorkflowRunsForRepo({
+            owner: state.owner,
+            repo: state.repo,
+            status: 'in_progress',
+            per_page: 10,
+          });
+
+          for (const run of runs.workflow_runs) {
+            if (run.head_commit?.message?.includes('BEM test')) {
+              try {
+                await octokit.rest.actions.cancelWorkflowRun({
+                  owner: state.owner,
+                  repo: state.repo,
+                  run_id: run.id,
+                });
+              } catch (e) {
+                // May already be completed, ignore
+              }
+            }
+          }
+        } catch (e) {
+          // Workflow cancellation failed, not critical
+        }
+      },
+    },
+  ],
+};