backend-manager 5.0.80 → 5.0.82

package/package.json

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

package/src/manager/functions/core/actions/api/admin/send-email.js

@@ -192,7 +192,7 @@ Module.prototype.defaultize = function () {
       email.dynamicTemplateData.signoff.urlText = options?.data?.signoff?.urlText || '@ianwieds';
     }
 
-    email.dynamicTemplateData.user = Manager.User(options.user, { defaults: false, prune: false }).properties;
+    email.dynamicTemplateData.user = Manager.User(options.user).properties;
 
     // Get app configuration from Manager.config.brand (backend-manager-config.json)
     const brand = Manager.config?.brand;

package/src/manager/functions/core/actions/api/test/health.js

@@ -13,6 +13,7 @@ Module.prototype.main = function () {
       timestamp: new Date().toISOString(),
       environment: assistant.meta?.environment || 'unknown',
       version: Manager.package?.version || 'unknown',
+      bemVersion: Manager.version || 'unknown',
     };
 
     assistant.log('Health check', response);

package/src/manager/helpers/user.js

@@ -1,225 +1,343 @@
-const _ = require('lodash');
 const uuid4 = require('uuid').v4;
-const shortid = require('shortid');
 const powertools = require('node-powertools');
 const UIDGenerator = require('uid-generator');
 const uidgen = new UIDGenerator(256);
 
 /**
- * Helper: returns value if defined, otherwise returns defaultValue (if useDefaults=true) or null
- * @param {*} value - The value to check
- * @param {*} defaultValue - The default value to use if value is null/undefined
- * @param {boolean} useDefaults - Whether to use defaultValue or return null
- * @returns {*}
+ * User schema definition
+ *
+ * Each leaf field is { type, default, nullable }
+ * Special keys:
+ *   $passthrough  — preserve all existing keys from input, don't strip unknowns
+ *   $template     — shape applied to every dynamic key in a $passthrough object
+ *   '$template'   — (string value) reference to parent's $template
+ *   '$timestamp'  — shorthand for { timestamp, timestampUNIX } defaulting to epoch
+ *   '$timestamp:now' — same but defaults to current time
+ *   '$uuid', '$randomId', '$apiKey', '$oldDate' — resolved at runtime
  */
-function getWithDefault(value, defaultValue, useDefaults) {
-  return value ?? (useDefaults ? defaultValue : null);
-}
-
-function User(Manager, settings, options) {
-  const self = this;
-
-  self.Manager = Manager;
-
-  settings = settings || {};
-  options = options || {};
-
-  options.defaults = typeof options.defaults === 'undefined' ? true : options.defaults;
-  options.prune = typeof options.prune === 'undefined' ? false : options.prune;
-
-  const now = powertools.timestamp(new Date(), {output: 'string'});
-  const nowUNIX = powertools.timestamp(now, {output: 'unix'});
-  const oldDate = powertools.timestamp(new Date(0), {output: 'string'})
-  const oldDateUNIX = powertools.timestamp(oldDate, {output: 'unix'});
-
-  const defaults = options.defaults;
-
-  self.properties = {
-    auth: {
-      uid: settings?.auth?.uid ?? null,
-      email: settings?.auth?.email ?? null,
-      temporary: getWithDefault(settings?.auth?.temporary, false, defaults),
+const SCHEMA = {
+  auth: {
+    uid: { type: 'string', default: null, nullable: true },
+    email: { type: 'string', default: null, nullable: true },
+    temporary: { type: 'boolean', default: false },
+  },
+  subscription: {
+    product: {
+      id: { type: 'string', default: 'basic' },
+      name: { type: 'string', default: 'Basic' },
     },
-    subscription: {
-      product: {
-        id: getWithDefault(settings?.subscription?.product?.id, 'basic', defaults), // product ID from config (e.g., 'basic', 'premium', 'pro')
-        name: getWithDefault(settings?.subscription?.product?.name, 'Basic', defaults), // display name from config
-      },
-      status: getWithDefault(settings?.subscription?.status, 'active', defaults), // 'active' | 'suspended' | 'cancelled'
-      expires: {
-        timestamp: getWithDefault(settings?.subscription?.expires?.timestamp, oldDate, defaults),
-        timestampUNIX: getWithDefault(settings?.subscription?.expires?.timestampUNIX, oldDateUNIX, defaults),
-      },
-      trial: {
-        claimed: getWithDefault(settings?.subscription?.trial?.claimed, false, defaults),
-        expires: {
-          timestamp: getWithDefault(settings?.subscription?.trial?.expires?.timestamp, oldDate, defaults),
-          timestampUNIX: getWithDefault(settings?.subscription?.trial?.expires?.timestampUNIX, oldDateUNIX, defaults),
-        },
-      },
-      cancellation: {
-        pending: getWithDefault(settings?.subscription?.cancellation?.pending, false, defaults),
-        date: {
-          timestamp: getWithDefault(settings?.subscription?.cancellation?.date?.timestamp, oldDate, defaults),
-          timestampUNIX: getWithDefault(settings?.subscription?.cancellation?.date?.timestampUNIX, oldDateUNIX, defaults),
-        },
-      },
-      limits: {
-        // devices: settings?.subscription?.limits?.devices ?? null,
-      },
-      payment: {
-        processor: settings?.subscription?.payment?.processor ?? null, // 'stripe' | 'paypal' | etc
-        resourceId: settings?.subscription?.payment?.resourceId ?? null, // subscription ID from provider (e.g., 'sub_xxx')
-        frequency: settings?.subscription?.payment?.frequency ?? null, // 'monthly' | 'annually'
-        startDate: {
-          timestamp: getWithDefault(settings?.subscription?.payment?.startDate?.timestamp, oldDate, defaults),
-          timestampUNIX: getWithDefault(settings?.subscription?.payment?.startDate?.timestampUNIX, oldDateUNIX, defaults),
-        },
-        updatedBy: {
-          event: {
-            name: settings?.subscription?.payment?.updatedBy?.event?.name ?? null,
-            id: settings?.subscription?.payment?.updatedBy?.event?.id ?? null,
-          },
-          date: {
-            timestamp: getWithDefault(settings?.subscription?.payment?.updatedBy?.date?.timestamp, oldDate, defaults),
-            timestampUNIX: getWithDefault(settings?.subscription?.payment?.updatedBy?.date?.timestampUNIX, oldDateUNIX, defaults),
-          },
+    status: { type: 'string', default: 'active' },
+    expires: '$timestamp',
+    trial: {
+      claimed: { type: 'boolean', default: false },
+      expires: '$timestamp',
+    },
+    cancellation: {
+      pending: { type: 'boolean', default: false },
+      date: '$timestamp',
+    },
+    payment: {
+      processor: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+      frequency: { type: 'string', default: null, nullable: true },
+      startDate: '$timestamp',
+      updatedBy: {
+        event: {
+          name: { type: 'string', default: null, nullable: true },
+          id: { type: 'string', default: null, nullable: true },
         },
+        date: '$timestamp',
       },
     },
-    roles: {
-      admin: getWithDefault(settings?.roles?.admin, false, defaults),
-      betaTester: getWithDefault(settings?.roles?.betaTester, false, defaults),
-      developer: getWithDefault(settings?.roles?.developer, false, defaults),
-    },
-    flags: {
-      signupProcessed: getWithDefault(settings?.flags?.signupProcessed, false, defaults),
+  },
+  roles: {
+    $passthrough: true,
+    admin: { type: 'boolean', default: false },
+    betaTester: { type: 'boolean', default: false },
+    developer: { type: 'boolean', default: false },
+  },
+  flags: {
+    $passthrough: true,
+    signupProcessed: { type: 'boolean', default: false },
+  },
+  affiliate: {
+    code: { type: 'string', default: '$randomId' },
+    referrals: { type: 'array', default: [] },
+  },
+  activity: {
+    lastActivity: '$timestamp:now',
+    created: '$timestamp:now',
+    geolocation: {
+      ip: { type: 'string', default: null, nullable: true },
+      continent: { type: 'string', default: null, nullable: true },
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
+      latitude: { type: 'number', default: 0 },
+      longitude: { type: 'number', default: 0 },
     },
-    affiliate: {
-      code: getWithDefault(settings?.affiliate?.code, self.Manager.Utilities().randomId({size: 7}), defaults),
-      referrals: settings?.affiliate?.referrals ?? [],
+    client: {
+      language: { type: 'string', default: null, nullable: true },
+      mobile: { type: 'boolean', default: false },
+      device: { type: 'string', default: null, nullable: true },
+      platform: { type: 'string', default: null, nullable: true },
+      browser: { type: 'string', default: null, nullable: true },
+      vendor: { type: 'string', default: null, nullable: true },
+      runtime: { type: 'string', default: null, nullable: true },
+      userAgent: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
     },
-    activity: {
-      lastActivity: {
-        timestamp: getWithDefault(settings?.activity?.lastActivity?.timestamp, now, defaults),
-        timestampUNIX: getWithDefault(settings?.activity?.lastActivity?.timestampUNIX, nowUNIX, defaults),
-      },
-      created: {
-        timestamp: getWithDefault(settings?.activity?.created?.timestamp, now, defaults),
-        timestampUNIX: getWithDefault(settings?.activity?.created?.timestampUNIX, nowUNIX, defaults),
-      },
-      geolocation: {
-        ip: settings?.activity?.geolocation?.ip ?? null,
-        continent: settings?.activity?.geolocation?.continent ?? null,
-        country: settings?.activity?.geolocation?.country ?? null,
-        region: settings?.activity?.geolocation?.region ?? null,
-        city: settings?.activity?.geolocation?.city ?? null,
-        latitude: getWithDefault(settings?.activity?.geolocation?.latitude, 0, defaults),
-        longitude: getWithDefault(settings?.activity?.geolocation?.longitude, 0, defaults),
-      },
-      client: {
-        language: settings?.activity?.client?.language ?? null,
-        mobile: getWithDefault(settings?.activity?.client?.mobile, false, defaults),
-        device: settings?.activity?.client?.device ?? null,
-        platform: settings?.activity?.client?.platform ?? null,
-        browser: settings?.activity?.client?.browser ?? null,
-        vendor: settings?.activity?.client?.vendor ?? null,
-        runtime: settings?.activity?.client?.runtime ?? null,
-        userAgent: settings?.activity?.client?.userAgent ?? null,
-        url: settings?.activity?.client?.url ?? null,
+  },
+  api: {
+    clientId: { type: 'string', default: '$uuid' },
+    privateKey: { type: 'string', default: '$apiKey' },
+  },
+  usage: {
+    $passthrough: true,
+    $template: {
+      period: { type: 'number', default: 0 },
+      total: { type: 'number', default: 0 },
+      last: {
+        id: { type: 'string', default: null, nullable: true },
+        timestamp: { type: 'string', default: '$oldDate' },
+        timestampUNIX: { type: 'number', default: 0 },
       },
     },
-    api: {
-      clientId: getWithDefault(settings?.api?.clientId, `${uuid4()}`, defaults),
-      privateKey: getWithDefault(settings?.api?.privateKey, `${uidgen.generateSync()}`, defaults),
+    requests: '$template',
+  },
+  personal: {
+    birthday: '$timestamp',
+    gender: { type: 'string', default: null, nullable: true },
+    location: {
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
     },
-    usage: {
-      requests: {
-        period: getWithDefault(settings?.usage?.requests?.period, 0, defaults),
-        total: getWithDefault(settings?.usage?.requests?.total, 0, defaults),
-        last: {
-          id: settings?.usage?.requests?.last?.id ?? null,
-          timestamp: getWithDefault(settings?.usage?.requests?.last?.timestamp, oldDate, defaults),
-          timestampUNIX: getWithDefault(settings?.usage?.requests?.last?.timestampUNIX, oldDateUNIX, defaults),
-        },
-      },
+    name: {
+      first: { type: 'string', default: null, nullable: true },
+      last: { type: 'string', default: null, nullable: true },
     },
-    personal: {
-      birthday: {
-        timestamp: getWithDefault(settings?.personal?.birthday?.timestamp, oldDate, defaults),
-        timestampUNIX: getWithDefault(settings?.personal?.birthday?.timestampUNIX, oldDateUNIX, defaults),
-      },
-      gender: settings?.personal?.gender ?? null,
-      location: {
-        country: settings?.personal?.location?.country ?? null,
-        region: settings?.personal?.location?.region ?? null,
-        city: settings?.personal?.location?.city ?? null,
-      },
-      name: {
-        first: settings?.personal?.name?.first ?? null,
-        last: settings?.personal?.name?.last ?? null,
-      },
-      company: {
-        name: settings?.personal?.company?.name ?? null,
-        position: settings?.personal?.company?.position ?? null,
-      },
-      telephone: {
-        countryCode: getWithDefault(settings?.personal?.telephone?.countryCode, 0, defaults),
-        national: getWithDefault(settings?.personal?.telephone?.national, 0, defaults),
-      },
+    company: {
+      name: { type: 'string', default: null, nullable: true },
+      position: { type: 'string', default: null, nullable: true },
     },
-    oauth2: {
-      // updated: {
-      //   timestamp: getWithDefault(settings?.oauth2?.updated?.timestamp, oldDate, defaults),
-      //   timestampUNIX: getWithDefault(settings?.oauth2?.updated?.timestampUNIX, oldDateUNIX, defaults),
-      // },
+    telephone: {
+      countryCode: { type: 'number', default: 0 },
+      national: { type: 'number', default: 0 },
     },
-    attribution: {
-      affiliate: {
-        code: settings?.attribution?.affiliate?.code ?? null,
-        timestamp: settings?.attribution?.affiliate?.timestamp ?? null,
-        url: settings?.attribution?.affiliate?.url ?? null,
-        page: settings?.attribution?.affiliate?.page ?? null,
-      },
-      utm: {
-        tags: settings?.attribution?.utm?.tags ?? {},
-        timestamp: settings?.attribution?.utm?.timestamp ?? null,
-        url: settings?.attribution?.utm?.url ?? null,
-        page: settings?.attribution?.utm?.page ?? null,
-      },
+  },
+  oauth2: {
+    $passthrough: true,
+  },
+  attribution: {
+    affiliate: {
+      code: { type: 'string', default: null, nullable: true },
+      timestamp: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+      page: { type: 'string', default: null, nullable: true },
     },
+    utm: {
+      tags: { $passthrough: true },
+      timestamp: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+      page: { type: 'string', default: null, nullable: true },
+    },
+  },
+};
+
+/**
+ * Check if a schema node is a leaf field definition (has 'type' and 'default')
+ */
+function isLeaf(node) {
+  return node !== null
+    && typeof node === 'object'
+    && typeof node.type === 'string'
+    && 'default' in node;
+}
+
+/**
+ * Coerce a value to the expected type. Returns the coerced value or undefined if coercion fails.
+ */
+function coerce(value, type) {
+  if (typeof value === type) {
+    return value;
   }
 
-  if (options.prune) {
-    self.properties = pruneObject(self.properties);
+  switch (type) {
+    case 'number': {
+      const n = Number(value);
+      return Number.isNaN(n) ? undefined : n;
+    }
+    case 'boolean': {
+      if (value === 'true' || value === 1) return true;
+      if (value === 'false' || value === 0) return false;
+      return Boolean(value);
+    }
+    case 'string': {
+      return String(value);
+    }
+    default: {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Resolve a single leaf field value
+ */
+function resolveLeaf(leaf, value, ctx) {
+  // Null handling
+  if (value === null) {
+    return leaf.nullable ? null : resolveDefault(leaf.default, ctx);
   }
 
-  self.merge = function (userObject) {
-    self.properties = _.merge({}, self.properties, userObject)
-    return self;
+  // Undefined → apply default
+  if (value === undefined) {
+    return resolveDefault(leaf.default, ctx);
   }
 
-  return self;
+  // Array type — just check it's an array, don't coerce
+  if (leaf.type === 'array') {
+    return Array.isArray(value) ? value : resolveDefault(leaf.default, ctx);
+  }
+
+  // Type coercion
+  if (typeof value !== leaf.type) {
+    const coerced = coerce(value, leaf.type);
+    return coerced !== undefined ? coerced : resolveDefault(leaf.default, ctx);
+  }
+
+  return value;
+}
+
+/**
+ * Resolve a default value, handling special tokens
+ */
+function resolveDefault(def, ctx) {
+  if (typeof def !== 'string' || !def.startsWith('$')) {
+    // For arrays, return a fresh copy to avoid shared references
+    if (Array.isArray(def)) {
+      return [...def];
+    }
+    return def;
+  }
+
+  switch (def) {
+    case '$uuid':
+      return `${uuid4()}`;
+    case '$randomId':
+      return ctx.Manager.Utilities().randomId({ size: 7 });
+    case '$apiKey':
+      return `${uidgen.generateSync()}`;
+    case '$oldDate':
+      return ctx.oldDate;
+    case '$oldDateUNIX':
+      return ctx.oldDateUNIX;
+    case '$now':
+      return ctx.now;
+    case '$nowUNIX':
+      return ctx.nowUNIX;
+    default:
+      return def;
+  }
 }
 
+/**
+ * Expand $timestamp shorthand into a schema branch
+ */
+function expandTimestamp(variant) {
+  const useNow = variant === '$timestamp:now';
 
-// https://stackoverflow.com/a/26202058/7305269
-function pruneObject(obj) {
-  return function prune(current) {
-    _.forOwn(current, function (value, key) {
-      if (_.isUndefined(value) || _.isNull(value) || _.isNaN(value) ||
-        (_.isObject(value) && _.isEmpty(prune(value)))) {
+  return {
+    timestamp: { type: 'string', default: useNow ? '$now' : '$oldDate' },
+    timestampUNIX: { type: 'number', default: useNow ? '$nowUNIX' : 0 },
+  };
+}
 
-        delete current[key];
+/**
+ * Recursively resolve a schema node against input data
+ */
+function resolve(schema, data, ctx) {
+  data = data || {};
+  const result = {};
+
+  // If $passthrough, start by copying all existing keys from data
+  const isPassthrough = schema.$passthrough === true;
+  const template = schema.$template || null;
+
+  if (isPassthrough) {
+    // Copy all data keys first (they'll be overwritten by defined schema fields below)
+    for (const key of Object.keys(data)) {
+      if (template && !key.startsWith('$') && !(key in schema)) {
+        // Dynamic key — resolve against template
+        result[key] = resolve(template, data[key], ctx);
+      } else if (!(key in schema) || key.startsWith('$')) {
+        // Unknown key not in schema — passthrough as-is
+        result[key] = data[key];
       }
-    });
-    // remove any leftover undefined values from the delete
-    // operation on an array
-    if (_.isArray(current)) _.pull(current, undefined);
+    }
+  }
 
-    return current;
+  // Now resolve each defined schema field
+  for (const [key, node] of Object.entries(schema)) {
+    // Skip meta keys
+    if (key.startsWith('$')) {
+      continue;
+    }
+
+    // Handle string shorthands
+    if (typeof node === 'string') {
+      if (node === '$template') {
+        // Resolve against parent's $template
+        result[key] = resolve(template, data[key], ctx);
+        continue;
+      }
+      if (node.startsWith('$timestamp')) {
+        // Expand timestamp shorthand and recurse
+        result[key] = resolve(expandTimestamp(node), data[key], ctx);
+        continue;
+      }
+    }
+
+    // Leaf field
+    if (isLeaf(node)) {
+      result[key] = resolveLeaf(node, data[key], ctx);
+      continue;
+    }
+
+    // Nested branch (plain object)
+    if (node !== null && typeof node === 'object') {
+      result[key] = resolve(node, data[key], ctx);
+      continue;
+    }
+  }
+
+  return result;
+}
 
-  }(_.cloneDeep(obj));  // Do not modify the original object, create a clone instead
+// ─── User constructor ───
+
+function User(Manager, settings) {
+  const self = this;
+
+  self.Manager = Manager;
+
+  settings = settings || {};
+
+  // Build resolver context
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const ctx = {
+    Manager,
+    now: now,
+    nowUNIX: powertools.timestamp(now, { output: 'unix' }),
+    oldDate: powertools.timestamp(new Date(0), { output: 'string' }),
+    oldDateUNIX: powertools.timestamp(new Date(0), { output: 'unix' }),
+  };
+
+  // Resolve
+  self.properties = resolve(SCHEMA, settings, ctx);
+
+  return self;
 }
 
 module.exports = User;

package/src/manager/index.js

@@ -18,10 +18,14 @@ const cron = path.resolve(__dirname, './cron');
 const events = path.resolve(__dirname, './events');
 
 const BEM_CONFIG_TEMPLATE_PATH = path.resolve(__dirname, '../../templates/backend-manager-config.json');
+const BEM_PACKAGE = require('../../package.json');
 
 function Manager() {
   const self = this;
 
+  // BEM library version
+  self.version = BEM_PACKAGE.version;
+
   // Constants
   self.SERVER_UUID = '11111111-1111-1111-1111-111111111111';
 

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

@@ -171,7 +171,7 @@ async function buildEmail(Manager, assistant, settings) {
     email.dynamicTemplateData.signoff.urlText = settings?.data?.signoff?.urlText || '@ianwieds';
   }
 
-  email.dynamicTemplateData.user = Manager.User(settings.user, { defaults: false, prune: false }).properties;
+  email.dynamicTemplateData.user = Manager.User(settings.user).properties;
 
   // Get app configuration from Manager.config.brand
   const brand = Manager.config?.brand;

package/src/manager/routes/test/health/get.js

@@ -5,6 +5,7 @@ module.exports = async ({ assistant, Manager }) => {
     timestamp: new Date().toISOString(),
     environment: assistant.meta?.environment || 'unknown',
     version: Manager.package?.version || 'unknown',
+    bemVersion: Manager.version || 'unknown',
   };
 
   assistant.log('Health check', response);

package/test/helpers/user.js

@@ -0,0 +1,518 @@
+/**
+ * Test: helpers/user
+ * Unit tests for Manager.User() schema-driven normalization
+ *
+ * Tests the declarative schema resolver: defaults, passthrough, templates, type coercion
+ */
+const User = require('../../src/manager/helpers/user.js');
+
+// Mock Manager with minimal Utilities
+const Manager = {
+  Utilities: () => ({
+    randomId: ({ size }) => 'test123',
+  }),
+};
+
+function createUser(settings) {
+  return new User(Manager, settings).properties;
+}
+
+module.exports = {
+  description: 'User() schema resolver',
+  type: 'group',
+
+  tests: [
+    // ─── Empty / new user ───
+
+    {
+      name: 'empty-settings-gets-all-defaults',
+      async run({ assert }) {
+        const user = createUser({});
+
+        // Auth
+        assert.equal(user.auth.uid, null, 'auth.uid should be null');
+        assert.equal(user.auth.email, null, 'auth.email should be null');
+        assert.equal(user.auth.temporary, false, 'auth.temporary should be false');
+
+        // Subscription
+        assert.equal(user.subscription.product.id, 'basic', 'subscription.product.id should be basic');
+        assert.equal(user.subscription.product.name, 'Basic', 'subscription.product.name should be Basic');
+        assert.equal(user.subscription.status, 'active', 'subscription.status should be active');
+        assert.equal(user.subscription.trial.claimed, false, 'subscription.trial.claimed should be false');
+        assert.equal(user.subscription.cancellation.pending, false, 'subscription.cancellation.pending should be false');
+
+        // Timestamps should exist
+        assert.ok(user.subscription.expires.timestamp, 'subscription.expires.timestamp should exist');
+        assert.equal(typeof user.subscription.expires.timestampUNIX, 'number', 'subscription.expires.timestampUNIX should be number');
+
+        // Roles
+        assert.equal(user.roles.admin, false, 'roles.admin should be false');
+        assert.equal(user.roles.betaTester, false, 'roles.betaTester should be false');
+        assert.equal(user.roles.developer, false, 'roles.developer should be false');
+
+        // Flags
+        assert.equal(user.flags.signupProcessed, false, 'flags.signupProcessed should be false');
+
+        // Affiliate
+        assert.equal(typeof user.affiliate.code, 'string', 'affiliate.code should be string');
+        assert.ok(user.affiliate.code.length > 0, 'affiliate.code should not be empty');
+        assert.ok(Array.isArray(user.affiliate.referrals), 'affiliate.referrals should be array');
+
+        // Activity
+        assert.ok(user.activity.lastActivity.timestamp, 'activity.lastActivity.timestamp should exist');
+        assert.ok(user.activity.created.timestamp, 'activity.created.timestamp should exist');
+        assert.equal(user.activity.geolocation.latitude, 0, 'geolocation.latitude should be 0');
+        assert.equal(user.activity.geolocation.longitude, 0, 'geolocation.longitude should be 0');
+        assert.equal(user.activity.client.mobile, false, 'client.mobile should be false');
+
+        // API keys
+        assert.equal(typeof user.api.clientId, 'string', 'api.clientId should be string');
+        assert.ok(user.api.clientId.length > 0, 'api.clientId should not be empty');
+        assert.equal(typeof user.api.privateKey, 'string', 'api.privateKey should be string');
+        assert.ok(user.api.privateKey.length > 0, 'api.privateKey should not be empty');
+
+        // Usage
+        assert.equal(user.usage.requests.period, 0, 'usage.requests.period should be 0');
+        assert.equal(user.usage.requests.total, 0, 'usage.requests.total should be 0');
+        assert.equal(user.usage.requests.last.id, null, 'usage.requests.last.id should be null');
+
+        // Personal
+        assert.equal(user.personal.name.first, null, 'personal.name.first should be null');
+        assert.equal(user.personal.name.last, null, 'personal.name.last should be null');
+        assert.equal(user.personal.telephone.countryCode, 0, 'telephone.countryCode should be 0');
+
+        // OAuth2
+        assert.deepEqual(user.oauth2, {}, 'oauth2 should be empty object');
+
+        // Attribution
+        assert.equal(user.attribution.affiliate.code, null, 'attribution.affiliate.code should be null');
+        assert.deepEqual(user.attribution.utm.tags, {}, 'attribution.utm.tags should be empty object');
+      },
+    },
+
+    {
+      name: 'undefined-settings-gets-all-defaults',
+      async run({ assert }) {
+        const user = new User(Manager).properties;
+
+        assert.equal(user.auth.uid, null, 'auth.uid should be null');
+        assert.equal(user.subscription.product.id, 'basic', 'subscription.product.id should be basic');
+        assert.equal(user.roles.admin, false, 'roles.admin should be false');
+      },
+    },
+
+    // ─── Preserving real user data ───
+
+    {
+      name: 'real-data-takes-precedence-over-defaults',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { uid: 'user123', email: 'test@test.com', temporary: true },
+          subscription: { product: { id: 'pro', name: 'Pro' }, status: 'cancelled' },
+          roles: { admin: true, betaTester: true, developer: false },
+          personal: { name: { first: 'Ian', last: 'W' } },
+        });
+
+        assert.equal(user.auth.uid, 'user123', 'auth.uid should be preserved');
+        assert.equal(user.auth.email, 'test@test.com', 'auth.email should be preserved');
+        assert.equal(user.auth.temporary, true, 'auth.temporary should be preserved');
+        assert.equal(user.subscription.product.id, 'pro', 'subscription.product.id should be preserved');
+        assert.equal(user.subscription.status, 'cancelled', 'subscription.status should be preserved');
+        assert.equal(user.roles.admin, true, 'roles.admin should be preserved');
+        assert.equal(user.personal.name.first, 'Ian', 'personal.name.first should be preserved');
+      },
+    },
+
+    // ─── $passthrough: oauth2 ───
+
+    {
+      name: 'oauth2-passthrough-preserves-provider-data',
+      async run({ assert }) {
+        const googleToken = {
+          access_token: 'ya29.xxx',
+          refresh_token: '1//xxx',
+          expiry_date: 1700000000,
+        };
+        const msToken = {
+          access_token: 'eyJ.xxx',
+          refresh_token: 'M.xxx',
+        };
+
+        const user = createUser({
+          oauth2: {
+            google: {
+              token: googleToken,
+              identity: { email: 'g@gmail.com', name: 'Test' },
+            },
+            microsoft: {
+              token: msToken,
+            },
+          },
+        });
+
+        assert.equal(user.oauth2.google.token.access_token, 'ya29.xxx', 'google access_token preserved');
+        assert.equal(user.oauth2.google.token.refresh_token, '1//xxx', 'google refresh_token preserved');
+        assert.equal(user.oauth2.google.identity.email, 'g@gmail.com', 'google identity preserved');
+        assert.equal(user.oauth2.microsoft.token.access_token, 'eyJ.xxx', 'microsoft token preserved');
+      },
+    },
+
+    {
+      name: 'oauth2-empty-when-not-provided',
+      async run({ assert }) {
+        const user = createUser({});
+        assert.deepEqual(user.oauth2, {}, 'oauth2 should be empty object when not provided');
+      },
+    },
+
+    // ─── $passthrough: roles (with defined defaults) ───
+
+    {
+      name: 'roles-passthrough-preserves-custom-roles',
+      async run({ assert }) {
+        const user = createUser({
+          roles: { admin: true, customRole: true, moderator: false },
+        });
+
+        assert.equal(user.roles.admin, true, 'admin should be true');
+        assert.equal(user.roles.customRole, true, 'customRole should be preserved');
+        assert.equal(user.roles.moderator, false, 'moderator should be preserved');
+        assert.equal(user.roles.betaTester, false, 'betaTester should get default');
+        assert.equal(user.roles.developer, false, 'developer should get default');
+      },
+    },
+
+    // ─── $passthrough: flags (with defined defaults) ───
+
+    {
+      name: 'flags-passthrough-preserves-custom-flags',
+      async run({ assert }) {
+        const user = createUser({
+          flags: { signupProcessed: true, featureX: true, betaOptIn: false },
+        });
+
+        assert.equal(user.flags.signupProcessed, true, 'signupProcessed preserved');
+        assert.equal(user.flags.featureX, true, 'featureX preserved');
+        assert.equal(user.flags.betaOptIn, false, 'betaOptIn preserved');
+      },
+    },
+
+    // ─── $template: usage with dynamic keys ───
+
+    {
+      name: 'usage-template-preserves-dynamic-keys',
+      async run({ assert }) {
+        const user = createUser({
+          usage: {
+            requests: { period: 10, total: 100, last: { id: 'r1', timestamp: '2025-01-01T00:00:00.000Z', timestampUNIX: 1735689600 } },
+            emails: { period: 5, total: 50, last: { id: 'e1', timestamp: '2025-01-02T00:00:00.000Z', timestampUNIX: 1735776000 } },
+            sends: { period: 3, total: 30 },
+          },
+        });
+
+        // Defined key (requests)
+        assert.equal(user.usage.requests.period, 10, 'requests.period preserved');
+        assert.equal(user.usage.requests.total, 100, 'requests.total preserved');
+        assert.equal(user.usage.requests.last.id, 'r1', 'requests.last.id preserved');
+
+        // Dynamic key (emails) — full data
+        assert.equal(user.usage.emails.period, 5, 'emails.period preserved');
+        assert.equal(user.usage.emails.total, 50, 'emails.total preserved');
+        assert.equal(user.usage.emails.last.id, 'e1', 'emails.last.id preserved');
+
+        // Dynamic key (sends) — partial data, template fills in missing
+        assert.equal(user.usage.sends.period, 3, 'sends.period preserved');
+        assert.equal(user.usage.sends.total, 30, 'sends.total preserved');
+        assert.equal(user.usage.sends.last.id, null, 'sends.last.id defaulted to null');
+        assert.ok(user.usage.sends.last.timestamp, 'sends.last.timestamp defaulted');
+        assert.equal(typeof user.usage.sends.last.timestampUNIX, 'number', 'sends.last.timestampUNIX defaulted to number');
+      },
+    },
+
+    {
+      name: 'usage-only-requests-when-no-extra-keys',
+      async run({ assert }) {
+        const user = createUser({});
+
+        assert.ok(user.usage.requests, 'usage.requests should exist');
+        assert.equal(Object.keys(user.usage).length, 1, 'usage should only have requests key');
+      },
+    },
+
+    // ─── $passthrough: utm.tags ───
+
+    {
+      name: 'utm-tags-passthrough-preserves-all-tags',
+      async run({ assert }) {
+        const user = createUser({
+          attribution: {
+            utm: {
+              tags: { source: 'google', medium: 'cpc', campaign: 'summer' },
+              timestamp: '2025-06-01T00:00:00.000Z',
+            },
+          },
+        });
+
+        assert.equal(user.attribution.utm.tags.source, 'google', 'utm source preserved');
+        assert.equal(user.attribution.utm.tags.medium, 'cpc', 'utm medium preserved');
+        assert.equal(user.attribution.utm.tags.campaign, 'summer', 'utm campaign preserved');
+        assert.equal(user.attribution.utm.timestamp, '2025-06-01T00:00:00.000Z', 'utm timestamp preserved');
+      },
+    },
+
+    // ─── Type coercion ───
+
+    {
+      name: 'coerces-number-from-string',
+      async run({ assert }) {
+        const user = createUser({
+          activity: { geolocation: { latitude: '42.5', longitude: '-73.2' } },
+          personal: { telephone: { countryCode: '44', national: '7911123456' } },
+        });
+
+        assert.equal(user.activity.geolocation.latitude, 42.5, 'string "42.5" coerced to number');
+        assert.equal(user.activity.geolocation.longitude, -73.2, 'string "-73.2" coerced to number');
+        assert.equal(user.personal.telephone.countryCode, 44, 'string "44" coerced to number');
+      },
+    },
+
+    {
+      name: 'coerces-boolean-from-number',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { temporary: 1 },
+          activity: { client: { mobile: 0 } },
+        });
+
+        assert.equal(user.auth.temporary, true, '1 coerced to true');
+        assert.equal(user.activity.client.mobile, false, '0 coerced to false');
+      },
+    },
+
+    {
+      name: 'coerces-boolean-from-string',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { temporary: 'true' },
+          roles: { admin: 'false' },
+        });
+
+        assert.equal(user.auth.temporary, true, '"true" coerced to true');
+        assert.equal(user.roles.admin, false, '"false" coerced to false');
+      },
+    },
+
+    {
+      name: 'invalid-coercion-falls-back-to-default',
+      async run({ assert }) {
+        const user = createUser({
+          activity: { geolocation: { latitude: 'not-a-number', longitude: undefined } },
+          personal: { telephone: { national: 'abc' } },
+        });
+
+        assert.equal(user.activity.geolocation.latitude, 0, 'invalid string falls back to default 0');
+        assert.equal(user.activity.geolocation.longitude, 0, 'undefined falls back to default 0');
+        assert.equal(user.personal.telephone.national, 0, 'non-numeric string falls back to default 0');
+      },
+    },
+
+    // ─── Nullable fields ───
+
+    {
+      name: 'nullable-fields-preserve-null',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { uid: null, email: null },
+          personal: { name: { first: null, last: null }, gender: null },
+          activity: { geolocation: { ip: null, country: null } },
+        });
+
+        assert.equal(user.auth.uid, null, 'null uid preserved');
+        assert.equal(user.auth.email, null, 'null email preserved');
+        assert.equal(user.personal.name.first, null, 'null first name preserved');
+        assert.equal(user.personal.gender, null, 'null gender preserved');
+        assert.equal(user.activity.geolocation.ip, null, 'null ip preserved');
+      },
+    },
+
+    {
+      name: 'non-nullable-fields-replace-null-with-default',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { temporary: null },
+          roles: { admin: null },
+          activity: { geolocation: { latitude: null } },
+        });
+
+        // These are non-nullable, so null should be replaced with the schema default
+        assert.equal(user.auth.temporary, false, 'null temporary replaced with false');
+        assert.equal(user.roles.admin, false, 'null admin replaced with false');
+        assert.equal(user.activity.geolocation.latitude, 0, 'null latitude replaced with 0');
+      },
+    },
+
+    // ─── Fragmented / incomplete users ───
+
+    {
+      name: 'partial-subscription-fills-missing-fields',
+      async run({ assert }) {
+        const user = createUser({
+          subscription: { product: { id: 'premium' } },
+        });
+
+        assert.equal(user.subscription.product.id, 'premium', 'provided id preserved');
+        assert.equal(user.subscription.product.name, 'Basic', 'missing name gets default');
+        assert.equal(user.subscription.status, 'active', 'missing status gets default');
+        assert.equal(user.subscription.trial.claimed, false, 'missing trial.claimed gets default');
+        assert.ok(user.subscription.expires.timestamp, 'missing expires gets default timestamp');
+      },
+    },
+
+    {
+      name: 'partial-activity-fills-missing-fields',
+      async run({ assert }) {
+        const user = createUser({
+          activity: { geolocation: { country: 'US' } },
+        });
+
+        assert.equal(user.activity.geolocation.country, 'US', 'provided country preserved');
+        assert.equal(user.activity.geolocation.ip, null, 'missing ip defaults to null');
+        assert.equal(user.activity.geolocation.latitude, 0, 'missing latitude defaults to 0');
+        assert.ok(user.activity.lastActivity.timestamp, 'missing lastActivity gets default');
+        assert.ok(user.activity.created.timestamp, 'missing created gets default');
+      },
+    },
+
+    {
+      name: 'deeply-nested-partial-payment-fills-correctly',
+      async run({ assert }) {
+        const user = createUser({
+          subscription: {
+            payment: { processor: 'stripe', resourceId: 'sub_123' },
+          },
+        });
+
+        assert.equal(user.subscription.payment.processor, 'stripe', 'processor preserved');
+        assert.equal(user.subscription.payment.resourceId, 'sub_123', 'resourceId preserved');
+        assert.equal(user.subscription.payment.frequency, null, 'missing frequency defaults to null');
+        assert.ok(user.subscription.payment.startDate.timestamp, 'missing startDate gets default');
+        assert.equal(user.subscription.payment.updatedBy.event.name, null, 'missing event.name defaults to null');
+      },
+    },
+
+    // ─── Top-level structure ───
+
+    {
+      name: 'all-top-level-keys-present',
+      async run({ assert }) {
+        const user = createUser({});
+        const expectedKeys = [
+          'auth', 'subscription', 'roles', 'flags', 'affiliate',
+          'activity', 'api', 'usage', 'personal', 'oauth2', 'attribution',
+        ];
+
+        for (const key of expectedKeys) {
+          assert.ok(key in user, `Top-level key "${key}" should exist`);
+        }
+      },
+    },
+
+    {
+      name: 'no-extra-top-level-keys',
+      async run({ assert }) {
+        const user = createUser({});
+        const expectedKeys = [
+          'auth', 'subscription', 'roles', 'flags', 'affiliate',
+          'activity', 'api', 'usage', 'personal', 'oauth2', 'attribution',
+        ];
+
+        for (const key of Object.keys(user)) {
+          assert.ok(expectedKeys.includes(key), `Unexpected top-level key "${key}"`);
+        }
+      },
+    },
+
+    // ─── Unique/generated values ───
+
+    {
+      name: 'api-keys-are-unique-per-call',
+      async run({ assert }) {
+        const u1 = createUser({});
+        const u2 = createUser({});
+
+        // privateKey uses UIDGenerator which should produce unique values
+        assert.notEqual(u1.api.privateKey, u2.api.privateKey, 'privateKey should be unique per call');
+        assert.notEqual(u1.api.clientId, u2.api.clientId, 'clientId should be unique per call');
+      },
+    },
+
+    {
+      name: 'existing-api-keys-not-overwritten',
+      async run({ assert }) {
+        const user = createUser({
+          api: { clientId: 'my-client-id', privateKey: 'my-secret-key' },
+        });
+
+        assert.equal(user.api.clientId, 'my-client-id', 'existing clientId preserved');
+        assert.equal(user.api.privateKey, 'my-secret-key', 'existing privateKey preserved');
+      },
+    },
+
+    // ─── Complex real-world user ───
+
+    {
+      name: 'full-real-world-user-preserves-everything',
+      async run({ assert }) {
+        const user = createUser({
+          auth: { uid: 'V4U9wR0AiLUQRxpcP7WhgA4FX9H2', email: 'ian@example.com', temporary: false },
+          subscription: {
+            product: { id: 'premium', name: 'Premium' },
+            status: 'active',
+            expires: { timestamp: '2026-12-31T00:00:00.000Z', timestampUNIX: 1798761600 },
+            trial: { claimed: true, expires: { timestamp: '2024-01-01T00:00:00.000Z', timestampUNIX: 1704067200 } },
+            payment: { processor: 'stripe', resourceId: 'sub_abc', frequency: 'annually' },
+          },
+          roles: { admin: true, betaTester: true, developer: true, superAdmin: true },
+          flags: { signupProcessed: true, onboarded: true },
+          affiliate: { code: 'IAN7', referrals: ['ref1', 'ref2'] },
+          api: { clientId: 'uuid-123', privateKey: 'key-456' },
+          oauth2: {
+            google: {
+              token: { access_token: 'ya29.real', refresh_token: '1//real', expiry_date: 1700000000 },
+              identity: { email: 'ian@gmail.com', name: 'Ian W', picture: 'https://photo.url' },
+            },
+          },
+          usage: {
+            requests: { period: 100, total: 5000, last: { id: 'req-z', timestamp: '2025-12-01T00:00:00.000Z', timestampUNIX: 1764633600 } },
+            emails: { period: 42, total: 2100, last: { id: 'em-z', timestamp: '2025-12-01T00:00:00.000Z', timestampUNIX: 1764633600 } },
+          },
+          personal: {
+            name: { first: 'Ian', last: 'Wiedenman' },
+            company: { name: 'ITW Creative Works', position: 'CEO' },
+            birthday: { timestamp: '1990-05-15T00:00:00.000Z', timestampUNIX: 642988800 },
+          },
+          attribution: {
+            affiliate: { code: 'PARTNER1', timestamp: '2024-06-01T00:00:00.000Z' },
+            utm: { tags: { source: 'twitter', campaign: 'launch' }, url: 'https://example.com' },
+          },
+        });
+
+        // Everything should be preserved exactly
+        assert.equal(user.auth.uid, 'V4U9wR0AiLUQRxpcP7WhgA4FX9H2', 'uid preserved');
+        assert.equal(user.subscription.product.id, 'premium', 'product preserved');
+        assert.equal(user.roles.superAdmin, true, 'custom role preserved');
+        assert.equal(user.flags.onboarded, true, 'custom flag preserved');
+        assert.equal(user.affiliate.code, 'IAN7', 'affiliate code preserved');
+        assert.deepEqual(user.affiliate.referrals, ['ref1', 'ref2'], 'referrals preserved');
+        assert.equal(user.api.clientId, 'uuid-123', 'api clientId preserved');
+        assert.equal(user.oauth2.google.token.access_token, 'ya29.real', 'oauth2 token preserved');
+        assert.equal(user.oauth2.google.identity.email, 'ian@gmail.com', 'oauth2 identity preserved');
+        assert.equal(user.usage.emails.period, 42, 'usage emails preserved');
+        assert.equal(user.personal.name.first, 'Ian', 'name preserved');
+        assert.equal(user.personal.company.name, 'ITW Creative Works', 'company preserved');
+        assert.equal(user.personal.birthday.timestampUNIX, 642988800, 'birthday preserved');
+        assert.equal(user.attribution.utm.tags.source, 'twitter', 'utm tags preserved');
+      },
+    },
+  ],
+};

package/.claude/settings.local.json

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