@omega.js/backend 0.1.0

package/dist/manager/libraries/notification.js

@@ -0,0 +1,256 @@
+/**
+ * Push notification library — send FCM notifications to subscribers
+ *
+ * Usage:
+ *   const notification = require('./libraries/notification.js');
+ *   await notification.send(ctx, { title, body, icon, clickAction, filters });
+ *
+ * Used by:
+ * - POST /admin/notification route
+ * - marketing-campaigns cron job (type: 'push')
+ */
+const PATH_NOTIFICATIONS = 'notifications';
+const BAD_TOKEN_REASONS = [
+  'messaging/invalid-registration-token',
+  'messaging/registration-token-not-registered',
+];
+const BATCH_SIZE = 500;
+
+/**
+ * Send push notification to FCM subscribers.
+ *
+ * @param {object} ctx - @omega.js/backend ctx instance
+ * @param {object} options
+ * @param {string} options.title - Notification title
+ * @param {string} options.body - Notification body
+ * @param {string} [options.icon] - Notification icon URL (defaults to brand.images.brandmark)
+ * @param {string} [options.clickAction] - URL to open on click (defaults to brand.url)
+ * @param {object} [options.filters] - Targeting filters
+ * @param {Array<string>} [options.filters.tags] - Filter by tags
+ * @param {string} [options.filters.owner] - Filter by owner UID
+ * @param {string} [options.filters.token] - Send to specific token
+ * @param {number} [options.filters.limit] - Max tokens to send to
+ * @returns {{ subscribers: number, batches: number, sent: number, deleted: number }}
+ */
+async function send(ctx, options) {
+  const { title, body, icon, clickAction, filters } = options;
+
+  if (!title || !body) {
+    throw new Error('Notification title and body are required');
+  }
+
+  const notification = buildPayload(ctx.Manager.config?.brand, { title, body, icon, clickAction });
+
+  ctx.log('notification.send():', notification);
+
+  const response = { subscribers: 0, batches: 0, sent: 0, deleted: 0 };
+  const filterOptions = {
+    tags: filters?.tags || false,
+    owner: filters?.owner || null,
+    token: filters?.token || null,
+    limit: filters?.limit || null,
+  };
+
+  await processTokens(ctx, notification, filterOptions, response);
+
+  return response;
+}
+
+/**
+ * Build the FCM payload from the caller's options and the brand's OWN config.
+ *
+ * A push notification lands on a user's lock screen wearing whoever's icon and
+ * link it carries, so there is no framework fallback for either. The icon comes
+ * from `brand.images.brandmark` and is OMITTED when unconfigured (a text-only
+ * notification, never another company's mark); the click target comes from
+ * `brand.url` and fails LOUDLY when unconfigured, because a push with nowhere
+ * to go is not worth sending anywhere else.
+ *
+ * @param {object} brand - Resolved brand config object
+ * @param {object} options
+ * @param {string} options.title
+ * @param {string} options.body
+ * @param {string} [options.icon] - Explicit icon URL (wins over config)
+ * @param {string} [options.clickAction] - Explicit click target (wins over config)
+ * @returns {{ title: string, body: string, imageUrl?: string, click_action: string }}
+ * @throws {Error} When no click target is configured, or it is not a valid URL
+ */
+function buildPayload(brand, { title, body, icon, clickAction }) {
+  const imageUrl = icon || brand?.images?.brandmark;
+  const clickTarget = clickAction || brand?.url;
+
+  if (!clickTarget) {
+    // Coded 400 like the email library's config-hole throws — a code-less Error
+    // would respond as a 500 and capture to Sentry for what is a brand-config fault.
+    const err = new Error('Missing brand.url in config/omega.json5 — required to send a push notification (or pass clickAction)');
+    err.code = 400;
+    throw err;
+  }
+
+  const notification = { title, body, click_action: clickTarget };
+
+  if (imageUrl) {
+    notification.imageUrl = imageUrl;
+  }
+
+  // Add cache buster to click_action URL
+  try {
+    const url = new URL(notification.click_action);
+    url.searchParams.set('cb', new Date().getTime());
+    notification.click_action = url.toString();
+  } catch (e) {
+    throw new Error(`Invalid click_action URL: ${e.message}`);
+  }
+
+  return notification;
+}
+
+async function processTokens(ctx, notification, options, response) {
+  const Manager = ctx.Manager;
+
+  // Specific token — send directly
+  if (options.token) {
+    ctx.log(`Sending to specific token: ${options.token}`);
+
+    try {
+      await sendBatch(ctx, [options.token], 0, notification, response);
+    } catch (e) {
+      ctx.error('Error sending to specific token', e);
+    }
+
+    return;
+  }
+
+  // Build query conditions
+  const queryConditions = [];
+
+  if (options.tags) {
+    queryConditions.push({ field: 'tags', operator: 'array-contains-any', value: options.tags });
+  }
+  if (options.owner) {
+    queryConditions.push({ field: 'owner', operator: '==', value: options.owner });
+  }
+
+  const maxBatches = options.limit
+    ? Math.ceil(options.limit / BATCH_SIZE)
+    : Infinity;
+
+  ctx.log('Processing tokens with filters:', {
+    tags: options.tags,
+    owner: options.owner,
+    limit: options.limit,
+    maxBatches,
+  });
+
+  let tokensProcessed = 0;
+
+  await Manager.Utilities().iterateCollection(
+    async (batch, index) => {
+      const batchTokens = [];
+
+      for (const doc of batch.docs) {
+        if (options.limit && tokensProcessed >= options.limit) {
+          break;
+        }
+
+        const data = doc.data();
+        batchTokens.push(data.token);
+        tokensProcessed++;
+      }
+
+      if (batchTokens.length === 0) {
+        return;
+      }
+
+      try {
+        ctx.log(`Sending batch ${index} with ${batchTokens.length} tokens.`);
+        await sendBatch(ctx, batchTokens, index, notification, response);
+      } catch (e) {
+        ctx.error(`Error sending batch ${index}`, e);
+      }
+    },
+    {
+      collection: PATH_NOTIFICATIONS,
+      where: queryConditions,
+      batchSize: BATCH_SIZE,
+      maxBatches,
+      log: true,
+    }
+  ).catch(e => {
+    ctx.error(`Error during token processing: ${e}`);
+  });
+}
+
+async function sendBatch(ctx, batch, id, notification, response) {
+  const { admin } = ctx.Manager.libraries;
+
+  ctx.log(`Sending batch #${id}: tokens=${batch.length}...`);
+
+  const messages = batch.map(token => ({
+    token,
+    notification: {
+      title: notification.title,
+      body: notification.body,
+      ...(notification.imageUrl ? { imageUrl: notification.imageUrl } : {}),
+    },
+    webpush: {
+      notification: {
+        title: notification.title,
+        body: notification.body,
+        ...(notification.imageUrl ? { icon: notification.imageUrl } : {}),
+        click_action: notification.click_action,
+      },
+      data: {
+        click_action: notification.click_action,
+      },
+      fcm_options: {
+        link: notification.click_action,
+      },
+    },
+    data: {
+      click_action: notification.click_action,
+    },
+  }));
+
+  const result = await admin.messaging().sendEach(messages);
+
+  ctx.log(`Sent batch #${id}: success=${result.successCount}, failures=${result.failureCount}`);
+
+  result.responses = result.responses.map((item, index) => {
+    item.token = batch[index];
+    return item;
+  });
+
+  // Clean bad tokens
+  if (result.failureCount > 0) {
+    await cleanTokens(ctx, batch, result.responses, id, response);
+  }
+
+  response.sent += (batch.length - result.failureCount);
+  response.batches++;
+}
+
+async function cleanTokens(ctx, batch, results, id, response) {
+  const { admin } = ctx.Manager.libraries;
+
+  const cleanPromises = results
+    .map((item) => {
+      if (!item.error || !BAD_TOKEN_REASONS.includes(item?.error?.code)) {
+        return null;
+      }
+
+      return admin.firestore().doc(`${PATH_NOTIFICATIONS}/${item.token}`).delete()
+        .then(() => {
+          ctx.log(`Deleted bad token: ${item.token} (${item.error.code})`);
+          response.deleted++;
+        })
+        .catch((e) => {
+          ctx.error(`Failed to delete bad token: ${item.token}`, e);
+        });
+    })
+    .filter(Boolean);
+
+  await Promise.all(cleanPromises);
+}
+
+module.exports = { send, buildPayload };

package/dist/manager/libraries/openai.js

@@ -0,0 +1,13 @@
+/**
+ * Compatibility shim — `libraries/openai.js` was the original AI library.
+ * It has been moved to `libraries/ai/providers/openai.js` and the new unified
+ * surface is `libraries/ai/index.js`.
+ *
+ * Existing callers (`require('./libraries/openai.js')`) continue to receive the
+ * OpenAI provider class with the same constructor + prototype as before. New
+ * code should use the unified surface:
+ *
+ *   const ai = Manager.AI(ctx);
+ *   await ai.request({ provider: 'openai' | 'anthropic', ... });
+ */
+module.exports = require('./ai/providers/openai.js');

package/dist/manager/libraries/payment/discount-codes.js

@@ -0,0 +1,204 @@
+/**
+ * Discount codes — SSOT for all promo codes
+ *
+ * Each code maps to a discount definition. A code is EITHER percent-based or
+ * amount-based — the two shapes Stripe's coupons come in:
+ *   - percent: Percentage off (1-100) — Stripe's `percent_off`
+ *   - amount: Flat dollars off — Stripe's `amount_off` (which is CENTS on
+ *     Stripe's side; every builder converts)
+ *   - duration: 'once' (first payment only)
+ *   - eligible: Optional function (user) => boolean. If present, the code is only
+ *     valid for users who pass this check. Receives the raw user doc or User instance.
+ *     If omitted, the code is valid for everyone.
+ */
+const User = require('../../helpers/user.js');
+
+const DISCOUNT_CODES = {
+  // Website (displayed on pricing page, landing pages — no eligibility restrictions)
+  'WELCOME15': { percent: 15, duration: 'once' },
+  'SAVE10': { percent: 10, duration: 'once' },
+  'FLASH20': { percent: 20, duration: 'once' },
+  'GIFT15': { percent: 15, duration: 'once' },
+  'WELCOME10OFF': { amount: 10, duration: 'once' },
+
+  // Email campaigns (used by recurring sale seeds — restricted by audience)
+  'UPGRADE15': {
+    percent: 15,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.plan === 'basic';
+    },
+  },
+  'COMEBACK20': {
+    percent: 20,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.plan === 'basic' && user.subscription?.trial?.claimed === true;
+    },
+  },
+  'MISSYOU25': {
+    percent: 25,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.everPaid && user.subscription?.status === 'cancelled';
+    },
+  },
+  'TRYAGAIN10': {
+    percent: 10,
+    duration: 'once',
+    eligible: (user) => {
+      return user.subscription?.status === 'cancelled';
+    },
+  },
+};
+
+/**
+ * Validate a discount code, optionally checking user eligibility.
+ *
+ * @param {string} code - The discount code (case-insensitive)
+ * @param {object} [user] - User doc or User instance. If provided and the code has
+ *   an eligible() function, eligibility is checked. If not provided, eligibility is skipped.
+ * @returns {{ valid: boolean, code: string, percent?: number, amount?: number, duration?: string, reason?: string }}
+ */
+function validate(code, user) {
+  const normalized = (code || '').trim().toUpperCase();
+
+  if (!normalized) {
+    return { valid: false, code: normalized };
+  }
+
+  const entry = DISCOUNT_CODES[normalized];
+
+  if (!entry) {
+    return { valid: false, code: normalized };
+  }
+
+  // Check eligibility if user is provided and code has a restriction
+  if (user && entry.eligible) {
+    // Support both raw user doc and User instance (check .properties for User instance)
+    const userDoc = user.properties || user;
+
+    if (!entry.eligible(userDoc)) {
+      return { valid: false, code: normalized, reason: 'not eligible' };
+    }
+  }
+
+  // The result carries the ONE shape the code has — everything downstream reads a
+  // validate() RESULT and never the table, so an amount code that reported no
+  // amount would quietly charge full price everywhere. The absent shape is
+  // OMITTED, never set to undefined: `POST /payments/intent` writes this object
+  // into payments-intents/{orderId}, and firebase-admin refuses a document
+  // carrying an undefined value — synchronously, after the provider has already
+  // created the real checkout session
+  // ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+  return {
+    valid: true,
+    code: normalized,
+    ...(entry.percent !== undefined && { percent: entry.percent }),
+    ...(entry.amount !== undefined && { amount: entry.amount }),
+    duration: entry.duration,
+  };
+}
+
+/**
+ * Which shape a discount can be QUOTED as, or null for neither.
+ *
+ * A code in the table always declares exactly one shape, so a fresh validate()
+ * result always answers 'percent' or 'amount' — the providers branch on that
+ * directly. A discount read back off a STORED order is the case this exists for:
+ * one written before the amount field existed is `valid` and carries no shape at
+ * all, and a reader that assumed one would throw on it
+ * ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+ *
+ * @param {object} [discount] - A validate() result, a stored order's discount, or null
+ * @returns {'percent'|'amount'|null}
+ */
+function promoShape(discount) {
+  if (discount?.valid !== true) {
+    return null;
+  }
+
+  if (discount.percent > 0) {
+    return 'percent';
+  }
+
+  return discount.amount > 0 ? 'amount' : null;
+}
+
+/**
+ * Apply a validated discount to a charge amount.
+ *
+ * The FIRST charge only — every code is `duration: 'once'`, so the renewal keeps
+ * the full price and callers only ever hand this the amount being charged now.
+ * Mirrors what a Stripe coupon does to the first invoice: `percent` is Stripe's
+ * `percent_off`, `amount` its `amount_off` (in dollars here, not cents).
+ *
+ * @param {number} amount - The undiscounted charge (e.g., 99.99)
+ * @param {object} [discount] - A validate() result, or null for no discount
+ * @returns {number} The discounted charge, never below 0 (e.g., 84.99)
+ */
+function applyToAmount(amount, discount) {
+  const base = Number(amount) || 0;
+
+  if (!discount || discount.valid === false) {
+    return base;
+  }
+
+  // `base * percent / 100`, in that order, is not a style choice: the callers this
+  // function was folded out of all associated it that way, and `base * (percent /
+  // 100)` differs by an ULP often enough to flip a half-cent rounding (a $0.05
+  // charge at 10% off rounds to $0.05 one way and $0.04 the other)
+  const off = discount.percent > 0
+    ? base * discount.percent / 100
+    : (discount.amount || 0);
+
+  return Math.max(0, parseFloat((base - off).toFixed(2)));
+}
+
+/**
+ * The first charge for a provider that has no coupon object — applyToAmount()
+ * with the zero-total refusal in front of it.
+ *
+ * Stripe and Chargebee hand their hosted page a real coupon and let it decide
+ * what a zero total means. PayPal and Coinbase are prices THIS framework
+ * computes and sends, and neither a PayPal v2 Order/setup fee nor a Coinbase
+ * charge accepts a zero amount — so a code that covered the whole price was
+ * sent as a real $0.00 charge and came back as a provider 400 the buyer read as
+ * the checkout's generic failure sentence
+ * ([#786](https://github.com/Omega-JS-Stack/omega/issues/786)). It is refused
+ * here instead, before the provider is called at all, and the refusal is coded
+ * 400 so `POST /payments/intent` answers the buyer with THESE words (naming
+ * their code and the price) rather than its neutral 500 line.
+ *
+ * A product priced 0 is NOT this case: it carries no code that could have taken
+ * anything off, and every provider already refuses it with its own "No price
+ * configured for …" — which stays theirs.
+ *
+ * @param {number} listPrice - The charge before any code
+ * @param {object} [discount] - A validate() result, or null for no discount
+ * @param {object} options
+ * @param {string} options.provider - The provider's display name, for the message
+ * @returns {number} The discounted charge, always above zero
+ * @throws {Error} Coded 400 when the code leaves nothing to charge
+ */
+function chargeableAmount(listPrice, discount, { provider }) {
+  const amount = applyToAmount(listPrice, discount);
+
+  // A priced product that discounts to nothing can only have got there through a
+  // code — applyToAmount() returns the base untouched without one — so the
+  // refusal can always name it
+  if (listPrice > 0 && amount <= 0) {
+    const error = new Error(`Discount code ${discount.code} covers the full $${Number(listPrice).toFixed(2)} price, so there is nothing for ${provider} to charge. Remove the code or choose another payment method.`);
+
+    error.code = 400;
+
+    throw error;
+  }
+
+  return amount;
+}
+
+module.exports = { validate, applyToAmount, chargeableAmount, promoShape, DISCOUNT_CODES };

package/dist/manager/libraries/payment/fetch-failure.js

@@ -0,0 +1,56 @@
+const isAlreadyGone = require('./provider-errors.js');
+
+/**
+ * The ONE way a provider library reports a lookup it could not answer.
+ *
+ * `fetchResource()` used to swallow its own failure and hand back the payload the
+ * WEBHOOK carried, flagged stale — so an unverified object supplied by whoever
+ * posted the event drove real subscription state and real conversions. The
+ * provider's own answer is the only trusted source, so a lookup that fails
+ * produces no resource at all ([#506](https://github.com/Omega-JS-Stack/omega/issues/506)).
+ *
+ * What the caller still needs is WHICH failure it was, because the two have
+ * opposite outcomes:
+ *
+ * - **not found** (`notFound: true`) — the provider affirmatively does not have
+ *   this resource. Nothing will ever make it processable, so the pipeline refuses
+ *   the event and acknowledges it rather than redelivering forever.
+ * - **unreachable** (`notFound: false`) — a timeout, a 5xx, an expired key. The
+ *   answer exists; this attempt could not read it. The pipeline defers, and the
+ *   retry ladder is the reconciliation mechanism.
+ *
+ * The split itself is [provider-errors.js](provider-errors.js), so every provider
+ * classifies by the same rule instead of each naming its own not-found shape.
+ */
+
+/**
+ * Wrap a failed provider lookup as the classified error the pipeline branches on
+ *
+ * @param {Error} error - The error the provider call threw
+ * @param {object} options
+ * @param {string} options.provider - Provider name (e.g. 'stripe')
+ * @param {string} options.fn - The library method that made the call, so the message names its own call site (e.g. 'getRefundDetails')
+ * @param {string} options.resourceType - Resource type that was being fetched
+ * @param {string} options.resourceId - Resource ID that was being fetched
+ * @param {string} [options.consequence] - What the failed call did NOT do (e.g. an uncaptured capture)
+ * @returns {Error} The error to throw, carrying `notFound` plus what it was about
+ */
+function fetchFailure(error, { provider, fn, resourceType, resourceId, consequence }) {
+  const notFound = isAlreadyGone(error);
+  const verdict = notFound
+    ? `${provider} does not have ${resourceType} ${resourceId}`
+    : `${provider} could not be reached for ${resourceType} ${resourceId}`;
+  const suffix = consequence ? ` — ${consequence}` : '';
+
+  const failure = new Error(`${provider} ${fn}(${resourceType}/${resourceId}) failed — ${verdict}: ${error?.message || error}${suffix}`);
+
+  failure.notFound = notFound;
+  failure.provider = provider;
+  failure.resourceType = resourceType;
+  failure.resourceId = resourceId;
+  failure.cause = error;
+
+  return failure;
+}
+
+module.exports = fetchFailure;

package/dist/manager/libraries/payment/license.js

@@ -0,0 +1,44 @@
+/**
+ * The payment half of the OMEGA license
+ * ([#320](https://github.com/Omega-JS-Stack/omega/issues/320)).
+ *
+ * A published OMEGA install needs a license to run the payment system live.
+ * The check itself is a DEPLOY-time question the CLI asks
+ * (@omega.js/devkit/license) — this runtime never phones home. What reaches
+ * here is the verdict the deploy composed into the artifact's own .env:
+ *
+ *   OMEGA_LICENSE_STATUS=licensed  → nothing changes
+ *   OMEGA_LICENSE_STATUS=keyless   → the real providers refuse to initialize
+ *   (absent)                       → nothing changes
+ *
+ * ABSENT is the important case: only a deploy writes the key, so every local
+ * lane — the emulator, `omega serve`, every test lane, a demo-* project —
+ * behaves exactly as it did before this existed. The `test` provider is never
+ * gated either: "payments gated" MEANS test mode still works (spec call 5).
+ *
+ * One gate, called from the three real providers' init(). They share no entry
+ * module to hold it, so the assertion lives here and each init calls it in one
+ * line rather than three copies of the rule.
+ */
+const env = require('../env.js');
+
+/**
+ * Refuse live payment processing on a keyless deploy.
+ *
+ * @param {string} provider - The provider being initialized (names the refusal).
+ * @throws {Error} UnlicensedPaymentsError (code 500) when the deploy was keyless.
+ */
+function assertLicensedPayments(provider) {
+  if (env.get('OMEGA_LICENSE_STATUS') !== 'keyless') { return; }
+
+  const error = new Error(
+    `${provider} is disabled: this backend was deployed WITHOUT an OMEGA license, so live payment processing is off. `
+    + 'A license is a subscription on omegajs.dev; put its account API key in the brand .env as OMEGA_LICENSE_KEY and deploy again. '
+    + 'Test-mode payments keep working without one.',
+  );
+  error.name = 'UnlicensedPaymentsError';
+  error.code = 500;
+  throw error;
+}
+
+module.exports = assertLicensedPayments;

package/dist/manager/libraries/payment/order-id.js

@@ -0,0 +1,57 @@
+const crypto = require('crypto');
+
+// How many ids one mint may try before it gives up. 12 random digits is a
+// trillion-wide space, so a run that collides this many times in a row is not
+// bad luck — it is a broken generator or a broken read, and both are worth
+// hearing about ([#664](https://github.com/Omega-JS-Stack/omega/issues/664)).
+const MAX_ATTEMPTS = 5;
+
+/**
+ * Generate a unique order ID in the format XXXX-XXXX-XXXX
+ * 12 random digits, grouped in 3 segments of 4
+ *
+ * @returns {string} e.g. '4637-8821-0473'
+ */
+function generate() {
+  const bytes = crypto.randomBytes(6);
+  const digits = Array.from(bytes)
+    .map(b => (b % 100).toString().padStart(2, '0'))
+    .join('');
+
+  return `${digits.slice(0, 4)}-${digits.slice(4, 8)}-${digits.slice(8, 12)}`;
+}
+
+/**
+ * Mint an order id no intent already holds.
+ *
+ * The id keys `payments-intents/<orderId>` (and `payments-orders/<orderId>`
+ * after it), so a repeat does not collide harmlessly — it OVERWRITES another
+ * customer's intent, and hands both purchases the same analytics dedupe id. The
+ * odds are small and they grow with volume, which is exactly the shape of bug
+ * that is cheap now and unfixable later.
+ *
+ * An exhausted mint throws: an id that is already taken must never be handed
+ * back, and there is nothing else this can return.
+ *
+ * @param {object} options
+ * @param {object} options.admin - The firebase-admin app
+ * @param {object} options.ctx - RouteContext, for the collision record
+ * @param {function} [options.generate] - The id source, injectable so a collision can be produced on demand
+ * @returns {Promise<string>} An order id no intent doc holds
+ */
+async function mint({ admin, ctx, generate: generateId = generate }) {
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const orderId = generateId();
+    const existing = await admin.firestore().doc(`payments-intents/${orderId}`).get();
+
+    if (!existing.exists) {
+      return orderId;
+    }
+
+    ctx.warn(`Order id collision: payments-intents/${orderId} already exists, minting another (attempt ${attempt}/${MAX_ATTEMPTS})`);
+  }
+
+  throw new Error(`Could not mint an unused order id in ${MAX_ATTEMPTS} attempts`);
+}
+
+module.exports = { generate, mint, MAX_ATTEMPTS };