@omega.js/backend 0.1.0

package/dist/manager/libraries/payment/providers/test.js

@@ -0,0 +1,250 @@
+const Stripe = require('./stripe.js');
+
+/**
+ * Test provider library
+ * Delegates to Stripe's transformers since test provider generates Stripe-shaped data
+ * Stamps provider as 'test' to distinguish from real Stripe data
+ */
+const Test = {
+  /**
+   * No-op init — test provider doesn't need an external SDK
+   */
+  init() {
+    return null;
+  },
+
+  /**
+   * Fetch resource — the test provider IS its own API
+   *
+   * The one library that may read the event body ([../fetch-failure.js](../fetch-failure.js)):
+   * there is no test provider out there to ask, so its "API records" are the
+   * emulator's own payments-orders plus the body the event carried. A REAL
+   * provider never reads it — that is the trust rule this seam enforces
+   * ([#506](https://github.com/Omega-JS-Stack/omega/issues/506)) — and the route
+   * refuses `provider=test` in production, so nothing outside a test run reaches here.
+   *
+   * When the requested resourceType doesn't match the event's own resource (e.g.,
+   * requesting a subscription but the event carries an invoice from
+   * invoice.payment_failed), look up the existing resource from Firestore instead
+   * of returning mismatched data.
+   */
+  async fetchResource(resourceType, resourceId, context) {
+    const eventResource = this.extractResource(context?.raw) || {};
+
+    // If the event's resource matches the requested type AND has a UID, return it directly
+    // When UID is missing (e.g., PAYMENT.SALE events), fall through to Firestore lookup
+    // so we can reconstruct a resource with the UID from the order's owner field
+    if (eventResource.object === resourceType && eventResource.metadata?.uid) {
+      return eventResource;
+    }
+
+    // Look up the existing resource from payments-orders in Firestore
+    // This simulates what a real API call (Stripe/PayPal) would return — a resource
+    // with the full metadata including UID
+    const admin = context?.admin;
+    if (admin && resourceId) {
+      const snapshot = await admin.firestore()
+        .collection('payments-orders')
+        .where('resourceId', '==', resourceId)
+        .limit(1)
+        .get();
+
+      if (!snapshot.empty) {
+        const data = snapshot.docs[0].data();
+        // payments-orders stores the unified subscription inside .unified
+        // Reconstruct a Stripe-shaped object from the unified data for toUnifiedSubscription()
+        if (resourceType === 'subscription' && data.unified) {
+          const reconstructed = buildStripeSubscriptionFromUnified(data.unified, resourceId, context?.eventType, context?.config, data.owner);
+
+          // If the event's resource matched the type but lacked UID, overlay its new
+          // state onto the reconstructed resource, but keep the reconstructed metadata (has uid)
+          if (eventResource.object === resourceType) {
+            return { ...eventResource, metadata: { ...eventResource.metadata, ...reconstructed.metadata } };
+          }
+
+          return reconstructed;
+        }
+
+        // The same reconstruction on the one-time side: a session/invoice webhook
+        // that carries no metadata (no uid, no orderId) is answered from the order
+        // the first webhook already wrote
+        if (data.type === 'one-time' && data.unified) {
+          const reconstructed = buildStripeOneTimeFromOrder(data, resourceId);
+
+          // Keep the event's fresh state, take the metadata only the order has
+          if (Object.keys(eventResource).length > 0) {
+            return { ...eventResource, metadata: { ...eventResource.metadata, ...reconstructed.metadata } };
+          }
+
+          return reconstructed;
+        }
+      }
+    }
+
+    // Last resort: the event's own resource is all this provider has
+    return eventResource;
+  },
+
+  /**
+   * Extract the resource the webhook envelope carries — delegates to Stripe
+   * (test provider uses Stripe-shaped data), and is where its own fetchResource
+   * reads the event body it answers from
+   */
+  extractResource(raw) {
+    return Stripe.extractResource(raw);
+  },
+
+  /**
+   * Extract orderId — delegates to Stripe (test provider uses Stripe-shaped data)
+   */
+  getOrderId(resource) {
+    return Stripe.getOrderId(resource);
+  },
+
+  /**
+   * Extract UID — delegates to Stripe (test provider uses Stripe-shaped data)
+   */
+  getUid(resource) {
+    return Stripe.getUid(resource);
+  },
+
+  /**
+   * Refund details — Stripe's reader over the charge this provider has
+   *
+   * The test provider IS its own API ([../fetch-failure.js](../fetch-failure.js)),
+   * so the charge of record is whichever one it already holds: the fetched
+   * resource when the event resolved to the charge itself, otherwise the event's
+   * own body. Never a real Stripe lookup — there is no Stripe account behind a
+   * test-provider event to answer one
+   * ([#510](https://github.com/Omega-JS-Stack/omega/issues/510)).
+   */
+  async getRefundDetails(resource, options = {}) {
+    const charge = resource?.object === 'charge'
+      ? resource
+      : this.extractResource(options.raw);
+
+    return Stripe.toRefundDetails(charge);
+  },
+
+  /**
+   * Transform raw subscription into unified shape
+   * Delegates to Stripe's toUnifiedSubscription (same data shape), stamps provider as 'test'
+   */
+  toUnifiedSubscription(rawSubscription, options) {
+    const unified = Stripe.toUnifiedSubscription(rawSubscription, options);
+    unified.payment.provider = 'test';
+    return unified;
+  },
+
+  /**
+   * Transform raw one-time payment into unified shape
+   * Delegates to Stripe's toUnifiedOneTime, stamps provider as 'test'
+   */
+  toUnifiedOneTime(rawResource, options) {
+    const unified = Stripe.toUnifiedOneTime(rawResource, options);
+    unified.payment.provider = 'test';
+    return unified;
+  },
+};
+
+module.exports = Test;
+
+/**
+ * Reconstruct a Stripe-shaped subscription from the unified subscription stored in Firestore
+ * This is only needed for the test provider when the webhook fallback doesn't match the resource type
+ * (e.g., invoice.payment_failed sends invoice data but we need the subscription)
+ *
+ * The unified → Stripe mapping must produce data that toUnifiedSubscription() can process correctly.
+ * For payment failure events, we override the status to past_due so it maps to 'suspended'.
+ */
+function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, config, ownerUid) {
+  // Map unified status back to a Stripe status
+  const STATUS_MAP = {
+    active: 'active',
+    suspended: 'past_due',
+    cancelled: 'canceled',
+  };
+
+  // Map unified frequency back to Stripe interval
+  const INTERVAL_MAP = {
+    monthly: 'month',
+    annually: 'year',
+    weekly: 'week',
+    daily: 'day',
+  };
+
+  // Determine status: for payment failure events, force past_due regardless of current state
+  // In production, Stripe would have already updated the subscription status
+  let status = STATUS_MAP[unified.status] || 'active';
+  if (eventType === 'invoice.payment_failed') {
+    status = 'past_due';
+  }
+
+  // Resolve the Stripe product ID from config
+  // This is needed for resolveProduct() in toUnifiedSubscription() to match the correct product
+  const frequency = unified.payment?.frequency;
+  const productId = unified.product?.id;
+  const stripeProductId = resolveStripeProductId(productId, config);
+
+  return {
+    id: resourceId,
+    object: 'subscription',
+    status: status,
+    metadata: { orderId: unified.payment?.orderId || null, uid: ownerUid || null },
+    plan: {
+      product: stripeProductId,
+      interval: INTERVAL_MAP[frequency] || 'month',
+    },
+    current_period_end: unified.expires?.timestampUNIX || 0,
+    current_period_start: unified.payment?.startDate?.timestampUNIX || 0,
+    start_date: unified.payment?.startDate?.timestampUNIX || 0,
+    cancel_at_period_end: unified.cancellation?.pending || false,
+    cancel_at: unified.cancellation?.pending ? unified.cancellation?.date?.timestampUNIX : null,
+    canceled_at: null,
+    trial_start: unified.trial?.claimed ? (unified.payment?.startDate?.timestampUNIX || 0) : null,
+    trial_end: unified.trial?.claimed ? (unified.trial?.expires?.timestampUNIX || 0) : null,
+  };
+}
+
+/**
+ * Reconstruct a Stripe-shaped one-time resource from the order stored in Firestore
+ *
+ * The one-time twin of buildStripeSubscriptionFromUnified(): what a real API call
+ * would return for a session/invoice — most importantly the metadata (uid, orderId,
+ * productId) that a bare webhook payload may not carry.
+ */
+function buildStripeOneTimeFromOrder(order, resourceId) {
+  const unified = order.unified || {};
+
+  return {
+    id: resourceId,
+    object: 'checkout.session',
+    status: unified.status === 'completed' ? 'complete' : unified.status || 'complete',
+    metadata: {
+      orderId: unified.payment?.orderId || order.id || null,
+      uid: order.owner || null,
+      productId: unified.product?.id || order.productId || null,
+    },
+  };
+}
+
+/**
+ * Look up the Stripe product ID from config given a product ID
+ * e.g., ('plus') → 'prod_plus'
+ */
+function resolveStripeProductId(productId, config) {
+  if (!productId || !config?.payment?.products) {
+    return null;
+  }
+
+  const product = config.payment.products.find(p => p.id === productId);
+
+  if (!product) {
+    return null;
+  }
+
+  // Real Stripe product ID if configured, otherwise the "_test_<id>" sentinel that the
+  // Stripe resolver recognizes and maps back to the @omega.js/backend product. Lets reconstruction
+  // work in brands without real Stripe (Somiibo uses PayPal, Chargebee, etc.).
+  return product.stripe?.productId || `_test_${product.id}`;
+}

package/dist/manager/libraries/payment/refund-linkage.js

@@ -0,0 +1,78 @@
+/**
+ * The ONE rule that says a refund record belongs to the event that named it.
+ *
+ * A refund's numbers come from the provider, looked up by an id the payload
+ * carried ([#510](https://github.com/Omega-JS-Stack/omega/issues/510)). That id is
+ * as trusted as the resourceId every lookup starts from — with one difference the
+ * trust argument missed: a resourceId is SELF-CONSISTENT (whatever it names is
+ * what gets fetched and what gets written), while a refund id imports numbers
+ * ACROSS records. Pair a real sale of your own with an unrelated refund id from
+ * the same merchant account and another customer's refund amount lands on your
+ * order, their email and their refund conversion
+ * ([#532](https://github.com/Omega-JS-Stack/omega/issues/532)).
+ *
+ * So every refund lookup is linked back. Each provider knows its own back-pointer
+ * — a PayPal v1 refund names its `sale_id` and a v2 refund links `up` to its
+ * capture, a Chargebee credit note names its `subscription_id` /
+ * `reference_invoice_id`, a Stripe charge carries the subscription and the uid it
+ * was made under — and hands the pair here, so the DECISION is written once:
+ *
+ * - **disagrees** — the record is about another order. Thrown as
+ *   `refundNotLinked`, which the pipeline refuses and acknowledges (the #509
+ *   shape): nothing is written, and the stamp on the event's own doc is what a
+ *   human reconciles from.
+ * - **agrees** — proceed.
+ * - **nothing to compare** — the record carries no back-pointer for this kind of
+ *   resource (a PayPal subscription refund names the sale, never the billing
+ *   agreement). Unprovable is not the same as wrong, so it proceeds — and the log
+ *   line saying so is the only warning a human gets that this one refund was
+ *   never cross-checked, exactly like the #509 uid fallback.
+ */
+
+/**
+ * Assert that a looked-up refund record points back at the event's resource
+ *
+ * @param {object} options
+ * @param {string} options.provider - Provider name (e.g. 'paypal')
+ * @param {string} options.refundType - What was looked up ('refund', 'credit_note', 'charge', 'transaction')
+ * @param {string} options.refundId - The id it was looked up by
+ * @param {string|null} options.field - The record's back-pointer field, named as the provider spells it
+ * @param {string|null} options.found - What that field says the record belongs to
+ * @param {string|null} options.expected - What the event says it should belong to
+ * @param {string} options.resourceType - The event's resource type
+ * @param {string} options.resourceId - The event's resource id
+ * @param {object} [options.ctx] - Assistant instance for logging
+ * @throws {Error} Carrying `refundNotLinked` when the record belongs to something else
+ */
+function assertRefundLinkage({ provider, refundType, refundId, field, found, expected, resourceType, resourceId, ctx }) {
+  if (!field || !found || !expected) {
+    const message = `REFUND LINK UNPROVEN: ${provider} ${refundType} ${refundId} carries no ${field || 'back-pointer'} to check against ${resourceType} ${resourceId}, so this refund's numbers are recorded without being linked back to the resource the event named`;
+
+    if (ctx?.warn) {
+      ctx.warn(message);
+    } else {
+      console.warn(`[@omega.js/backend:payment:refund-linkage] ${message}`);
+    }
+
+    return;
+  }
+
+  if (found === expected) {
+    return;
+  }
+
+  const failure = new Error(`${provider} ${refundType} ${refundId} names ${field} ${found}, but the ${resourceType} ${resourceId} this event is about is ${expected} — the refund belongs to another record`);
+
+  failure.refundNotLinked = true;
+  failure.provider = provider;
+  failure.refundType = refundType;
+  failure.refundId = refundId;
+  failure.field = field;
+  failure.linkedTo = found;
+  failure.resourceType = resourceType;
+  failure.resourceId = resourceId;
+
+  throw failure;
+}
+
+module.exports = assertRefundLinkage;

package/dist/manager/libraries/payment/refund-policy.js

@@ -0,0 +1,113 @@
+/**
+ * Refund policy — the ONE home of the brand's refund window.
+ *
+ * Every refund provider answers the same question ("is this payment recent
+ * enough for a full refund, or is it prorated by days remaining?") and the
+ * answer must be identical across Stripe, PayPal, and Chargebee: a user who
+ * paid the same day must not get a different outcome because of which button
+ * they checked out with. Three private copies of the number would drift; this
+ * is the single definition all three import ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * It is also where a ONE-TIME order's refundability is decided, for the same
+ * reason: the refund route enforces it, and the account page's orders list has
+ * to offer the button on exactly the orders that route would accept. Two
+ * spellings of "refundable" would eventually offer a button that 400s
+ * ([#672](https://github.com/Omega-JS-Stack/omega/issues/672)).
+ */
+
+// Payments this many days old or younger refund in FULL. Older ones prorate by
+// the days remaining in the billing period the payment bought.
+const FULL_REFUND_DAYS = 7;
+
+// Payments older than this are not eligible for a refund, whatever was bought.
+const REFUND_WINDOW_SECONDS = 6 * 30 * 24 * 60 * 60;
+const OUTSIDE_WINDOW_MESSAGE = 'Payments older than 6 months are not eligible for refunds';
+
+// Providers with no refund API at all. Coinbase Commerce settles in crypto and
+// exposes no refund endpoint — returning coins is a manual transfer the merchant
+// makes from its dashboard, at whatever the coin is worth that day, and nothing
+// about it is ever attached to the charge. So the refusal belongs HERE, with
+// every other one, rather than as a provider call that could only ever fail: the
+// route would answer the customer "try again shortly" for something no retry can
+// fix, and the account page would offer a Refund button on it
+// ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)).
+const NO_REFUND_PROVIDERS = ['coinbase'];
+const NO_REFUND_MESSAGE = 'Crypto purchases cannot be refunded automatically. Contact support and we will arrange it by hand.';
+
+/**
+ * Is a payment recent enough to refund? An absent date cannot disqualify one.
+ *
+ * @param {number} [paidUNIX] - When the payment happened
+ * @returns {boolean}
+ */
+function isWithinRefundWindow(paidUNIX) {
+  if (!paidUNIX) {
+    return true;
+  }
+
+  return paidUNIX >= Math.floor(Date.now() / 1000) - REFUND_WINDOW_SECONDS;
+}
+
+/**
+ * Why this one-time order cannot be refunded, if it cannot.
+ *
+ * Ownership is deliberately NOT here: that is an authorization question the
+ * caller answers (the refund route compares the order's owner against the
+ * caller; the orders route only ever reads the caller's own).
+ *
+ * @param {object} order - The payments-orders document
+ * @returns {{ reason: string, message: string }|null} The refusal, or null when the order is refundable
+ */
+function oneTimeRefundRefusal(order) {
+  if (!order || order.type !== 'one-time') {
+    return { reason: 'not-one-time', message: 'That order is not a one-time purchase' };
+  }
+
+  // requests.refund covers the in-app path; unified.status covers a refund issued
+  // from the provider dashboard, which arrives by webhook and writes no request
+  if (order.requests?.refund || order.unified?.status === 'refunded') {
+    return { reason: 'already-refunded', message: 'This purchase has already been refunded' };
+  }
+
+  // Nothing was captured, so there is nothing to reverse. Every provider
+  // normalizes a successful purchase to 'completed' and passes its own word
+  // through otherwise (stripe.js:485, paypal.js:326, chargebee.js:416-423), so an
+  // abandoned checkout keeps its provider and its resourceId and passed every
+  // other refusal — the orders list offered a refund button on a Failed pill, and
+  // pressing it asked the provider to refund a charge that never happened
+  if (order.unified?.status !== 'completed') {
+    return { reason: 'not-completed', message: 'That purchase has not completed' };
+  }
+
+  // The purchase date is the order's creation; the last webhook write is the fallback
+  const purchasedUNIX = order.metadata?.created?.timestampUNIX
+    || order.unified?.payment?.updatedBy?.date?.timestampUNIX;
+
+  if (!isWithinRefundWindow(purchasedUNIX)) {
+    return { reason: 'outside-window', message: OUTSIDE_WINDOW_MESSAGE };
+  }
+
+  const provider = order.provider || order.unified?.payment?.provider;
+  const resourceId = order.resourceId || order.unified?.payment?.resourceId;
+
+  if (!provider || !resourceId) {
+    return { reason: 'missing-payment-details', message: 'Order payment details not found' };
+  }
+
+  // Last, because it is the least specific thing wrong with an order: a crypto
+  // purchase that is also already refunded should still say so.
+  if (NO_REFUND_PROVIDERS.includes(provider)) {
+    return { reason: 'provider-cannot-refund', message: NO_REFUND_MESSAGE };
+  }
+
+  return null;
+}
+
+module.exports = {
+  FULL_REFUND_DAYS,
+  REFUND_WINDOW_SECONDS,
+  OUTSIDE_WINDOW_MESSAGE,
+  NO_REFUND_PROVIDERS,
+  isWithinRefundWindow,
+  oneTimeRefundRefusal,
+};

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

@@ -0,0 +1,55 @@
+/**
+ * The cancel-flow save offer, in the shape the payment stack already speaks
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * A customer who starts cancelling is pitched a discount on the next cycle
+ * before the questionnaire. What the offer IS belongs to the brand
+ * (`payment.winback` in omega.json5, resolved by @omega.js/config — 50% off the
+ * next cycle when a brand configures nothing), so nothing here carries a number
+ * of its own.
+ *
+ * Everything downstream of the apply route — the Stripe coupon builder, the
+ * order doc, the analytics line — already reads a discount-codes VALIDATE
+ * RESULT, so the offer is handed over as one instead of teaching each of them a
+ * second shape. It is not a code anyone can type: the codes table is the SSOT
+ * for what a customer may enter, and this offer is never entered, only accepted.
+ */
+const { resolveWinbackOffer } = require('../../../vendor/config/index.js');
+
+/**
+ * The offer a resolved config makes, framework default applied.
+ *
+ * @param {object} config - The Manager's resolved config
+ * @returns {{ enabled: boolean, percent?: number, amount?: number, duration: string }}
+ */
+function resolveOffer(config) {
+  return resolveWinbackOffer(config?.payment);
+}
+
+/**
+ * The offer as a discount-codes validate() result.
+ *
+ * The synthetic code names the offer for every downstream reader — it is what
+ * the providers derive their deterministic coupon id from, so two brands on the
+ * same percentage share one coupon and a brand that changes its mind gets a new
+ * one instead of silently reusing the old number.
+ *
+ * The absent shape is OMITTED, never set to undefined: this object is written
+ * onto payments-orders/{orderId}, and firebase-admin refuses a document carrying
+ * an undefined value (the rule discount-codes.validate() records at length).
+ *
+ * @param {object} offer - A resolveOffer() result
+ * @returns {{ valid: boolean, code: string, percent?: number, amount?: number, duration: string }}
+ */
+function toDiscount(offer) {
+  const isAmount = offer.amount > 0;
+
+  return {
+    valid: true,
+    code: isAmount ? `WINBACK${offer.amount}OFF` : `WINBACK${offer.percent}`,
+    ...(isAmount ? { amount: offer.amount } : { percent: offer.percent }),
+    duration: offer.duration,
+  };
+}
+
+module.exports = { resolveOffer, toDiscount };

package/dist/manager/libraries/prompts/infer-contact.md

@@ -0,0 +1,78 @@
+<identity>
+You extract real human names and company from email addresses.
+</identity>
+
+<rules>
+- Only return a name if it is a REAL human name. If the local part contains placeholder text, gibberish, generic words, or fictional/brand names, return empty strings for firstName and lastName.
+- Placeholder/test examples that are NOT real names: firstname.lastname, first.last, asdf.qwerty, test.user, mixed.case, bobs.burgers, john.doe (this is a well-known placeholder)
+- Generic role words are NOT names: admin, info, support, hello, contact, sales, billing, noreply, webmaster, postmaster, dev, ceo
+- Single letters or initials ARE acceptable (e.g., "j" from j@company.com → firstName: "J")
+- ALWAYS infer company from the domain, even when there is no name. Generic email providers (gmail.com, yahoo.com, hotmail.com, outlook.com, aol.com, icloud.com, mail.com, protonmail.com, proton.me, zoho.com, yandex.com, gmx.com, live.com, msn.com, me.com) should return empty company.
+- Hyphenated names should preserve capitalization on both parts (e.g., jean-pierre → Jean-Pierre)
+- Plus-addressing tags are NOT part of the name — ignore everything from "+" to "@" (e.g., sarah.martinez+newsletter@acme.com → treat as sarah.martinez@acme.com). A +tag alone never makes an otherwise-real name a placeholder or test address.
+- confidence should reflect how certain you are that the name is a REAL person's name. Placeholders and gibberish should never have confidence above 0.
+</rules>
+
+<format>
+Return ONLY valid JSON:
+{
+  "firstName": "...",
+  "lastName": "...",
+  "company": "...",
+  "confidence": "..."
+}
+
+- firstName: First name (string), properly capitalized
+- lastName: Last name (string), properly capitalized
+- company: Company name (string), capitalized. Infer from domain (not generic providers).
+- confidence: Confidence level (number), 0-1 scale. How sure you are the name is real.
+
+If you cannot determine a real name, use empty strings for firstName and lastName.
+</format>
+
+<examples>
+<example>
+<input>john.smith@acme.com</input>
+<output>{"firstName": "John", "lastName": "Smith", "company": "Acme", "confidence": 0.9}</output>
+</example>
+<example>
+<input>jsmith123@gmail.com</input>
+<output>{"firstName": "J", "lastName": "Smith", "company": "", "confidence": 0.4}</output>
+</example>
+<example>
+<input>support@bigcorp.io</input>
+<output>{"firstName": "", "lastName": "", "company": "Bigcorp", "confidence": 0}</output>
+</example>
+<example>
+<input>mary_jane_watson@stark-industries.com</input>
+<output>{"firstName": "Mary", "lastName": "Watson", "company": "Stark Industries", "confidence": 0.85}</output>
+</example>
+<example>
+<input>info@company.org</input>
+<output>{"firstName": "", "lastName": "", "company": "Company", "confidence": 0}</output>
+</example>
+<example>
+<input>firstname.lastname@company.com</input>
+<output>{"firstName": "", "lastName": "", "company": "Company", "confidence": 0}</output>
+</example>
+<example>
+<input>asdf.qwerty@outlook.com</input>
+<output>{"firstName": "", "lastName": "", "company": "", "confidence": 0}</output>
+</example>
+<example>
+<input>jean-pierre.dupont@orange.fr</input>
+<output>{"firstName": "Jean-Pierre", "lastName": "Dupont", "company": "Orange", "confidence": 0.95}</output>
+</example>
+<example>
+<input>bobs.burgers@example.com</input>
+<output>{"firstName": "", "lastName": "", "company": "Example", "confidence": 0}</output>
+</example>
+<example>
+<input>j@company.com</input>
+<output>{"firstName": "J", "lastName": "", "company": "Company", "confidence": 0.3}</output>
+</example>
+<example>
+<input>david.chen+newsletter@globex.com</input>
+<output>{"firstName": "David", "lastName": "Chen", "company": "Globex", "confidence": 0.9}</output>
+</example>
+</examples>

package/dist/manager/libraries/rate-limits.js

@@ -0,0 +1,17 @@
+/**
+ * Framework anti-abuse gate limits (SSOT)
+ *
+ * These are EXPLICIT limits on the framework's own public routes, never plan
+ * features a brand prices in its `features` catalog ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+ * The per-IP signup cap is the one gate a brand tunes, so it keeps its own
+ * config key (`targets.backend.auth.signup.maxPerIpPerDay`) instead of a
+ * constant here.
+ *
+ * Used by:
+ * - routes/marketing/contact/post.js (per-IP subscribe gate)
+ * - routes/marketing/email-preferences/post.js (per-user and per-IP toggle gate)
+ */
+module.exports = {
+  // How many marketing-form calls one caller may make in a counting period
+  MARKETING_RATE_LIMIT: 5,
+};

package/dist/manager/libraries/recaptcha.js

@@ -0,0 +1,58 @@
+const fetch = require('wonderful-fetch');
+const env = require('./env.js');
+
+/**
+ * Print Google's verdict for a REJECTED token — never the token, never the secret.
+ *
+ * A rejection turns into a 403 the caller cannot explain on its own: wrong
+ * secret, wrong domain, low score and expired token all look identical
+ * downstream. This is the one line that names the reason.
+ *
+ * @param {object} data - The siteverify response
+ */
+function logRejection(data) {
+  const codes = (data['error-codes'] || []).join(',') || 'none';
+
+  console.warn(`[@omega.js/backend:recaptcha] verify() rejected: error-codes=${codes} score=${data.score ?? 'none'} action=${data.action || 'none'} hostname=${data.hostname || 'none'}`);
+}
+
+/**
+ * Verify a Google reCAPTCHA token
+ * @param {string} token - The reCAPTCHA response token
+ * @param {object} [options] - Options
+ * @param {number} [options.minScore=0.5] - Minimum score threshold (v3)
+ * @returns {Promise<boolean>} Whether the token is valid
+ */
+async function verify(token, options) {
+  const minScore = options?.minScore || 0.5;
+
+  if (!env.has('RECAPTCHA_SECRET_KEY')) {
+    return true;
+  }
+
+  if (!token) {
+    return false;
+  }
+
+  try {
+    const data = await fetch('https://www.google.com/recaptcha/api/siteverify', {
+      method: 'post',
+      response: 'json',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `secret=${env.get('RECAPTCHA_SECRET_KEY')}&response=${token}`,
+    });
+
+    const passed = data.success && (data.score === undefined || data.score >= minScore);
+
+    if (!passed) {
+      logRejection(data);
+    }
+
+    return passed;
+  } catch (e) {
+    console.error('reCAPTCHA verification error:', e);
+    return false;
+  }
+}
+
+module.exports = { verify };