@omega.js/backend 0.1.0

package/dist/manager/routes/payments/webhook/providers/stripe.js

@@ -0,0 +1,182 @@
+/**
+ * Stripe webhook provider
+ * Extracts and categorizes webhook event data from Stripe
+ *
+ * Each event is mapped to a category (subscription or one-time) and includes
+ * the resource type + ID needed to fetch the latest state from Stripe's API.
+ */
+
+// Invoice events, successful and failed. A renewal produces NO subscription
+// transition (active → active, same product), so the invoice event is the only
+// thing that tells the pipeline money moved — without it Stripe recurring
+// revenue never reaches analytics ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+//
+// `invoice.paid` is deliberately NOT here. Stripe fires it alongside
+// `invoice.payment_succeeded` for the same paid invoice, and the analytics
+// resolver treats every renewal-shaped webhook as its own payment — ingesting
+// both would report a renewal's revenue TWICE. `invoice.payment_succeeded` is
+// the narrower of the two (a payment attempt actually succeeded), so it is the
+// one that carries renewals. A brand must send `invoice.payment_succeeded`:
+// `invoice.paid` is rejected at the route (`isSupported`) and never stored.
+const INVOICE_EVENTS = new Set([
+  'invoice.payment_failed',
+  'invoice.payment_succeeded',
+]);
+
+// Events we process, mapped to their default category
+// Some events (the invoice events, checkout.session.completed) require
+// inspecting the payload to determine the actual category
+const SUPPORTED_EVENTS = new Set([
+  // Subscription lifecycle
+  'customer.subscription.created',
+  'customer.subscription.updated',
+  'customer.subscription.deleted',
+
+  // Invoice outcomes — renewals and failures (could be subscription or one-time)
+  ...INVOICE_EVENTS,
+
+  // Checkout completion (could be subscription or one-time)
+  'checkout.session.completed',
+
+  // Refunds
+  'charge.refunded',
+]);
+
+module.exports = {
+  /**
+   * Returns true if this event type should be saved and processed
+   */
+  isSupported(eventType) {
+    return SUPPORTED_EVENTS.has(eventType);
+  },
+
+  /**
+   * Parse a Stripe webhook request
+   * Extracts event data and determines category, resource type, resource ID, and UID
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, category, resourceType, resourceId, chargeId, raw, uid }
+   *   - category: 'subscription' | 'one-time' | null (null = skip)
+   *   - resourceType: 'subscription' | 'invoice' | 'session' | 'charge'
+   *   - resourceId: ID to fetch from provider API
+   *   - chargeId: THIS charge's own id, where a subscription event names one —
+   *     Stripe's invoice id. The resourceId is the subscription, which is
+   *     constant for its whole life, so it can never key a single charge
+   *     ([#656](https://github.com/Omega-JS-Stack/omega/issues/656)).
+   */
+  parseWebhook(req) {
+    const event = req.body;
+
+    // Validate event structure
+    if (!event || !event.id || !event.type) {
+      throw new Error('Invalid Stripe webhook payload');
+    }
+
+    const dataObject = event.data?.object || {};
+    const eventType = event.type;
+
+    // Resolve category, resource info, and UID based on event type
+    let category = null;
+    let resourceType = null;
+    let resourceId = null;
+    let uid = null;
+    // The invoice this event is about, when it is about one. A one-time purchase
+    // has exactly one charge and the order names it, so only the SUBSCRIPTION
+    // branches fill this in ([#656]).
+    let chargeId = null;
+
+    if (eventType.startsWith('customer.subscription.')) {
+      // Subscription lifecycle events — always subscription category
+      category = 'subscription';
+      resourceType = 'subscription';
+      resourceId = dataObject.id;
+      uid = dataObject.metadata?.uid || null;
+
+    } else if (INVOICE_EVENTS.has(eventType)) {
+      // Invoice outcome (renewal or failure) — inspect billing_reason to determine
+      // category. A subscription invoice resolves to the SUBSCRIPTION it belongs
+      // to, so the pipeline re-fetches live subscription state either way.
+      const billingReason = dataObject.billing_reason || '';
+      const subscriptionId = dataObject.parent?.subscription_details?.subscription
+        || dataObject.subscription
+        || null;
+
+      if (billingReason.startsWith('subscription') && subscriptionId) {
+        // Subscription-related invoice
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = subscriptionId;
+        // The invoice IS the charge — one per renewal, recovery and conversion.
+        chargeId = dataObject.id || null;
+        uid = dataObject.parent?.subscription_details?.metadata?.uid
+          || dataObject.subscription_details?.metadata?.uid
+          || dataObject.metadata?.uid
+          || null;
+      } else {
+        // One-time (manual) invoice
+        category = 'one-time';
+        resourceType = 'invoice';
+        resourceId = dataObject.id;
+        uid = dataObject.metadata?.uid || null;
+      }
+
+    } else if (eventType === 'checkout.session.completed') {
+      const mode = dataObject.mode;
+
+      if (mode === 'subscription') {
+        // Subscription checkout — skip, subscription events handle this
+        category = null;
+      } else if (mode === 'payment') {
+        // One-time payment checkout
+        category = 'one-time';
+        resourceType = 'session';
+        resourceId = dataObject.id;
+        uid = dataObject.metadata?.uid || null;
+      }
+
+    } else if (eventType === 'charge.refunded') {
+      // Refund event — the charge object contains an invoice ID which links to a subscription
+      const invoiceId = dataObject.invoice;
+      const subscriptionId = dataObject.subscription
+        || dataObject.metadata?.subscriptionId
+        || null;
+
+      if (subscriptionId) {
+        // Subscription-related refund
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = subscriptionId;
+        // The invoice the reversed charge was paid against, so the refund can
+        // name the same id GA4 recorded that charge under ([#656]).
+        chargeId = invoiceId || null;
+      } else if (invoiceId) {
+        // Has invoice — likely subscription-related, will resolve via fetchResource
+        category = 'subscription';
+        resourceType = 'invoice';
+        resourceId = invoiceId;
+        chargeId = invoiceId;
+      } else {
+        // One-time payment refund — no subscription, no invoice, so the charge
+        // itself is the resource. Dropping it (category = null) meant the refund
+        // of a one-time purchase never entered the pipeline at all
+        // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+        category = 'one-time';
+        resourceType = 'charge';
+        resourceId = dataObject.id;
+      }
+
+      uid = dataObject.metadata?.uid || null;
+    }
+
+    return {
+      eventId: event.id,
+      eventType: eventType,
+      category: category,
+      resourceType: resourceType,
+      resourceId: resourceId,
+      chargeId: chargeId,
+      raw: event,
+      uid: uid,
+    };
+  },
+};

package/dist/manager/routes/payments/webhook/providers/test.js

@@ -0,0 +1,18 @@
+/**
+ * Test webhook provider
+ * Delegates to Stripe's parser since test provider generates Stripe-shaped event payloads
+ *
+ * Only the parser is delegated: these events are FABRICATED locally, and the
+ * route's production guard is what keeps this provider out of production.
+ */
+const stripeProvider = require('./stripe.js');
+
+module.exports = {
+  isSupported(eventType) {
+    return stripeProvider.isSupported(eventType);
+  },
+
+  parseWebhook(req) {
+    return stripeProvider.parseWebhook(req);
+  },
+};

package/dist/manager/routes/payments/winback/post.js

@@ -0,0 +1,276 @@
+const path = require('path');
+const powertools = require('node-powertools');
+const loadProvider = require('../../../libraries/load-provider.js');
+const winback = require('../../../libraries/payment/winback.js');
+const isTrialing = require('../cancel/_is-trialing.js');
+
+/**
+ * POST /payments/winback
+ * Applies the cancel-flow SAVE OFFER to the authenticated user's live
+ * subscription, so the cancel they started never happens
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * The offer is the brand's (`payment.winback` in omega.json5 — 50% off the next
+ * cycle by default) and it reaches the provider as a discount, through the same
+ * coupon plumbing a checkout discount code rides. The subscription itself does
+ * not change: the customer keeps the plan, the cadence and the renewal date they
+ * already had, and the next invoice is the only thing that moves — so the only
+ * thing this route writes onto the account is the discount itself
+ * (`subscription.discount`, [#325]), never the plan, the cadence or the renewal.
+ *
+ * Claimed ONCE per subscription: the claim is recorded on
+ * payments-orders/{orderId}.requests.winback, which is also what a second call
+ * is refused against (`offer-already-claimed`) — an offer that could be taken
+ * every time the cancel dialog opens is a permanent discount nobody agreed to.
+ * A subscription with no order doc has nowhere to record it, so it is refused
+ * (`offer-not-claimable`) rather than handed an offer with no memory.
+ *
+ * Cross-provider and CAPABILITY-GATED, the same shape uncancel uses: a provider
+ * that can discount a live subscription exports applyOffer(), one that cannot
+ * simply lacks the export, and the route refuses before dispatch rather than
+ * letting the caller discover it as a provider error
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * EVERY refusal here carries a machine-readable code on the response properties
+ * (`additional.code`), not just the capability gate's
+ * ([#311](https://github.com/Omega-JS-Stack/omega/issues/311)): the client
+ * pitches the offer off the ACCOUNT alone, so a state it cannot see — an
+ * admin-granted subscription with no provider details, a brand that turned the
+ * offer off since the page loaded — reaches accept, and a refusal it cannot name
+ * leaves the customer in a dialog arming a retry that can never succeed. The
+ * codes, in the order they are refused: `confirmation-required`,
+ * `offer-disabled`, `no-active-subscription`, `trial-not-eligible`,
+ * `cancellation-pending`, `missing-payment-details`, `unknown-provider`,
+ * `not-supported-by-provider`, `offer-not-claimable`, `offer-already-claimed`.
+ * All but the first are dead ends for that account: the billing card retires the
+ * offer on them and opens the questionnaire the customer came for.
+ * Requires authentication.
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const confirmed = settings.confirmed;
+
+  // Require explicit confirmation
+  if (!confirmed) {
+    return ctx.respond('Accepting the offer must be confirmed', {
+      code: 400,
+      additional: { code: 'confirmation-required' },
+    });
+  }
+
+  // The brand's own offer. A brand that turned it off has no offer to apply, and
+  // the client never shows the step — so a call arriving here is a stale page or
+  // a hand-rolled request, and it is refused rather than given a default.
+  const offer = winback.resolveOffer(ctx.Manager.config);
+
+  if (!offer.enabled) {
+    ctx.log(`Winback rejected: uid=${uid}, the save offer is disabled for this brand`);
+    return ctx.respond('This offer is not available', {
+      code: 400,
+      additional: { code: 'offer-disabled' },
+    });
+  }
+
+  const subscription = user.subscription;
+
+  // Require an ACTIVE paid subscription — there is no next cycle to discount on
+  // a suspended or already-ended one
+  if (!subscription || subscription.status !== 'active' || subscription.product?.id === 'basic') {
+    ctx.log(`Winback rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
+    return ctx.respond('No active paid subscription found', {
+      code: 400,
+      additional: { code: 'no-active-subscription' },
+    });
+  }
+
+  // A TRIAL is never offered this: cancelling a trial ends access immediately
+  // (#267) and nothing has been paid, so "off your next cycle" is not the offer
+  // that state needs. The billing card gates the same way, off the same rule.
+  if (isTrialing(subscription)) {
+    ctx.log(`Winback rejected: uid=${uid}, subscription is still in its free trial`);
+    return ctx.respond('This offer is not available on a free trial', {
+      code: 400,
+      additional: { code: 'trial-not-eligible' },
+    });
+  }
+
+  // The offer is made BEFORE the questionnaire, so a subscription already
+  // scheduled to end is past it. Undo cancellation is the honest verb there.
+  if (subscription.cancellation?.pending === true) {
+    ctx.log(`Winback rejected: uid=${uid}, cancellation already pending`);
+    return ctx.respond('Your subscription is already scheduled to cancel', {
+      code: 400,
+      additional: { code: 'cancellation-pending' },
+    });
+  }
+
+  const provider = subscription.payment?.provider;
+  const resourceId = subscription.payment?.resourceId;
+
+  // A paid, active subscription can still carry NO provider details at all —
+  // granted by an admin, imported, a webhook backfill that never landed — and
+  // the client pitches what the account says, which is "paid and active". There
+  // is nothing to send a discount to, and no retry adds the details, so the
+  // refusal is a dead end the billing card retires the offer on ([#311]).
+  if (!provider || !resourceId) {
+    ctx.log(`Winback rejected: uid=${uid}, missing provider=${provider} or resourceId=${resourceId}`);
+    return ctx.respond('Subscription payment details not found', {
+      code: 400,
+      additional: { code: 'missing-payment-details' },
+    });
+  }
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, {
+      code: 400,
+      additional: { code: 'unknown-provider' },
+    });
+  }
+
+  // The capability gate. A missing export is the provider saying it cannot
+  // discount a live subscription at all — a CLIENT fault to be branched on, not
+  // an outage to retry, so the code rides the response properties where every
+  // 4xx carries its machine-readable half, and the billing card retires the
+  // offer and lets the cancel through on it.
+  if (typeof providerModule.applyOffer !== 'function') {
+    ctx.log(`Winback not supported: uid=${uid}, provider=${provider}`);
+    return ctx.respond('Your payment provider cannot apply this offer. Please use the billing portal to manage your subscription.', {
+      code: 400,
+      additional: { code: 'not-supported-by-provider' },
+    });
+  }
+
+  // One claim per subscription. The order doc is where the claim lives, so the
+  // check reads the same document the write below lands on.
+  //
+  // No order doc, no claim — and an offer whose claim cannot be RECORDED is an
+  // offer takeable every time the cancel dialog opens, each accept re-couponing
+  // the subscription. A subscription can reach here without one (created in the
+  // provider's dashboard, imported, a metadata backfill that never landed), so
+  // it is refused before dispatch rather than handed an offer this route cannot
+  // remember. The code rides the response properties the capability gate's does,
+  // so the billing card branches on it and lets the cancel through. It is read
+  // AFTER that gate: a provider that cannot discount at all is the more
+  // permanent answer, and it costs no read.
+  const orderId = subscription.payment?.orderId;
+
+  if (!orderId) {
+    ctx.log(`Winback rejected: uid=${uid}, the subscription carries no orderId to record the claim on`);
+    return ctx.respond('This offer is not available on your subscription. Please use the billing portal to manage your subscription.', {
+      code: 400,
+      additional: { code: 'offer-not-claimable' },
+    });
+  }
+
+  const admin = ctx.Manager.libraries.admin;
+  const orderRef = admin.firestore().doc(`payments-orders/${orderId}`);
+  const orderDoc = await orderRef.get();
+
+  // A past claimant reaching the cancel flow again is pitched the offer anyway
+  // — the client reads the ACCOUNT, which carries no claim — so this refusal
+  // rides the same branchable code the two gates above do ([#310]). Without
+  // one, accepting shows an error toast and leaves the dialog armed for a retry
+  // that can never succeed; with it the billing card retires the offer and
+  // opens the questionnaire, which is what the customer came for.
+  if (orderDoc.exists && orderDoc.data().requests?.winback) {
+    ctx.log(`Winback rejected: uid=${uid}, offer already claimed on payments-orders/${orderId}`);
+    return ctx.respond('You have already claimed this offer', {
+      code: 400,
+      additional: { code: 'offer-already-claimed' },
+    });
+  }
+
+  // The offer, in the shape every downstream reader already speaks
+  const discount = winback.toDiscount(offer);
+
+  try {
+    await providerModule.applyOffer({ resourceId, uid, subscription, discount, ctx });
+  } catch (e) {
+    // The provider's own words stay in the logs — a client gets one neutral
+    // sentence, never an SDK message naming our internals ([#212]).
+    ctx.error(`Failed to apply the winback offer via ${provider}: uid=${uid}, sub=${resourceId}, error=${e.message}`);
+    return ctx.respond('We could not apply your discount right now. Please try again shortly.', { code: 500 });
+  }
+
+  // Record the claim. This is the offer's whole memory: the refusal above reads
+  // it, and it is what an analysis of the experiment counts accepts from.
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  await orderRef.set({
+    requests: {
+      winback: {
+        discount: discount,
+        date: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    },
+  }, { merge: true });
+
+  ctx.log(`Stored winback claim on payments-orders/${orderId}: code=${discount.code}`);
+
+  // The ACCOUNT's half of the same claim ([#325]). The order doc is the offer's
+  // memory — what a second claim is refused against — but the billing card reads
+  // the account, and a saving that disappears on the next page load was never
+  // announced at all. The subscription itself still does not change: this is the
+  // discount riding it, not a new plan, a new cadence or a new renewal date.
+  //
+  // EVERY field is written, never the validate() result's own half-shape: the
+  // node can already carry a checkout code's discount, and a percent claim
+  // merging onto a stored amount would be read as the older, wrong number. And
+  // `source` is what makes the node safe to read as a claim at all — a checkout
+  // code sets the same shape, so only 'winback' is the cancel flow's signal.
+  //
+  // `resourceId` is the subscription it was applied TO, and it is what lets the
+  // claim ever END ([#333]). The unified webhook write carries no discount key,
+  // so the merge preserves this node forever: without the stamp, a customer who
+  // churned and resubscribed carried a spent claim into the new subscription,
+  // where `source: 'winback'` reads as "already claimed" and the save offer is
+  // silently never pitched again. Stamped, the webhook pipeline clears the node
+  // the moment the account's subscription is a different one.
+  await admin.firestore().doc(`users/${uid}`).set({
+    subscription: {
+      discount: {
+        valid: true,
+        code: discount.code,
+        percent: discount.percent || 0,
+        amount: discount.amount || 0,
+        duration: discount.duration,
+        source: 'winback',
+        resourceId: resourceId,
+      },
+    },
+  }, { merge: true });
+
+  ctx.log(`Stored the applied discount on users/${uid}: code=${discount.code}, sub=${resourceId}`);
+
+  // The experiment's server-side half. The offer is measured against the
+  // existing `subscription-winback` baseline (a returning subscriber the webhook
+  // pipeline already reads as a purchase), so the ACCEPT is recorded where that
+  // pipeline's events go — the client counts shown/declined, which never reach a
+  // server at all.
+  ctx.analytics.event('payments/winback', {
+    code: discount.code,
+    percent: discount.percent || null,
+    amount: discount.amount || null,
+    duration: discount.duration,
+    payment_provider: provider,
+    product_id: subscription.product?.id || null,
+    payment_frequency: subscription.payment?.frequency || null,
+  });
+
+  ctx.log(`Winback offer applied: uid=${uid}, provider=${provider}, sub=${resourceId}, code=${discount.code}, duration=${discount.duration}`);
+
+  return ctx.respond({ success: true, discount: discount });
+};

package/dist/manager/routes/payments/winback/providers/chargebee.js

@@ -0,0 +1,24 @@
+/**
+ * Chargebee winback provider — DELIBERATELY EMPTY, for now.
+ *
+ * Chargebee DOES have coupons, and the checkout already creates them
+ * (resolveChargebeeCoupon in routes/payments/intent/providers/chargebee.js).
+ * What it has no existing plumbing for is attaching one to a subscription that
+ * is already running: the only verb this framework drives on a live Chargebee
+ * subscription is `update_for_items`, which REPLACES the subscription's items
+ * with whatever is sent (see the plan-switch provider). Carrying a coupon
+ * through it would mean reading the live item set back and restating it on every
+ * offer — a re-pricing risk taken for a discount — and any other route to it is
+ * provider surface nothing here has proven
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * So Chargebee declares the capability it has today, which is none. The module
+ * exports NOTHING on purpose: the gate in ../post.js reads
+ * `typeof providerModule.applyOffer === 'function'`, the caller gets a
+ * `not-supported-by-provider` 400, and the billing card retires the offer and
+ * opens the questionnaire — a Chargebee subscriber can always still cancel.
+ *
+ * The file still has to EXIST: without it the route would answer "Unknown
+ * provider", which is a different (and wrong) statement about Chargebee.
+ */
+module.exports = {};

package/dist/manager/routes/payments/winback/providers/paypal.js

@@ -0,0 +1,22 @@
+/**
+ * PayPal winback provider — DELIBERATELY EMPTY.
+ *
+ * PayPal has no coupon or discount object at all. A subscription's price is the
+ * PLAN's price, and the only ways to change what a subscriber pays next are to
+ * revise them onto a different plan (which is a plan switch, not a one-cycle
+ * discount, and would leave them there) or to write a one-off pricing scheme
+ * onto the plan itself — which would move every subscriber on it. Neither is the
+ * offer, and neither rides plumbing that already exists here: the checkout's
+ * discount codes have never reached PayPal either
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * The module exports NOTHING on purpose: the capability gate in ../post.js reads
+ * `typeof providerModule.applyOffer === 'function'`, so the absent export IS the
+ * declaration, and the caller gets a `not-supported-by-provider` 400 that the
+ * billing card turns into "the offer is retired, here is the questionnaire"
+ * rather than a dead dialog ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * The file still has to EXIST: without it the route would answer "Unknown
+ * provider", which is a different (and wrong) statement about PayPal.
+ */
+module.exports = {};

package/dist/manager/routes/payments/winback/providers/stripe.js

@@ -0,0 +1,41 @@
+/**
+ * Stripe winback provider
+ * Applies the save offer to a live subscription as a coupon.
+ *
+ * The coupon is the SAME object a checkout discount code creates — deterministic
+ * id, created once, reused forever (StripeLib.resolveCoupon) — and attaching it
+ * to the subscription is what makes the next invoice cheaper. A `once` coupon
+ * discounts exactly the next cycle and then falls away on its own; a `forever`
+ * one is the permanent cut a brand asked for in config.
+ *
+ * The subscription is otherwise untouched: same price, same interval, same
+ * renewal date. Stripe then sends customer.subscription.updated, which the
+ * existing pipeline processes.
+ */
+module.exports = {
+  /**
+   * Apply the save offer to a Stripe subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Stripe subscription ID (e.g., 'sub_xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's current subscription object
+   * @param {object} options.discount - The offer as a discount-codes validate() result
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async applyOffer({ resourceId, uid, discount, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    const couponId = await StripeLib.resolveCoupon(discount, ctx);
+
+    // `discounts` REPLACES every discount already on the subscription — it is
+    // the whole list, not an addition — so an existing coupon (a retention
+    // credit, an earlier offer) is dropped when this one lands.
+    await stripe.subscriptions.update(resourceId, {
+      discounts: [{ coupon: couponId }],
+    });
+
+    ctx.log(`Stripe winback offer applied: sub=${resourceId}, uid=${uid}, coupon=${couponId}`);
+  },
+};

package/dist/manager/routes/payments/winback/providers/test.js

@@ -0,0 +1,42 @@
+/**
+ * Test winback provider
+ * Applies the save offer the way the real ones do: to the PROVIDER, not to us.
+ *
+ * The other test providers write a payments-webhooks doc, because the thing
+ * they simulate changes subscription state and the pipeline is what writes it.
+ * A coupon changes none: the plan, the cadence and the renewal date all stay
+ * exactly as they were, and the only thing that moves is the next invoice, which
+ * this framework does not model. Minting a webhook here would put an event
+ * through the pipeline that resolves to no transition at all — noise that reads
+ * like a bug the first time someone finds it in the logs.
+ *
+ * So this provider does what Stripe's does to OUR data, which is nothing, and
+ * says so. A local QA run through `_dev_cardProvider=test` still proves the
+ * whole flow end to end — the gate, the dialog, the route's guards, the claim
+ * written on payments-orders/{orderId} — against exactly the data a real
+ * provider leaves behind
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * Only available in non-production environments.
+ */
+module.exports = {
+  /**
+   * Apply the save offer to a test subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Test subscription ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's current subscription object
+   * @param {object} options.discount - The offer as a discount-codes validate() result
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async applyOffer({ resourceId, uid, discount, ctx }) {
+    if (ctx.isProduction()) {
+      throw new Error('Test provider is not available in production');
+    }
+
+    const off = discount.amount > 0 ? `${discount.amount} off` : `${discount.percent}%`;
+
+    ctx.log(`Test winback provider: applied ${discount.code} (${off}, ${discount.duration}) to sub=${resourceId}, uid=${uid}`);
+  },
+};

package/dist/manager/routes/restart/index.js

@@ -0,0 +1,37 @@
+const jetpack = require('fs-jetpack');
+
+module.exports = async ({ ctx, user, analytics }) => {
+
+  // Send analytics event
+  analytics.event('restart', {});
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required', { code: 403 });
+  }
+
+  // Log
+  ctx.log('Restarting...');
+
+  // Remove node_modules
+  jetpack.remove('node_modules');
+
+  // Perform delayed refresh to allow a successful response
+  setTimeout(function () {
+    require('child_process').exec('refresh', (error, stdout, stderr) => {
+      // Quit the process if there is an error
+      if (error || stderr) {
+        console.log(`error: ${error ? error.message : stderr}`);
+        return process.exit(1);
+      }
+    });
+  }, 1000);
+
+  // Return success
+  return ctx.respond({success: true});
+};