@omega.js/backend 0.1.0

package/test/events/payments/journey-payments-legacy-product.test.js

@@ -0,0 +1,151 @@
+/**
+ * Test: Payment Journey - Legacy Product ID Resolution
+ * Simulates: webhook with a legacy Stripe product ID → resolves to the correct product
+ *
+ * Verifies Fix 4: when an existing subscriber's webhook carries a legacy product ID
+ * (from before product migration), resolveProduct() checks stripe.legacyProductIds[]
+ * and maps it to the correct current product.
+ *
+ * Flow:
+ * 1. Find a config product that has stripe.legacyProductIds (skip if none)
+ * 2. Send a customer.subscription.created webhook with the legacy product ID in plan.product
+ * 3. Verify: subscription.product.id resolves to the correct (current) product ID
+ *
+ * This test is config-dependent — it requires at least one product with legacyProductIds.
+ * If no such product exists, the test skips gracefully.
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Payment journey: webhook with legacy product ID → correct product resolution',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'find-product-with-legacy-ids',
+      async run({ accounts, assert, state, config }) {
+        const uid = accounts['journey-payments-legacy-product'].uid;
+        state.uid = uid;
+
+        // Find a paid product that has legacy Stripe product IDs configured
+        const productWithLegacy = config.payment?.products?.find(
+          p => p.id !== 'basic'
+            && p.prices?.monthly
+            && p.stripe?.legacyProductIds?.length > 0,
+        );
+
+        if (!productWithLegacy) {
+          state.skip = true;
+          console.log('No product with stripe.legacyProductIds found in config — skipping legacy product ID test');
+          return;
+        }
+
+        state.skip = false;
+        state.productId = productWithLegacy.id;
+        state.productName = productWithLegacy.name;
+        state.currentStripeProductId = productWithLegacy.stripe.productId;
+        state.legacyStripeProductId = productWithLegacy.stripe.legacyProductIds[0];
+
+        assert.ok(state.legacyStripeProductId, 'Legacy product ID should exist');
+        assert.notEqual(state.legacyStripeProductId, state.currentStripeProductId, 'Legacy ID should differ from current ID');
+      },
+    },
+
+    {
+      name: 'send-webhook-with-legacy-product-id',
+      async run({ http, assert, state, config }) {
+        if (state.skip) {
+          return;
+        }
+
+        const futureDate = new Date();
+        futureDate.setMonth(futureDate.getMonth() + 1);
+
+        state.legacyEventId = `_test-evt-journey-legacy-prod-${Date.now()}`;
+        state.subscriptionId = `sub_test_legacy_${Date.now()}`;
+
+        // Send a subscription created webhook with the LEGACY product ID
+        // This simulates an existing subscriber whose Stripe subscription still
+        // references the old product ID from before migration
+        const response = await http.as('none').post(`backend-manager/payments/webhook?provider=test&key=${config.webhookKey}`, {
+          id: state.legacyEventId,
+          type: 'customer.subscription.created',
+          data: {
+            object: {
+              id: state.subscriptionId,
+              object: 'subscription',
+              status: 'active',
+              metadata: { uid: state.uid },
+              cancel_at_period_end: false,
+              canceled_at: null,
+              current_period_end: Math.floor(futureDate.getTime() / 1000),
+              current_period_start: Math.floor(Date.now() / 1000),
+              start_date: Math.floor(Date.now() / 1000),
+              trial_start: null,
+              trial_end: null,
+              // KEY: use the LEGACY product ID, not the current one
+              plan: { product: state.legacyStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook with legacy product ID should be accepted');
+      },
+    },
+
+    {
+      name: 'legacy-product-resolved-correctly',
+      async run({ firestore, assert, state, waitFor }) {
+        if (state.skip) {
+          return;
+        }
+
+        // Wait for webhook to complete
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.legacyEventId}`);
+          return doc?.status === 'completed' || doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.legacyEventId}`);
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete successfully');
+        assert.equal(webhookDoc.transition, 'new-subscription', 'Transition should be new-subscription');
+
+        // Core assertion: the legacy product ID resolved to the correct current product
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        assert.equal(
+          userDoc.subscription.product.id,
+          state.productId,
+          `Legacy product ID "${state.legacyStripeProductId}" should resolve to "${state.productId}" (not "basic")`,
+        );
+        assert.equal(userDoc.subscription.status, 'active', 'Status should be active');
+        assert.equal(userDoc.subscription.payment.provider, 'test', 'Provider should be test');
+      },
+    },
+
+    {
+      name: 'order-doc-has-correct-product',
+      async run({ firestore, assert, state }) {
+        if (state.skip) {
+          return;
+        }
+
+        // Find the order doc — legacy webhook may not have an orderId from metadata,
+        // so look it up by resourceId
+        const orderQuery = await firestore.query('payments-orders', {
+          where: [{ field: 'resourceId', op: '==', value: state.subscriptionId }],
+          limit: 1,
+        });
+
+        if (orderQuery && orderQuery.length > 0) {
+          const orderDoc = orderQuery[0];
+          assert.equal(
+            orderDoc.unified?.product?.id,
+            state.productId,
+            `Order unified product should be "${state.productId}"`,
+          );
+        }
+      },
+    },
+  ],
+});

package/test/events/payments/journey-payments-one-time-decline.test.js

@@ -0,0 +1,127 @@
+/**
+ * Test: Payment Journey - Declined Checkout (one-time)
+ * Simulates: POST /payments/intent { simulate: 'decline' } on a one-time product
+ *            → invoice.payment_failed (billing_reason: manual) → purchase-failed
+ *
+ * Unlike journey-payments-one-time-failure (which posts the failed invoice straight
+ * to the webhook route), this journey reaches the decline THROUGH checkout.
+ *
+ * A one-time decline touches NO subscription state: the only residue is the failed
+ * purchase's own order + intent docs.
+ *
+ * Uses the journey-payments-one-time account (one-time events don't modify
+ * subscription state, so the one-time journeys share it).
+ */
+const User = require('../../../dist/manager/helpers/user.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  description: 'Payment journey: declined one-time checkout → purchase-failed, user untouched',
+  type: 'suite',
+  timeout: 60000,
+
+  tests: [
+    {
+      name: 'declined-checkout-accepted',
+      async run({ accounts, firestore, assert, state, config, http, skip }) {
+        const uid = accounts['journey-payments-one-time'].uid;
+
+        // Resolve first one-time product from config. If none configured, skip the
+        // entire journey — this is a config-gap, not a code failure.
+        const oneTimeProduct = config.payment.products.find(p => p.type === 'one-time' && p.prices?.once);
+        if (!oneTimeProduct) {
+          skip('No one-time product configured in this brand');
+        }
+
+        state.uid = uid;
+        state.productId = oneTimeProduct.id;
+
+        // Snapshot the subscription so the "untouched" assertion compares against
+        // whatever this shared account looked like going in
+        const before = await firestore.get(`users/${uid}`);
+        state.subscriptionBefore = before?.subscription || null;
+
+        const response = await http.as('journey-payments-one-time').post('backend-manager/payments/intent', {
+          provider: 'test',
+          productId: oneTimeProduct.id,
+          simulate: 'decline',
+        });
+
+        assert.isSuccess(response, 'Intent should succeed — the checkout starts, the payment is what fails');
+        state.orderId = response.data.orderId;
+      },
+    },
+
+    {
+      name: 'purchase-failed-transition-detected',
+      async run({ firestore, assert, state, waitFor }) {
+        const snapshot = await waitFor(async () => {
+          const query = await firestore.collection('payments-webhooks')
+            .where('orderId', '==', state.orderId)
+            .limit(1)
+            .get();
+
+          if (query.empty) {
+            return null;
+          }
+
+          const status = query.docs[0].data().status;
+          return (status === 'completed' || status === 'failed') ? query : null;
+        }, 20000, 500);
+
+        const webhookDoc = snapshot.docs[0].data();
+
+        assert.equal(webhookDoc.status, 'completed', 'Failed-invoice webhook should process cleanly');
+        assert.equal(webhookDoc.event.type, 'invoice.payment_failed', 'A declined one-time checkout fires the failed invoice');
+        assert.equal(webhookDoc.event.category, 'one-time', 'Category should be one-time');
+        assert.equal(webhookDoc.event.resourceType, 'invoice', 'Resource type should be invoice');
+        assert.equal(webhookDoc.transition, 'purchase-failed', 'Transition should be purchase-failed');
+      },
+    },
+
+    {
+      name: 'order-doc-records-the-failed-purchase',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.provider, 'test', 'Provider should be test');
+        assert.equal(orderDoc.productId, state.productId, 'Order should name the attempted product');
+        assert.notEqual(orderDoc.unified.status, 'completed', 'The purchase must not read as completed');
+      },
+    },
+
+    {
+      name: 'intent-doc-reflects-webhook-outcome',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.type, 'one-time', 'Type should be one-time');
+
+        // 'completed' means the PIPELINE completed, not that the payment succeeded —
+        // the intent sync is outcome-blind today ([#212]).
+        assert.equal(intentDoc.status, 'completed', 'Intent status tracks webhook processing, not payment outcome');
+        assert.equal(intentDoc.simulate, undefined, 'simulate is request-only — never persisted');
+      },
+    },
+
+    {
+      name: 'user-untouched',
+      async run({ firestore, assert, state }) {
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        assert.deepEqual(
+          userDoc.subscription,
+          state.subscriptionBefore,
+          'A one-time decline must leave subscription state exactly as it was',
+        );
+
+        const resolved = User.resolveSubscription(userDoc);
+        assert.equal(resolved.active, false, 'The account keeps its (free) access level');
+      },
+    },
+  ],
+});

package/test/events/payments/journey-payments-one-time-failure.test.js

@@ -0,0 +1,113 @@
+/**
+ * Test: Payment Journey - One-Time Payment Failure
+ * Simulates: invoice.payment_failed for a non-subscription invoice → purchase-failed transition
+ *
+ * This verifies the webhook routing for one-time invoice failures:
+ * invoice.payment_failed with no subscription billing_reason → category: 'one-time'
+ *
+ * Uses the journey-payments-one-time account (one-time events don't modify subscription state)
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Payment journey: one-time invoice.payment_failed → purchase-failed',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'resolve-one-time-product',
+      async run({ accounts, assert, state, config, skip }) {
+        const uid = accounts['journey-payments-one-time'].uid;
+
+        // Resolve first one-time product from config. If none configured, skip the
+        // entire journey — this is a config-gap, not a code failure.
+        const oneTimeProduct = config.payment.products.find(p => p.type === 'one-time' && p.prices?.once);
+        if (!oneTimeProduct) {
+          skip('No one-time product configured in this brand');
+        }
+
+        state.uid = uid;
+        state.productId = oneTimeProduct.id;
+      },
+    },
+
+    {
+      name: 'send-one-time-payment-failed',
+      async run({ http, assert, state, config }) {
+        state.eventId = `_test-evt-journey-onetime-fail-${Date.now()}`;
+        state.invoiceId = `_test-inv-onetime-fail-${Date.now()}`;
+        state.orderId = `0000-0000-0000`; // Fake orderId for test
+
+        // Send invoice.payment_failed with a non-subscription billing reason
+        // This routes to category: 'one-time' in the webhook parser
+        const response = await http.as('none').post(`backend-manager/payments/webhook?provider=test&key=${config.webhookKey}`, {
+          id: state.eventId,
+          type: 'invoice.payment_failed',
+          data: {
+            object: {
+              id: state.invoiceId,
+              object: 'invoice',
+              billing_reason: 'manual',
+              amount_due: 999,
+              amount_paid: 0,
+              status: 'open',
+              metadata: {
+                uid: state.uid,
+                orderId: state.orderId,
+                productId: state.productId,
+              },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'webhook-categorized-as-one-time',
+      async run({ firestore, assert, state, waitFor }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.eventId}`);
+          return doc?.status === 'completed' || doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
+        assert.ok(webhookDoc, 'Webhook doc should exist');
+        assert.equal(webhookDoc.event?.category, 'one-time', 'Category should be one-time');
+        assert.equal(webhookDoc.event?.resourceType, 'invoice', 'Resource type should be invoice');
+        assert.equal(webhookDoc.transition, 'purchase-failed', 'Transition should be purchase-failed');
+      },
+    },
+
+    {
+      name: 'order-doc-created-with-failure',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.provider, 'test', 'Provider should be test');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
+    {
+      name: 'subscription-unchanged',
+      async run({ firestore, assert, state }) {
+        // One-time payment failures must NOT modify subscription state
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        assert.equal(
+          userDoc.subscription?.product?.id,
+          'basic',
+          'Subscription should remain basic after one-time failure',
+        );
+      },
+    },
+  ],
+});

package/test/events/payments/journey-payments-one-time-refund.test.js

@@ -0,0 +1,186 @@
+/**
+ * Test: Payment Journey - One-Time Purchase Refunded
+ * Simulates: user → test intent (one-time product) → purchase-completed → POST /payments/refund
+ *            → charge.refunded webhook → purchase-refunded
+ *
+ * The refund of a one-time purchase is its own path end to end: the subject is
+ * the `payments-orders` doc (a one-time purchase never touches the user doc), the
+ * provider refunds the payment behind that order, and the resulting
+ * `charge.refunded` webhook carries no subscription — so it is categorized
+ * one-time and fires purchase-refunded ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * Requires at least one product with type: 'one-time' in config.payment.products
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Payment journey: one-time purchase → refund endpoint → purchase-refunded',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'resolve-one-time-product',
+      async run({ accounts, firestore, assert, state, config, skip }) {
+        const uid = accounts['journey-payments-one-time-refund'].uid;
+        const userDoc = await firestore.get(`users/${uid}`);
+
+        assert.ok(userDoc, 'User doc should exist');
+
+        // Resolve first one-time product from config. If the brand has none configured,
+        // skip the entire journey — this is a config-gap, not a code failure.
+        const oneTimeProduct = config.payment.products.find(p => p.type === 'one-time' && p.prices?.once);
+        if (!oneTimeProduct) {
+          skip('No one-time product configured in this brand');
+        }
+
+        state.uid = uid;
+        state.productId = oneTimeProduct.id;
+        state.price = oneTimeProduct.prices.once;
+
+        // Snapshot subscription before the purchase — a one-time refund must not touch it
+        state.subscriptionBefore = userDoc.subscription || null;
+      },
+    },
+
+    {
+      name: 'buy-the-one-time-product',
+      async run({ http, firestore, assert, state, waitFor }) {
+        const response = await http.as('journey-payments-one-time-refund').post('backend-manager/payments/intent', {
+          provider: 'test',
+          productId: state.productId,
+        });
+
+        assert.isSuccess(response, 'Intent should succeed');
+
+        state.orderId = response.data.orderId;
+        state.purchaseEventId = response.data.id.replace('_test-cs-', '_test-evt-');
+
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.purchaseEventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
+        assert.equal(orderDoc.requests.refund, null, 'The purchase should start un-refunded');
+
+        // What the purchase IS, before any refund touches it — the refund updates
+        // this record, it never redefines it
+        state.purchase = {
+          productId: orderDoc.productId,
+          productName: orderDoc.unified?.product?.name,
+          price: orderDoc.unified?.payment?.price,
+          resourceId: orderDoc.resourceId,
+          paymentResourceId: orderDoc.unified?.payment?.resourceId,
+        };
+
+        assert.equal(state.purchase.productId, state.productId, 'The purchase should record the product bought');
+        assert.equal(state.purchase.price, state.price, 'The purchase should record what it cost');
+      },
+    },
+
+    {
+      name: 'refund-the-purchase',
+      async run({ http, assert, state }) {
+        const response = await http.as('journey-payments-one-time-refund').post('backend-manager/payments/refund', {
+          confirmed: true,
+          reason: 'Bought the wrong thing',
+          feedback: 'Testing the one-time refund flow',
+          orderId: state.orderId,
+        });
+
+        assert.isSuccess(response, 'Refund should succeed');
+        assert.ok(response.data.success, 'Should return success: true');
+        assert.ok(response.data.refund, 'Should return refund details');
+        assert.equal(response.data.refund.amount, state.price, 'A one-time purchase refunds its full price');
+        assert.equal(response.data.refund.full, true, 'A one-time refund is always full — there is no period to prorate');
+      },
+    },
+
+    {
+      name: 'refund-request-stored-on-the-order',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc.requests?.refund, 'The refund request should be stored on the order');
+        assert.equal(orderDoc.requests.refund.reason, 'Bought the wrong thing', 'The reason should be stored');
+        assert.equal(orderDoc.requests.refund.feedback, 'Testing the one-time refund flow', 'The feedback should be stored');
+        assert.equal(orderDoc.requests.refund.full, true, 'The stored request should record a full refund');
+        assert.ok(orderDoc.requests.refund.date?.timestampUNIX > 0, 'The refund date should be stamped');
+      },
+    },
+
+    {
+      name: 'refund-webhook-fires-purchase-refunded',
+      async run({ firestore, assert, state, waitFor }) {
+        // The test provider writes the synthetic charge.refunded doc itself, so its
+        // event id is not knowable here — find it by owner + event type.
+        const webhookDoc = await waitFor(async () => {
+          const snapshot = await firestore.collection('payments-webhooks')
+            .where('owner', '==', state.uid)
+            .where('event.type', '==', 'charge.refunded')
+            .get();
+
+          const doc = snapshot.docs.map(d => d.data()).find(d => d.status === 'completed' || d.status === 'failed');
+          return doc || null;
+        }, 15000, 500);
+
+        assert.equal(webhookDoc.status, 'completed', `The refund webhook should complete (error: ${webhookDoc.error || 'none'})`);
+        assert.equal(webhookDoc.event.category, 'one-time', 'A refund with no subscription is a one-time event');
+        assert.equal(webhookDoc.transition, 'purchase-refunded', 'Transition should be purchase-refunded');
+        assert.equal(webhookDoc.orderId, state.orderId, 'The refund should resolve back to the order it refunded');
+      },
+    },
+
+    {
+      name: 'the-purchase-record-survives-the-refund',
+      async run({ firestore, assert, state }) {
+        // The refund event carries the CHARGE that moved the money back — a bare
+        // charge names no product and no price. Re-deriving the order from it
+        // degraded the purchase to product=unknown / price=0 and replaced the
+        // checkout resourceId with the charge id, so the buyer's order silently
+        // stopped saying what they bought ([#212]).
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.equal(orderDoc.productId, state.purchase.productId, 'The refunded order should still name the product bought');
+        assert.equal(orderDoc.unified.product.id, state.purchase.productId, 'The unified product should survive the refund');
+        assert.equal(orderDoc.unified.product.name, state.purchase.productName, 'The product name should survive the refund');
+        assert.equal(orderDoc.unified.payment.price, state.purchase.price, 'The price paid should survive the refund');
+        assert.equal(orderDoc.resourceId, state.purchase.resourceId, 'The order should still point at the checkout resource, not the charge');
+        assert.equal(orderDoc.unified.payment.resourceId, state.purchase.paymentResourceId, 'The unified payment resource should still be the checkout resource');
+
+        // What the refund DOES change: the outcome
+        assert.equal(orderDoc.unified.status, 'refunded', 'The purchase should now read as refunded');
+        assert.equal(parseFloat(orderDoc.unified.payment.refund.amount), state.price, 'The refunded amount should be recorded on the order');
+        assert.equal(orderDoc.unified.payment.refund.currency, 'USD', 'The refunded currency should be recorded');
+        assert.ok(orderDoc.unified.payment.refund.date?.timestampUNIX > 0, 'The refund should be dated');
+
+        // The endpoint's own record is untouched by the webhook that followed it
+        assert.equal(orderDoc.requests.refund.reason, 'Bought the wrong thing', 'The refund request should still be on the order');
+      },
+    },
+
+    {
+      name: 'subscription-unchanged',
+      async run({ firestore, assert, state }) {
+        // A one-time refund must NOT modify users/{uid}.subscription
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        const subAfter = userDoc.subscription || null;
+
+        assert.equal(
+          subAfter?.product?.id,
+          state.subscriptionBefore?.product?.id,
+          'Subscription product should be unchanged after a one-time refund',
+        );
+        assert.equal(
+          subAfter?.status,
+          state.subscriptionBefore?.status,
+          'Subscription status should be unchanged after a one-time refund',
+        );
+      },
+    },
+  ],
+});