@omega.js/manager 0.1.0

package/dist/services/forms/index.js

@@ -0,0 +1,138 @@
+/**
+ * Forms service (`forms.providers.slapform`) — the brand's contact form on
+ * Slapform (slapform.com): keeps the form's settings in sync and sets the
+ * form-owner account to the configured plan (Slapform's top tier by default)
+ * so the brand has full access. Forms live in Slapform's own Firestore, so this service is for
+ * the Slapform operator: it needs a service account for Slapform's Firebase
+ * project.
+ *
+ * Auth tiers (2b, Ian 2026-07-13):
+ *   1. Operator SA — SLAPFORM_SERVICE_ACCOUNT in the brand .env (path to
+ *      the service-account JSON, absolute or brand-root-relative). Full
+ *      create + manage: a missing formId with `forms.providers.slapform.templateFormId`
+ *      configured (the company layer's shape donor) MINTS the brand's own
+ *      form — product user (email = brand contact email, password via the
+ *      account service's owner channels) + doc shape-templated from the
+ *      donor — and writes the new id back into omega.json5. The ensures
+ *      then converge name/settings/plan in the same run.
+ *   2. User API key — SLAPFORM_API_KEY (the product accepts
+ *      user.api.privateKey): recognized, management via the product's
+ *      public API lands when those routes are verified.
+ *   3. Dashboard — interactive runs offer the setup flow (open
+ *      slapform.com, paste the form id back — comment-preserving
+ *      writeback, with a Disable option that sets `slapform: false`).
+ *      Non-interactive and dry runs skip cleanly.
+ */
+const chalk = require('chalk').default;
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+const { createAuthAdmin } = require('../../lib/auth-admin.js');
+const { resolveConfigValue, landValue } = require('../../lib/config-flow.js');
+const { createProductAsset } = require('../../lib/product-create.js');
+const { createPasswordResolver } = require('../account/lib/resolve-password.js');
+
+const SLAPFORM_URL = 'https://slapform.com';
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.forms?.providers?.slapform;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'forms.providers.slapform.enabled = false' };
+    }
+
+    // Shared form: another brand owns its branding (the chatsy/replyify
+    // updateAgentInfo pattern) — never rename or re-enable it from here
+    if (config?.updateFormInfo === false) {
+      return { skip: true, reason: 'form managed by another brand (forms.providers.slapform.updateFormInfo = false)' };
+    }
+
+    // The contact form lives on the brand's website
+    if (!context.brandConfig.targets?.web) {
+      return { skip: true, reason: 'no web target' };
+    }
+
+    // Operator credentials first — create-on-missing needs them before the
+    // id resolution. Tests inject fakes via context.slapformDb/-AuthAdmin.
+    let db = context.slapformDb;
+    let authAdmin = context.slapformAuthAdmin;
+    if (!db) {
+      const envPath = process.env.SLAPFORM_SERVICE_ACCOUNT;
+      if (envPath) {
+        const serviceAccount = loadServiceAccount(envPath, context.brandRoot);
+        db = new FirestoreREST(serviceAccount);
+        authAdmin = createAuthAdmin(serviceAccount);
+      }
+    }
+
+    const brand = context.brandConfig.brand || {};
+    const dryRun = context.options?.dryRun || false;
+    let formId = config?.formId;
+
+    // 2b create-on-missing: operator SA + a template donor → a missing form
+    // means MINT the brand's own (product user + doc), write the id back,
+    // and let the ensures below converge it in this same run.
+    if (!formId && db && authAdmin && config?.templateFormId && brand.contact?.email) {
+      const created = await createProductAsset({
+        db,
+        authAdmin,
+        collection: 'forms',
+        templateId: config.templateFormId,
+        email: brand.contact.email,
+        resolvePassword: createPasswordResolver({
+          brandRoot: context.brandRoot,
+          domain: new URL(brand.url || 'https://invalid.test').hostname,
+          brand,
+          dryRun,
+        }),
+        dryRun,
+        log: (line) => console.log(`      ${line}`),
+      });
+
+      if (!created) {
+        return { skip: true, reason: 'dry run — form creation planned (from forms.providers.slapform.templateFormId)' };
+      }
+
+      landValue(context, 'forms.providers.slapform.formId', created.id);
+      console.log(`      ${chalk.green('✓')} forms.providers.slapform.formId = ${chalk.cyan(created.id)} written to omega.json5`);
+      formId = created.id;
+    }
+
+    if (!formId) {
+      formId = await resolveConfigValue(context, {
+        path: 'forms.providers.slapform.formId',
+        label: 'Slapform contact form',
+        instructions: [
+          `1. Create an account at ${chalk.cyan(SLAPFORM_URL)} (if you haven't already)`,
+          `2. Create a contact form for ${chalk.cyan(brand.name || context.brandId)}`,
+        ],
+        entry: { url: SLAPFORM_URL, message: 'Slapform form ID:' },
+        disablePath: 'forms.providers.slapform',
+      });
+    }
+    if (!formId) {
+      return { skip: true, reason: 'no forms.providers.slapform.formId configured — set forms.providers.slapform.templateFormId + the operator SA to mint one automatically, create one at https://slapform.com (paste back interactively), or set it in omega.json5' };
+    }
+
+    if (!db) {
+      if (process.env.SLAPFORM_API_KEY) {
+        return {
+          skip: true,
+          reason: 'SLAPFORM_API_KEY recognized, but product-API management is not wired yet — use the operator SA (SLAPFORM_SERVICE_ACCOUNT) or the dashboard',
+        };
+      }
+
+      // The shared setup contract (#608): the operator SA is asked for right
+      // here — most brands are not the Slapform operator and answer Disable,
+      // which retires the ask for good.
+      const gate = await requestServiceInput(context, serviceInputSpec('forms'));
+      if (gate) return gate;
+      db = new FirestoreREST(loadServiceAccount(process.env.SLAPFORM_SERVICE_ACCOUNT, context.brandRoot));
+    }
+
+    return { db, formId };
+  },
+});

package/dist/services/migrations/ensure/notifications.js

@@ -0,0 +1,189 @@
+/**
+ * Notifications collection migration — converges push-subscription docs to
+ * the canonical @omega.js/backend + @omega.js/client shape.
+ *
+ * Fixes:
+ * - Renames `uid` field to `owner` and deletes `uid`
+ * - Flattens `owner.uid` (object) to `owner` (string)
+ * - Moves legacy created/updated → metadata.created/metadata.updated
+ * - Moves `url` to `context.client.url` and builds the full context structure
+ * - Folds the legacy `attribution.utm` blob into `attribution.first`/`last`
+ * - Adds empty `attribution` when missing
+ * - Trims whitespace on all string values
+ *
+ * Validates:
+ * - All fields match the expected schema
+ */
+const { runMigration, FieldValue } = require('../lib/migration-runner.js');
+const { createMetadataFix } = require('../lib/ensure-metadata.js');
+const { validateDocument } = require('../lib/schema-validator.js');
+const { createSanitizeFix } = require('../lib/sanitize-strings.js');
+const { createAttributionFoldFix } = require('../lib/attribution-touch.js');
+
+/**
+ * Default context structure from @omega.js/client's getContext()
+ */
+const DEFAULT_CONTEXT = {
+  client: {
+    language: null,
+    mobile: null,
+    device: null,
+    platform: null,
+    browser: null,
+    vendor: null,
+    runtime: null,
+    userAgent: null,
+    url: null,
+  },
+};
+
+/**
+ * Notifications collection schema
+ * Based on @omega.js/client's notifications _saveSubscription()
+ */
+const schema = {
+  token: { type: 'string', required: true },
+  owner: { type: 'string', required: true, nullable: true },
+  tags: { type: 'array', required: true, itemType: 'string' },
+  attribution: { type: 'object', required: true },
+  metadata: {
+    type: 'object',
+    required: true,
+    properties: {
+      created: {
+        type: 'object',
+        required: true,
+        properties: {
+          timestamp: { type: 'string', required: true },
+          timestampUNIX: { type: 'number', required: true },
+        },
+      },
+      updated: {
+        type: 'object',
+        required: true,
+        properties: {
+          timestamp: { type: 'string', required: true },
+          timestampUNIX: { type: 'number', required: true },
+        },
+      },
+    },
+  },
+  context: {
+    type: 'object',
+    required: true,
+    properties: {
+      client: {
+        type: 'object',
+        required: true,
+        properties: {
+          language: { type: 'string', required: true, nullable: true },
+          mobile: { type: 'boolean', required: true, nullable: true },
+          device: { type: 'string', required: true, nullable: true },
+          platform: { type: 'string', required: true, nullable: true },
+          browser: { type: 'string', required: true, nullable: true },
+          vendor: { type: 'string', required: true, nullable: true },
+          runtime: { type: 'string', required: true, nullable: true },
+          userAgent: { type: 'string', required: true, nullable: true },
+          url: { type: 'string', required: true, nullable: true },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Notifications collection migration handler.
+ *
+ * @param {Object} context - Handler context
+ * @returns {Object} Migration results
+ */
+module.exports = async function ensureNotifications(context) {
+  return runMigration(context, {
+    collection: 'notifications',
+
+    fixes: [
+      // Fix: uid → owner (rename + delete uid)
+      (data) => {
+        if (data.uid === undefined) {
+          return null;
+        }
+        const updates = { uid: FieldValue.delete() };
+        if (data.owner === undefined) {
+          updates.owner = data.uid;
+        }
+        return updates;
+      },
+
+      // Fix: owner.uid (object) → owner (string)
+      (data) => {
+        if (typeof data.owner !== 'object' || data.owner?.uid === undefined) {
+          return null;
+        }
+        return { owner: data.owner.uid };
+      },
+
+      // Fix: Move created/updated → metadata.created/metadata.updated
+      // Falls back to the document's server createTime/updateTime if missing
+      createMetadataFix({
+        legacyCreatedFields: ['created'],
+        legacyUpdatedFields: ['updated'],
+      }),
+
+      // Fix: build full context structure with all fields
+      (data) => {
+        const existing = data.context || {};
+        const existingClient = existing.client || {};
+
+        // Merge existing values over defaults
+        const mergedClient = { ...DEFAULT_CONTEXT.client, ...existingClient };
+
+        // If old url field exists, use it as context.client.url
+        if (data.url && !existingClient.url) {
+          mergedClient.url = data.url;
+        }
+
+        const merged = { client: mergedClient };
+
+        // Check if anything changed
+        const isComplete = data.context
+          && JSON.stringify(data.context) === JSON.stringify(merged)
+          && !data.url;
+
+        if (isComplete) {
+          return null;
+        }
+
+        const updates = { context: merged };
+        if (data.url) {
+          updates.url = FieldValue.delete();
+        }
+        return updates;
+      },
+
+      // Fix: fold the legacy attribution.utm blob → attribution.first/last.
+      // A subscription copies the client's stored attribution verbatim
+      // (@omega.js/client notifications _saveSubscription), so docs written
+      // before #384 carry the same blob users and payments do. Placed before
+      // the attribution backfill to match every other surface; unlike users
+      // (whose DEFAULT_USER husks make the order load-bearing) the backfill
+      // here only fires when attribution is absent, so the order is inert.
+      createAttributionFoldFix(),
+
+      // Fix: add empty attribution when missing
+      (data) => {
+        if (data.attribution !== undefined) {
+          return null;
+        }
+        return { attribution: {} };
+      },
+
+      // Fix: trim whitespace on all string values
+      createSanitizeFix(),
+    ],
+
+    // Validate against schema
+    validate: (data) => {
+      return validateDocument(data, schema);
+    },
+  });
+};

package/dist/services/migrations/ensure/orders.js

@@ -0,0 +1,34 @@
+/**
+ * Orders collection migration — converges `payments-orders` documents to the
+ * current attribution shape.
+ *
+ * An order copies the checkout context off its payments-intents doc verbatim,
+ * so orders written before #384 still carry the legacy `attribution.utm` blob
+ * and resolve to no campaign data at all on a server conversion send.
+ *
+ * Fixes:
+ * - Folds legacy `attribution.utm` → `attribution.first` + `attribution.last`
+ *
+ * No schema validation: an order's shape is owned by the payments webhook
+ * pipeline (provider payloads, refunds, discounts) — this migration touches
+ * attribution only and has no business declaring the rest.
+ */
+const { runMigration } = require('../lib/migration-runner.js');
+const { createAttributionFoldFix } = require('../lib/attribution-touch.js');
+
+/**
+ * Orders collection migration handler.
+ *
+ * @param {Object} context - Handler context
+ * @returns {Object} Migration results
+ */
+module.exports = async function ensureOrders(context) {
+  return runMigration(context, {
+    collection: 'payments-orders',
+
+    fixes: [
+      // Fix: legacy attribution blob → first/last touches
+      createAttributionFoldFix(),
+    ],
+  });
+};

package/dist/services/migrations/ensure/payment-provider.js

@@ -0,0 +1,132 @@
+/**
+ * Payment-provider rename migration ([#428](https://github.com/Omega-JS-Stack/omega/issues/428))
+ * — the DATA half of the word change. #425 renamed the config block
+ * (`payment.processors` → `payment.providers`) and #428 finished the job: the
+ * singular word is `provider` in code, on the API, and on every document the
+ * payment pipeline writes. Documents written BEFORE the cutover still carry
+ * the old key, and nothing dual-reads it, so this sweep moves them.
+ *
+ * Five collections carry the field, each at its own path:
+ * - `users`             — `subscription.payment.processor`
+ * - `payments-orders`   — `processor`
+ * - `payments-intents`  — `processor`
+ * - `payments-webhooks` — `processor`
+ * - `payments-disputes` — `alert.processor`
+ *
+ * Idempotent by construction: a document with no legacy key is a strict no-op,
+ * and one that somehow carries BOTH keeps `provider` (written by the current
+ * code, so it is the newer of the two) and drops only the leftover. A null
+ * value still moves — `null` is what the schema stores for an account that
+ * never paid, and leaving the retired key behind is the thing this exists to
+ * stop.
+ *
+ * No schema validation: the payment collections' shapes are owned by the
+ * webhook pipeline, and this migration touches ONE field.
+ *
+ * Like every migration, a run is an AUDIT until `--execute`:
+ *   npx omega manage --migration=payment-provider            # counts, writes nothing
+ *   npx omega manage --migration=payment-provider --execute  # performs it
+ */
+const { runMigration, FieldValue } = require('../lib/migration-runner.js');
+
+// Every collection the payment pipeline stamps the provider onto, with the
+// path the field sits at in that collection's documents.
+const TARGETS = [
+  { collection: 'users', legacy: 'subscription.payment.processor', current: 'subscription.payment.provider' },
+  { collection: 'payments-orders', legacy: 'processor', current: 'provider' },
+  { collection: 'payments-intents', legacy: 'processor', current: 'provider' },
+  { collection: 'payments-webhooks', legacy: 'processor', current: 'provider' },
+  { collection: 'payments-disputes', legacy: 'alert.processor', current: 'alert.provider' },
+];
+
+/**
+ * Read a dot-notation path off a document, distinguishing "absent" from a
+ * stored null.
+ *
+ * @param {Object} data - The document object
+ * @param {string} path - Dot-notation field path
+ * @returns {*} The value, or undefined when any segment is missing
+ */
+function readPath(data, path) {
+  let target = data;
+
+  for (const part of path.split('.')) {
+    if (target === null || typeof target !== 'object' || !(part in target)) {
+      return undefined;
+    }
+    target = target[part];
+  }
+
+  return target;
+}
+
+/**
+ * Create the rename fix for one collection's field path.
+ *
+ * @param {string} legacy - The retired dot-notation path (`…processor`)
+ * @param {string} current - The path it moves to (`…provider`)
+ * @returns {Function} Fix function for runMigration: (data) => updates or null
+ */
+function createProviderRenameFix(legacy, current) {
+  return (data) => {
+    const legacyValue = readPath(data, legacy);
+    if (legacyValue === undefined) {
+      return null;
+    }
+
+    // Already renamed (by the current code, or by an earlier run) — the new
+    // field is the newer of the two, so only the leftover goes.
+    if (readPath(data, current) !== undefined) {
+      return { [legacy]: FieldValue.delete() };
+    }
+
+    return {
+      [current]: legacyValue,
+      [legacy]: FieldValue.delete(),
+    };
+  };
+}
+
+/**
+ * Payment-provider rename migration handler.
+ *
+ * @param {Object} context - Handler context
+ * @returns {Object} Migration results, one stats block per collection
+ */
+module.exports = async function ensurePaymentProvider(context) {
+  const output = {};
+  let status;
+  const warnings = [];
+
+  for (const target of TARGETS) {
+    const result = await runMigration(context, {
+      collection: target.collection,
+      fixes: [createProviderRenameFix(target.legacy, target.current)],
+    });
+
+    // Namespaced: three of these collections are ALSO migrated by another
+    // handler in the same walk, and the service runner merges every
+    // operation's output into one flat map — a bare `users` key would
+    // silently overwrite the users migration's stats.
+    for (const [collection, stats] of Object.entries(result.output || {})) {
+      output[`payment-provider:${collection}`] = stats;
+    }
+
+    // A REST failure is credentials or permissions, which every remaining
+    // collection would hit identically — stop and report rather than five
+    // copies of the same error.
+    if (result.status === 'error') {
+      return { ...result, output };
+    }
+
+    if (result.status === 'warned') {
+      status = 'warned';
+      warnings.push(`${target.collection}: ${result.reason}`);
+    }
+  }
+
+  return status ? { output, status, reason: warnings.join('; ') } : { output };
+};
+
+module.exports.TARGETS = TARGETS;
+module.exports.createProviderRenameFix = createProviderRenameFix;

package/dist/services/migrations/ensure/payments-intents.js

@@ -0,0 +1,34 @@
+/**
+ * Payments-intents collection migration — converges `payments-intents`
+ * documents to the current attribution shape.
+ *
+ * The intent is where the browser's attribution lands at checkout (the
+ * webhook reads it back onto the order), so intents written before #384 hold
+ * the legacy `attribution.utm` blob and are the upstream copy of the same
+ * degradation the orders migration cures.
+ *
+ * Fixes:
+ * - Folds legacy `attribution.utm` → `attribution.first` + `attribution.last`
+ *
+ * No schema validation: the intent's shape is owned by the payments intent
+ * route — this migration touches attribution only.
+ */
+const { runMigration } = require('../lib/migration-runner.js');
+const { createAttributionFoldFix } = require('../lib/attribution-touch.js');
+
+/**
+ * Payments-intents collection migration handler.
+ *
+ * @param {Object} context - Handler context
+ * @returns {Object} Migration results
+ */
+module.exports = async function ensurePaymentsIntents(context) {
+  return runMigration(context, {
+    collection: 'payments-intents',
+
+    fixes: [
+      // Fix: legacy attribution blob → first/last touches
+      createAttributionFoldFix(),
+    ],
+  });
+};