@omega.js/backend 0.1.0

package/dist/manager/routes/verts/utils.js

@@ -0,0 +1,436 @@
+/**
+ * Shared utilities for the verts routes (house inventory).
+ *
+ * Owns the in-memory inventory cache (one Firestore read per instance per
+ * TTL interval — Ian's ruling: runtime serving stays cheap), the selection
+ * scoring pipeline (eligibility → contextual match score → weighted random),
+ * and the mapping of a stored vert onto the shared unit-document renderer in
+ * @omega.js/client (this package holds no unit template of its own).
+ */
+
+const { BRAND_ID_PATTERN } = require('../../../vendor/config/index.js');
+
+const BATCH_SIZE = 500;
+const CACHE_TTL = 5 * 60 * 1000; // ~5 minutes
+
+// Module-level inventory cache — shared by the serve and redirect routes.
+const cache = {
+  verts: null,
+  fetched: 0,
+};
+
+/**
+ * Normalize a host-ish value ('https://www.example.com/path', 'Example.com')
+ * to a bare lowercase host ('example.com'). Returns '' when unparseable.
+ */
+function normalizeHost(input) {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+
+  const raw = input.trim().toLowerCase();
+
+  if (!raw) {
+    return '';
+  }
+
+  try {
+    const url = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    return url.hostname.replace(/^www\./, '');
+  } catch (e) {
+    return '';
+  }
+}
+
+/**
+ * Normalize a host-ish value to the ORIGIN parent-frame messages should
+ * target — scheme + host with any explicit port PRESERVED
+ * ('localhost:4100' → 'http://localhost:4100'; 'Example.com' →
+ * 'https://example.com'). Local hosts speak http (dev servers have no TLS);
+ * everything else https. A port-stripped origin would make the browser
+ * silently drop every postMessage, collapsing dev units as no-fill.
+ * Returns '' when unparseable.
+ */
+function normalizeOrigin(input) {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+
+  const raw = input.trim().toLowerCase();
+
+  if (!raw) {
+    return '';
+  }
+
+  try {
+    const url = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    const hostname = url.hostname.replace(/^www\./, '');
+    const isLocal = hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1';
+    const host = url.port ? `${hostname}:${url.port}` : hostname;
+
+    return `${isLocal ? 'http' : 'https'}://${host}`;
+  } catch (e) {
+    return '';
+  }
+}
+
+/**
+ * Normalize a requesting brand's id (the `brand` param the client sends with
+ * every impression, and it becomes utm_source on the click). Only a real config
+ * slug survives (`brand.id`'s own pattern), so a caller-supplied value can
+ * never write arbitrary text onto an advertiser's destination URL.
+ * Returns '' when unusable.
+ */
+function normalizeBrandId(input) {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+
+  const raw = input.trim().toLowerCase();
+
+  return BRAND_ID_PATTERN.test(raw) ? raw : '';
+}
+
+/**
+ * True when the value is a usable http(s) URL.
+ */
+function isHttpUrl(input) {
+  if (!input || typeof input !== 'string') {
+    return false;
+  }
+
+  try {
+    const url = new URL(input);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Resolve a vert's weight — required by spec, default 1. Anything
+ * non-numeric or non-positive falls back to 1.
+ */
+function getWeight(vert) {
+  const weight = Number(vert?.weight);
+
+  return Number.isFinite(weight) && weight > 0
+    ? weight
+    : 1;
+}
+
+/**
+ * Flatten a vert's targeting object (sites + categories + keywords) into
+ * one normalized lowercase tag list.
+ */
+function getVertTags(vert) {
+  const targeting = vert?.targeting || {};
+  const tags = []
+    .concat(targeting.sites || [])
+    .concat(targeting.categories || [])
+    .concat(targeting.keywords || []);
+
+  return tags
+    .map((tag) => `${tag}`.trim().toLowerCase())
+    .filter((tag) => tag);
+}
+
+/**
+ * Parse a request's comma-separated tags string into a normalized list.
+ */
+function parseTags(input) {
+  return `${input || ''}`
+    .split(',')
+    .map((tag) => tag.trim().toLowerCase())
+    .filter((tag) => tag);
+}
+
+/**
+ * Eligibility: enabled + whitelist/blacklist vs the parent host + never
+ * advertise a vert whose link host IS the parent host (never-self).
+ */
+function isEligible(vert, parentHost) {
+  // Disabled verts never serve
+  if (vert?.enabled === false) {
+    return false;
+  }
+
+  const whitelist = (vert?.whitelist || []).map(normalizeHost).filter((host) => host);
+  const blacklist = (vert?.blacklist || []).map(normalizeHost).filter((host) => host);
+
+  // Whitelisted verts only serve on their listed hosts (unknown parent fails closed)
+  if (whitelist.length && !whitelist.includes(parentHost)) {
+    return false;
+  }
+
+  // Blacklisted hosts never receive the vert
+  if (parentHost && blacklist.includes(parentHost)) {
+    return false;
+  }
+
+  // Never advertise a site to itself
+  if (parentHost && normalizeHost(vert?.link) === parentHost) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Filter an inventory down to the verts eligible for a parent host.
+ */
+function filterEligible(verts, parentHost) {
+  return (verts || []).filter((vert) => isEligible(vert, parentHost));
+}
+
+/**
+ * Contextual match score: the count of overlapping tags between the vert's
+ * targeting and the request's tags. No tags on either side = 0 (neutral —
+ * pure weighted shuffle, the legacy behavior).
+ */
+function scoreVert(vert, tags) {
+  const vertTags = getVertTags(vert);
+
+  if (!vertTags.length || !tags?.length) {
+    return 0;
+  }
+
+  return tags.filter((tag) => vertTags.includes(tag)).length;
+}
+
+/**
+ * Weighted random pick from a list of verts (weight, default 1).
+ */
+function weightedPick(verts, random) {
+  if (!verts?.length) {
+    return null;
+  }
+
+  const roll = (random || Math.random)();
+  const total = verts.reduce((sum, vert) => sum + getWeight(vert), 0);
+
+  let cursor = roll * total;
+
+  for (const vert of verts) {
+    cursor -= getWeight(vert);
+
+    if (cursor < 0) {
+      return vert;
+    }
+  }
+
+  return verts[verts.length - 1];
+}
+
+/**
+ * Full selection pipeline: eligibility → vertId pin → contextual match
+ * score → weighted random among the top scorers. Returns null on no fill.
+ */
+function selectVert(verts, options) {
+  options = options || {};
+
+  const eligible = filterEligible(verts, options.parentHost || '');
+
+  if (!eligible.length) {
+    return null;
+  }
+
+  // Optional pin — serve the requested vert when it is eligible
+  if (options.vertId) {
+    const pinned = eligible.find((vert) => vert.id === options.vertId);
+
+    if (pinned) {
+      return pinned;
+    }
+  }
+
+  // Score contextually and keep only the top scorers
+  const tags = options.tags || [];
+  const scored = eligible.map((vert) => ({ vert, score: scoreVert(vert, tags) }));
+  const topScore = Math.max(...scored.map((entry) => entry.score));
+  const top = scored.filter((entry) => entry.score === topScore).map((entry) => entry.vert);
+
+  return weightedPick(top, options.random);
+}
+
+/**
+ * Read the enabled verts inventory, cached in function memory (~5 min TTL —
+ * one Firestore read per instance per interval, not per impression).
+ *
+ * Under the emulator (FIRESTORE_EMULATOR_HOST) the default TTL is 0 so dev
+ * and route round-trip tests always see freshly seeded docs; cache-behavior
+ * tests pass an explicit options.ttl instead.
+ */
+async function getInventory(Manager, options) {
+  options = options || {};
+
+  const ttl = typeof options.ttl === 'number'
+    ? options.ttl
+    : process.env.FIRESTORE_EMULATOR_HOST ? 0 : CACHE_TTL;
+  const now = Date.now();
+
+  if (cache.verts && (now - cache.fetched) < ttl) {
+    return cache.verts;
+  }
+
+  const { admin } = Manager.libraries;
+  const db = admin.firestore();
+  const verts = [];
+
+  try {
+    // Batch-read the collection (~500 cursor pagination per docs/firestore.md)
+    let lastDoc = null;
+
+    while (true) {
+      let query = db.collection('verts').limit(BATCH_SIZE);
+
+      if (lastDoc) {
+        query = query.startAfter(lastDoc);
+      }
+
+      const snapshot = await query.get();
+
+      if (snapshot.empty) {
+        break;
+      }
+
+      for (const doc of snapshot.docs) {
+        verts.push({ id: doc.id, ...doc.data() });
+      }
+
+      lastDoc = snapshot.docs[snapshot.docs.length - 1];
+    }
+  } catch (e) {
+    // A transient Firestore error must not 500 the public serve route — fall back
+    // to the last-good inventory (stale beats down), or [] (→ 204 no-fill). Leave
+    // cache.fetched alone so the next impression retries instead of re-caching failure.
+    console.error(`[@omega.js/backend:verts:utils] getInventory failed (${e.message}) — serving ${cache.verts ? 'last-good cache' : 'no-fill'}`);
+    return cache.verts || [];
+  }
+
+  cache.verts = verts.filter((vert) => vert.enabled !== false);
+  cache.fetched = now;
+
+  return cache.verts;
+}
+
+/**
+ * Reset the inventory cache (called by the admin CRUD writes so the same
+ * instance serves fresh inventory immediately; also the test seam).
+ */
+function resetInventoryCache() {
+  cache.verts = null;
+  cache.fetched = 0;
+}
+
+/**
+ * Look up a single vert by id — cache first, direct doc read on miss (a
+ * freshly created or disabled vert must still resolve its OWN stored link).
+ */
+async function getVertById(Manager, id, options) {
+  if (!id) {
+    return null;
+  }
+
+  const inventory = await getInventory(Manager, options);
+  const cached = inventory.find((vert) => vert.id === id);
+
+  if (cached) {
+    return cached;
+  }
+
+  const { admin } = Manager.libraries;
+  const doc = await admin.firestore().doc(`verts/${id}`).get();
+
+  if (!doc.exists) {
+    return null;
+  }
+
+  return { id: doc.id, ...doc.data() };
+}
+
+/**
+ * Render the self-contained vert unit page.
+ *
+ * The document itself comes from the ONE renderer in @omega.js/client
+ * (`modules/vert-document.js`) — the same function the client's terminal
+ * promo lane calls, so a served vert and the built-in promo are the same
+ * markup, css, and script contract. This function only maps the stored vert
+ * shape onto the renderer's options; no template lives here.
+ *
+ * Node >=22 (the declared engines floor and the pinned Functions runtime)
+ * loads the client's ESM module through require() directly.
+ */
+async function renderVertUnit(options) {
+  const { renderVertDocument } = require('@omega.js/client/modules/vert-document.js');
+  const vert = options.vert || {};
+
+  return renderVertDocument({
+    id: vert.id || '',
+    href: options.redirectUrl,
+    title: vert.title,
+    description: vert.description,
+    button: vert.button,
+    // The stored footer is the unit's muted label ('Sponsored by X'); the
+    // renderer falls back to a plain 'Sponsored' when a vert carries none
+    label: vert.footer,
+    imageUrl: isHttpUrl(vert.image) ? vert.image : '',
+    theme: options.theme,
+    width: options.width,
+    height: options.height,
+    // Origin-checked postMessage: when the parent origin is known (computed by
+    // the serve route via normalizeOrigin — port-preserving), messages only
+    // ever go to that origin.
+    targetOrigin: options.parentOrigin || '*',
+  });
+}
+
+/**
+ * Build a vert's click destination: its stored link tagged with the vert UTM
+ * set. The tagging itself lives in the ONE helper both lanes share
+ * (@omega.js/client's `modules/vert-document.js` — the client's promo lane
+ * tags its own link with the same function), so existing params on an
+ * advertiser's URL win here exactly as they do there.
+ *
+ * Node >=22 (the declared engines floor and the pinned Functions runtime)
+ * loads the client's ESM module through require() directly.
+ *
+ * utm_source is the HOST brand's own id (the `brand` param the client sends
+ * with the impression and the serve route stamps on this redirect URL), with
+ * the parent host as the fallback when no id came along.
+ *
+ * @param {object} vert - the stored vert ({ id, link })
+ * @param {string} [parentHost] - the referring host (utm_source fallback)
+ * @param {string} [brandId] - the host brand's id (utm_source)
+ * @returns {string} the tagged destination URL
+ */
+function buildClickDestination(vert, parentHost, brandId) {
+  const { applyVertUtm, UTM_MEDIUM } = require('@omega.js/client/modules/vert-document.js');
+
+  return applyVertUtm(vert.link, {
+    source: brandId || parentHost,
+    medium: UTM_MEDIUM,
+    campaign: vert.id,
+  });
+}
+
+module.exports = {
+  CACHE_TTL,
+  normalizeHost,
+  normalizeOrigin,
+  normalizeBrandId,
+  isHttpUrl,
+  getWeight,
+  getVertTags,
+  parseTags,
+  isEligible,
+  filterEligible,
+  scoreVert,
+  weightedPick,
+  selectVert,
+  getInventory,
+  resetInventoryCache,
+  getVertById,
+  renderVertUnit,
+  buildClickDestination,
+};

package/dist/manager/schemas/admin/backup/post.js

@@ -0,0 +1,8 @@
+/**
+ * Schema for POST /admin/backup
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  deletionRegex: f.string({ default: undefined }),
+});

package/dist/manager/schemas/admin/cron/post.js

@@ -0,0 +1,8 @@
+/**
+ * Schema for POST /admin/cron
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  id: f.string({ default: undefined, required: true }),
+});

package/dist/manager/schemas/admin/database/get.js

@@ -0,0 +1,5 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+});

package/dist/manager/schemas/admin/database/post.js

@@ -0,0 +1,6 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+  document: f.multi(['object', 'string', 'number', 'boolean', 'array'], { default: {}, required: false }),
+});

package/dist/manager/schemas/admin/email/post.js

@@ -0,0 +1,31 @@
+/**
+ * Schema for POST /admin/email
+ *
+ * Recipients (to, cc, bcc) accept flexible formats:
+ * - Email string: "user@example.com"
+ * - UID string (no @): "abc123" — auto-fetches user doc from Firestore
+ * - Email object: { email: "user@example.com", name: "John" }
+ * - Array of any of the above
+ *
+ * No raw-HTML field is declared here. `html` (the top-level override) joins
+ * `contentHtml` and `trustedContent` as internal-caller only — the schema strip is
+ * the belt, `prepare.internalOnlyFieldFault()` in the handler is the braces
+ * ([#125](https://github.com/Omega-JS-Stack/omega/issues/125)).
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  to: f.multi(['array', 'string', 'object'], { default: [] }),
+  cc: f.multi(['array', 'string', 'object'], { default: [] }),
+  bcc: f.multi(['array', 'string', 'object'], { default: [] }),
+  from: f.passthrough({ default: undefined }),
+  replyTo: f.string({ default: undefined }),
+  sender: f.string({ default: undefined }),
+  subject: f.string({ default: undefined }),
+  template: f.string({ default: 'card' }),
+  group: f.multi(['number', 'string'], { default: undefined }),
+  sendAt: f.multi(['number', 'string'], { default: undefined }),
+  data: f.passthrough({ default: {} }),
+  categories: f.array({ default: [] }),
+  copy: f.boolean({ default: undefined }),
+});

package/dist/manager/schemas/admin/firestore/get.js

@@ -0,0 +1,5 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+});

package/dist/manager/schemas/admin/firestore/post.js

@@ -0,0 +1,8 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+  document: f.passthrough({ default: {}, required: false }),
+  merge: f.boolean({ default: true, required: false }),
+  metadataTag: f.string({ default: 'admin/firestore', required: false }),
+});

package/dist/manager/schemas/admin/firestore/query/post.js

@@ -0,0 +1,5 @@
+const { fields: f } = require('../../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  queries: f.array({ default: [], required: false }),
+});

package/dist/manager/schemas/admin/hook/post.js

@@ -0,0 +1,8 @@
+/**
+ * Schema for POST /admin/hook
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+});

package/dist/manager/schemas/admin/infer-contact/post.js

@@ -0,0 +1,6 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  email: f.string({ default: '', required: false }),
+  emails: f.array({ default: [], required: false }),
+});

package/dist/manager/schemas/admin/notification/post.js

@@ -0,0 +1,23 @@
+/**
+ * Schema for POST /admin/notification
+ * (The route reads named props only and rebuilds filters explicitly, so the zod
+ * engine's clean defaults — no injected types/min/max keys — are wire-identical.)
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  notification: f.passthrough({
+    default: {
+      title: 'Notification',
+      body: 'Check this out',
+    },
+  }),
+  filters: f.passthrough({
+    default: {
+      tags: false,
+      owner: null,
+      token: null,
+      limit: null,
+    },
+  }),
+});

package/dist/manager/schemas/admin/payment/post.js

@@ -0,0 +1,8 @@
+/**
+ * Schema for POST /admin/payment
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  payload: f.passthrough({ default: {} }),
+});

package/dist/manager/schemas/admin/post/post.js

@@ -0,0 +1,23 @@
+/**
+ * Schema for POST /admin/post (create)
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  title: f.string({ default: undefined, required: true }),
+  url: f.string({ default: undefined, required: true }),
+  description: f.string({ default: undefined, required: true }),
+  headerImageURL: f.string({ default: undefined, required: true }),
+  body: f.string({ default: undefined, required: true }),
+  author: f.string({ default: undefined }),
+  affiliate: f.string({ default: '' }),
+  tags: f.array({ default: [] }),
+  categories: f.array({ default: [] }),
+  layout: f.string({ default: 'blueprint/blog/post' }),
+  date: f.string({ default: undefined }),
+  id: f.number({ default: undefined }),
+  postPath: f.string({ default: 'guest' }),
+  source: f.string({ default: null }),
+  // D13: content-publish implies deploy — false opts out of the build dispatch
+  deploy: f.boolean({ default: true, required: false }),
+});

package/dist/manager/schemas/admin/post/put.js

@@ -0,0 +1,13 @@
+/**
+ * Schema for PUT /admin/post (edit)
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  url: f.string({ default: undefined, required: true }),
+  body: f.string({ default: undefined, required: true }),
+  title: f.string({ default: undefined }),
+  postPath: f.string({ default: 'guest' }),
+  // D13: content-publish implies deploy — false opts out of the build dispatch
+  deploy: f.boolean({ default: true, required: false }),
+});

package/dist/manager/schemas/admin/repo/content/post.js

@@ -0,0 +1,10 @@
+/**
+ * Schema for POST /admin/repo/content
+ */
+const { fields: f } = require('../../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  path: f.string({ default: undefined, required: true }),
+  content: f.string({ default: undefined, required: true }),
+  type: f.string({ default: 'text' }),
+});

package/dist/manager/schemas/admin/stats/get.js

@@ -0,0 +1,5 @@
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  update: f.multi(['boolean', 'object'], { default: false, required: false }),
+});

package/dist/manager/schemas/admin/users/disable/post.js

@@ -0,0 +1,9 @@
+/**
+ * Schema for POST /admin/users/disable
+ */
+const { fields: f } = require('../../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  uid: f.string({ required: true }),
+  disabled: f.boolean({ default: true, required: false }),
+});

package/dist/manager/schemas/admin/users/list/get.js

@@ -0,0 +1,10 @@
+/**
+ * Schema for GET /admin/users/list
+ */
+const { fields: f } = require('../../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  limit: f.number({ default: 20, required: false }),
+  search: f.string({ default: '', required: false }),
+  startAfter: f.string({ default: '', required: false }),
+});

package/dist/manager/schemas/admin/users/sync/post.js

@@ -0,0 +1,7 @@
+/**
+ * Schema for POST /admin/users/sync
+ */
+const { fields: f } = require('../../../../helpers/schema-zod.js');
+
+// No specific parameters required, uses stored pageToken
+module.exports = () => f.object({});

package/dist/manager/schemas/brand/get.js

@@ -0,0 +1,3 @@
+const { fields: f } = require('../../helpers/schema-zod.js');
+
+module.exports = () => f.object({});

package/dist/manager/schemas/content/post/get.js

@@ -0,0 +1,8 @@
+/**
+ * Schema for GET /content/post
+ */
+const { fields: f } = require('../../../helpers/schema-zod.js');
+
+module.exports = () => f.object({
+  url: f.string({ default: undefined, required: true }),
+});