@omega.js/backend 0.1.0

package/test/routes/payments/refund-one-time.test.js

@@ -0,0 +1,254 @@
+/**
+ * Test: POST /payments/refund — refunding a ONE-TIME purchase
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * The route was subscription-shaped end to end: it read the caller's
+ * `user.subscription` and rejected anybody without a paid one, so a one-time
+ * purchase — which never touches the user doc at all — could not be refunded
+ * through it. A one-time refund names its subject in the request instead: the
+ * `payments-orders` doc of the purchase.
+ *
+ * The guards are the point of this suite, so it calls the handler DIRECTLY: each
+ * case gets exactly the order doc it is about, without minting a persona per
+ * permutation. The one valid order deliberately carries an unknown provider —
+ * reaching "Unknown provider" proves the request got PAST every guard without
+ * anything external being touched.
+ *
+ * Run: npx omega test backend:routes/payments/refund-one-time
+ */
+const { buildUser, callHandler } = require('./_route-harness.js');
+
+const handler = require('../../../dist/manager/routes/payments/refund/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const OWNER = '_test-refund-one-time-owner';
+
+function purchaser(Manager, uid) {
+  return buildUser(Manager, {
+    auth: { uid: uid, email: `${uid}@example.com` },
+    roles: {},
+    // A one-time buyer is an ordinary Basic user — the whole point of the branch
+    subscription: { product: { id: 'basic' }, status: 'active' },
+  });
+}
+
+// A completed one-time order, the shape the webhook pipeline writes
+function oneTimeOrder(orderId, overrides) {
+  const nowUNIX = Math.floor(Date.now() / 1000);
+
+  return {
+    id: orderId,
+    type: 'one-time',
+    owner: OWNER,
+    productId: 'credits-100',
+    provider: 'unknown-provider',
+    resourceId: `_test-cs-${orderId}`,
+    unified: {
+      product: { id: 'credits-100', name: '100 Credits' },
+      status: 'completed',
+      payment: { provider: 'unknown-provider', orderId: orderId, resourceId: `_test-cs-${orderId}`, price: 9.99 },
+    },
+    requests: { cancellation: null, refund: null },
+    metadata: { created: { timestamp: new Date(nowUNIX * 1000).toISOString(), timestampUNIX: nowUNIX } },
+    ...(overrides || {}),
+  };
+}
+
+function refund(Manager, user, orderId) {
+  return callHandler({
+    Manager,
+    handler,
+    functionName: 'payments-refund',
+    user,
+    settings: { confirmed: true, reason: 'Bought the wrong thing', feedback: null, orderId: orderId },
+  });
+}
+
+module.exports = defineCases({
+  description: 'Payment refund endpoint: one-time purchases',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'rejects-an-order-that-does-not-exist',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const sent = await refund(Manager, purchaser(Manager, OWNER), '_test-order-never-existed');
+
+        assert.equal(sent.code, 400, `An unknown order should be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /order not found/i, 'The rejection should name the order');
+      },
+    },
+
+    {
+      name: 'rejects-an-order-owned-by-somebody-else',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-not-yours';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId));
+
+        const sent = await refund(Manager, purchaser(Manager, '_test-refund-one-time-stranger'), orderId);
+
+        assert.equal(sent.code, 400, `Another user's order should be rejected, got ${sent.code}: ${sent.body}`);
+        // Not-found and not-yours read identically: an order id must not be a
+        // probe for whether somebody else's purchase exists
+        assert.match(`${sent.body}`, /order not found/i, 'Somebody else\'s order must not be distinguishable from a missing one');
+      },
+    },
+
+    {
+      name: 'rejects-a-subscription-order',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-is-a-subscription';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId, { type: 'subscription' }));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `A subscription order should be rejected here, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /one-time/i, 'The rejection should say the order is not a one-time purchase');
+      },
+    },
+
+    {
+      name: 'rejects-an-already-refunded-order',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-already-refunded';
+        const nowUNIX = Math.floor(Date.now() / 1000);
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId, {
+          requests: {
+            cancellation: null,
+            refund: {
+              reason: 'Changed my mind',
+              amount: 9.99,
+              full: true,
+              date: { timestamp: new Date(nowUNIX * 1000).toISOString(), timestampUNIX: nowUNIX },
+            },
+          },
+        }));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `A refunded order should be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /already been refunded/i, 'The rejection should say it was already refunded');
+      },
+    },
+
+    {
+      name: 'rejects-a-dashboard-refunded-order',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        // A refund issued from the provider dashboard arrives by webhook: it
+        // flips unified.status to 'refunded' but writes NO requests.refund
+        const orderId = '_test-order-one-time-dashboard-refunded';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId, {
+          unified: {
+            product: { id: 'credits-100', name: '100 Credits' },
+            status: 'refunded',
+            payment: { provider: 'unknown-provider', orderId: orderId, resourceId: `_test-cs-${orderId}`, price: 9.99 },
+          },
+        }));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `A dashboard-refunded order should be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /already been refunded/i, 'The rejection should say it was already refunded, not 500 out of the provider');
+      },
+    },
+
+    {
+      name: 'rejects-a-purchase-that-never-completed',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        // An abandoned Stripe checkout session stays `open` on the order, with
+        // its provider and resourceId intact — so every other refusal passes it
+        // and the provider is asked to reverse a charge that never happened
+        const orderId = '_test-order-one-time-never-completed';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId, {
+          unified: {
+            product: { id: 'credits-100', name: '100 Credits' },
+            status: 'open',
+            payment: { provider: 'unknown-provider', orderId: orderId, resourceId: `_test-cs-${orderId}`, price: 9.99 },
+          },
+        }));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `An incomplete purchase should be refused, not sent to the provider, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /has not completed/i, 'The rejection should say the purchase never completed');
+      },
+    },
+
+    {
+      name: 'rejects-a-purchase-older-than-6-months',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-too-old';
+        const oldUNIX = Math.floor(Date.now() / 1000) - (200 * 24 * 60 * 60);
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId, {
+          metadata: { created: { timestamp: new Date(oldUNIX * 1000).toISOString(), timestampUNIX: oldUNIX } },
+        }));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `An old purchase should be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /older than 6 months/i, 'The refund window applies to one-time purchases too');
+      },
+    },
+
+    {
+      name: 'reaches-the-provider-for-a-valid-one-time-order',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-valid';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId));
+
+        const sent = await refund(Manager, purchaser(Manager, OWNER), orderId);
+
+        assert.equal(sent.code, 400, `A valid order should reach the provider lookup, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /Unknown provider/i, 'A valid one-time order should get PAST every guard');
+      },
+    },
+
+    {
+      name: 'still-requires-confirmation',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const orderId = '_test-order-one-time-unconfirmed';
+        await firestore.set(`payments-orders/${orderId}`, oneTimeOrder(orderId));
+
+        const sent = await callHandler({
+          Manager,
+          handler,
+          functionName: 'payments-refund',
+          user: purchaser(Manager, OWNER),
+          settings: { confirmed: false, reason: 'Bought the wrong thing', feedback: null, orderId: orderId },
+        });
+
+        assert.equal(sent.code, 400, `An unconfirmed refund should be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /must be confirmed/i, 'The confirmation guard covers both paths');
+      },
+    },
+
+    {
+      name: 'without-an-order-id-it-is-still-the-subscription-path',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        // No orderId: a Basic user is refused for having no paid subscription,
+        // exactly as before the one-time branch existed
+        const sent = await callHandler({
+          Manager,
+          handler,
+          functionName: 'payments-refund',
+          user: purchaser(Manager, OWNER),
+          settings: { confirmed: true, reason: 'Too expensive', feedback: null, orderId: null },
+        });
+
+        assert.equal(sent.code, 400, `A basic user should still be rejected, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /no paid subscription/i, 'The subscription path must be untouched');
+      },
+    },
+  ],
+});

package/test/routes/payments/refund-paypal-proration.test.js

@@ -0,0 +1,190 @@
+/**
+ * Test: the PayPal refund provider derives its billing period, never guesses it
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * A prorated refund is `days remaining / days in period × amount`. PayPal
+ * exposes no period on a transaction, and when a subscription is cancelled or
+ * suspended it drops `next_billing_time` too — exactly the state a refund is
+ * requested in. The old code answered that with a flat 50% of the payment, which
+ * is not a computation, it is an invented number attached to somebody's money.
+ * The period is now rebuilt from the payment being refunded plus the plan's own
+ * REGULAR billing interval, and when even that is unavailable the refund refuses.
+ *
+ * PayPal's HTTP client is the one thing stood in for here: it is the external
+ * boundary (a live subscription and plan), and every assertion is about the
+ * arithmetic on this side of it.
+ *
+ * Run: npx omega test backend:routes/payments/refund-paypal-proration
+ */
+const paypalRefund = require('../../../dist/manager/routes/payments/refund/providers/paypal.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// A stand-in for the PayPal HTTP client — the external boundary. It answers plan
+// lookups from the fixture it was built with and records what was asked for.
+function paypalClient(plan) {
+  const requested = [];
+
+  return {
+    requested,
+    async request(path) {
+      requested.push(path);
+
+      if (plan) {
+        return plan;
+      }
+
+      throw new Error('PayPal API 404: The specified resource does not exist.');
+    },
+  };
+}
+
+const monthlyPlan = { billing_cycles: [{ tenure_type: 'TRIAL', frequency: { interval_unit: 'DAY', interval_count: 7 } }, { tenure_type: 'REGULAR', frequency: { interval_unit: 'MONTH', interval_count: 1 } }] };
+const annualPlan = { billing_cycles: [{ tenure_type: 'REGULAR', frequency: { interval_unit: 'YEAR', interval_count: 1 } }] };
+const weeklyPlan = { billing_cycles: [{ tenure_type: 'REGULAR', frequency: { interval_unit: 'WEEK', interval_count: 2 } }] };
+
+const PERIOD_START = new Date('2026-03-01T00:00:00.000Z');
+
+function resolve({ sub, plan, periodStart, ctx }) {
+  const PayPalLib = paypalClient(plan);
+
+  return paypalRefund.resolvePeriodEnd({
+    sub,
+    resourceId: 'I-TEST-PRORATION',
+    periodStart: periodStart || PERIOD_START,
+    PayPalLib,
+    ctx,
+  });
+}
+
+async function rejects(assert, promise, pattern, message) {
+  try {
+    await promise;
+  } catch (e) {
+    assert.match(e.message, pattern, `${message} — got: ${e.message}`);
+    return;
+  }
+
+  assert.ok(false, `${message} — it resolved instead of refusing`);
+}
+
+module.exports = defineCases({
+  description: 'PayPal refund proration: the billing period is derived or refused',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'uses-paypals-own-next-billing-time',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-TEST', billing_info: { next_billing_time: '2026-04-01T00:00:00.000Z' } };
+
+        const periodEnd = await resolve({ sub, plan: monthlyPlan, ctx });
+
+        assert.equal(periodEnd.toISOString(), '2026-04-01T00:00:00.000Z', "PayPal's own period end wins when it is present");
+      },
+    },
+
+    {
+      name: 'derives-a-monthly-period-from-the-plan',
+      async run({ assert, ctx }) {
+        // A cancelled subscription: no next_billing_time, which is the state a refund arrives in
+        const sub = { plan_id: 'P-TEST', status: 'CANCELLED', billing_info: {} };
+
+        const periodEnd = await resolve({ sub, plan: monthlyPlan, ctx });
+
+        assert.equal(periodEnd.toISOString(), '2026-04-01T00:00:00.000Z', 'One MONTH after the payment being refunded');
+      },
+    },
+
+    {
+      name: 'derives-an-annual-period-from-the-plan',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-TEST', billing_info: {} };
+
+        const periodEnd = await resolve({ sub, plan: annualPlan, ctx });
+
+        assert.equal(periodEnd.toISOString(), '2027-03-01T00:00:00.000Z', 'One YEAR after the payment being refunded');
+      },
+    },
+
+    {
+      name: 'honors-the-plans-interval-count',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-TEST', billing_info: {} };
+
+        const periodEnd = await resolve({ sub, plan: weeklyPlan, ctx });
+
+        assert.equal(periodEnd.toISOString(), '2026-03-15T00:00:00.000Z', 'Two WEEKs after the payment being refunded');
+      },
+    },
+
+    {
+      name: 'ignores-the-trial-cycle',
+      async run({ assert, ctx }) {
+        // monthlyPlan leads with a 7-day TRIAL cycle: the REGULAR one is the billing period
+        const sub = { plan_id: 'P-TEST', billing_info: {} };
+
+        const periodEnd = await resolve({ sub, plan: monthlyPlan, ctx });
+
+        assert.equal(periodEnd.toISOString(), '2026-04-01T00:00:00.000Z', 'The REGULAR cycle is the billing interval, not the trial');
+      },
+    },
+
+    {
+      name: 'refuses-when-the-subscription-has-no-plan',
+      async run({ assert, ctx }) {
+        const sub = { billing_info: {} };
+
+        await rejects(
+          assert,
+          resolve({ sub, plan: monthlyPlan, ctx }),
+          /billing period cannot be derived/i,
+          'No next_billing_time and no plan_id must refuse',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-when-the-plan-has-no-regular-cycle',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-TEST', billing_info: {} };
+        const trialOnlyPlan = { billing_cycles: [{ tenure_type: 'TRIAL', frequency: { interval_unit: 'DAY', interval_count: 7 } }] };
+
+        await rejects(
+          assert,
+          resolve({ sub, plan: trialOnlyPlan, ctx }),
+          /billing period cannot be derived/i,
+          'A plan with no REGULAR cycle must refuse',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-when-the-plan-lookup-fails',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-GONE', billing_info: {} };
+
+        await rejects(
+          assert,
+          resolve({ sub, plan: null, ctx }),
+          /PayPal API 404/,
+          'A failed plan lookup must surface, not fall back to a guess',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-an-unknown-interval-unit',
+      async run({ assert, ctx }) {
+        const sub = { plan_id: 'P-TEST', billing_info: {} };
+        const oddPlan = { billing_cycles: [{ tenure_type: 'REGULAR', frequency: { interval_unit: 'FORTNIGHT', interval_count: 1 } }] };
+
+        await rejects(
+          assert,
+          resolve({ sub, plan: oddPlan, ctx }),
+          /billing period cannot be derived/i,
+          'An interval unit we cannot convert must refuse',
+        );
+      },
+    },
+  ],
+});

package/test/routes/payments/refund.test.js

@@ -0,0 +1,181 @@
+/**
+ * Test: POST /payments/refund
+ * Tests rejection cases and a full end-to-end refund flow with the test provider.
+ *
+ * Refund requires the subscription to be cancelled or pending cancellation.
+ * The test provider simulates refund by writing a customer.subscription.deleted
+ * webhook which triggers the existing pipeline.
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Payment refund endpoint',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'rejects-unauthenticated',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 401, 'Should reject unauthenticated request');
+      },
+    },
+
+    {
+      name: 'rejects-missing-confirmed',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/refund', {
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject missing confirmed field');
+      },
+    },
+
+    {
+      name: 'rejects-missing-reason',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/refund', {
+          confirmed: true,
+        });
+
+        assert.isError(response, 400, 'Should reject missing reason field');
+      },
+    },
+
+    {
+      name: 'rejects-basic-user',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject basic user with no paid subscription');
+      },
+    },
+
+    {
+      name: 'rejects-active-subscription-without-cancellation',
+      async run({ http, assert }) {
+        // refund-active-no-cancel has an active subscription without pending cancellation
+        const response = await http.as('refund-active-no-cancel').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject active subscription that is not cancelled or pending cancellation');
+      },
+    },
+
+    {
+      name: 'rejects-payment-older-than-6-months',
+      async run({ http, assert }) {
+        // refund-expired-payment has a cancelled subscription with a payment older than 6 months
+        const response = await http.as('refund-expired-payment').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject payment older than 6 months');
+      },
+    },
+
+    {
+      name: 'rejects-no-provider-or-resource-id',
+      async run({ http, assert }) {
+        // refund-no-provider has a cancelled subscription but no provider
+        const response = await http.as('refund-no-provider').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject when no provider or resourceId is set');
+      },
+    },
+
+    {
+      name: 'rejects-unknown-provider',
+      async run({ http, assert }) {
+        // refund-unknown-provider has a cancelled subscription with unknown provider
+        const response = await http.as('refund-unknown-provider').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Too expensive',
+        });
+
+        assert.isError(response, 400, 'Should reject unknown provider');
+      },
+    },
+
+    {
+      name: 'succeeds-with-test-provider',
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
+        const uid = accounts['route-refund-success'].uid;
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        if (!paidProduct) {
+          skip('No paid product with monthly price configured in this brand');
+        }
+
+        // Step 1: Create a test subscription intent to set up a proper paid subscription
+        const intentResponse = await http.as('route-refund-success').post('backend-manager/payments/intent', {
+          provider: 'test',
+          productId: paidProduct.id,
+          frequency: 'monthly',
+        });
+
+        assert.isSuccess(intentResponse, 'Intent should succeed');
+
+        // Wait for the auto-webhook to activate the subscription
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.payment?.provider === 'test'
+            && userDoc?.subscription?.payment?.resourceId
+            && userDoc?.subscription?.status === 'active';
+        }, 15000, 500);
+
+        // Step 2: Cancel the subscription first (refund requires cancellation).
+        // skipGuards bypasses the 24-hour subscription-age guard on the cancel route.
+        const cancelResponse = await http.as('route-refund-success').post('backend-manager/payments/cancel', {
+          confirmed: true,
+          reason: 'Too expensive',
+          skipGuards: true,
+        });
+
+        assert.isSuccess(cancelResponse, 'Cancel should succeed');
+
+        // Wait for cancellation.pending to be set via the webhook pipeline
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.cancellation?.pending === true;
+        }, 15000, 500);
+
+        // Step 3: Request a refund
+        const refundResponse = await http.as('route-refund-success').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Not satisfied with the service',
+          feedback: 'Testing refund flow',
+        });
+
+        assert.isSuccess(refundResponse, 'Refund should succeed');
+        assert.ok(refundResponse.data.success, 'Should return success: true');
+        assert.ok(refundResponse.data.refund, 'Should return refund details');
+        assert.isType(refundResponse.data.refund.amount, 'number', 'Refund amount should be a number');
+        assert.equal(refundResponse.data.refund.full, true, 'Should be a full refund (test provider)');
+
+        // Step 4: Verify subscription is cancelled via the webhook pipeline
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.status === 'cancelled';
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+        assert.equal(userDoc?.subscription?.status, 'cancelled', 'Subscription should be cancelled after refund');
+      },
+    },
+  ],
+});