@omega.js/backend 0.1.0

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

@@ -0,0 +1,341 @@
+const fetch = require('wonderful-fetch');
+const powertools = require('node-powertools');
+const discountCodes = require('../../../../libraries/payment/discount-codes.js');
+const env = require('../../../../libraries/env.js');
+
+// A declined subscription fires two events, and the second one reads what the
+// first one wrote — how long it waits for that, and how often it looks
+const ORDER_WAIT_ATTEMPTS = 40;
+const ORDER_WAIT_INTERVAL = 500;
+
+/**
+ * Test intent provider
+ * Creates fake Stripe-shaped checkout sessions and auto-fires webhooks
+ * Only available in non-production environments
+ */
+module.exports = {
+  /**
+   * Create a test payment intent
+   * Generates Stripe-shaped data and auto-fires a webhook to trigger the full pipeline
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {object} options.product - Full product object from config
+   * @param {string} options.productId - Product ID from config
+   * @param {string} options.frequency - 'monthly', 'annually', 'weekly', or 'daily' (subscriptions only)
+   * @param {boolean} options.trial - Whether to include a trial period (subscriptions only)
+   * @param {object} options.discount - Validated discount from discount-codes.validate(), or null
+   * @param {string} options.simulate - Checkout outcome to simulate ('decline' | 'abandon'), or null for success
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
+   * @param {object} options.ctx - Assistant instance
+   * @returns {object} { id, url, raw }
+   */
+  async createIntent({ uid, orderId, product, productId, frequency, trial, discount, simulate, confirmationUrl, ctx }) {
+    // Guard: test provider is not available in production
+    if (ctx.isProduction()) {
+      throw new Error('Test provider is not available in production');
+    }
+
+    const productType = product.type || 'subscription';
+    const declined = simulate === 'decline';
+    // An ABANDONED checkout is the absence of an event, not a different one: the
+    // session is created, the customer closes the tab, and the provider has
+    // nothing to report. So the session comes back exactly as it always does and
+    // no webhook is fired — the state under test is what that leaves behind
+    // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+    const abandoned = simulate === 'abandon';
+
+    if (productType === 'subscription') {
+      return createSubscriptionIntent({ uid, orderId, product, frequency, trial, discount, declined, abandoned, confirmationUrl, ctx });
+    }
+
+    return createOneTimeIntent({ uid, orderId, product, productId, discount, declined, abandoned, confirmationUrl, ctx });
+  },
+};
+
+/**
+ * Create a test subscription intent
+ * Generates Stripe-shaped subscription + customer.subscription.created event
+ *
+ * A declined checkout mirrors what a real provider does: the subscription is
+ * created in a dunning state (past_due → suspended) and its first invoice fails.
+ */
+async function createSubscriptionIntent({ uid, orderId, product, frequency, trial, discount, declined, abandoned, confirmationUrl, ctx }) {
+  // Generate IDs
+  const timestamp = Date.now();
+  const sessionId = `_test-cs-${timestamp}`;
+  const subscriptionId = `_test-sub-${timestamp}`;
+  const eventId = `_test-evt-${timestamp}`;
+  const invoiceId = `_test-in-${timestamp}`;
+
+  // Map frequency to Stripe interval
+  const FREQUENCY_TO_INTERVAL = { annually: 'year', monthly: 'month', weekly: 'week', daily: 'day' };
+  const FREQUENCY_TO_PERIOD = { annually: 365 * 86400, monthly: 30 * 86400, weekly: 7 * 86400, daily: 1 * 86400 };
+  const interval = FREQUENCY_TO_INTERVAL[frequency] || 'month';
+
+  // Build timestamps
+  const now = Math.floor(timestamp / 1000);
+  const periodEnd = now + (FREQUENCY_TO_PERIOD[frequency] || 30 * 86400);
+
+  // Build Stripe-shaped subscription object.
+  // Prefer the real Stripe product ID if configured; otherwise use a sentinel of the
+  // form "_test_<id>" that the Stripe resolver recognizes and maps back to product.id.
+  // This lets the test provider work in brands that haven't wired up Stripe yet.
+  const planProductId = product.stripe?.productId || `_test_${product.id}`;
+
+  const subscription = {
+    id: subscriptionId,
+    object: 'subscription',
+    status: declined ? 'past_due' : (trial && product.trial?.days ? 'trialing' : 'active'),
+    metadata: { uid, orderId },
+    plan: { product: planProductId, interval },
+    current_period_end: periodEnd,
+    current_period_start: now,
+    start_date: now,
+    cancel_at_period_end: false,
+    cancel_at: null,
+    canceled_at: null,
+    trial_start: null,
+    trial_end: null,
+  };
+
+  // Add trial dates if applicable (a declined checkout claims no trial — nothing cleared)
+  if (!declined && trial && product.trial?.days) {
+    subscription.trial_start = now;
+    subscription.trial_end = now + (product.trial.days * 86400);
+    subscription.current_period_end = subscription.trial_end;
+  }
+
+  // What the coupon leaves on the first invoice — Stripe reports that reduced
+  // amount back on its own events, so the fabricated ones carry it too. The route
+  // owns the confirmation URL's amount; this is the PAYLOAD's
+  // ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)). The renewal keeps
+  // the full config price — a 'once' coupon only touches the first charge.
+  const firstCharge = discountCodes.applyToAmount(product.prices?.[frequency] || 0, discount);
+
+  if (discount) {
+    subscription.discount = buildStripeDiscount(discount);
+  }
+
+  // Build Stripe-shaped event
+  const event = {
+    id: eventId,
+    type: 'customer.subscription.created',
+    data: { object: subscription },
+  };
+
+  ctx.log(`Test subscription intent: sessionId=${sessionId}, subscriptionId=${subscriptionId}, eventId=${eventId}, trial=${!!subscription.trial_start}, declined=${!!declined}, abandoned=${!!abandoned}, discount=${discount?.code || 'none'}, firstCharge=${firstCharge}`);
+
+  // Auto-fire webhook
+  if (abandoned) {
+    ctx.log(`Test subscription intent: abandoned — no webhook fired, the intent stays pending`);
+  } else if (declined) {
+    // The failed invoice names the subscription, and the pipeline resolves that
+    // subscription from the order the FIRST event wrote — so the two events go out
+    // in order, not at once.
+    fireWebhook({ event, ctx })
+      .then(() => waitForOrder({ orderId, ctx }))
+      .then(() => fireWebhook({
+        event: buildFailedInvoiceEvent({
+          uid,
+          orderId,
+          invoiceId,
+          eventId: `${eventId}-invoice`,
+          amountDue: Math.round(firstCharge * 100),
+          billingReason: 'subscription_create',
+          subscriptionId,
+        }),
+        ctx,
+      }));
+  } else {
+    fireWebhook({ event, ctx });
+  }
+
+  return {
+    id: sessionId,
+    url: confirmationUrl,
+    raw: { id: sessionId, object: 'checkout.session', subscription: subscriptionId },
+  };
+}
+
+/**
+ * Create a test one-time payment intent
+ * Generates Stripe-shaped checkout session + checkout.session.completed event
+ *
+ * A declined checkout still creates the session — the payment is what fails, so
+ * a failed manual invoice goes out in place of the completed session.
+ */
+async function createOneTimeIntent({ uid, orderId, product, productId, discount, declined, abandoned, confirmationUrl, ctx }) {
+  // Validate that a price exists
+  if (!product.prices?.once) {
+    throw new Error(`No one-time price configured for ${product.id}`);
+  }
+
+  // Generate IDs
+  const timestamp = Date.now();
+  const sessionId = `_test-cs-${timestamp}`;
+  const invoiceId = `_test-in-${timestamp}`;
+  const eventId = `_test-evt-${timestamp}`;
+
+  // The single charge this purchase makes, after the coupon Stripe would have
+  // applied at its own checkout ([#239](https://github.com/Omega-JS-Stack/omega/issues/239))
+  const firstCharge = discountCodes.applyToAmount(product.prices.once || 0, discount);
+
+  // Build Stripe-shaped checkout session object
+  const session = {
+    id: sessionId,
+    object: 'checkout.session',
+    mode: 'payment',
+    status: 'complete',
+    payment_status: 'paid',
+    metadata: { uid, orderId, productId },
+    amount_total: Math.round(firstCharge * 100),
+    currency: 'usd',
+  };
+
+  // What Stripe's session reports about the money the coupon took off
+  if (discount) {
+    session.total_details = {
+      amount_discount: Math.round(((product.prices.once || 0) - firstCharge) * 100),
+    };
+  }
+
+  // Build Stripe-shaped event
+  const event = declined
+    ? buildFailedInvoiceEvent({
+      uid,
+      orderId,
+      productId,
+      invoiceId,
+      eventId,
+      amountDue: session.amount_total,
+      billingReason: 'manual',
+    })
+    : {
+      id: eventId,
+      type: 'checkout.session.completed',
+      data: { object: session },
+    };
+
+  ctx.log(`Test one-time intent: sessionId=${sessionId}, eventId=${eventId}, productId=${productId}, declined=${!!declined}, abandoned=${!!abandoned}, discount=${discount?.code || 'none'}, firstCharge=${firstCharge}`);
+
+  // Auto-fire webhook
+  if (abandoned) {
+    ctx.log(`Test one-time intent: abandoned — no webhook fired, the intent stays pending`);
+  } else {
+    fireWebhook({ event, ctx });
+  }
+
+  return {
+    id: sessionId,
+    url: confirmationUrl,
+    raw: { id: sessionId, object: 'checkout.session', mode: 'payment' },
+  };
+}
+
+/**
+ * Build the Stripe-shaped discount a coupon leaves on the resource
+ *
+ * Stripe attaches the coupon it applied to the subscription, so a reader of the
+ * webhook can see WHICH code moved the amount. `amount` is dollars on our side and
+ * cents on Stripe's, the same as `percent` → `percent_off`.
+ *
+ * @param {object} discount - Validated discount from discount-codes.validate()
+ * @returns {object} Stripe-shaped discount object
+ */
+function buildStripeDiscount(discount) {
+  return {
+    id: `_test-di-${discount.code}`,
+    object: 'discount',
+    coupon: {
+      id: `_test-coupon-${discount.code}`,
+      object: 'coupon',
+      name: discount.code,
+      percent_off: discount.percent || null,
+      amount_off: discount.amount ? Math.round(discount.amount * 100) : null,
+      duration: discount.duration || 'once',
+    },
+  };
+}
+
+/**
+ * Build a Stripe-shaped invoice.payment_failed event
+ *
+ * `billingReason` is what the webhook parser reads to route the event: a
+ * 'subscription*' reason (with a subscription) resolves to the subscription,
+ * anything else ('manual') to the one-time invoice itself.
+ */
+function buildFailedInvoiceEvent({ uid, orderId, productId, invoiceId, eventId, amountDue, billingReason, subscriptionId }) {
+  const invoice = {
+    id: invoiceId,
+    object: 'invoice',
+    billing_reason: billingReason,
+    amount_due: amountDue,
+    amount_paid: 0,
+    status: 'open',
+    metadata: { uid, orderId },
+  };
+
+  // Only the one-time side carries a product on the invoice — the subscription
+  // side resolves its product from the subscription
+  if (productId) {
+    invoice.metadata.productId = productId;
+  }
+
+  if (subscriptionId) {
+    invoice.parent = {
+      type: 'subscription_details',
+      subscription_details: {
+        subscription: subscriptionId,
+        metadata: { uid, orderId },
+      },
+    };
+  }
+
+  return {
+    id: eventId,
+    type: 'invoice.payment_failed',
+    data: { object: invoice },
+  };
+}
+
+/**
+ * Wait for the order the first webhook writes
+ *
+ * Only the declined subscription path needs this: the pipeline answers the failed
+ * invoice's subscription lookup out of payments-orders, so the invoice event that
+ * arrives before the order exists resolves against nothing.
+ */
+async function waitForOrder({ orderId, ctx }) {
+  const ref = ctx.Manager.libraries.admin.firestore().doc(`payments-orders/${orderId}`);
+
+  for (let attempt = 0; attempt < ORDER_WAIT_ATTEMPTS; attempt++) {
+    const doc = await ref.get();
+
+    if (doc.exists) {
+      return true;
+    }
+
+    await powertools.wait(ORDER_WAIT_INTERVAL);
+  }
+
+  ctx.warn(`Test provider: payments-orders/${orderId} never landed after ${(ORDER_WAIT_ATTEMPTS * ORDER_WAIT_INTERVAL) / 1000}s — firing the failed invoice anyway, it will resolve against whatever state exists`);
+  return false;
+}
+
+/**
+ * Fire-and-forget webhook to trigger the full pipeline
+ * Returns the request so a caller that must order two events can chain them
+ */
+function fireWebhook({ event, ctx }) {
+  const webhookUrl = `${ctx.Manager.getApiUrl()}/omega/payments/webhook?provider=test&key=${env.get('OMEGA_WEBHOOK_KEY')}`;
+  return fetch(webhookUrl, {
+    method: 'POST',
+    response: 'json',
+    body: event,
+    timeout: 60000,
+  }).catch((e) => {
+    ctx.log(`Test provider auto-webhook failed: ${e.message}`);
+  });
+}

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

@@ -0,0 +1,147 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+
+/**
+ * POST /payments/plan
+ * Moves the authenticated user's LIVE subscription to a different plan — another
+ * product, another billing frequency, or both — without cancelling and
+ * re-subscribing. Delegates to the provider (e.g., Stripe) to swap the price on
+ * the existing subscription. The resulting webhook triggers the Firestore pipeline
+ * which updates subscription state and fires the plan-changed transition handler.
+ * This route writes no subscription state of its own, exactly like cancel.
+ * Requires authentication.
+ *
+ * Cross-provider and CAPABILITY-GATED: a provider that can move a live
+ * subscription exports switchPlan(), 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)).
+ *
+ * A switch NEVER grants, resets, or extends a trial (Ian 2026-08-14,
+ * [#237](https://github.com/Omega-JS-Stack/omega/issues/237)): a mid-trial switch
+ * carries the trial over — same original end date, new plan. The route writes no
+ * state, so each provider's switchPlan() is what preserves it through the swap.
+ */
+module.exports = async ({ ctx, Manager, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const productId = settings.productId;
+  const frequency = settings.frequency;
+
+  // Require explicit confirmation
+  if (!settings.confirmed) {
+    return ctx.respond('Plan change must be confirmed', { code: 400 });
+  }
+
+  const subscription = user.subscription;
+
+  // Require an active paid subscription — there is nothing to move otherwise
+  if (!subscription || subscription.status !== 'active' || subscription.product?.id === 'basic') {
+    ctx.log(`Plan change rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
+    return ctx.respond('No active paid subscription found', { code: 400 });
+  }
+
+  // A cancellation already in flight is a decision of its own. The providers
+  // swap the PRICE, never the schedule, so a switch here would land the caller
+  // on a new plan still set to end at period end — silently. Undo the
+  // cancellation first; that is the honest button ([#237]).
+  if (subscription.cancellation?.pending === true) {
+    ctx.log(`Plan change rejected: uid=${uid}, cancellation pending`);
+    return ctx.respond('Your subscription is scheduled to cancel. Undo the cancellation before changing plans.', {
+      code: 400,
+      additional: { code: 'cancellation-pending' },
+    });
+  }
+
+  // Validate the target product against the brand's own config — the same
+  // resolution the intent route does, over the same products array
+  const product = (Manager.config.payment?.products || []).find(p => p.id === productId);
+
+  if (!product) {
+    ctx.log(`Plan change rejected: uid=${uid}, product "${productId}" not found (available: ${(Manager.config.payment?.products || []).map(p => p.id).join(', ')})`);
+    return ctx.respond(`Product '${productId}' not found`, { code: 400 });
+  }
+
+  const productType = product.type || 'subscription';
+
+  // A subscription can only move to another subscription plan
+  if (productType !== 'subscription' || productId === 'basic') {
+    ctx.log(`Plan change rejected: uid=${uid}, target product=${productId} is type=${productType}`);
+    return ctx.respond(`Product '${productId}' is not a subscription plan`, { code: 400 });
+  }
+
+  // The target has to be a plan the brand actually sells at that frequency —
+  // catching it here keeps a client-fault input from surfacing as a 500 out of
+  // the provider's price lookup
+  if (!product.prices?.[frequency]) {
+    ctx.log(`Plan change rejected: uid=${uid}, no ${frequency} price for product=${productId}`);
+    return ctx.respond(`Product '${productId}' is not sold ${frequency}`, { code: 400 });
+  }
+
+  // The switch has to BE a switch: same product at the same frequency is a
+  // no-op, and dispatching one costs a real provider call and a real webhook.
+  // The guard lives HERE and never leans on the client's own filtering — the
+  // modal's filter silently misses when the recorded frequency is absent
+  // ([#236]), and the trial the no-op switch used to end was real.
+  //
+  // An UNRECORDED current frequency refuses the whole product: `'monthly' ===
+  // undefined` is false, so a pair comparison alone would sail the no-op through
+  // to a real provider call — the exact state the QA repro was in. Both cadences
+  // are refused until the backend records one, mirroring the modal's own
+  // conservatism ([#236]).
+  const currentProductId = subscription.product?.id;
+  const currentFrequency = subscription.payment?.frequency;
+
+  if (productId === currentProductId && (!currentFrequency || frequency === currentFrequency)) {
+    ctx.log(`Plan change rejected: uid=${uid}, already on product=${productId}, frequency=${frequency} (current frequency: ${currentFrequency || 'unrecorded'})`);
+    return ctx.respond('You are already on that plan', {
+      code: 400,
+      additional: { code: 'already-on-plan' },
+    });
+  }
+
+  const provider = subscription.payment?.provider;
+  const resourceId = subscription.payment?.resourceId;
+
+  if (!provider || !resourceId) {
+    ctx.log(`Plan change rejected: uid=${uid}, missing provider=${provider} or resourceId=${resourceId}`);
+    return ctx.respond('Subscription payment details not found', { code: 400 });
+  }
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // The capability gate. A missing export is the provider saying it cannot do
+  // this 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 sentence points at the fallback that works.
+  if (typeof providerModule.switchPlan !== 'function') {
+    ctx.log(`Plan change not supported: uid=${uid}, provider=${provider}`);
+    return ctx.respond('Your payment provider cannot change plans here. Please use the billing portal to manage your subscription.', {
+      code: 400,
+      additional: { code: 'not-supported-by-provider' },
+    });
+  }
+
+  // Swap the plan via the provider
+  try {
+    await providerModule.switchPlan({ resourceId, uid, subscription, product, productType, frequency, 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 change plan via ${provider}: uid=${uid}, sub=${resourceId}, product=${productId}, frequency=${frequency}, error=${e.message}`);
+    return ctx.respond('We could not change your plan right now. Please try again shortly.', { code: 500 });
+  }
+
+  ctx.log(`Plan change requested: uid=${uid}, provider=${provider}, sub=${resourceId}, ${currentProductId}/${currentFrequency} → ${productId}/${frequency}`);
+
+  return ctx.respond({ success: true });
+};

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

@@ -0,0 +1,62 @@
+/**
+ * Chargebee plan-switch provider
+ * Moves a live subscription onto a different item price.
+ *
+ * update_for_items REPLACES the subscription's items with the ones sent, so the
+ * target item price is the whole payload. The item price id is the same
+ * deterministic `{itemId}-{frequency}` the checkout builds, so a plan switch
+ * lands on exactly the price a fresh subscription would have. Chargebee then
+ * sends subscription_changed, which the existing pipeline processes into the
+ * plan-changed transition.
+ */
+module.exports = {
+  /**
+   * Switch a Chargebee subscription to another plan
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Chargebee subscription ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.product - Target product object from config
+   * @param {string} options.frequency - Target billing frequency ('monthly', 'annually', …)
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async switchPlan({ resourceId, uid, product, frequency, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    const chargebeeItemId = product.chargebee?.itemId;
+
+    if (!chargebeeItemId) {
+      throw new Error(`No Chargebee item ID configured for product ${product.id}`);
+    }
+
+    // Deterministic item price ID: {itemId}-{frequency} — the checkout's own convention
+    const itemPriceId = `${chargebeeItemId}-${frequency}`;
+
+    // A switch never grants, resets, or extends a trial ([#237]): a subscription
+    // still IN its trial keeps the end date it already had, restated on the
+    // update so the new item price cannot reopen or close the trial.
+    //
+    // The date comes from the LIVE subscription, never from our own user doc —
+    // exactly like the Stripe branch reads the item it is replacing. A user doc
+    // that lags the provider would otherwise make this route MOVE the trial it
+    // is meant to preserve, or restate an end date Chargebee has already passed
+    // (a 400). A trial that is over is left alone (encodeFormData drops the null).
+    const current = await ChargebeeLib.request(`/subscriptions/${resourceId}`);
+    const live = current.subscription || current;
+    const trialEnd = live.status === 'in_trial' ? (live.trial_end || null) : null;
+
+    await ChargebeeLib.request(`/subscriptions/${resourceId}/update_for_items`, {
+      method: 'POST',
+      body: {
+        subscription_items: {
+          item_price_id: [itemPriceId],
+          quantity: [1],
+        },
+        trial_end: trialEnd,
+      },
+    });
+
+    ctx.log(`Chargebee plan switched: sub=${resourceId}, uid=${uid}, itemPriceId=${itemPriceId} (${product.id}/${frequency}), trialEnd=${trialEnd || 'none'}`);
+  },
+};

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

@@ -0,0 +1,62 @@
+/**
+ * PayPal plan-switch provider
+ * Moves a live subscription onto a different plan via revise.
+ *
+ * Unlike uncancel — which PayPal has no verb for at all — revise is PayPal's
+ * first-class plan change: it swaps the plan on an ACTIVE subscription and
+ * prorates by its own rules. PayPal then sends BILLING.SUBSCRIPTION.UPDATED,
+ * which the existing pipeline processes into the plan-changed transition.
+ *
+ * The plan id is resolved from config at runtime (product + frequency → the
+ * matching active PayPal plan), the same resolution the checkout uses, so a
+ * switch lands on exactly the plan a fresh subscription would have.
+ *
+ * Trials ([#237]): revise takes no trial parameter, so unlike Stripe and
+ * Chargebee there is nothing to restate here. PayPal exposes no trial dates at
+ * all — the library derives them from the PLAN's `TRIAL` billing cycle anchored
+ * to the subscription's original `start_time` — so a revise cannot extend a
+ * trial past what it would have been from day one. It can still shift the end
+ * date when the target plan's trial is a different LENGTH; a brand that prices
+ * unequal trials on PayPal needs the plans reconciled, not this route patched.
+ *
+ * Which is why the plan lookup is asked for a TWIN ([#761]): a trial product
+ * carries one plan with the TRIAL cycle and one without, so a switcher still
+ * inside a trial has to land on the trial twin to carry that trial over, and a
+ * PAYING switcher has to land on the twin with no free cycle on it — landing
+ * a paying subscriber on a trial plan would read them as trialing everywhere
+ * the backend asks.
+ */
+const isTrialing = require('../../cancel/_is-trialing.js');
+
+module.exports = {
+  /**
+   * Switch a PayPal subscription to another plan
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - PayPal subscription ID (e.g., 'I-xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - The user's current subscription (picks the trial twin)
+   * @param {object} options.product - Target product object from config
+   * @param {string} options.frequency - Target billing frequency ('monthly', 'annually', …)
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async switchPlan({ resourceId, uid, subscription, product, frequency, ctx }) {
+    const PayPalLib = require('../../../../libraries/payment/providers/paypal.js');
+
+    // The twin is a property of the TARGET product: a trial-less product has
+    // no trial twin to carry a trial over to, so a switcher mid-trial lands on
+    // its one plan (the trial ends, as the header says it may) instead of a
+    // lookup for a plan no manage run will ever mint
+    const carryTrial = isTrialing(subscription) && !!product.trial?.days;
+    const planId = await PayPalLib.resolvePlanId(product, frequency, carryTrial);
+
+    await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}/revise`, {
+      method: 'POST',
+      body: JSON.stringify({
+        plan_id: planId,
+      }),
+    });
+
+    ctx.log(`PayPal plan switched: sub=${resourceId}, uid=${uid}, plan=${planId} (${product.id}/${frequency})`);
+  },
+};

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

@@ -0,0 +1,59 @@
+/**
+ * Stripe plan-switch provider
+ * Moves a live subscription onto a different price, prorating the difference.
+ *
+ * Stripe swaps plans by updating the subscription's ITEM: the existing item's id
+ * has to be sent alongside the new price, or Stripe adds a second item instead of
+ * replacing the first. proration_behavior 'create_prorations' credits the unused
+ * part of the current period and charges the new plan pro rata on the next
+ * invoice. Stripe then sends customer.subscription.updated, which the existing
+ * pipeline processes into the plan-changed transition.
+ */
+module.exports = {
+  /**
+   * Switch a Stripe subscription to another plan
+   *
+   * @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.product - Target product object from config
+   * @param {string} options.productType - Target product type ('subscription')
+   * @param {string} options.frequency - Target billing frequency ('monthly', 'annually', …)
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async switchPlan({ resourceId, uid, product, productType, frequency, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    const priceId = await StripeLib.resolvePriceId(product, productType, frequency);
+
+    // The item being replaced — read from the live subscription, never assumed
+    const current = await stripe.subscriptions.retrieve(resourceId);
+    const itemId = current.items?.data?.[0]?.id;
+
+    if (!itemId) {
+      throw new Error(`Stripe subscription ${resourceId} has no subscription item to update`);
+    }
+
+    const update = {
+      items: [{ id: itemId, price: priceId }],
+      proration_behavior: 'create_prorations',
+    };
+
+    // A switch never grants, resets, or extends a trial ([#237]): a subscription
+    // still IN its trial keeps the end date it already had, sent back to Stripe
+    // explicitly so the carry-over is this route's statement rather than a
+    // default we inherit. A trial that already ended is left alone — Stripe
+    // rejects a trial_end in the past, and its dates stay on the object anyway.
+    const nowUNIX = Math.floor(Date.now() / 1000);
+    const trialing = current.status === 'trialing' && current.trial_end > nowUNIX;
+
+    if (trialing) {
+      update.trial_end = current.trial_end;
+    }
+
+    await stripe.subscriptions.update(resourceId, update);
+
+    ctx.log(`Stripe plan switched: sub=${resourceId}, uid=${uid}, item=${itemId}, price=${priceId} (${product.id}/${frequency}), trialEnd=${trialing ? current.trial_end : 'none'}`);
+  },
+};