@omega.js/backend 0.1.0

package/test/routes/payments/dedup-race.test.js

@@ -0,0 +1,186 @@
+/**
+ * Test: the webhook and dispute-alert doors deduplicate ATOMICALLY
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * Both routes used to read the doc, then write it. Providers retry, and a retry
+ * can arrive while the first delivery is still in flight — in that window both
+ * deliveries see no doc and both write, and the pipeline runs the same event
+ * twice (for a dispute, that is two refunds). Both routes now claim the doc
+ * inside a transaction, so exactly one delivery wins.
+ *
+ * The race can only be proven by running two deliveries CONCURRENTLY, which is
+ * why these ride the direct-handler harness: two handlers in one process,
+ * started together, are a real same-instant pair — an HTTP pair would race the
+ * network instead of the code.
+ *
+ * The concurrent pair runs on the WEBHOOK door only, and that is a property of
+ * the emulator, not of the fix. The dispute door's own onWrite trigger fails
+ * every synthetic alert (no STRIPE_SECRET_KEY, so the charge search throws), and
+ * a `failed` doc is by contract RECLAIMABLE — so the losing transaction, which
+ * correctly blocks and re-reads, finds a failed doc and legitimately retries.
+ * That sanctioned retry is indistinguishable from the bug, so racing it would
+ * assert the trigger's timing rather than the claim. The dispute door's claim is
+ * the same transaction as the webhook's, and its reclaim contract is pinned
+ * below; its duplicate contract is pinned in dispute-alert.test.js.
+ *
+ * Run: npx omega test backend:routes/payments/dedup-race
+ */
+const { callHandler } = require('./_route-harness.js');
+const { TEST_ACCOUNTS } = require('../../../dist/test/test-accounts.js');
+
+const webhookHandler = require('../../../dist/manager/routes/payments/webhook/post.js');
+const disputeHandler = require('../../../dist/manager/routes/payments/dispute-alert/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const VALID_KEY = () => process.env.OMEGA_WEBHOOK_KEY;
+
+// The `test` provider fabricates Stripe-shaped events locally and signs nothing,
+// so a webhook delivery here never needs a secret or the network.
+function deliverWebhook(Manager, eventId) {
+  return callHandler({
+    Manager,
+    handler: webhookHandler,
+    functionName: 'payments-webhook',
+    req: {
+      query: { provider: 'test', key: VALID_KEY() },
+      body: {
+        id: eventId,
+        type: 'customer.subscription.updated',
+        data: {
+          object: {
+            id: 'sub_test_dedup_race',
+            metadata: { uid: TEST_ACCOUNTS.basic.uid },
+            status: 'active',
+          },
+        },
+      },
+    },
+  });
+}
+
+function deliverDisputeAlert(Manager, alertId) {
+  return callHandler({
+    Manager,
+    handler: disputeHandler,
+    functionName: 'payments-dispute-alert',
+    req: {
+      query: { key: VALID_KEY() },
+      body: {
+        id: alertId,
+        card: '4242',
+        amount: 19.99,
+        transactionDate: '2026-03-07',
+      },
+    },
+  });
+}
+
+// Exactly one of the two deliveries may be the one that processed.
+function assertExactlyOneProcessed(assert, sent, label) {
+  sent.forEach((response, index) => {
+    assert.equal(response.code, 200, `${label} delivery ${index + 1} should answer 200, got ${response.code}: ${JSON.stringify(response.body)}`);
+  });
+
+  const processed = sent.filter((response) => !response.body?.duplicate);
+  const duplicates = sent.filter((response) => response.body?.duplicate === true);
+
+  assert.equal(processed.length, 1, `${label}: exactly one delivery may process, got ${processed.length}`);
+  assert.equal(duplicates.length, 1, `${label}: the other delivery must be told it is a duplicate, got ${duplicates.length}`);
+}
+
+module.exports = defineCases({
+  description: 'Payment webhook + dispute alert: same-instant deliveries deduplicate',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'two-same-instant-webhook-deliveries-process-once',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const eventId = '_test-evt-dedup-race';
+
+        const sent = await Promise.all([
+          deliverWebhook(Manager, eventId),
+          deliverWebhook(Manager, eventId),
+        ]);
+
+        assertExactlyOneProcessed(assert, sent, 'webhook');
+      },
+    },
+
+    {
+      name: 'a-failed-webhook-is-still-reclaimable',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const eventId = '_test-evt-dedup-race-retry';
+
+        // The retry path the atomic claim must preserve: a previously FAILED
+        // delivery is the one existing state a new delivery may take over.
+        await firestore.set(`payments-webhooks/${eventId}`, { id: eventId, status: 'failed', error: 'Previous error' });
+
+        const sent = await deliverWebhook(Manager, eventId);
+
+        assert.equal(sent.code, 200, `A retry should answer 200, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.ok(!sent.body?.duplicate, 'A failed webhook must not be reported as a duplicate');
+      },
+    },
+
+    {
+      // The reclaim's OTHER half, and the one nothing pinned: the claim is a full
+      // `set`, not a merge, so taking over a failed doc wipes the retry ledger the
+      // frequent sweep built up — `retryCount`, `deadLetter` and the previous
+      // error all go. That is the documented escape hatch, ruled on #220: a
+      // provider REDELIVERY is fresh evidence, so it starts a new bounded ladder
+      // and a dead-lettered doc becomes processable again. Ruled, but only
+      // reachable through the claim, so a future merge-instead-of-set would have
+      // taken the escape hatch away silently
+      // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+      name: 'a-reclaimed-webhook-starts-a-fresh-retry-ladder',
+      auth: 'none',
+      async run({ assert, Manager, firestore, waitFor }) {
+        const eventId = '_test-evt-dedup-race-deadlettered';
+
+        // A doc the sweep gave up on: the ceiling burned, stamped once, terminal.
+        await firestore.set(`payments-webhooks/${eventId}`, {
+          id: eventId,
+          status: 'failed',
+          error: 'Previous error',
+          retryCount: 5,
+          deadLetter: true,
+        });
+
+        const sent = await deliverWebhook(Manager, eventId);
+
+        assert.equal(sent.code, 200, `A redelivery should answer 200, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.ok(!sent.body?.duplicate, 'A dead-lettered webhook must still be reclaimable — redelivery is the escape hatch');
+
+        // The trigger takes it from here; either terminal state proves the claim
+        // landed and the pipeline ran it again.
+        const settled = await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${eventId}`);
+          return ['completed', 'failed'].includes(doc?.status) ? doc : null;
+        }, 20000, 250);
+
+        assert.ok(!settled.deadLetter, 'The reclaim clears the dead-letter stamp — the doc is live again');
+        assert.ok((settled.retryCount || 0) < 5, `The reclaim restarts the ladder rather than resuming a burned one, got retryCount=${settled.retryCount}`);
+        assert.notEqual(settled.error, 'Previous error', 'The reclaim replaces the record wholesale — the previous failure does not survive it');
+      },
+    },
+
+    {
+      name: 'a-failed-dispute-alert-is-still-reclaimable',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const alertId = '_test-dispute-dedup-race-retry';
+
+        await firestore.set(`payments-disputes/${alertId}`, { id: alertId, status: 'failed', error: 'Previous error' });
+
+        const sent = await deliverDisputeAlert(Manager, alertId);
+
+        assert.equal(sent.code, 200, `A retry should answer 200, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.ok(!sent.body?.duplicate, 'A failed dispute alert must not be reported as a duplicate');
+      },
+    },
+  ],
+});

package/test/routes/payments/discount.test.js

@@ -0,0 +1,82 @@
+/**
+ * Test: GET /payments/discount
+ * Tests discount code validation endpoint
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Discount code validation',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'rejects-missing-code',
+      async run({ http, assert }) {
+        const response = await http.as('none').get('backend-manager/payments/discount');
+
+        assert.isError(response, 400, 'Should reject missing code');
+      },
+    },
+
+    {
+      name: 'returns-valid-for-known-code',
+      async run({ http, assert }) {
+        const response = await http.as('none').get('backend-manager/payments/discount', {
+          code: 'FLASH20',
+        });
+
+        assert.isSuccess(response, 'Should succeed for valid code');
+        assert.equal(response.data.valid, true, 'Should be valid');
+        assert.equal(response.data.code, 'FLASH20', 'Should return normalized code');
+        assert.equal(response.data.percent, 20, 'Should return correct percent');
+        assert.equal(response.data.duration, 'once', 'Should return duration');
+      },
+    },
+
+    {
+      name: 'returns-valid-case-insensitive',
+      async run({ http, assert }) {
+        const response = await http.as('none').get('backend-manager/payments/discount', {
+          code: 'flash20',
+        });
+
+        assert.isSuccess(response, 'Should succeed for lowercase code');
+        assert.equal(response.data.valid, true, 'Should be valid (case-insensitive)');
+        assert.equal(response.data.code, 'FLASH20', 'Should return uppercase code');
+      },
+    },
+
+    {
+      name: 'returns-invalid-for-unknown-code',
+      async run({ http, assert }) {
+        const response = await http.as('none').get('backend-manager/payments/discount', {
+          code: 'NOTAREALCODE',
+        });
+
+        assert.isSuccess(response, 'Should return 200 even for invalid code');
+        assert.equal(response.data.valid, false, 'Should be invalid');
+      },
+    },
+
+    {
+      name: 'validates-all-known-codes',
+      async run({ http, assert }) {
+        const codes = [
+          { code: 'FLASH20', percent: 20 },
+          { code: 'SAVE10', percent: 10 },
+          { code: 'WELCOME15', percent: 15 },
+        ];
+
+        for (const { code, percent } of codes) {
+          const response = await http.as('none').get('backend-manager/payments/discount', { code });
+
+          assert.isSuccess(response, `Should succeed for ${code}`);
+          assert.equal(response.data.valid, true, `${code} should be valid`);
+          assert.equal(response.data.percent, percent, `${code} should be ${percent}%`);
+          assert.equal(response.data.duration, 'once', `${code} should be once`);
+        }
+      },
+    },
+  ],
+});

package/test/routes/payments/dispute-alert.test.js

@@ -0,0 +1,324 @@
+/**
+ * Test: POST /payments/dispute-alert
+ * Tests the dispute alert endpoint validates requests and saves to Firestore
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Dispute alert endpoint',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'rejects-missing-key',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/dispute-alert', {});
+
+        assert.isError(response, 401, 'Should reject missing key');
+      },
+    },
+
+    {
+      name: 'rejects-invalid-key',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/dispute-alert?key=wrong-key', {});
+
+        assert.isError(response, 401, 'Should reject invalid key');
+      },
+    },
+
+    {
+      name: 'rejects-unknown-provider',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?provider=unknown&key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: '_test-dispute-unknown-provider',
+          card: '4242',
+          amount: 9.99,
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isError(response, 400, 'Should reject unknown alert provider');
+      },
+    },
+
+    {
+      name: 'rejects-missing-id',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          card: '4242',
+          amount: 9.99,
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isError(response, 400, 'Should reject missing id');
+      },
+    },
+
+    {
+      name: 'rejects-missing-card',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: '_test-dispute-no-card',
+          amount: 9.99,
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isError(response, 400, 'Should reject missing card');
+      },
+    },
+
+    {
+      name: 'rejects-missing-amount',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: '_test-dispute-no-amount',
+          card: '4242',
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isError(response, 400, 'Should reject missing amount');
+      },
+    },
+
+    {
+      name: 'rejects-missing-transaction-date',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: '_test-dispute-no-date',
+          card: '4242',
+          amount: 9.99,
+        });
+
+        assert.isError(response, 400, 'Should reject missing transactionDate');
+      },
+    },
+
+    {
+      name: 'accepts-valid-chargeblast-alert',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-valid';
+
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '4242424242424242',
+          cardBrand: 'Visa',
+          amount: 29.99,
+          transactionDate: '2026-03-07 14:30:00',
+          // Chargeblast's own field name on the wire (#428 leftover) — the
+          // route normalizes it onto `alert.provider`
+          processor: 'stripe',
+          alertType: 'FRAUD',
+          customerEmail: 'test@example.com',
+          externalOrder: 'ch_test123',
+          metadata: 'pi_test456',
+          externalUrl: 'https://dashboard.stripe.com/charges/ch_test123',
+          reasonCode: 'WIP',
+          subprovider: 'Ethoca',
+          isRefunded: false,
+        });
+
+        assert.isSuccess(response, 'Should accept valid Chargeblast alert');
+        assert.equal(response.data.received, true, 'Should confirm receipt');
+
+        // Verify doc was saved to Firestore
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.ok(doc, 'Dispute doc should exist in Firestore');
+        assert.equal(doc.provider, 'chargeblast', 'Provider should be chargeblast');
+        assert.ok(
+          doc.status === 'pending' || doc.status === 'processing',
+          'Status should be pending or processing',
+        );
+
+        // Verify core normalized alert data
+        assert.equal(doc.alert.card.last4, '4242', 'Should extract last4 from full card number');
+        assert.equal(doc.alert.card.brand, 'visa', 'Should lowercase card brand');
+        assert.equal(doc.alert.amount, 29.99, 'Amount should be preserved');
+        assert.equal(doc.alert.transactionDate, '2026-03-07', 'Should extract date without time');
+        assert.equal(doc.alert.provider, 'stripe', 'Provider should be stripe');
+
+        // Verify new normalized fields
+        assert.equal(doc.alert.alertType, 'FRAUD', 'Alert type should be preserved');
+        assert.equal(doc.alert.customerEmail, 'test@example.com', 'Customer email should be preserved');
+        assert.equal(doc.alert.chargeId, 'ch_test123', 'Charge ID should be extracted from externalOrder');
+        assert.equal(doc.alert.paymentIntentId, 'pi_test456', 'Payment intent ID should be extracted from metadata');
+        assert.equal(doc.alert.stripeUrl, 'https://dashboard.stripe.com/charges/ch_test123', 'Stripe URL should be preserved');
+        assert.equal(doc.alert.reasonCode, 'WIP', 'Reason code should be preserved');
+        assert.equal(doc.alert.subprovider, 'Ethoca', 'Subprovider should be preserved');
+        assert.equal(doc.alert.isRefunded, false, 'isRefunded should be preserved');
+
+        // Verify raw payload is preserved
+        assert.ok(doc.raw, 'Raw payload should be preserved');
+        assert.equal(doc.raw.id, alertId, 'Raw id should match');
+      },
+    },
+
+    {
+      name: 'accepts-alert-with-alertId-field',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-alertid-field';
+
+        // Chargeblast alert.created events use alertId instead of id
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          alertId: alertId,
+          card: '546616******5805',
+          cardBrand: 'Mastercard',
+          amount: 8,
+          transactionDate: '2026-03-19 00:00:00.000000Z',
+        });
+
+        assert.isSuccess(response, 'Should accept alert using alertId field');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.ok(doc, 'Dispute doc should exist in Firestore');
+        assert.equal(doc.id, alertId, 'Doc ID should match alertId');
+        assert.equal(doc.alert.id, alertId, 'Alert id should be set from alertId');
+        assert.equal(doc.alert.card.last4, '5805', 'Should extract last4 from masked card');
+      },
+    },
+
+    {
+      name: 'accepts-alert-without-optional-fields',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-minimal';
+
+        // Send minimal alert (alert.created shape — no externalOrder, metadata, etc.)
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '9124',
+          amount: 10,
+          transactionDate: '2026-03-21 00:01:02',
+        });
+
+        assert.isSuccess(response, 'Should accept minimal alert');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.equal(doc.alert.card.last4, '9124', 'Should use card as last4');
+        assert.equal(doc.alert.provider, 'stripe', 'Provider should default to stripe');
+        assert.equal(doc.alert.chargeId, null, 'Charge ID should be null when not provided');
+        assert.equal(doc.alert.paymentIntentId, null, 'Payment intent should be null when not provided');
+        assert.equal(doc.alert.customerEmail, null, 'Customer email should be null when not provided');
+        assert.equal(doc.alert.alertType, null, 'Alert type should be null when not provided');
+        assert.equal(doc.alert.stripeUrl, null, 'Stripe URL should be null when not provided');
+        assert.equal(doc.alert.reasonCode, null, 'Reason code should be null when not provided');
+        assert.equal(doc.alert.subprovider, null, 'Subprovider should be null when not provided');
+        assert.equal(doc.alert.isRefunded, false, 'isRefunded should default to false');
+      },
+    },
+
+    {
+      name: 'accepts-alert-with-last4-only',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-last4';
+
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '1234',
+          amount: 9.99,
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isSuccess(response, 'Should accept alert with card last4 only');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.equal(doc.alert.card.last4, '1234', 'Should use card value as last4 when already 4 digits');
+        assert.equal(doc.alert.provider, 'stripe', 'Provider should default to stripe');
+      },
+    },
+
+    {
+      name: 'deduplicates-dispute-alerts',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-duplicate';
+
+        // Pre-seed an in-flight dispute directly. We seed (rather than POST a first alert)
+        // because the route fires an async on-write trigger that, for synthetic test data
+        // with no matching charge, can transition the doc to 'failed' — at which point the
+        // dedup contract intentionally treats it as RETRYABLE, not a duplicate. Racing a
+        // live POST against that trigger made this test flaky. Seeding 'processing' (a
+        // non-failed, in-flight state) deterministically exercises the dedup path.
+        await firestore.set(`payments-disputes/${alertId}`, {
+          id: alertId,
+          status: 'processing',
+        });
+
+        // A subsequent identical alert must be reported as a duplicate (not reprocessed).
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '4242',
+          amount: 29.99,
+          transactionDate: '2026-03-07',
+        });
+
+        assert.isSuccess(response, 'Duplicate should still return 200');
+        assert.equal(response.data.duplicate, true, 'Should indicate duplicate');
+      },
+    },
+
+    {
+      name: 'retries-failed-alerts',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-retry';
+
+        // Pre-seed a failed dispute
+        await firestore.set(`payments-disputes/${alertId}`, {
+          id: alertId,
+          status: 'failed',
+          error: 'Previous error',
+        });
+
+        // Send alert with same ID — should retry since previous status was 'failed'
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '4242',
+          amount: 29.99,
+          transactionDate: '2026-03-07',
+        });
+
+        assert.isSuccess(response, 'Should accept retry of failed alert');
+        assert.ok(!response.data.duplicate, 'Should not indicate duplicate for failed retry');
+
+        // Verify doc was updated
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.ok(
+          doc.status === 'pending' || doc.status === 'processing',
+          'Status should be pending or processing after retry',
+        );
+      },
+    },
+
+    {
+      name: 'defaults-provider-to-chargeblast',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-default-provider';
+
+        // Send without provider query param
+        const response = await http.as('none').post(`backend-manager/payments/dispute-alert?key=${process.env.OMEGA_WEBHOOK_KEY}`, {
+          id: alertId,
+          card: '4242',
+          amount: 9.99,
+          transactionDate: '2026-01-15',
+        });
+
+        assert.isSuccess(response, 'Should accept without explicit provider param');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.equal(doc.provider, 'chargeblast', 'Provider should default to chargeblast');
+      },
+    },
+  ],
+});