Installation

npm install backend-manager

Requirements:

• Node.js 22
• Firebase project with Firestore and Authentication enabled
• service-account.json - Firebase service account credentials
• backend-manager-config.json - BEM configuration file

Quick Start

Create functions/index.js:

const Manager = (new (require('backend-manager'))).init(exports, {
  setupFunctionsIdentity: true,
});
const { functions } = Manager.libraries;

// Create a custom function
exports.myEndpoint = functions
  .runWith({ memory: '256MB', timeoutSeconds: 120 })
  .https.onRequest((req, res) => Manager.Middleware(req, res).run('myEndpoint', { /* options */ }));

Create functions/routes/myEndpoint/index.js:

function Route() {}

Route.prototype.main = async function (assistant) {
  const Manager = assistant.Manager;
  const user = assistant.usage.user;
  const settings = assistant.settings;

  assistant.log('Request data:', assistant.request.data);

  // Return response
  assistant.respond({ success: true, timestamp: new Date().toISOString() });
};

module.exports = Route;

Create functions/schemas/myEndpoint/index.js:

module.exports = function (assistant) {
  return {
    defaults: {
      message: {
        types: ['string'],
        default: 'Hello World',
      },
    },
  };
};

Run the setup command:

npx bm setup

Initialization Options

const Manager = (new (require('backend-manager'))).init(exports, options);

| Option | Default | Description | |--------|---------|-------------| | initialize | true | Initialize Firebase Admin SDK | | projectType | 'firebase' | 'firebase' for Cloud Functions, 'custom' for Express server | | setupFunctions | true | Setup built-in Cloud Functions (bm_api, etc.) | | setupFunctionsIdentity | true | Setup auth event functions (onCreate, onDelete, beforeCreate, beforeSignIn) | | setupFunctionsLegacy | false | Setup legacy admin functions | | setupServer | true | Setup custom Express server for routes | | routes | '/routes' | Directory for custom route handlers | | schemas | '/schemas' | Directory for schema definitions | | resourceZone | 'us-central1' | Firebase/GCP region | | sentry | true | Enable Sentry error tracking | | serviceAccountPath | 'service-account.json' | Path to Firebase service account | | backendManagerConfigPath | 'backend-manager-config.json' | Path to BEM config file | | initializeLocalStorage | false | Initialize local lowdb storage on startup | | checkNodeVersion | true | Validate Node.js version on startup | | express.bodyParser.json | { limit: '100kb' } | Express JSON body parser options | | express.bodyParser.urlencoded | { limit: '100kb', extended: true } | Express URL-encoded options |

Configuration File

Create backend-manager-config.json in your functions directory:

{
  brand: {
    id: 'my-app',
    name: 'My Brand',
    url: 'https://example.com',
    contact: {
      email: '[email protected]',
    },
    images: {
      wordmark: 'https://example.com/wordmark.png',
      brandmark: 'https://example.com/brandmark.png',
      combomark: 'https://example.com/combomark.png',
    },
  },
  sentry: {
    dsn: 'https://[email protected]/xxx',
  },
  googleAnalytics: {
    id: 'G-XXXXXXXXXX',
    secret: 'your-ga4-secret',
  },
  backend_manager: {
    key: 'your-admin-key',
    namespace: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  },
  firebaseConfig: {
    apiKey: 'xxx',
    authDomain: 'project-id.firebaseapp.com',
    projectId: 'project-id',
    storageBucket: 'project-id.appspot.com',
    messagingSenderId: '123456789',
    appId: '1:123:web:456',
    measurementId: 'G-XXXXXXXXXX',
  },
}

Creating Custom Functions

Routes

Routes handle HTTP requests. Create files in your routes/ directory:

Structure:

• routes/{name}/index.js - Handles all HTTP methods
• routes/{name}/get.js - Handles GET requests only
• routes/{name}/post.js - Handles POST requests only
• (also supports put.js, delete.js, patch.js)

Route File Pattern:

function Route() {}

Route.prototype.main = async function (assistant) {
  // Access Manager and helpers
  const Manager = assistant.Manager;
  const usage = assistant.usage;
  const user = assistant.usage.user;
  const analytics = assistant.analytics;
  const settings = assistant.settings;

  // Access request data
  const data = assistant.request.data;       // Merged body + query
  const body = assistant.request.body;       // POST body
  const query = assistant.request.query;     // Query params
  const headers = assistant.request.headers;
  const method = assistant.request.method;
  const geolocation = assistant.request.geolocation; // { ip, country, region, city, latitude, longitude }
  const client = assistant.request.client;   // { userAgent, language, platform, mobile }

  // Check authentication
  if (!user.authenticated) {
    return assistant.respond('Authentication required', { code: 401 });
  }

  // Check admin role
  if (!user.roles.admin) {
    return assistant.respond('Admin required', { code: 403 });
  }

  // Track analytics
  analytics.event('my_event', { action: 'test' });

  // Validate usage limits
  await usage.validate('requests');
  usage.increment('requests');
  await usage.update();

  // Send response
  assistant.respond({ success: true, data: settings });
};

module.exports = Route;

Schemas

Schemas define and validate request parameters with defaults and plan-based limits:

module.exports = function (assistant, settings, options) {
  const user = options.user;

  return {
    // Default values for all plans
    defaults: {
      message: {
        types: ['string'],
        default: 'Hello',
        required: false,
      },
      count: {
        types: ['number'],
        default: 10,
        min: 1,
        max: 100,
      },
      format: {
        types: ['string'],
        default: 'json',
        // Dynamic required based on other settings
        required: (assistant, settings) => settings.output === 'file',
        // Clean/sanitize input
        clean: (value) => value.toLowerCase().trim(),
      },
    },

    // Override defaults for premium plan
    premium: {
      count: {
        types: ['number'],
        default: 100,
        max: 1000,
      },
    },
  };
};

Schema Property Options:

| Property | Type | Description | |----------|------|-------------| | types | string[] | Allowed types: 'string', 'number', 'boolean', 'object', 'array' | | default | any | Default value if not provided | | required | boolean \| function | Whether the field is required | | clean | RegExp \| function | Sanitize/transform the value | | min | number | Minimum value (for numbers) | | max | number | Maximum value (for numbers) | | available | boolean | Whether the field is available |

Middleware Options

Manager.Middleware(req, res).run('routeName', {
  authenticate: true,           // Authenticate user (default: true)
  setupAnalytics: true,         // Initialize analytics (default: true)
  setupUsage: true,             // Initialize usage tracking (default: true)
  setupSettings: true,          // Resolve settings from schema (default: true)
  schema: 'routeName',          // Schema file to use (default: same as route)
  parseMultipartFormData: true, // Parse multipart uploads (default: true)
  routesDir: '/routes',         // Custom routes directory
  schemasDir: '/schemas',       // Custom schemas directory
});

Hook System

Intercept and modify bm_api requests before/after processing:

const Manager = (new (require('backend-manager'))).init(exports, {});

Manager.handlers.bm_api = function (mod, position) {
  const assistant = mod.assistant;

  return new Promise(async function(resolve, reject) {
    const command = mod.assistant.request.data.command || '';
    const payload = mod.assistant.request.data.payload || {};

    assistant.log('Intercepted bm_api', position, command, payload);

    // Handle specific commands
    if (command === 'user:sign-up') {
      if (position === 'pre') {
        // Before sign-up: validate, modify payload, etc.
        assistant.log('Pre sign-up hook');
      } else if (position === 'post') {
        // After sign-up: send notifications, etc.
        assistant.log('Post sign-up hook');
      }
    }

    // Handle all commands
    if (command === '*') {
      if (position === 'pre') {
        // Before any command
      } else if (position === 'post') {
        // After any command
      }
    }

    return resolve();
  });
};

Built-in Functions

HTTP API (bm_api)

The main API endpoint accepts commands in the format category:action:

// POST to https://us-central1-{project}.cloudfunctions.net/bm_api
{
  "command": "general:generate-uuid",
  "payload": {
    "version": "4"
  },
  "apiKey": "optional-api-key"
}

Available Commands:

| Category | Commands | |----------|----------| | admin | firestore-write, firestore-read, firestore-query, database-write, database-read, send-email, send-notification, payment-processor, backup, cron, create-post, edit-post, get-stats, run-hook, sync-users, write-repo-content | | user | sign-up, delete, oauth2, resolve, get-subscription-info, get-active-sessions, sign-out-all-sessions, create-custom-token, regenerate-api-keys, submit-feedback, validate-settings | | general | generate-uuid, send-email, fetch-post | | handler | create-post | | firebase | get-providers | | test | authenticate, webhook, lab, redirect | | special | setup-electron-manager-client |

Auth Events

| Function | Trigger | Description | |----------|---------|-------------| | bm_authBeforeCreate | beforeUserCreated | Runs before user creation, can block signup | | bm_authBeforeSignIn | beforeUserSignedIn | Runs before sign-in, can block login | | bm_authOnCreate | onCreate | Runs after user creation, creates user document | | bm_authOnDelete | onDelete | Runs when user is deleted, cleanup |

Firestore Events

| Function | Trigger | Description | |----------|---------|-------------| | bm_notificationsOnWrite | onWrite | Triggers on notifications/{id} changes |

Cron Jobs

| Function | Schedule | Description | |----------|----------|-------------| | bm_cronDaily | Every 24 hours | Runs daily jobs from cron/daily/ and hooks/cron/daily/ |

Creating Custom Cron Jobs:

Create hooks/cron/daily/myJob.js in your functions directory:

function Job() {}

Job.prototype.main = function () {
  const self = this;
  const Manager = self.Manager;
  const assistant = self.assistant;

  return new Promise(async function(resolve, reject) {
    assistant.log('Running my daily job...');

    // Your job logic here

    return resolve();
  });
};

module.exports = Job;

Marketing & Campaigns

Built-in marketing system with multi-provider support (SendGrid + Beehiiv + FCM push).

• Contact management — add, sync, remove contacts across providers with custom field syncing
• Campaign CRUD — POST/GET/PUT/DELETE /marketing/campaign with calendar-backed scheduling
• Recurring campaigns — seasonal sales, newsletters with automatic sendAt advancement
• Newsletter generator — AI-assembled newsletters from parent server content sources
• Segment SSOT — 22 segment definitions resolved to provider IDs at runtime
• UTM auto-tagging — brand domain links tagged automatically in marketing + transactional emails
• Contact pruning — monthly 2-stage re-engagement + deletion of inactive contacts
• Template variables — {brand.name}, {holiday.name}, {season.name}, {date.*} resolved at send time

Configure via marketing section in backend-manager-config.json. See CLAUDE.md for full documentation.

Helper Classes

Assistant

Handles request/response lifecycle, authentication, and logging.

const assistant = Manager.Assistant({ req, res });

// Authentication
const user = await assistant.authenticate();
// Returns: { authenticated, auth: { uid, email }, roles, plan, ... }

// Request data
assistant.request.data;        // Merged body + query
assistant.request.body;        // POST body
assistant.request.query;       // Query params
assistant.request.headers;     // Request headers
assistant.request.method;      // HTTP method
assistant.request.geolocation; // { ip, country, region, city, latitude, longitude }
assistant.request.client;      // { userAgent, language, platform, mobile }

// Response
assistant.respond({ success: true });              // 200 JSON
assistant.respond({ success: true }, { code: 201 }); // Custom status
assistant.respond('https://example.com', { code: 302 }); // Redirect

// Errors
assistant.errorify('Something went wrong', { code: 500, sentry: true });
assistant.respond(new Error('Bad request'), { code: 400 });

// Logging
assistant.log('Info message');
assistant.warn('Warning message');
assistant.error('Error message');
assistant.debug('Debug message');

// Environment
assistant.isDevelopment(); // true in emulator
assistant.isProduction();  // true in production
assistant.isTesting();     // true when running tests

// File uploads
const { fields, files } = await assistant.parseMultipartFormData();

User

Creates user objects with default properties:

const userProps = Manager.User(existingData, { defaults: true }).properties;

// User structure:
{
  auth: { uid, email, temporary },
  subscription: {
    product: { id, name },   // product from config ('basic', 'premium', etc.)
    status: 'active',        // active | suspended | cancelled
    expires: { timestamp, timestampUNIX },
    trial: { claimed, expires: {...} },
    cancellation: { pending, date: {...} },
    limits: {},
    payment: { processor, resourceId, frequency, startDate, updatedBy }
  },
  roles: { admin, betaTester, developer },
  affiliate: { code, referrals, referrer },
  metadata: { created, updated },
  activity: { geolocation, client },
  api: { clientId, privateKey },
  usage: { requests: { monthly, daily, total, last } },
  personal: { birthday, gender, location, name, company, telephone },
  oauth2: {}
}

// Methods
userProps.merge(otherUser);    // Merge with another user object

Analytics

Send events to Google Analytics 4:

const analytics = Manager.Analytics({
  assistant: assistant,
  uuid: user.auth.uid,
});

analytics.event('purchase', {
  item_id: 'product-123',
  value: 29.99,
  currency: 'USD',
});

Auto-tracked User Properties:

• app_version, device_category, operating_system, platform
• authenticated, subscription_id, subscription_trial_claimed, activity_created
• country, city, language, age, gender

Usage

Track and limit API usage:

const usage = await Manager.Usage().init(assistant, {
  app: 'my-app',                    // App ID for limits
  key: 'custom-key',                // Optional custom key (default: user UID or IP)
  whitelistKeys: ['admin-key'],     // Keys that bypass limits
  unauthenticatedMode: 'firestore', // 'firestore' or 'local'
  refetch: false,                   // Force refetch app limits
  log: true,                        // Enable logging
});

// Check and validate limits
const currentUsage = usage.getUsage('requests');  // Get current monthly usage
const limit = usage.getLimit('requests');         // Get plan limit (monthly)
await usage.validate('requests');                 // Throws if over daily or monthly limit

// Increment usage (increments monthly, daily, and total counters)
usage.increment('requests', 1);
usage.set('requests', 0);  // Reset monthly to specific value

// Save to Firestore
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

Process requests through the middleware pipeline:

// In your function definition
exports.myEndpoint = functions
  .https.onRequest((req, res) => Manager.Middleware(req, res).run('myEndpoint', {
    authenticate: true,
    setupAnalytics: true,
    setupUsage: true,
    setupSettings: true,
    schema: 'myEndpoint',
  }));

The middleware automatically:

1. Parses multipart form data
2. Logs request details
3. Loads route handler (method-specific or index.js)
4. Authenticates user
5. Initializes usage tracking
6. Sets up analytics
7. Resolves settings from schema
8. Calls your route handler

Settings

Resolve and validate request settings against a schema:

const settings = Manager.Settings().resolve(assistant, schema, inputSettings, {
  dir: '/schemas',
  schema: 'mySchema',
  user: user,
  checkRequired: true,
});

// Timestamp constants
const timestamp = Manager.Settings().constant('timestamp');
// { types: ['string'], value: undefined, default: '2024-01-01T00:00:00.000Z' }

const timestampUNIX = Manager.Settings().constant('timestampUNIX');
// { types: ['number'], value: undefined, default: 1704067200 }

const timestampFULL = Manager.Settings().constant('timestampFULL');
// { timestamp: {...}, timestampUNIX: {...} }

Utilities

Batch operations and helper functions:

const utilities = Manager.Utilities();

// Batch iterate Firestore collection
const results = await utilities.iterateCollection(
  async ({ docs }, batch, totalCount) => {
    for (const doc of docs) {
      // Process each document
    }
    return { processed: docs.length };
  },
  {
    collection: 'users',
    batchSize: 1000,
    maxBatches: 10,
    where: [{ field: 'subscription.product.id', operator: '==', value: 'premium' }],
    orderBy: { field: 'metadata.created.timestamp', direction: 'desc' },
    startAfter: 'lastDocId',
    log: true,
  }
);

// Batch iterate Firebase Auth users
await utilities.iterateUsers(
  async ({ users, pageToken }, batch) => {
    for (const user of users) {
      // Process each auth user
    }
  },
  {
    batchSize: 1000,
    maxBatches: Infinity,
    log: true,
  }
);

// Get document with owner user
const { document, user } = await utilities.getDocumentWithOwnerUser('posts/abc123', {
  owner: 'owner',
  resolve: {
    schema: 'posts',
    assistant: assistant,
    checkRequired: false,
  },
});

// Generate random ID
const id = utilities.randomId({ size: 14 }); // 'A1b2C3d4E5f6G7'

// Cached Firestore read
const doc = await utilities.get('users/abc123', {
  maxAge: 1000 * 60 * 5, // 5 minute cache
  format: 'data',        // 'raw' or 'data'
});

Metadata

Add timestamps and tags to documents:

const metadata = Manager.Metadata(document);

document.metadata = metadata.set({ tag: 'my-operation' });
// {
//   updated: { timestamp: '...', timestampUNIX: ... },
//   tag: 'my-operation'
// }

Local Storage

Persistent JSON storage using lowdb:

const storage = Manager.storage({
  name: 'myStorage',     // Storage name (default: 'main')
  temporary: false,      // Use OS temp directory (default: false)
  clear: true,           // Clear on dev startup (default: true)
  log: false,            // Enable logging
});

// lowdb API
storage.set('key', 'value').write();
const value = storage.get('key').value();
storage.set('nested.path', { data: true }).write();

Authentication

BEM supports multiple authentication methods (checked in order):

1. Bearer Token (JWT)

   Authorization: Bearer <firebase-id-token>

2. API Key

   { apiKey: 'user-private-key' }
   // or
   { authenticationToken: 'user-private-key' }

3. Backend Manager Key (Admin access)

   { backendManagerKey: 'your-backend-manager-key' }

4. Session Cookie

   Cookie: __session=<firebase-id-token>

Authenticated User Object:

const user = await assistant.authenticate();

{
  authenticated: true,
  auth: { uid: 'abc123', email: '[email protected]' },
  roles: { admin: false, betaTester: false, developer: false },
  subscription: { product: { id: 'basic', name: 'Basic' }, status: 'active', ... },
  api: { clientId: '...', privateKey: '...' },
  // ... other user properties
}

CLI Commands

BEM includes a CLI for development and deployment:

# Install globally or use npx
npm install -g backend-manager
# or
npx backend-manager <command>

| Command | Description | |---------|-------------| | bem setup | Run Firebase project setup and validation | | bem serve | Start local Firebase emulator | | bem deploy | Deploy functions to Firebase | | bem test [paths...] | Run integration tests | | bem emulator | Start Firebase emulator (keep-alive mode) | | bem stripe | Start Stripe CLI webhook forwarding to local server | | bem version, bem v | Show BEM version | | bem clear | Clear cache and temp files | | bem install, bem i | Install BEM (local or production) | | bem clean:npm | Clean and reinstall npm modules | | bem firestore:indexes:get | Get Firestore indexes | | bem cwd | Show current working directory | | bem firestore:get <path> | Read a Firestore document | | bem firestore:set <path> '<json>' | Write/merge a Firestore document | | bem firestore:query <collection> | Query a Firestore collection | | bem firestore:delete <path> | Delete a Firestore document | | bem auth:get <uid-or-email> | Get an Auth user by UID or email | | bem auth:list | List Auth users | | bem auth:delete <uid-or-email> | Delete an Auth user | | bem auth:set-claims <uid-or-email> '<json>' | Set custom claims on an Auth user | | bem logs:read | Fetch Cloud Function logs from Google Cloud Logging | | bem logs:tail | Stream live Cloud Function logs |

All Firestore and Auth commands support --emulator to target the local emulator, --force to skip confirmation, and --raw for compact JSON output.

Logs commands support --fn <name> (function name filter), --severity <level>, --since <duration> (read only), --limit <n> (read only), and --raw. Requires gcloud CLI installed and authenticated.

Environment Variables

Set these in your functions/.env file:

| Variable | Description | |----------|-------------| | BACKEND_MANAGER_KEY | Admin authentication key | | STRIPE_SECRET_KEY | Stripe secret key (enables auto webhook forwarding in serve/emulator) |

Response Headers

BEM attaches metadata to responses:

bm-properties: {"code":200,"tag":"functionName/executionId","usage":{...},"schema":{...}}

Testing

BEM includes an integration test framework that runs against the Firebase emulator.

Running Tests

# Option 1: Two terminals (recommended for development)
npx bm emulator  # Terminal 1 - keeps emulator running
npx bm test      # Terminal 2 - runs tests

# Option 2: Single command (auto-starts emulator, shuts down after)
npx bm test

Filtering Tests

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

Log Files

BEM CLI commands automatically save output to log files in the project directory:

• emulator.log — Full emulator + Cloud Functions output (npx bm emulator)
• test.log — Test runner output (npx bm test, when running against an existing emulator)
• logs.log — Cloud Function logs (npx bm logs:read or npx bm logs:tail)

Logs are overwritten on each run. Use them to debug failing tests or review function output.

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):

// 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):

// 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.

Subscription System

BEM includes a built-in payment/subscription system with Stripe and PayPal integration.

Subscription Statuses

| Status | Meaning | User can delete account? | |--------|---------|--------------------------| | active | Subscription is current and valid (includes trialing) | No (unless product.id === 'basic') | | suspended | Payment failed (Stripe: past_due, unpaid) | No | | cancelled | Subscription terminated (Stripe: canceled, incomplete, incomplete_expired) | Yes |

Stripe Status Mapping

| Stripe Status | subscription.status | Notes | |---|---|---| | active | active | Normal active subscription | | trialing | active | trial.claimed = true | | past_due | suspended | Payment failed, retrying | | unpaid | suspended | Payment failed | | canceled | cancelled | Subscription terminated | | incomplete | cancelled | Never completed initial payment | | incomplete_expired | cancelled | Expired before completion | | active + cancel_at_period_end | active | cancellation.pending = true |

PayPal Status Mapping

| PayPal Status | subscription.status | Notes | |---|---|---| | ACTIVE | active | Normal active subscription | | SUSPENDED | suspended | Payment failed or manually suspended | | CANCELLED | cancelled | Subscription terminated | | EXPIRED | cancelled | Billing cycles completed |

Product Configuration

Products are defined in config.payment.products with flat prices and per-processor IDs:

payment: {
  products: [
    { id: 'basic', name: 'Basic', type: 'subscription', limits: { requests: 10 } },
    {
      id: 'plus', name: 'Plus', type: 'subscription',
      limits: { requests: 100 }, trial: { days: 14 },
      prices: { monthly: 28, annually: 276 },  // also supports 'weekly' and 'daily'
      stripe: { productId: 'prod_xxx' },
      paypal: { productId: 'PROD-abc123' },
    },
    {
      id: 'boost', name: 'Boost Pack', type: 'one-time',
      prices: { once: 9.99 },
      stripe: { productId: 'prod_yyy' },
    },
  ],
}

Unified Subscription Object

The same subscription shape is stored in users/{uid}.subscription and payments-orders/{orderId}.subscription:

subscription: {
  product: {
    id: 'basic',                   // product ID from config ('basic', 'premium', etc.)
    name: 'Basic',                 // display name from config
  },
  status: 'active',                // 'active' | 'suspended' | 'cancelled'
  expires: { timestamp, timestampUNIX },
  trial: {
    claimed: false,                // has user EVER used a trial
    expires: { timestamp, timestampUNIX },
  },
  cancellation: {
    pending: false,                // true = cancel at period end
    date: { timestamp, timestampUNIX },
  },
  payment: {
    processor: null,               // 'stripe' | 'paypal' | etc.
    resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
    frequency: null,               // 'monthly' | 'annually' | 'weekly' | 'daily'
    startDate: { timestamp, timestampUNIX },
    updatedBy: {
      event: { name: null, id: null },
      date: { timestamp, timestampUNIX },
    },
  },
}

Access Check Patterns

// Is premium (paid)?
user.subscription.status === 'active' && user.subscription.product.id !== 'basic'

// Is on trial?
user.subscription.trial.claimed && user.subscription.status === 'active'

// Has pending cancellation?
user.subscription.cancellation.pending === true

// Payment failed?
user.subscription.status === 'suspended'

resolveSubscription(account)

Static method on the User helper that derives calculated subscription fields. Returns only fields that require derivation logic — raw data lives on the account object directly.

const User = require('backend-manager/src/manager/helpers/user');

const resolved = User.resolveSubscription(account);
// Returns: { plan, active, trialing, cancelling }

| Field | Type | Description | |-------|------|-------------| | plan | string | Effective plan ID right now ('basic' if cancelled/suspended) | | active | boolean | Has paid access (product is not 'basic' and status is 'active') | | trialing | boolean | In active trial (status 'active' + claimed + unexpired) | | cancelling | boolean | Cancellation pending (status 'active' + cancellation.pending) |

The same function exists as auth.resolveSubscription(account) in web-manager with identical logic and return shape.

Final Words

If you are still having difficulty, we would love for you to post a question to the Backend Manager issues page. 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!)

Projects Using this Library

Somiibo: A Social Media Bot with an open-source module library. JekyllUp: A website devoted to sharing the best Jekyll themes. Slapform: A backend processor for your HTML forms on static sites. SoundGrail Music App: A resource for producers, musicians, and DJs. Hammock Report: An API for exploring and listing backyard products.

Ask us to have your project listed! :)

License

ISC