@omega.js/backend 0.1.0

package/test/routes/payments/plan.test.js

@@ -0,0 +1,367 @@
+/**
+ * Test: POST /payments/plan — guards and the per-provider capability gate
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * Plan-switch is an OWNED route next to cancel, cross-provider and capability-gated
+ * the same way uncancel is: a provider that can move a live subscription between
+ * plans EXPORTS `switchPlan`, one that cannot simply lacks the export.
+ *
+ * The route is called directly against a real ctx (the _route-harness technique),
+ * so one test can choose a provider, a product and a frequency without minting a
+ * persona per permutation. The full end-to-end pipeline run lives in
+ * test/events/payments/journey-payments-plan-switch.test.js.
+ *
+ * Run: npx omega test framework:routes/payments/plan
+ */
+const { buildUser, callHandler, recordingResponse } = require('./_route-harness.js');
+
+const handler = require('../../../dist/manager/routes/payments/plan/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const PROVIDERS = ['stripe', 'chargebee', 'paypal', 'test'];
+
+function providerModule(name) {
+  return require(`../../../dist/manager/routes/payments/plan/providers/${name}.js`);
+}
+
+// Two distinct paid subscription products from the brand's own config — the
+// switch has no meaning without them, so a brand that lacks a pair skips.
+function paidPair(config, skip) {
+  const paid = (config.payment?.products || []).filter((p) => p.id !== 'basic' && p.type === 'subscription' && p.prices);
+
+  if (paid.length < 2) {
+    skip('Fewer than two paid subscription products configured in this brand');
+  }
+
+  return { from: paid[0], to: paid[1] };
+}
+
+// A paying subscriber sitting on `product` at `frequency`.
+function subscriber(Manager, { uid, product, frequency, provider, resourceId, pending }) {
+  const lastYearUNIX = Math.floor(Date.now() / 1000) - (365 * 24 * 60 * 60);
+
+  return buildUser(Manager, {
+    auth: { uid: uid, email: `${uid}@example.com` },
+    roles: {},
+    subscription: {
+      product: { id: product.id, name: product.name || product.id },
+      status: 'active',
+      cancellation: { pending: pending === true },
+      payment: {
+        provider: provider === undefined ? 'test' : provider,
+        resourceId: resourceId === undefined ? 'sub_test_plan_guard' : resourceId,
+        frequency: frequency,
+        startDate: { timestamp: new Date(lastYearUNIX * 1000).toISOString(), timestampUNIX: lastYearUNIX },
+      },
+    },
+  });
+}
+
+function switchPlan(Manager, user, settings) {
+  return callHandler({
+    Manager,
+    handler,
+    functionName: 'payments-plan',
+    user,
+    settings: { confirmed: true, ...(settings || {}) },
+  });
+}
+
+/**
+ * The same direct call, with the `omega-properties` header captured — the
+ * uncancel suite's technique, for the same reason: the branchable half of a 4xx
+ * rides that header, so a test that asserts a CODE has to read it.
+ *
+ * @returns {Promise<{ sent: object, properties: object|null }>}
+ */
+async function switchPlanReadingProperties(Manager, user, settings) {
+  const res = recordingResponse();
+  const headers = {};
+
+  res.header = (key, value) => {
+    headers[key] = value;
+    return res;
+  };
+  res.get = (key) => headers[key];
+
+  const req = { method: 'POST', headers: { 'content-type': 'application/json' }, query: {}, body: {} };
+  const ctx = Manager.RouteContext({ req, res }, { functionName: 'payments-plan' });
+
+  await handler({ ctx, Manager, user, settings: { confirmed: true, ...(settings || {}) }, libraries: Manager.libraries });
+
+  return {
+    sent: res.sent,
+    properties: headers['omega-properties'] ? JSON.parse(headers['omega-properties']) : null,
+  };
+}
+
+// The frequency a product is actually priced at in this brand's config.
+function frequencyOf(product) {
+  return Object.keys(product.prices)[0];
+}
+
+module.exports = defineCases({
+  description: 'Payment plan endpoint: guards + provider capability gate',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    // ─── the wire guards ───
+
+    {
+      name: 'rejects-unauthenticated',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/plan', {
+          productId: 'premium',
+          frequency: 'monthly',
+          confirmed: true,
+        });
+
+        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/plan', {
+          productId: 'premium',
+          frequency: 'monthly',
+        });
+
+        assert.isError(response, 400, 'Should reject a request that never confirmed');
+      },
+    },
+
+    {
+      name: 'rejects-missing-product-id',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/plan', {
+          confirmed: true,
+        });
+
+        assert.isError(response, 400, 'Should reject a switch with no target product');
+      },
+    },
+
+    // ─── the subscription-state guards ───
+
+    {
+      name: 'rejects-unconfirmed',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { from, to } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-unconfirmed', product: from, frequency: frequencyOf(from) });
+
+        const sent = await switchPlan(Manager, user, { confirmed: false, productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `An unconfirmed switch must be refused, got ${sent.code}`);
+      },
+    },
+
+    {
+      name: 'rejects-basic-user',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { to } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-basic', product: { id: 'basic', name: 'Basic' }, frequency: null });
+
+        const sent = await switchPlan(Manager, user, { productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `A free user has no subscription to move, got ${sent.code}`);
+      },
+    },
+
+    {
+      name: 'rejects-a-product-the-brand-does-not-sell',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { from } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-unknown-product', product: from, frequency: frequencyOf(from) });
+
+        const sent = await switchPlan(Manager, user, { productId: '_not-a-configured-product', frequency: 'monthly' });
+
+        assert.equal(sent.code, 400, `An unconfigured product must be refused, got ${sent.code}`);
+      },
+    },
+
+    {
+      name: 'rejects-the-plan-the-user-is-already-on',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { from } = paidPair(config, skip);
+        const frequency = frequencyOf(from);
+        const user = subscriber(Manager, { uid: '_test-plan-same', product: from, frequency });
+
+        const sent = await switchPlan(Manager, user, { productId: from.id, frequency });
+
+        assert.equal(sent.code, 400, `Switching to the current plan is a no-op, got ${sent.code}`);
+        assert.match(`${sent.body}`, /already on/i, `Expected the same-plan message, got: ${sent.body}`);
+      },
+    },
+
+    {
+      name: 'rejects-the-current-plan-at-EVERY-cadence-it-is-sold-at',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // The no-op is "this product at THIS frequency", whichever frequency the
+        // account happens to sit on — a subscriber on the annual price must be
+        // refused an annual "switch" exactly as a monthly one is.
+        const { from } = paidPair(config, skip);
+
+        for (const frequency of Object.keys(from.prices)) {
+          const user = subscriber(Manager, { uid: `_test-plan-same-${frequency}`, product: from, frequency });
+
+          const sent = await switchPlan(Manager, user, { productId: from.id, frequency });
+
+          assert.equal(sent.code, 400, `Switching to the current plan (${frequency}) is a no-op, got ${sent.code}`);
+          assert.match(`${sent.body}`, /already on/i, `Expected the same-plan message at ${frequency}, got: ${sent.body}`);
+        }
+      },
+    },
+
+    {
+      name: 'rejects-the-current-product-when-no-frequency-is-recorded',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // The QA repro's actual state: `payment.frequency` never got recorded,
+        // so a pair comparison alone ('monthly' === undefined) let the no-op
+        // through to a real provider call. With nothing to compare, the product
+        // id decides and EVERY cadence of it is refused — the same conservatism
+        // the modal applies, and the reason the backend can stop leaning on it.
+        const { from } = paidPair(config, skip);
+
+        for (const frequency of Object.keys(from.prices)) {
+          const user = subscriber(Manager, { uid: `_test-plan-no-frequency-${frequency}`, product: from, frequency: undefined });
+
+          const { sent, properties } = await switchPlanReadingProperties(Manager, user, { productId: from.id, frequency });
+
+          assert.equal(sent.code, 400, `An unrecorded frequency must refuse the current product at ${frequency}, got ${sent.code}`);
+          assert.equal(properties?.additional?.code, 'already-on-plan', `Expected already-on-plan at ${frequency}, got: ${JSON.stringify(properties?.additional)}`);
+        }
+      },
+    },
+
+    {
+      name: 'still-lets-ANOTHER-product-through-when-no-frequency-is-recorded',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // The conservative branch keys on the PRODUCT — it must not become a
+        // blanket refusal for an account whose frequency was never written.
+        const { from, to } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-no-frequency-other', product: from, frequency: undefined, provider: 'unknown-provider' });
+
+        const sent = await switchPlan(Manager, user, { productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `Expected the unknown-provider gate, got ${sent.code}`);
+        assert.ok(!/already on/i.test(`${sent.body}`), `A different product must clear the same-plan guard, got: ${sent.body}`);
+      },
+    },
+
+    {
+      name: 'the-same-plan-guard-carries-a-structured-code',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // The client branches on the code, not on the sentence — the same
+        // contract the capability gate ships under.
+        const { from } = paidPair(config, skip);
+        const frequency = frequencyOf(from);
+        const user = subscriber(Manager, { uid: '_test-plan-same-code', product: from, frequency });
+
+        const { sent, properties } = await switchPlanReadingProperties(Manager, user, { productId: from.id, frequency });
+
+        assert.equal(sent.code, 400, `Expected the same-plan guard, got ${sent.code}`);
+        assert.equal(properties?.additional?.code, 'already-on-plan', `Expected a branchable code on omega-properties, got: ${JSON.stringify(properties?.additional)}`);
+      },
+    },
+
+    {
+      name: 'rejects-a-switch-while-a-cancellation-is-pending',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // Swapping the price under a scheduled cancellation would land the user
+        // on a NEW plan still set to end at period end, silently. Undo the
+        // cancellation first — the provider is deliberately unknown here, so a
+        // refusal before that gate is the proof nothing was dispatched.
+        const { from, to } = paidPair(config, skip);
+        const user = subscriber(Manager, {
+          uid: '_test-plan-cancelling',
+          product: from,
+          frequency: frequencyOf(from),
+          provider: 'unknown-provider',
+          pending: true,
+        });
+
+        const { sent, properties } = await switchPlanReadingProperties(Manager, user, { productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `A pending cancellation must refuse the switch, got ${sent.code}`);
+        assert.equal(properties?.additional?.code, 'cancellation-pending', `Expected a branchable code on omega-properties, got: ${JSON.stringify(properties?.additional)}`);
+        assert.match(`${sent.body}`, /cancel/i, `The refusal should name the cancellation, got: ${sent.body}`);
+      },
+    },
+
+    {
+      name: 'lets-a-frequency-change-on-the-same-product-through',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        // Monthly → annually on ONE product is a real switch: the same-plan guard
+        // keys on product AND frequency, never on product alone. The provider is
+        // deliberately unknown, so the route stops at the NEXT gate — reaching it
+        // is the proof, and nothing is dispatched.
+        const { from } = paidPair(config, skip);
+        const frequencies = Object.keys(from.prices);
+
+        if (frequencies.length < 2) {
+          skip(`Product ${from.id} is priced at a single frequency`);
+        }
+
+        const user = subscriber(Manager, { uid: '_test-plan-frequency', product: from, frequency: frequencies[0], provider: 'unknown-provider' });
+
+        const sent = await switchPlan(Manager, user, { productId: from.id, frequency: frequencies[1] });
+
+        assert.equal(sent.code, 400, `Expected the unknown-provider gate, got ${sent.code}`);
+        assert.ok(!/already on/i.test(`${sent.body}`), `A frequency change must clear the same-plan guard, got: ${sent.body}`);
+      },
+    },
+
+    {
+      name: 'rejects-missing-payment-details',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { from, to } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-no-provider', product: from, frequency: frequencyOf(from), provider: null, resourceId: null });
+
+        const sent = await switchPlan(Manager, user, { productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `Without a provider there is nothing to call, got ${sent.code}`);
+      },
+    },
+
+    {
+      name: 'rejects-unknown-provider',
+      auth: 'none',
+      async run({ assert, Manager, config, skip }) {
+        const { from, to } = paidPair(config, skip);
+        const user = subscriber(Manager, { uid: '_test-plan-unknown-provider', product: from, frequency: frequencyOf(from), provider: 'unknown-provider' });
+
+        const sent = await switchPlan(Manager, user, { productId: to.id, frequency: frequencyOf(to) });
+
+        assert.equal(sent.code, 400, `An unknown provider must be refused, got ${sent.code}`);
+      },
+    },
+
+    // ─── the capability TABLE: the export list IS the contract ───
+
+    {
+      name: 'every-provider-supports-plan-switch',
+      auth: 'none',
+      async run({ assert }) {
+        // Unlike uncancel, every provider here can move a live subscription:
+        // Stripe updates the item, Chargebee updates for items, PayPal revises.
+        PROVIDERS.forEach((name) => {
+          assert.equal(typeof providerModule(name).switchPlan, 'function', `${name} should export switchPlan()`);
+        });
+      },
+    },
+  ],
+});

package/test/routes/payments/portal-return-url.test.js

@@ -0,0 +1,107 @@
+/**
+ * Test: POST /payments/portal — `returnUrl` must be the brand's own
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * `returnUrl` is client-settable and lands inside the provider's hosted billing
+ * page as the "back to the site" link. An arbitrary host there turns the brand's
+ * own billing portal into a redirector to anywhere — a phishing hop that wears
+ * the brand's checkout. The route now accepts only the brand's own resolved
+ * origins and falls back to the brand's account page, with a warning, otherwise.
+ *
+ * The `test` portal provider answers with the returnUrl it was handed, so the
+ * response IS the assertion about what the provider would have received.
+ *
+ * Run: npx omega test backend:routes/payments/portal-return-url
+ */
+const { buildUser, callHandler } = require('./_route-harness.js');
+
+const handler = require('../../../dist/manager/routes/payments/portal/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// Where the route sends a caller whose returnUrl it refused.
+const DEFAULT_RETURN = (Manager) => new URL('/dashboard/account#billing', Manager.project.websiteUrl).toString();
+
+function subscriber(Manager) {
+  return buildUser(Manager, {
+    auth: { uid: '_test-portal-return-url', email: '_test.portal-return-url@example.com' },
+    roles: {},
+    subscription: {
+      product: { id: 'premium', name: 'Premium' },
+      status: 'active',
+      payment: { provider: 'test', resourceId: 'sub_test_portal_return_url' },
+    },
+  });
+}
+
+function openPortal(Manager, returnUrl) {
+  return callHandler({
+    Manager,
+    handler,
+    functionName: 'payments-portal',
+    user: subscriber(Manager),
+    settings: { returnUrl: returnUrl },
+  });
+}
+
+module.exports = defineCases({
+  description: 'Payment portal endpoint: returnUrl is same-origin only',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'an-off-brand-return-url-falls-back',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const sent = await openPortal(Manager, 'https://evil.example/steal');
+
+        assert.equal(sent.code, 200, `The portal should still open, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.equal(sent.body.url, DEFAULT_RETURN(Manager), 'An off-brand host must never reach the provider');
+      },
+    },
+
+    {
+      name: 'a-look-alike-host-falls-back',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        // The classic near-miss: the brand's origin as a prefix of somebody else's host
+        const origin = new URL(Manager.project.websiteUrl).origin;
+        const sent = await openPortal(Manager, `${origin}.evil.example/dashboard/account`);
+
+        assert.equal(sent.body.url, DEFAULT_RETURN(Manager), 'A host that merely starts with the brand origin must not pass');
+      },
+    },
+
+    {
+      name: 'an-unparseable-return-url-falls-back',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const sent = await openPortal(Manager, 'not a url at all');
+
+        assert.equal(sent.body.url, DEFAULT_RETURN(Manager), 'An unparseable value must fall back, never be forwarded');
+      },
+    },
+
+    {
+      name: 'a-missing-return-url-falls-back',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const sent = await openPortal(Manager, null);
+
+        assert.equal(sent.body.url, DEFAULT_RETURN(Manager), 'No returnUrl should still return to the brand');
+      },
+    },
+
+    {
+      name: 'the-brands-own-return-url-passes-through',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const returnUrl = new URL('/dashboard/account?tab=invoices', Manager.project.websiteUrl).toString();
+
+        const sent = await openPortal(Manager, returnUrl);
+
+        assert.equal(sent.body.url, returnUrl, "The brand's own URL should be honored exactly as asked");
+      },
+    },
+  ],
+});

package/test/routes/payments/portal.test.js

@@ -0,0 +1,94 @@
+/**
+ * Test: POST /payments/portal - Validation errors
+ * Tests rejection cases before any provider call is made.
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Payment portal endpoint: validation errors',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'rejects-unauthenticated',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/portal', {
+          returnUrl: 'https://example.com/account',
+        });
+
+        assert.isError(response, 401, 'Should reject unauthenticated request');
+      },
+    },
+
+    {
+      name: 'rejects-basic-user',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/portal', {
+          returnUrl: 'https://example.com/account',
+        });
+
+        assert.isError(response, 400, 'Should reject basic user with no paid subscription');
+      },
+    },
+
+    {
+      name: 'rejects-no-provider',
+      async run({ http, assert }) {
+        // portal-no-provider starts with payment.provider=null
+        const response = await http.as('portal-no-provider').post('backend-manager/payments/portal', {
+          returnUrl: 'https://example.com/account',
+        });
+
+        assert.isError(response, 400, 'Should reject when no provider is set');
+      },
+    },
+
+    {
+      name: 'rejects-unknown-provider',
+      async run({ http, assert }) {
+        // portal-unknown-provider starts with provider='unknown-provider'
+        const response = await http.as('portal-unknown-provider').post('backend-manager/payments/portal', {
+          returnUrl: 'https://example.com/account',
+        });
+
+        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['journey-payments-portal-route'].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');
+        }
+
+        // Set up a paid subscription with the test provider
+        const intentResponse = await http.as('journey-payments-portal-route').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?.status === 'active';
+        }, 15000, 500);
+
+        // Call the portal endpoint
+        const portalResponse = await http.as('journey-payments-portal-route').post('backend-manager/payments/portal', {
+          returnUrl: 'https://example.com/account',
+        });
+
+        assert.isSuccess(portalResponse, 'Portal should succeed');
+        assert.ok(portalResponse.data.url, 'Should return a URL');
+      },
+    },
+  ],
+});