@omega.js/backend 0.1.0

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

@@ -0,0 +1,204 @@
+const powertools = require('node-powertools');
+
+/**
+ * Test refund provider
+ * Simulates the webhook a real refund produces by writing directly to
+ * payments-webhooks/{eventId} with status=pending. The on-write trigger picks it
+ * up and runs the full pipeline.
+ *
+ * - Subscription: a Stripe-shaped customer.subscription.deleted (refund +
+ *   immediate cancellation), resulting in a subscription-cancelled transition.
+ * - One-time: a Stripe-shaped charge.refunded carrying no subscription and no
+ *   invoice, resulting in a purchase-refunded transition.
+ *
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async processRefund({ resourceId, uid, subscription, 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 eventId = `_test-evt-refund-${timestamp}`;
+    const now = Math.floor(timestamp / 1000);
+
+    // Look up the Stripe product ID for the plan so resolveProduct() can match.
+    // The order doc is the first source; when there is no order (a seeded paid persona, or
+    // any state where the order is missing) the subscription's own product is the fallback —
+    // without it the plan carries product=null and the pipeline downgrades the user to Basic
+    // mid-refund instead of recording the cancelled paid subscription
+    // ([#216](https://github.com/Omega-JS-Stack/omega/issues/216), the #210 fix on this path).
+    const orderId = subscription?.payment?.orderId;
+    let productId = null;
+
+    if (orderId) {
+      const orderDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+      if (orderDoc.exists) {
+        productId = orderDoc.data().unified?.product?.id || null;
+      }
+    }
+
+    productId = productId || subscription?.product?.id || null;
+
+    // Falls back to the "_test_<id>" sentinel when no real Stripe product is configured.
+    const products = ctx.Manager.config.payment?.products || [];
+    const product = products.find(p => p.id === productId);
+    const stripeProductId = product
+      ? (product.stripe?.productId || `_test_${product.id}`)
+      : null;
+
+    // Build a Stripe-shaped customer.subscription.deleted payload
+    // Mirrors what Stripe sends after an immediate cancellation (refund + cancel)
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: 'canceled',
+      metadata: { uid, orderId },
+      cancel_at_period_end: false,
+      cancel_at: null,
+      canceled_at: now,
+      current_period_end: now,
+      current_period_start: now - (30 * 86400),
+      start_date: now - (30 * 86400),
+      trial_start: null,
+      trial_end: null,
+      plan: { product: stripeProductId, interval: 'month' },
+    };
+
+    // Write directly to payments-webhooks — on-write trigger handles the rest
+    await writeWebhook({
+      admin,
+      eventId,
+      uid,
+      eventType: 'customer.subscription.deleted',
+      dataObject: subscriptionObj,
+      event: {
+        category: 'subscription',
+        resourceType: 'subscription',
+        resourceId: resourceId,
+      },
+    });
+
+    ctx.log(`Test refund provider: wrote payments-webhooks/${eventId} for sub=${resourceId}, uid=${uid}`);
+
+    // Return mock refund result
+    return {
+      amount: subscription?.payment?.price || 0,
+      currency: 'usd',
+      full: true,
+    };
+  },
+
+  async processOneTimeRefund({ resourceId, uid, order, 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 eventId = `_test-evt-refund-one-time-${timestamp}`;
+    const amount = order?.unified?.payment?.price || 0;
+    const amountCents = Math.round(amount * 100);
+
+    // Build a Stripe-shaped charge.refunded payload. It carries no subscription
+    // and no invoice — the shape a refunded one-time purchase produces, and what
+    // the webhook parser categorizes as one-time. Its metadata is the metadata a
+    // real charge inherits from the PaymentIntent the checkout created: uid and
+    // orderId ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+    const chargeObj = {
+      id: `_test-ch-${timestamp}`,
+      object: 'charge',
+      status: 'succeeded',
+      amount: amountCents,
+      amount_refunded: amountCents,
+      currency: 'usd',
+      invoice: null,
+      subscription: null,
+      metadata: { uid, orderId: order?.id || null },
+      refunds: {
+        data: [
+          {
+            id: `_test-re-${timestamp}`,
+            amount: amountCents,
+            currency: 'usd',
+            reason: 'requested_by_customer',
+          },
+        ],
+      },
+    };
+
+    await writeWebhook({
+      admin,
+      eventId,
+      uid,
+      eventType: 'charge.refunded',
+      dataObject: chargeObj,
+      event: {
+        category: 'one-time',
+        resourceType: 'charge',
+        resourceId: chargeObj.id,
+      },
+    });
+
+    ctx.log(`Test refund provider: wrote payments-webhooks/${eventId} for one-time order=${order?.id}, session=${resourceId}, uid=${uid}`);
+
+    // Return mock refund result — a one-time purchase always refunds in full
+    return {
+      amount: amount,
+      currency: 'usd',
+      full: true,
+    };
+  },
+};
+
+/**
+ * Write the synthetic pipeline doc both refund paths produce
+ *
+ * @param {object} options
+ * @param {object} options.admin - Firebase admin instance
+ * @param {string} options.eventId - The payments-webhooks doc id
+ * @param {string} options.uid - Owner UID
+ * @param {string} options.eventType - The Stripe-shaped event type
+ * @param {object} options.dataObject - The Stripe-shaped resource the event carries
+ * @param {object} options.event - The rest of the parsed event block (category, resourceType, resourceId)
+ */
+async function writeWebhook({ admin, eventId, uid, eventType, dataObject, event }) {
+  const nowTs = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(nowTs, { output: 'unix' });
+
+  await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+    id: eventId,
+    provider: 'test',
+    status: 'pending',
+    owner: uid,
+    raw: {
+      id: eventId,
+      type: eventType,
+      data: { object: dataObject },
+    },
+    event: {
+      type: eventType,
+      ...event,
+    },
+    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,
+      },
+    },
+  });
+}

package/dist/manager/routes/payments/trial-eligibility/get.js

@@ -0,0 +1,29 @@
+/**
+ * GET /payments/trial-eligibility
+ * Returns whether the authenticated user is eligible for a free trial
+ * Eligible = no previous subscription orders in payments-orders
+ */
+module.exports = async ({ ctx, user, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+
+  // Check for any previous subscription orders
+  const historySnapshot = await admin.firestore()
+    .collection('payments-orders')
+    .where('owner', '==', uid)
+    .where('type', '==', 'subscription')
+    .limit(1)
+    .get();
+
+  const eligible = historySnapshot.empty;
+
+  ctx.log(`Trial eligibility for ${uid}: ${eligible}`);
+
+  return ctx.respond({ eligible });
+};

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

@@ -0,0 +1,106 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+
+/**
+ * POST /payments/uncancel
+ * Withdraws a scheduled cancellation, so the authenticated user's subscription
+ * renews as normal instead of ending at the close of the current billing period.
+ * Delegates to the provider (e.g., Stripe) to clear cancel_at_period_end.
+ * The resulting webhook triggers the Firestore pipeline which updates subscription
+ * state — this route writes no subscription state of its own, exactly like cancel.
+ * Clears the cancellation request on payments-orders/{orderId}.requests.cancellation.
+ * Requires authentication.
+ *
+ * Cross-provider and CAPABILITY-GATED: a provider that can resume a subscription
+ * exports uncancel(), 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)).
+ */
+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('Resuming the subscription must be confirmed', { code: 400 });
+  }
+
+  const subscription = user.subscription;
+
+  // Require an ACTIVE paid subscription — a suspended or already-ended term
+  // cannot be resumed by clearing a scheduled cancellation
+  if (!subscription || subscription.status !== 'active' || subscription.product?.id === 'basic') {
+    ctx.log(`Uncancel rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
+    return ctx.respond('No active paid subscription found', { code: 400 });
+  }
+
+  // Require a cancellation actually scheduled — there is nothing else to withdraw
+  if (subscription.cancellation?.pending !== true) {
+    ctx.log(`Uncancel rejected: uid=${uid}, no cancellation pending`);
+    return ctx.respond('Your subscription is not scheduled to cancel', { code: 400 });
+  }
+
+  const provider = subscription.payment?.provider;
+  const resourceId = subscription.payment?.resourceId;
+
+  if (!provider || !resourceId) {
+    ctx.log(`Uncancel 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.uncancel !== 'function') {
+    ctx.log(`Uncancel not supported: uid=${uid}, provider=${provider}`);
+    return ctx.respond('Your payment provider cannot resume a cancelled subscription. Please use the billing portal to manage your subscription.', {
+      code: 400,
+      additional: { code: 'not-supported-by-provider' },
+    });
+  }
+
+  // Clear the scheduled cancellation via the provider
+  try {
+    await providerModule.uncancel({ 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 resume subscription via ${provider}: uid=${uid}, sub=${resourceId}, error=${e.message}`);
+    return ctx.respond('We could not resume your subscription right now. Please try again shortly.', { code: 500 });
+  }
+
+  // Clear the cancellation request on the order doc — the request is withdrawn,
+  // so leaving the reason/feedback behind would misreport the order's state.
+  // Null is the same empty shape the pipeline initializes an order with.
+  const orderId = subscription.payment?.orderId;
+
+  if (orderId) {
+    const admin = ctx.Manager.libraries.admin;
+
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      requests: {
+        cancellation: null,
+      },
+    }, { merge: true });
+
+    ctx.log(`Cleared cancellation request on payments-orders/${orderId}`);
+  }
+
+  ctx.log(`Cancellation withdrawn: uid=${uid}, provider=${provider}, sub=${resourceId}`);
+
+  return ctx.respond({ success: true });
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Chargebee uncancel provider
+ * Withdraws a scheduled cancellation via remove_scheduled_cancellation.
+ *
+ * A Chargebee subscription cancelled with cancel_option 'end_of_term' sits in
+ * status non_renewing — still serving the term, just not renewing. Removing the
+ * scheduled cancellation puts it back to active; Chargebee then sends the
+ * subscription_changed webhook the existing pipeline processes.
+ */
+module.exports = {
+  /**
+   * Resume a Chargebee subscription that is scheduled to cancel
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Chargebee subscription ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's current subscription object
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async uncancel({ resourceId, uid, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    await ChargebeeLib.request(`/subscriptions/${resourceId}/remove_scheduled_cancellation`, {
+      method: 'POST',
+    });
+
+    ctx.log(`Chargebee scheduled cancellation removed: sub=${resourceId}, uid=${uid}`);
+  },
+};

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

@@ -0,0 +1,25 @@
+/**
+ * PayPal uncancel provider — DELIBERATELY EMPTY.
+ *
+ * PayPal cannot resume a cancelled subscription. Its only reactivation verb,
+ * `/v1/billing/subscriptions/{id}/activate`, works on a SUSPENDED subscription;
+ * a CANCELLED one is terminal, and PayPal answers 422
+ * (`SUBSCRIPTION_STATUS_INVALID`). There is no "un-cancel" to call.
+ *
+ * That matters here because PayPal has no cancel-at-period-end either: our cancel
+ * route cancels the PayPal subscription outright and the pipeline represents the
+ * remaining paid term as `cancellation.pending` (see the unified mapping in
+ * libraries/payment/providers/paypal.js). So a PayPal subscriber whose state
+ * reads "pending cancellation" is already cancelled at PayPal — the state this
+ * route exists to undo is the one PayPal will not undo.
+ *
+ * The module exports NOTHING on purpose: the capability gate in ../post.js reads
+ * `typeof providerModule.uncancel === 'function'`, so the absent export IS the
+ * declaration, and the caller gets a `not-supported-by-provider` 400 pointing at
+ * the billing portal instead of a provider error
+ * ([#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/uncancel/providers/stripe.js

@@ -0,0 +1,27 @@
+/**
+ * Stripe uncancel provider
+ * Withdraws a scheduled cancellation by clearing cancel_at_period_end.
+ *
+ * The subscription is still live at this point — cancel_at_period_end only
+ * SCHEDULES the end — so clearing the flag resumes normal renewal. Stripe then
+ * sends customer.subscription.updated, which the existing pipeline processes.
+ */
+module.exports = {
+  /**
+   * Resume a Stripe subscription that is scheduled to cancel
+   *
+   * @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.ctx - Assistant instance for logging
+   */
+  async uncancel({ resourceId, uid, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    await stripe.subscriptions.update(resourceId, { cancel_at_period_end: false });
+
+    ctx.log(`Stripe scheduled cancellation removed: sub=${resourceId}, uid=${uid}`);
+  },
+};

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

@@ -0,0 +1,114 @@
+const powertools = require('node-powertools');
+
+/**
+ * Test uncancel provider
+ * Simulates the Stripe webhook that results from withdrawing a scheduled
+ * cancellation 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 cancel_at_period_end=false
+ * and cancel_at=null — the shape Stripe sends once the schedule is cleared, which
+ * the unified transform reads back as cancellation.pending=false.
+ *
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async uncancel({ resourceId, uid, subscription, 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 = subscription?.expires?.timestampUNIX || (now + (30 * 86400));
+
+    // Look up the Stripe product ID for the plan so resolveProduct() can match.
+    // The order doc is the first source; when there is no order the subscription's
+    // own product is the fallback — without it the plan carries product=null and
+    // the pipeline downgrades the user to Basic instead of resuming their plan.
+    const orderId = subscription?.payment?.orderId;
+    let productId = null;
+
+    if (orderId) {
+      const orderDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+      if (orderDoc.exists) {
+        productId = orderDoc.data().unified?.product?.id || null;
+      }
+    }
+
+    productId = productId || subscription?.product?.id || null;
+
+    // Falls back to the "_test_<id>" sentinel when no real Stripe product is configured.
+    const products = ctx.Manager.config.payment?.products || [];
+    const product = products.find(p => p.id === productId);
+    const stripeProductId = product
+      ? (product.stripe?.productId || `_test_${product.id}`)
+      : null;
+
+    // Carry the subscription's OWN billing frequency through: resuming a
+    // subscription must never quietly re-bill it on a different interval.
+    const FREQUENCY_TO_INTERVAL = { annually: 'year', monthly: 'month', weekly: 'week', daily: 'day' };
+    const interval = FREQUENCY_TO_INTERVAL[subscription?.payment?.frequency] || 'month';
+
+    const eventType = 'customer.subscription.updated';
+    const eventId = `_test-evt-uncancel-${timestamp}`;
+
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: 'active',
+      metadata: { uid, orderId },
+      cancel_at_period_end: false,
+      cancel_at: null,
+      canceled_at: null,
+      current_period_end: periodEnd,
+      current_period_start: now - (30 * 86400),
+      start_date: subscription?.payment?.startDate?.timestampUNIX || (now - (30 * 86400)),
+      trial_start: null,
+      trial_end: null,
+      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 uncancel provider: wrote payments-webhooks/${eventId} (${eventType}) for sub=${resourceId}, uid=${uid}`);
+  },
+};