@omega.js/backend 0.1.0

package/dist/vendor/account/schema.js

@@ -0,0 +1,272 @@
+/**
+ * USER_SCHEMA — the canonical OMEGA user/account schema (pure data, no logic).
+ *
+ * Extracted verbatim from @omega.js/backend's src/manager/helpers/user.js, which is
+ * the authoritative shape (@omega.js/client's DEFAULT_ACCOUNT had drifted from it).
+ *
+ * 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 (generators
+ *   are injected by the host — see engine.js; absent generators resolve to null)
+ */
+
+/**
+ * One attribution TOUCH — a single visit's campaign context, shared by
+ * `attribution.first` and `attribution.last`
+ * ([#384](https://github.com/Omega-JS-Stack/omega/issues/384)). `tags` holds the
+ * utm set and `clickIds` the ad-platform click ids (fbclid/gclid/…), both
+ * passthrough because the platforms keep adding params. The schema is read-only
+ * to the engine, so one object serves both slots.
+ */
+const ATTRIBUTION_TOUCH = {
+  tags: { $passthrough: true },
+  clickIds: { $passthrough: true },
+  referrer: { type: 'string', default: null, nullable: true },
+  url: { type: 'string', default: null, nullable: true },
+  page: { type: 'string', default: null, nullable: true },
+  timestamp: { type: 'string', default: null, nullable: true },
+};
+
+const USER_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' },
+    },
+    status: { type: 'string', default: 'active' },
+    expires: '$timestamp',
+    trial: {
+      claimed: { type: 'boolean', default: false },
+      expires: '$timestamp',
+      // How the trial ENDED: 'converted' | 'lapsed' | null (still running, or never
+      // answered). `claimed` says only that a trial happened — a converted trial and a
+      // lapsed one carry identical dates — so this is the one stored conversion signal.
+      // Stamped by the trial-lapse sweep once the provider confirms which it was.
+      outcome: { type: 'string', default: null, nullable: true },
+    },
+    cancellation: {
+      pending: { type: 'boolean', default: false },
+      date: '$timestamp',
+    },
+    payment: {
+      provider: { type: 'string', default: null, nullable: true },
+      orderId: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+      frequency: { type: 'string', default: null, nullable: true },
+      price: { type: 'number', default: 0 },
+      startDate: '$timestamp',
+      updatedBy: {
+        event: {
+          name: { type: 'string', default: null, nullable: true },
+          id: { type: 'string', default: null, nullable: true },
+        },
+        date: '$timestamp',
+      },
+    },
+    // The discount riding the subscription right now
+    // ([#325](https://github.com/Omega-JS-Stack/omega/issues/325)). Shaped as a
+    // discount-codes validate() RESULT — the one shape the whole payment stack
+    // already speaks — so the billing card reads exactly what the apply route
+    // wrote, and neither side learns a second spelling. `valid: false` (the
+    // default) IS "no discount": absent and denied read the same everywhere.
+    //
+    // Both shapes are always present and default to 0, unlike a fresh validate()
+    // result which omits the one it is not: this node is MERGED onto a document
+    // that may already carry a discount, and a percent claim landing on a stored
+    // amount would otherwise be read as the older, wrong number.
+    //
+    // `source` is what makes it safe to read as a CLAIM. Today only the winback
+    // claim writes this node; a code typed at checkout will set the same node
+    // when checkout starts writing it, and a winback pitch suppressed by someone
+    // else's promo is an offer silently withheld — so the node says which system
+    // applied it ('winback' | 'checkout'), and only 'winback' is the claimed
+    // signal the cancel flow gates on.
+    //
+    // `resourceId` is the subscription the discount was applied TO, stamped at
+    // claim time ([#333](https://github.com/Omega-JS-Stack/omega/issues/333)).
+    // It is what makes the node clearable: the unified webhook write carries no
+    // discount key, so a merge preserves this node forever, and a customer who
+    // churned and resubscribed carried a spent claim into the NEW subscription,
+    // where `source: 'winback'` reads as "already claimed" and silently retires
+    // an offer the backend would grant again. The webhook pipeline compares the
+    // stamp against the subscription each event is about and CLEARS the node
+    // (back to these defaults) on a mismatch: a new subscription is a clean
+    // slate. An unstamped node (written before the stamp existed) is read as
+    // belonging to the subscription it is found on, because nothing can prove
+    // otherwise and no live discount is ever taken away on a guess, and the
+    // pipeline stamps it there, so it clears on the next resubscribe like any
+    // other.
+    discount: {
+      valid: { type: 'boolean', default: false },
+      code: { type: 'string', default: null, nullable: true },
+      percent: { type: 'number', default: 0 },
+      amount: { type: 'number', default: 0 },
+      duration: { type: 'string', default: null, nullable: true },
+      source: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+    },
+  },
+  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: [] },
+  },
+  metadata: {
+    created: '$timestamp:now',
+    updated: '$timestamp:now',
+  },
+  activity: {
+    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 },
+    },
+    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 },
+    },
+  },
+  api: {
+    clientId: { type: 'string', default: '$uuid' },
+    privateKey: { type: 'string', default: '$apiKey' },
+  },
+  // The documents this account owns, by KIND: `{ teams: ['team-abc'] }`
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). A counted
+  // feature's catalog entry names the kinds its counters mirror onto
+  // (`usage: { mirror: ['teams'] }`), and this is what resolves a kind to real
+  // document paths — so a mirror is declared once in config instead of
+  // re-derived at every call site. Server-written like `usage`: a client that
+  // could write it could point another account's counters at its own doc.
+  owns: {
+    $passthrough: true,
+  },
+  usage: {
+    $passthrough: true,
+    // Admin-granted extra credits, feature id → number
+    // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). Declared
+    // HERE so the sibling `$template` never resolves it as a counter block:
+    // it is a map of limits, not a map of counts. `usage` is a framework field
+    // the security rules deny every client, so an override can only ever be
+    // server-written — which is what makes it trustworthy as a limit.
+    overrides: { $passthrough: true },
+    $template: {
+      monthly: { type: 'number', default: 0 },
+      daily: { type: 'number', default: 0 },
+      total: { type: 'number', default: 0 },
+      // When the counter last moved. The old `id` field went with the retired
+      // `increment(name, value, { id })` option (#647): nothing writes it now,
+      // and a schema field nothing fills reads as a fact that is always null.
+      last: {
+        timestamp: { type: 'string', default: '$oldDate' },
+        timestampUNIX: { type: 'number', default: 0 },
+      },
+    },
+  },
+  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 },
+      postalCode: { type: 'string', default: null, nullable: true },
+      street: { type: 'string', default: null, nullable: true },
+    },
+    name: {
+      first: { type: 'string', default: null, nullable: true },
+      last: { type: 'string', default: null, nullable: true },
+    },
+    company: {
+      name: { type: 'string', default: null, nullable: true },
+      position: { type: 'string', default: null, nullable: true },
+    },
+    telephone: {
+      countryCode: { type: 'number', default: 0 },
+      national: { type: 'number', default: 0 },
+    },
+  },
+  connections: {
+    $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 },
+    },
+    // The touch model: `first` is the visit that first brought the user here,
+    // written once and never overwritten; `last` is the newest TAGGED visit. No
+    // expiry — the timestamps carry any read-time lookback window. Replaces the
+    // single `utm` blob outright (no dual-read).
+    first: ATTRIBUTION_TOUCH,
+    last: ATTRIBUTION_TOUCH,
+  },
+  // The tracking-consent snapshot the client captured, stored verbatim: passthrough
+  // because this layer never interprets it — the consent module owns its shape. NOT
+  // the same thing as `consent` below, which is the legal/marketing decision.
+  trackingConsent: {
+    $passthrough: true,
+  },
+  consent: {
+    legal: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+    marketing: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+      revokedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+  },
+};
+
+module.exports = USER_SCHEMA;

package/dist/vendor/account/subscription.js

@@ -0,0 +1,38 @@
+/**
+ * resolveSubscription — extracted verbatim from @omega.js/backend's User.resolveSubscription
+ * (the superset: @omega.js/client's drifted copy lacked `everPaid`).
+ *
+ * Resolves calculated subscription fields that require derivation logic.
+ * Raw data (product.id, status, trial, cancellation) is on the account directly.
+ * Returns: { plan, active, trialing, cancelling, everPaid }
+ * - plan: the plan ID the user effectively has access to RIGHT NOW ('basic' if cancelled/suspended)
+ * - active: user has active access (active, trialing, or cancelling)
+ * - trialing: user is in an active trial (status is 'active' but trial hasn't expired)
+ * - cancelling: cancellation is pending (status is 'active' but cancellation.pending is true)
+ * - everPaid: user has had a paid subscription at some point (payment.startDate exists)
+ */
+function resolveSubscription(account) {
+  const subscription = (account?.subscription || account?.properties?.subscription) || {};
+  const productId = subscription.product?.id || 'basic';
+
+  let trialing = false;
+  let cancelling = false;
+
+  if (productId !== 'basic' && subscription.status === 'active') {
+    trialing = !!(subscription.trial?.claimed
+      && subscription.trial?.expires?.timestampUNIX > Math.floor(Date.now() / 1000));
+    cancelling = !trialing && !!subscription.cancellation?.pending;
+  }
+
+  const active = (productId !== 'basic' && subscription.status === 'active');
+
+  return {
+    plan: active ? productId : 'basic',
+    active,
+    trialing,
+    cancelling,
+    everPaid: (subscription.payment?.startDate?.timestampUNIX || 0) > 0,
+  };
+}
+
+module.exports = resolveSubscription;

package/dist/vendor/analytics/adapters/ga4.js

@@ -0,0 +1,26 @@
+/**
+ * GA4 adapter — Google Analytics 4.
+ *
+ * The canonical param vocabulary IS GA4's, so every entry without a `map()`
+ * passes straight through. Consent category: 'analytics'.
+ */
+
+const { createAdapter, pick } = require('./resolve.js');
+
+// GA4 takes campaign attribution as FLAT event params (the Measurement
+// Protocol's campaign reference), so it rides the payload itself. `gclid` joins
+// them as a plain param: GA4 has no match block to put a click id in, and it is
+// what a Google Ads enhanced-conversions upload will key on when that platform
+// file lands ([#385](https://github.com/Omega-JS-Stack/omega/issues/385)).
+const ATTRIBUTION_PARAMS = ['campaign_id', 'campaign', 'source', 'medium', 'term', 'content', 'gclid'];
+
+const adapter = createAdapter({
+  provider: 'ga4',
+  consentCategory: 'analytics',
+  attach: (descriptor, attribution) => {
+    Object.assign(descriptor.payload, pick(attribution, ATTRIBUTION_PARAMS));
+  },
+});
+
+module.exports = adapter;
+module.exports.ATTRIBUTION_PARAMS = ATTRIBUTION_PARAMS;

package/dist/vendor/analytics/adapters/meta.js

@@ -0,0 +1,26 @@
+/**
+ * Meta adapter — the Facebook Pixel and the Conversions API.
+ *
+ * Meta's commerce vocabulary (content_ids, num_items) differs from GA4's
+ * items[], so those entries carry a `map()` in the catalog; everything else
+ * passes through as custom data. Consent category: 'marketing'.
+ */
+
+const { createAdapter, pick, attachPage } = require('./resolve.js');
+
+// Meta's click/browser ids live in the user_data (match) block, never in the
+// event's custom data.
+const ATTRIBUTION_KEYS = ['fbc', 'fbp'];
+
+const adapter = createAdapter({
+  provider: 'meta',
+  consentCategory: 'marketing',
+  attach: (descriptor, attribution) => {
+    Object.assign(descriptor.userData, pick(attribution, ATTRIBUTION_KEYS));
+    // The Conversions API's `event_source_url` (#497) — the transport's to place.
+    attachPage(descriptor, attribution);
+  },
+});
+
+module.exports = adapter;
+module.exports.ATTRIBUTION_KEYS = ATTRIBUTION_KEYS;

package/dist/vendor/analytics/adapters/resolve.js

@@ -0,0 +1,130 @@
+/**
+ * The shared adapter mechanism — internal to the adapters.
+ *
+ * Every adapter is the same three steps: look the canonical event up in the
+ * catalog, take THIS provider's mapping (absent → null, the caller logs the
+ * dev skip), and run the entry's `map()` (or pass the canonical params
+ * through). Only the attribution attachment differs per provider, so that is
+ * the one thing an adapter file supplies.
+ *
+ * Pure: no I/O, no globals, no state. A descriptor is a plain object a
+ * transport executes.
+ */
+
+const { entryFor } = require('../catalog.js');
+
+/**
+ * Copy the keys a provider understands out of a flat source object.
+ * @param {object} source - The source object (may be undefined).
+ * @param {string[]} keys - The keys to take.
+ * @returns {object} Only the keys that are present.
+ */
+function pick(source, keys) {
+  const out = {};
+  if (!source) {
+    return out;
+  }
+
+  for (const key of keys) {
+    if (source[key] !== undefined && source[key] !== null) {
+      out[key] = source[key];
+    }
+  }
+
+  return out;
+}
+
+// The page a conversion happened on, as the attribution touch captured it. Only
+// the providers whose server API READS one take it (`attachPage` below).
+const PAGE_KEYS = ['url', 'referrer'];
+
+/**
+ * Attach the conversion's page to a descriptor — the touch's url, and its
+ * referrer when there is one
+ * ([#497](https://github.com/Omega-JS-Stack/omega/issues/497)).
+ *
+ * The URL is neither payload nor match data, so it rides its own descriptor
+ * member, and only when the touch actually carried one: a server conversion
+ * fires from a webhook or an auth trigger, and an INVENTED url is worse to a
+ * platform than an absent one. A referrer with no url is not half a page.
+ *
+ * @param {object} descriptor - The descriptor being built (mutated).
+ * @param {object} [attribution] - The flat attribution context.
+ */
+function attachPage(descriptor, attribution) {
+  const page = pick(attribution, PAGE_KEYS);
+
+  if (page.url) {
+    descriptor.page = page;
+  }
+}
+
+/**
+ * Build one provider's adapter.
+ *
+ * @param {object} options
+ * @param {string} options.provider - The provider key, matching the catalog's `providers` key.
+ * @param {string} options.consentCategory - 'analytics' | 'marketing'.
+ * @param {Function} [options.attach] - (descriptor, attribution) => void; places the
+ *   captured attribution where THIS provider wants it. Stage C
+ *   ([#384](https://github.com/Omega-JS-Stack/omega/issues/384)) owns the capture;
+ *   stage D ([#385](https://github.com/Omega-JS-Stack/omega/issues/385)) fills the
+ *   rest of `userData` with server match data.
+ * @returns {{ provider: string, CONSENT_CATEGORY: string, resolve: Function }}
+ */
+function createAdapter({ provider, consentCategory, attach }) {
+  /**
+   * Resolve a canonical event into this provider's descriptor.
+   * @param {string} canonicalName - The canonical event name.
+   * @param {object} [params] - The canonical params.
+   * @param {object} [context] - { attribution, consent, runtime }.
+   * @returns {{ provider: string, name: string, kind: string, payload: object, userData: object }|null}
+   */
+  function resolve(canonicalName, params = {}, context = {}) {
+    const entry = entryFor(canonicalName);
+    if (!entry) {
+      return null;
+    }
+
+    const mapping = entry.providers[provider];
+    if (!mapping) {
+      return null;
+    }
+
+    const descriptor = {
+      provider,
+      name: mapping.name,
+      kind: mapping.kind,
+      payload: mapping.map ? mapping.map(params, context) : { ...params },
+      // The identity/match block. Empty here by design: attribution lands via
+      // `attach` below, and the server enrichment is stage D's.
+      userData: {},
+    };
+
+    // The one mapping shape a transport executes differently: a provider's own
+    // pixel method (TikTok's `ttq.page()`), carried only when the catalog names
+    // one so nothing has to test for a key that is normally absent.
+    if (mapping.method) {
+      descriptor.method = mapping.method;
+    }
+
+    // The other optional mapping key a TRANSPORT reads rather than a platform's
+    // payload: Meta's `action_source`, the required server-event field naming
+    // WHERE a conversion happened. Carried the same way `method` is, only when
+    // the catalog overrides the default the sender supplies
+    // ([#498](https://github.com/Omega-JS-Stack/omega/issues/498)).
+    if (mapping.actionSource) {
+      descriptor.actionSource = mapping.actionSource;
+    }
+
+    if (attach) {
+      attach(descriptor, context.attribution);
+    }
+
+    return descriptor;
+  }
+
+  return { provider, CONSENT_CATEGORY: consentCategory, resolve };
+}
+
+module.exports = { createAdapter, pick, attachPage };

package/dist/vendor/analytics/adapters/tiktok.js

@@ -0,0 +1,27 @@
+/**
+ * TikTok adapter — the TikTok Pixel and the Events API.
+ *
+ * TikTok's commerce vocabulary is a `contents` array of product objects
+ * (content_id + content_name + price + quantity) beside the order's
+ * content_type/value/currency, so those entries carry a `map()` in the catalog;
+ * everything else passes through as properties. Consent category: 'marketing'.
+ */
+
+const { createAdapter, pick, attachPage } = require('./resolve.js');
+
+// TikTok's click id and cookie live in the Events API's context.user block —
+// never in the event properties.
+const ATTRIBUTION_KEYS = ['ttclid', 'ttp'];
+
+const adapter = createAdapter({
+  provider: 'tiktok',
+  consentCategory: 'marketing',
+  attach: (descriptor, attribution) => {
+    Object.assign(descriptor.userData, pick(attribution, ATTRIBUTION_KEYS));
+    // The Events API 2.0 data item's `page` member (#497) — the transport's to place.
+    attachPage(descriptor, attribution);
+  },
+});
+
+module.exports = adapter;
+module.exports.ATTRIBUTION_KEYS = ATTRIBUTION_KEYS;