@omega.js/backend 0.1.0

package/test/helpers/payment/paypal/refund-details.test.js

@@ -0,0 +1,202 @@
+/**
+ * Test: PayPal getRefundDetails()
+ * ([#510](https://github.com/Omega-JS-Stack/omega/issues/510)).
+ *
+ * The refund's amount used to be read out of the webhook envelope — whatever the
+ * caller posted — and written onto the order record and into the customer's
+ * refund email. The resource already in hand is no help either: it is the sale or
+ * the capture the refund reversed, i.e. the ORIGINAL payment, whose amount is the
+ * purchase price and not the refund's, which is simply wrong for a partial refund.
+ *
+ * So the refund is read back by its OWN id, the one the parser keeps beside the
+ * resourceId it reassigns to the sale/capture. Only the id comes from the event —
+ * the same trust level as the resourceId every lookup here starts from.
+ *
+ * The HTTP call is the one thing stubbed: reading a refund back needs live PayPal
+ * credentials (real PayPal calls are gated behind extended mode, never mocked).
+ *
+ * The fixtures are PayPal's own shapes: the v2 `Refund`
+ * (`GET /v2/payments/refunds/{id}`, `value`/`currency_code`) and the v1 refund
+ * (`GET /v1/payments/refund/{id}`, `total`/`currency`).
+ *
+ * Run: npx omega test backend:helpers/payment/paypal/refund-details
+ */
+const PayPal = require('../../../../dist/manager/libraries/payment/providers/paypal.js');
+
+const FIXTURE_CAPTURE_REFUNDED = require('../../../fixtures/paypal/capture-refunded.json');
+const defineCases = require('../../../../dist/vendor/devkit/test/define-cases.js');
+
+const REFUND_ID = FIXTURE_CAPTURE_REFUNDED.id;
+const V2_ENDPOINT = `/v2/payments/refunds/${REFUND_ID}`;
+const V1_ENDPOINT = `/v1/payments/refund/${REFUND_ID}`;
+
+// The sale the v1 refund reversed — the resource the pipeline already fetched,
+// carrying the price of the PURCHASE, not of the refund
+const SALE_RESOURCE = { id: 'SALE-OT', state: 'refunded', amount: { total: '49.99', currency: 'USD' } };
+
+/** Run fn with the library's HTTP call replaced by a stand-in, restored afterwards */
+async function withPayPalRequest(request, fn) {
+  const realRequest = PayPal.request;
+
+  PayPal.request = request;
+
+  try {
+    return await fn();
+  } finally {
+    PayPal.request = realRequest;
+  }
+}
+
+/** A stand-in that records every endpoint asked for and answers from `responses` */
+function requestReturning(responses, calls) {
+  return async (endpoint) => {
+    calls.push(endpoint);
+
+    const response = responses[endpoint];
+
+    if (!response) {
+      const error = new Error(`PayPal API 404: no stand-in response for ${endpoint}`);
+      error.statusCode = 404;
+      throw error;
+    }
+
+    return JSON.parse(JSON.stringify(response));
+  };
+}
+
+/** The envelope a refund event arrives in, claiming an inflated total */
+function envelope({ amount }) {
+  return { id: 'WH-refund', resource: { id: REFUND_ID, amount: amount } };
+}
+
+module.exports = defineCases({
+  description: 'PayPal getRefundDetails() reads the refund PayPal answered for',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'reads-the-v2-refund-back-by-its-own-id',
+      async run({ assert }) {
+        const calls = [];
+        const responses = { [V2_ENDPOINT]: FIXTURE_CAPTURE_REFUNDED };
+
+        const details = await withPayPalRequest(requestReturning(responses, calls), () => {
+          return PayPal.getRefundDetails({ id: 'CAPTURE-OT', amount: { value: '49.99', currency_code: 'USD' } }, {
+            refundId: REFUND_ID,
+            eventType: 'PAYMENT.CAPTURE.REFUNDED',
+            raw: envelope({ amount: { value: '999.99', currency_code: 'USD' } }),
+          });
+        });
+
+        assert.equal(calls.length, 1, 'The refund is read once');
+        assert.equal(calls[0], V2_ENDPOINT, 'A v2 capture refund reads at the v2 refunds endpoint');
+        assert.equal(details.amount, '9.99', 'The amount is PayPal\'s record of the refund');
+        assert.equal(details.currency, 'USD', 'And so is the currency');
+      },
+    },
+
+    {
+      name: 'reads-the-v1-refund-at-the-v1-endpoint',
+      async run({ assert }) {
+        const calls = [];
+        const responses = {
+          [V1_ENDPOINT]: { id: REFUND_ID, state: 'completed', amount: { total: '4.99', currency: 'EUR' }, reason_code: 'REFUND', sale_id: 'SALE-OT' },
+        };
+
+        const details = await withPayPalRequest(requestReturning(responses, calls), () => {
+          return PayPal.getRefundDetails(SALE_RESOURCE, {
+            refundId: REFUND_ID,
+            eventType: 'PAYMENT.SALE.REFUNDED',
+            raw: envelope({ amount: { total: '999.99', currency: 'EUR' } }),
+          });
+        });
+
+        assert.equal(calls[0], V1_ENDPOINT, 'A v1 sale refund reads at the v1 refund endpoint');
+        assert.equal(details.amount, '4.99', 'The v1 `total` spelling still resolves');
+        assert.equal(details.currency, 'EUR', 'And the v1 `currency` spelling with it');
+        assert.equal(details.reason, 'REFUND', 'The reason comes off the refund record');
+      },
+    },
+
+    {
+      name: 'never-answers-with-the-resource-the-refund-reversed',
+      async run({ assert }) {
+        // The sale is the ORIGINAL payment: reading its amount would report the
+        // purchase price as the refund, which a partial refund makes plainly wrong.
+        const responses = {
+          [V1_ENDPOINT]: { id: REFUND_ID, amount: { total: '4.99', currency: 'USD' } },
+        };
+
+        const details = await withPayPalRequest(requestReturning(responses, []), () => {
+          return PayPal.getRefundDetails(SALE_RESOURCE, { refundId: REFUND_ID, eventType: 'PAYMENT.SALE.REFUNDED' });
+        });
+
+        assert.equal(details.amount, '4.99', 'A partial refund reports what came back, not what was paid');
+      },
+    },
+
+    {
+      name: 'falls-back-to-the-refund-id-the-envelope-carries',
+      async run({ assert }) {
+        // A doc stored before the parser threaded the id still names the refund in
+        // the envelope — an identifier, read the same way resourceId is.
+        const calls = [];
+        const responses = { [V1_ENDPOINT]: { id: REFUND_ID, amount: { total: '4.99', currency: 'USD' } } };
+
+        await withPayPalRequest(requestReturning(responses, calls), () => {
+          return PayPal.getRefundDetails(SALE_RESOURCE, {
+            eventType: 'PAYMENT.SALE.REFUNDED',
+            raw: envelope({ amount: { total: '999.99', currency: 'USD' } }),
+          });
+        });
+
+        assert.equal(calls[0], V1_ENDPOINT, 'The envelope\'s refund id is enough to ask PayPal');
+      },
+    },
+
+    {
+      name: 'an-event-naming-no-refund-reports-no-amount',
+      async run({ assert }) {
+        const warnings = [];
+        const calls = [];
+
+        const details = await withPayPalRequest(requestReturning({}, calls), () => {
+          return PayPal.getRefundDetails(SALE_RESOURCE, {
+            eventType: 'PAYMENT.SALE.REFUNDED',
+            raw: { id: 'WH-refund', resource: {} },
+            ctx: { warn: (m) => warnings.push(m) },
+          });
+        });
+
+        assert.equal(calls.length, 0, 'There is nothing to ask PayPal about');
+        assert.equal(details.amount, null, 'The refund is recorded with no amount rather than with the payload\'s');
+        assert.equal(warnings.length, 1, 'And the gap is said out loud');
+      },
+    },
+
+    {
+      name: 'a-failed-refund-lookup-throws-rather-than-answering-with-the-payload',
+      async run({ assert }) {
+        // An amount that cannot be verified is not written at all ([#506]).
+        let threw = null;
+
+        try {
+          await withPayPalRequest(requestReturning({}, []), () => {
+            return PayPal.getRefundDetails(SALE_RESOURCE, {
+              refundId: REFUND_ID,
+              eventType: 'PAYMENT.SALE.REFUNDED',
+              raw: envelope({ amount: { total: '999.99', currency: 'USD' } }),
+            });
+          });
+        } catch (e) {
+          threw = e;
+        }
+
+        assert.ok(threw, 'A failed lookup must throw');
+        assert.equal(threw.notFound, true, 'A refund PayPal does not have is a terminal miss, classified by the same seam');
+        assert.equal(threw.resourceType, 'refund', 'The failure names the lookup that missed');
+        assert.equal(threw.resourceId, REFUND_ID, 'And the id it missed on');
+      },
+    },
+  ],
+});

package/test/helpers/payment/paypal/resolve-plan-id.test.js

@@ -0,0 +1,108 @@
+/**
+ * Test: PayPal resolvePlanId(), which TWIN a checkout subscribes to
+ * ([#761](https://github.com/Omega-JS-Stack/omega/issues/761)).
+ *
+ * PayPal puts a trial on the PLAN, never on the subscribe call, so the manager's
+ * payment walk mints two active plans per interval on a product that configures
+ * trial days: the trial twin (TRIAL cycle + REGULAR) and the skip-trial twin
+ * (REGULAR only). Matching by interval + amount alone picked whichever came back
+ * first, which is how a buyer who was refused a trial still got a free cycle.
+ *
+ * The HTTP call is the one thing stubbed (a real plan list needs live PayPal
+ * credentials); the matching is what is under test.
+ *
+ * Run: npx omega test backend:helpers/payment/paypal/resolve-plan-id
+ */
+const PayPal = require('../../../../dist/manager/libraries/payment/providers/paypal.js');
+const defineCases = require('../../../../dist/vendor/devkit/test/define-cases.js');
+
+const PRODUCT = { id: 'premium', name: 'Premium', type: 'subscription', trial: { days: 7 }, prices: { monthly: 20 }, paypal: { productId: 'PROD-TEST' } };
+
+/** A monthly plan for PROD-TEST, with or without the TRIAL cycle ahead of the REGULAR one */
+function plan(id, trialDays) {
+  const cycles = [];
+
+  if (trialDays > 0) {
+    cycles.push({ tenure_type: 'TRIAL', sequence: 1, total_cycles: trialDays, frequency: { interval_unit: 'DAY', interval_count: 1 }, pricing_scheme: { fixed_price: { value: '0', currency_code: 'USD' } } });
+  }
+
+  cycles.push({ tenure_type: 'REGULAR', sequence: cycles.length + 1, total_cycles: 0, frequency: { interval_unit: 'MONTH', interval_count: 1 }, pricing_scheme: { fixed_price: { value: '20.00', currency_code: 'USD' } } });
+
+  return { id, status: 'ACTIVE', billing_cycles: cycles };
+}
+
+// The trial twin FIRST, so a match on interval + amount alone would pick it
+const BOTH_TWINS = [plan('P-TRIAL', 7), plan('P-NO-TRIAL', 0)];
+
+/** Resolve against a fixed plan list, with the library's HTTP call restored afterwards */
+async function resolveAgainst(plans, trial) {
+  const realRequest = PayPal.request;
+
+  PayPal.request = async () => ({ plans: JSON.parse(JSON.stringify(plans)) });
+
+  try {
+    return await PayPal.resolvePlanId(PRODUCT, 'monthly', trial);
+  } finally {
+    PayPal.request = realRequest;
+  }
+}
+
+module.exports = defineCases({
+  description: 'PayPal resolvePlanId(): the twin a checkout lands on',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'a-trial-checkout-takes-the-trial-twin',
+      async run({ assert }) {
+        assert.equal(await resolveAgainst(BOTH_TWINS, true), 'P-TRIAL', 'The plan carrying the free cycle');
+      },
+    },
+
+    {
+      name: 'a-skip-trial-checkout-takes-the-no-trial-twin',
+      async run({ assert }) {
+        // The trial twin is first in the list and matches interval + amount, so
+        // this is exactly the pick the old matcher got wrong
+        assert.equal(await resolveAgainst(BOTH_TWINS, false), 'P-NO-TRIAL', 'The plan with no free cycle to skip');
+      },
+    },
+
+    {
+      name: 'a-product-without-trial-days-still-resolves-its-one-plan',
+      async run({ assert }) {
+        assert.equal(await resolveAgainst([plan('P-ONLY', 0)], false), 'P-ONLY', 'One plan, unchanged');
+      },
+    },
+
+    {
+      name: 'a-missing-twin-throws-and-names-it',
+      async run({ assert }) {
+        // A trial product the manager has not re-walked has only the trial twin.
+        // Falling back to it would hand a returning buyer a free period they
+        // were refused, so the lookup refuses instead and the fix is a manage run.
+        let threw = null;
+
+        try {
+          await resolveAgainst([plan('P-TRIAL', 7)], false);
+        } catch (e) {
+          threw = e;
+        }
+
+        assert.ok(threw, 'No twin, no plan id');
+        assert.match(threw.message, /No active PayPal plan/, 'The existing plan-lookup refusal');
+        assert.match(threw.message, /without a trial/, 'Naming the twin that is missing');
+      },
+    },
+
+    {
+      name: 'a-trial-twin-of-the-wrong-length-is-not-the-trial-twin',
+      async run({ assert }) {
+        // The manager matches a trial cycle by presence, so any TRIAL cycle
+        // answers a trial checkout — what must never answer it is a plan with
+        // none at all
+        assert.equal(await resolveAgainst([plan('P-TRIAL-30', 30), plan('P-NO-TRIAL', 0)], true), 'P-TRIAL-30', 'Presence is the match, not the day count');
+      },
+    },
+  ],
+});

package/test/helpers/payment/paypal/switch-plan.test.js

@@ -0,0 +1,92 @@
+/**
+ * Test: PayPal switchPlan(), which TWIN a plan change revises onto
+ * ([#761](https://github.com/Omega-JS-Stack/omega/issues/761)).
+ *
+ * The twin is a property of the TARGET product, not of the subscriber: a
+ * trialing switcher carries the trial only when the product they move to
+ * configures trial days, a paying switcher always lands on the no-trial twin,
+ * and a trial-less product has one plan for everybody. The HTTP calls are the
+ * one thing stubbed; the plan the revise is asked for is what is under test.
+ *
+ * Run: npx omega test backend:helpers/payment/paypal/switch-plan
+ */
+const provider = require('../../../../dist/manager/routes/payments/plan/providers/paypal.js');
+const PayPal = require('../../../../dist/manager/libraries/payment/providers/paypal.js');
+const defineCases = require('../../../../dist/vendor/devkit/test/define-cases.js');
+
+const TRIAL_PRODUCT = { id: 'premium', name: 'Premium', type: 'subscription', trial: { days: 7 }, prices: { monthly: 20 }, paypal: { productId: 'PROD-PREMIUM' } };
+const PLAIN_PRODUCT = { id: 'proof-press', name: 'Proof Press', type: 'subscription', prices: { monthly: 5 }, paypal: { productId: 'PROD-PROOF' } };
+
+const NOW = 1_700_000_000;
+const TRIALING = { status: 'active', trial: { claimed: true, expires: { timestampUNIX: NOW } }, expires: { timestampUNIX: NOW } };
+const PAYING = { status: 'active', trial: { claimed: false }, expires: { timestampUNIX: NOW + 86400 * 30 } };
+
+function plan(id, amount, trialDays) {
+  const cycles = [];
+
+  if (trialDays > 0) {
+    cycles.push({ tenure_type: 'TRIAL', sequence: 1, total_cycles: trialDays, frequency: { interval_unit: 'DAY', interval_count: 1 }, pricing_scheme: { fixed_price: { value: '0', currency_code: 'USD' } } });
+  }
+
+  cycles.push({ tenure_type: 'REGULAR', sequence: cycles.length + 1, total_cycles: 0, frequency: { interval_unit: 'MONTH', interval_count: 1 }, pricing_scheme: { fixed_price: { value: amount.toFixed(2), currency_code: 'USD' } } });
+
+  return { id, status: 'ACTIVE', billing_cycles: cycles };
+}
+
+const PLANS = {
+  'PROD-PREMIUM': [plan('P-PREMIUM-TRIAL', 20, 7), plan('P-PREMIUM', 20, 0)],
+  'PROD-PROOF': [plan('P-PROOF', 5, 0)],
+};
+
+/** Run a switch against the fixed plan lists and return the plan id the revise asked for */
+async function switchTo(product, subscription) {
+  const realRequest = PayPal.request;
+  let revised = null;
+
+  PayPal.request = async (path, options) => {
+    if (path.includes('/revise')) {
+      revised = JSON.parse(options.body).plan_id;
+      return {};
+    }
+    const productId = new URL(`https://x${path}`).searchParams.get('product_id');
+    return { plans: JSON.parse(JSON.stringify(PLANS[productId] || [])) };
+  };
+
+  try {
+    await provider.switchPlan({ resourceId: 'I-TEST', uid: '_test-switcher', subscription, product, frequency: 'monthly', ctx: { log() {} } });
+  } finally {
+    PayPal.request = realRequest;
+  }
+
+  return revised;
+}
+
+module.exports = defineCases({
+  description: 'PayPal switchPlan(): the twin a plan change lands on',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'a-trialing-switcher-carries-the-trial-onto-a-trial-products-trial-twin',
+      async run({ assert }) {
+        assert.equal(await switchTo(TRIAL_PRODUCT, TRIALING), 'P-PREMIUM-TRIAL', 'The trial rides over');
+      },
+    },
+
+    {
+      name: 'a-paying-switcher-lands-on-the-no-trial-twin',
+      async run({ assert }) {
+        assert.equal(await switchTo(TRIAL_PRODUCT, PAYING), 'P-PREMIUM', 'No free cycle for a paying customer');
+      },
+    },
+
+    {
+      name: 'a-trialing-switcher-onto-a-trial-less-product-takes-its-one-plan',
+      async run({ assert }) {
+        // No manage run will ever mint a trial twin for a product with no trial
+        // days, so asking for one would 500 every such switch
+        assert.equal(await switchTo(PLAIN_PRODUCT, TRIALING), 'P-PROOF', 'The trial ends; the switch still works');
+      },
+    },
+  ],
+});