@omega.js/backend 0.1.0

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

@@ -0,0 +1,113 @@
+const powertools = require('node-powertools');
+
+/**
+ * Test plan-switch provider
+ * Simulates the Stripe webhook that results from a plan change by writing
+ * directly to payments-webhooks/{eventId} with status=pending. The on-write
+ * trigger picks it up and runs the full pipeline.
+ *
+ * The event is customer.subscription.updated carrying the NEW product and the NEW
+ * billing interval, so the existing plan-changed transition fires naturally — the
+ * route needs no pipeline work of its own.
+ *
+ * It also carries the EXISTING trial forward, exactly as Stripe keeps trial_start
+ * and trial_end on a subscription whose item was swapped. Fabricating them as null
+ * is what ended a live trial on switch ([#237]) — the unified transform reads
+ * `trial.claimed` straight off the event, and the user-doc write is a merge.
+ *
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async switchPlan({ resourceId, uid, subscription, product, frequency, ctx }) {
+    if (ctx.isProduction()) {
+      throw new Error('Test provider is not available in production');
+    }
+
+    const admin = ctx.Manager.libraries.admin;
+
+    const timestamp = Date.now();
+    const now = Math.floor(timestamp / 1000);
+    const periodEnd = now + (30 * 86400);
+
+    // The TARGET product's Stripe ID — this is what makes the pipeline resolve the
+    // new plan. Falls back to the "_test_<id>" sentinel when no real Stripe
+    // product is configured.
+    const stripeProductId = product.stripe?.productId || `_test_${product.id}`;
+
+    const FREQUENCY_TO_INTERVAL = { annually: 'year', monthly: 'month', weekly: 'week', daily: 'day' };
+    const interval = FREQUENCY_TO_INTERVAL[frequency] || 'month';
+
+    const eventType = 'customer.subscription.updated';
+    const eventId = `_test-evt-plan-${timestamp}`;
+
+    const startDate = subscription?.payment?.startDate?.timestampUNIX || (now - (30 * 86400));
+
+    // The trial rides along untouched: a claimed trial keeps its ORIGINAL end
+    // date on the new plan, and the subscription is still `trialing` while that
+    // date is ahead of us — the same two facts Stripe reports after an item swap.
+    const trialEnd = subscription?.trial?.claimed ? (subscription.trial.expires?.timestampUNIX || null) : null;
+    const trialStart = trialEnd ? startDate : null;
+    const trialing = !!trialEnd && trialEnd > now;
+
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: trialing ? 'trialing' : 'active',
+      metadata: { uid, orderId: subscription?.payment?.orderId || null },
+      cancel_at_period_end: false,
+      cancel_at: null,
+      canceled_at: null,
+      // While a subscription is trialing, Stripe's current period IS the trial
+      // period — and the cancel providers read that equality (`trial.expires`
+      // === `expires`) to decide a cancellation is immediate. Fabricating a
+      // 30-day period under a live trial would break cancel-immediacy after a
+      // switch and misreport the next billing date.
+      current_period_end: trialing ? trialEnd : periodEnd,
+      current_period_start: trialing ? trialStart : now,
+      start_date: startDate,
+      trial_start: trialStart,
+      trial_end: trialEnd,
+      plan: { product: stripeProductId, interval: interval },
+    };
+
+    const nowTs = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(nowTs, { output: 'unix' });
+
+    // Write directly to payments-webhooks — on-write trigger handles the rest
+    await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+      id: eventId,
+      provider: 'test',
+      status: 'pending',
+      owner: uid,
+      raw: {
+        id: eventId,
+        type: eventType,
+        data: { object: subscriptionObj },
+      },
+      event: {
+        type: eventType,
+        category: 'subscription',
+        resourceType: 'subscription',
+        resourceId: resourceId,
+      },
+      error: null,
+      // The SAME keys the webhook route writes ([../../webhook/post.js]) — the
+      // pipeline's staleness clock reads `metadata.created.timestampUNIX`, so a
+      // synthetic doc spelling it `received` handed the clock nothing and rode a
+      // now-fallback that made every test-processor event look freshly arrived
+      // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+      metadata: {
+        created: {
+          timestamp: nowTs,
+          timestampUNIX: nowUNIX,
+        },
+        completed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+    });
+
+    ctx.log(`Test plan provider: wrote payments-webhooks/${eventId} (${eventType}) for sub=${resourceId}, uid=${uid}, product=${product.id}, frequency=${frequency}, trialEnd=${trialEnd}`);
+  },
+};

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

@@ -0,0 +1,113 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+
+// Where a portal session returns to when the caller names no URL of its own, or
+// names one that is not the brand's — the account page's billing section, the
+// same destination the transactional emails link to.
+const DEFAULT_RETURN_PATH = '/dashboard/account#billing';
+
+/**
+ * POST /payments/portal
+ * Creates a Stripe Billing Portal session for the authenticated user.
+ * The portal allows managing payment methods and viewing invoices,
+ * but does NOT allow cancellation (users must use POST /payments/cancel).
+ * Requires authentication.
+ */
+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 returnUrl = resolveReturnUrl(Manager, ctx, settings.returnUrl, uid);
+  const subscription = user.subscription;
+
+  // Require a paid subscription (any status — suspended users can still manage billing)
+  if (!subscription || subscription.product?.id === 'basic') {
+    ctx.log(`Portal rejected: uid=${uid}, product=${subscription?.product?.id}`);
+    return ctx.respond('No paid subscription found', { code: 400 });
+  }
+
+  const provider = subscription.payment?.provider;
+
+  if (!provider) {
+    ctx.log(`Portal rejected: uid=${uid}, no provider set`);
+    return ctx.respond('Subscription payment provider 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 });
+  }
+
+  // Create the portal session via the provider
+  const email = user.auth?.email || null;
+  let result;
+  try {
+    result = await providerModule.createPortalSession({ uid, email, returnUrl, 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 create ${provider} portal session: uid=${uid}, error=${e.message}`);
+    return ctx.respond('We could not open your billing portal right now. Please try again shortly.', { code: 500 });
+  }
+
+  ctx.log(`Portal session created: uid=${uid}, provider=${provider}`);
+
+  return ctx.respond({ url: result.url });
+};
+
+/**
+ * Resolve the URL the provider sends the user back to.
+ *
+ * `returnUrl` is client-settable and lands in the provider's hosted page, so an
+ * arbitrary host would make the brand's own billing portal a redirector to
+ * anywhere. Only the brand's OWN origins pass — the resolved website URL (which
+ * is localhost during a dev/test run) and the configured brand URL. Anything
+ * else, and anything unparseable, falls back to the brand's account page with a
+ * warning ([#212]).
+ *
+ * @param {object} Manager - The @omega.js/backend Manager
+ * @param {object} ctx - Assistant instance for logging
+ * @param {string|null} returnUrl - The caller's requested return URL
+ * @param {string} uid - User's UID (for logging)
+ * @returns {string} A URL on one of the brand's own origins
+ */
+function resolveReturnUrl(Manager, ctx, returnUrl, uid) {
+  const websiteUrl = Manager.project.websiteUrl;
+  const fallback = new URL(DEFAULT_RETURN_PATH, websiteUrl).toString();
+
+  if (!returnUrl) {
+    return fallback;
+  }
+
+  const allowedOrigins = [websiteUrl, Manager.config.brand?.url]
+    .filter(Boolean)
+    .map((url) => safeOrigin(url))
+    .filter(Boolean);
+
+  const requestedOrigin = safeOrigin(returnUrl);
+
+  if (requestedOrigin && allowedOrigins.includes(requestedOrigin)) {
+    return returnUrl;
+  }
+
+  ctx.warn(`Ignoring off-brand portal returnUrl "${returnUrl}" from uid=${uid} (allowed: ${allowedOrigins.join(', ') || 'none'}) — returning to ${fallback}`);
+
+  return fallback;
+}
+
+/**
+ * The origin of a URL, or null when it does not parse as one.
+ */
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch (e) {
+    return null;
+  }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Chargebee portal provider
+ * Creates a Chargebee Self-Serve Portal session for the customer.
+ *
+ * The portal session provides an access_url that expires after 1 hour.
+ * Once accessed, the session remains valid until the user logs out.
+ */
+module.exports = {
+  /**
+   * Create a Chargebee Portal session
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.email - User's email
+   * @param {string|null} options.returnUrl - URL to redirect after logout
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {object} { url }
+   */
+  async createPortalSession({ uid, email, returnUrl, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    // Chargebee portal sessions require a customer ID.
+    // The customer_id in Chargebee is set during subscription checkout.
+    // We look up the subscription to find the Chargebee customer_id.
+    const admin = ctx.Manager.libraries.admin;
+    const userDoc = await admin.firestore().doc(`users/${uid}`).get();
+    const subscription = userDoc.data()?.subscription;
+
+    if (!subscription?.payment?.resourceId) {
+      throw new Error('No active subscription found for portal access');
+    }
+
+    // Fetch the subscription to get the customer_id
+    const subResult = await ChargebeeLib.request(`/subscriptions/${subscription.payment.resourceId}`);
+    const customerId = subResult.subscription?.customer_id;
+
+    if (!customerId) {
+      throw new Error('Could not resolve Chargebee customer ID');
+    }
+
+    // Create portal session
+    const params = {
+      customer: { id: customerId },
+    };
+
+    if (returnUrl) {
+      params.redirect_url = returnUrl;
+    }
+
+    const result = await ChargebeeLib.request('/portal_sessions', {
+      method: 'POST',
+      body: params,
+    });
+
+    const portalSession = result.portal_session;
+
+    ctx.log(`Chargebee portal session created: uid=${uid}, customerId=${customerId}, url=${portalSession.access_url}`);
+
+    return { url: portalSession.access_url };
+  },
+};

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

@@ -0,0 +1,25 @@
+/**
+ * PayPal portal provider
+ * PayPal does not have a hosted billing portal like Stripe.
+ * Returns a link to PayPal's subscription management page.
+ */
+module.exports = {
+  /**
+   * Get the PayPal subscription management URL
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.email - User's email (not used for PayPal)
+   * @param {string|null} options.returnUrl - Not used for PayPal
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {object} { url }
+   */
+  async createPortalSession({ uid, email, returnUrl, ctx }) {
+    // PayPal subscribers manage their subscription directly at PayPal
+    const url = 'https://www.paypal.com/myaccount/autopay/';
+
+    ctx.log(`PayPal portal redirect: uid=${uid}, url=${url}`);
+
+    return { url };
+  },
+};

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

@@ -0,0 +1,62 @@
+/**
+ * Stripe portal provider
+ * Creates a Stripe Billing Portal session with cancellation disabled.
+ * The portal config is lazily created and cached per cold start.
+ */
+
+// Cached portal configuration ID (no cancellation allowed)
+let portalConfigId = null;
+
+module.exports = {
+  /**
+   * Create a Stripe Billing Portal session
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.email - User's email (for customer resolution)
+   * @param {string|null} options.returnUrl - URL to return to after portal session
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {object} { url }
+   */
+  async createPortalSession({ uid, email, returnUrl, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    // Resolve the Stripe customer for this user
+    const customer = await StripeLib.resolveCustomer(uid, email, ctx);
+
+    // Lazily create and cache a portal configuration with cancellation disabled
+    if (!portalConfigId) {
+      const config = await stripe.billingPortal.configurations.create({
+        business_profile: {
+          headline: 'Manage your subscription',
+        },
+        features: {
+          subscription_cancel: { enabled: false },
+          subscription_update: { enabled: false },
+          payment_method_update: { enabled: true },
+          invoice_history: { enabled: true },
+        },
+      });
+
+      portalConfigId = config.id;
+      ctx.log(`Created Stripe portal config: ${portalConfigId}`);
+    }
+
+    // Build session params
+    const sessionParams = {
+      customer: customer.id,
+      configuration: portalConfigId,
+    };
+
+    if (returnUrl) {
+      sessionParams.return_url = returnUrl;
+    }
+
+    const session = await stripe.billingPortal.sessions.create(sessionParams);
+
+    ctx.log(`Stripe portal session created: uid=${uid}, customerId=${customer.id}, url=${session.url}`);
+
+    return { url: session.url };
+  },
+};

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

@@ -0,0 +1,18 @@
+/**
+ * Test portal provider
+ * Returns a fake portal URL — no external API calls.
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async createPortalSession({ uid, returnUrl, ctx }) {
+    if (ctx.isProduction()) {
+      throw new Error('Test provider is not available in production');
+    }
+
+    const url = returnUrl || 'https://example.com/account';
+
+    ctx.log(`Test portal session: uid=${uid}, url=${url}`);
+
+    return { url };
+  },
+};

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

@@ -0,0 +1,207 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const { OUTSIDE_WINDOW_MESSAGE, isWithinRefundWindow, oneTimeRefundRefusal } = require('../../../libraries/payment/refund-policy.js');
+
+/**
+ * POST /payments/refund
+ * Refunds a purchase. Two subjects, one endpoint:
+ *
+ * - No `orderId` — the authenticated user's SUBSCRIPTION. Refunds the latest
+ *   payment and cancels immediately; requires the subscription to be cancelled or
+ *   pending cancellation first.
+ * - With `orderId` — a ONE-TIME purchase, named by its payments-orders doc. A
+ *   one-time purchase never touches the user doc, so the order IS the subject
+ *   ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * Delegates to the provider (e.g., Stripe) to issue the refund. The resulting
+ * webhook triggers the Firestore pipeline, which fires the matching transition
+ * handler (subscription-cancelled / purchase-refunded).
+ * Stores the refund reason/feedback on payments-orders/{orderId}.requests.refund.
+ * 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('Refund must be confirmed', { code: 400 });
+  }
+
+  // A named order is a one-time purchase — its own subject, its own guards
+  if (settings.orderId) {
+    return refundOneTimePurchase({ ctx, uid, settings });
+  }
+
+  const subscription = user.subscription;
+
+  // Require a paid subscription
+  if (!subscription || subscription.product?.id === 'basic') {
+    ctx.log(`Refund rejected: uid=${uid}, no paid subscription`);
+    return ctx.respond('No paid subscription found', { code: 400 });
+  }
+
+  // Require cancelled or pending cancellation — cannot refund an active subscription
+  const isCancelled = subscription.status === 'cancelled';
+  const isPendingCancel = subscription.cancellation?.pending === true;
+
+  if (!isCancelled && !isPendingCancel) {
+    ctx.log(`Refund rejected: uid=${uid}, status=${subscription.status}, pending=${subscription.cancellation?.pending}`);
+    return ctx.respond('Subscription must be cancelled or pending cancellation before requesting a refund', { code: 400 });
+  }
+
+  // Reject if the most recent payment is older than 6 months
+  const startDateUNIX = subscription.payment?.startDate?.timestampUNIX
+    || subscription.payment?.updatedBy?.date?.timestampUNIX;
+
+  if (!isWithinRefundWindow(startDateUNIX)) {
+    ctx.log(`Refund rejected: uid=${uid}, payment too old (startDate=${new Date(startDateUNIX * 1000).toISOString()})`);
+    return ctx.respond(OUTSIDE_WINDOW_MESSAGE, { code: 400 });
+  }
+
+  const provider = subscription.payment?.provider;
+  const resourceId = subscription.payment?.resourceId;
+
+  if (!provider || !resourceId) {
+    ctx.log(`Refund 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 });
+  }
+
+  // Process the refund via the provider
+  let refund;
+  try {
+    refund = await providerModule.processRefund({ resourceId, uid, subscription, 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 process refund via ${provider}: uid=${uid}, sub=${resourceId}, error=${e.message}`);
+    return ctx.respond('We could not process your refund right now. Please try again shortly.', { code: 500 });
+  }
+
+  // Store refund reason/feedback on the order doc
+  const orderId = subscription.payment?.orderId;
+
+  if (orderId) {
+    await storeRefundRequest({ ctx, orderId, refund, settings });
+  }
+
+  ctx.log(`Refund processed: uid=${uid}, provider=${provider}, sub=${resourceId}, amount=${refund.amount}, full=${refund.full}, reason=${settings.reason}`);
+
+  return ctx.respond({ success: true, refund });
+};
+
+/**
+ * Refund a ONE-TIME purchase, named by its payments-orders doc.
+ *
+ * The subject is the order, not the user doc: a one-time purchase writes nothing
+ * to users/{uid}.subscription, so there is no subscription state to check and
+ * nothing to cancel — the purchase is either refundable or it is not.
+ *
+ * @param {object} options
+ * @param {object} options.ctx - RouteContext
+ * @param {string} options.uid - The caller's UID
+ * @param {object} options.settings - Resolved request settings
+ */
+async function refundOneTimePurchase({ ctx, uid, settings }) {
+  const admin = ctx.Manager.libraries.admin;
+  const orderId = settings.orderId;
+
+  const orderSnap = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+  const order = orderSnap.exists ? orderSnap.data() : null;
+
+  // Missing and not-yours answer identically: an order id must never be a probe
+  // for whether somebody else's purchase exists
+  if (!order || order.owner !== uid) {
+    ctx.log(`Refund rejected: uid=${uid}, orderId=${orderId}, exists=${orderSnap.exists}, owner=${order?.owner || 'null'}`);
+    return ctx.respond('Order not found', { code: 400 });
+  }
+
+  // Type, already-refunded, age and payment details, in the ONE place that
+  // decides them: the account page's orders list offers its refund button off
+  // the same predicate, so a button it offers is a refund this route accepts
+  // ([#672](https://github.com/Omega-JS-Stack/omega/issues/672)).
+  const refusal = oneTimeRefundRefusal(order);
+
+  if (refusal) {
+    ctx.log(`Refund rejected: uid=${uid}, orderId=${orderId}, ${refusal.reason} (type=${order.type}, status=${order.unified?.status}, request=${!!order.requests?.refund})`);
+    return ctx.respond(refusal.message, { code: 400 });
+  }
+
+  const provider = order.provider || order.unified?.payment?.provider;
+  const resourceId = order.resourceId || order.unified?.payment?.resourceId;
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Process the refund via the provider
+  let refund;
+  try {
+    refund = await providerModule.processOneTimeRefund({ resourceId, uid, order, 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 process one-time refund via ${provider}: uid=${uid}, orderId=${orderId}, resource=${resourceId}, error=${e.message}`);
+    return ctx.respond('We could not process your refund right now. Please try again shortly.', { code: 500 });
+  }
+
+  await storeRefundRequest({ ctx, orderId, refund, settings });
+
+  ctx.log(`One-time refund processed: uid=${uid}, provider=${provider}, orderId=${orderId}, resource=${resourceId}, amount=${refund.amount}, reason=${settings.reason}`);
+
+  return ctx.respond({ success: true, refund });
+}
+
+/**
+ * Store the refund reason/feedback on the order doc.
+ *
+ * ONE shape for both subjects — the refund record on an order must not differ
+ * depending on which branch wrote it.
+ *
+ * @param {object} options
+ * @param {object} options.ctx - RouteContext
+ * @param {string} options.orderId - The payments-orders id
+ * @param {object} options.refund - What the provider returned ({ amount, currency, full })
+ * @param {object} options.settings - Resolved request settings (reason, feedback)
+ */
+async function storeRefundRequest({ ctx, orderId, refund, settings }) {
+  const admin = ctx.Manager.libraries.admin;
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  await admin.firestore().doc(`payments-orders/${orderId}`).set({
+    requests: {
+      refund: {
+        reason: settings.reason || null,
+        feedback: settings.feedback || null,
+        amount: refund.amount,
+        full: refund.full,
+        date: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    },
+  }, { merge: true });
+
+  ctx.log(`Stored refund request on payments-orders/${orderId}: reason=${settings.reason}, amount=${refund.amount}`);
+}
+