@omega.js/backend 0.1.0

package/test/helpers/payment/coinbase/to-unified-one-time.test.js

@@ -0,0 +1,201 @@
+/**
+ * Test: Coinbase Commerce toUnifiedOneTime()
+ * Unit tests for the Coinbase library's charge → unified one-time transformation
+ * ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)).
+ *
+ * Tests the pure function directly — no emulator, no Firestore, no HTTP.
+ * Mirrors paypal/to-unified-one-time.js for consistent coverage.
+ *
+ * A Coinbase charge has no status FIELD: its timeline is the record, appended to
+ * as the payment is detected, confirmed or expires, so the status is the last
+ * entry of that list and nothing else.
+ *
+ * Run: npx omega test backend:helpers/payment/coinbase/to-unified-one-time
+ */
+const Coinbase = require('../../../../dist/manager/libraries/payment/providers/coinbase.js');
+
+const FIXTURE_CONFIRMED = require('../../../fixtures/coinbase/charge-confirmed.json');
+const FIXTURE_PENDING = require('../../../fixtures/coinbase/charge-pending.json');
+const FIXTURE_FAILED = require('../../../fixtures/coinbase/charge-failed.json');
+const defineCases = require('../../../../dist/vendor/devkit/test/define-cases.js');
+
+const MOCK_CONFIG = {
+  payment: {
+    products: [
+      { id: 'basic', name: 'Basic', type: 'subscription', limits: { requests: 100 } },
+      { id: 'launch-kit', name: 'Starter Library', type: 'one-time', prices: { once: 49.99 } },
+    ],
+  },
+};
+
+const CHARGE_CONFIRMED = FIXTURE_CONFIRMED.event.data;
+const CHARGE_PENDING = FIXTURE_PENDING.event.data;
+const CHARGE_FAILED = FIXTURE_FAILED.event.data;
+
+function toUnifiedOneTime(charge, options) {
+  return Coinbase.toUnifiedOneTime(charge, { config: MOCK_CONFIG, ...options });
+}
+
+/** A charge whose timeline ends on `status` */
+function chargeEndingOn(status) {
+  return { id: 'ch_status_probe', timeline: [{ status: 'NEW' }, { status: status }] };
+}
+
+module.exports = defineCases({
+  description: 'Coinbase Commerce toUnifiedOneTime() transformation',
+  type: 'group',
+
+  tests: [
+    // ─── Status mapping (the timeline's LAST entry) ───
+
+    {
+      name: 'status-completed',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime(CHARGE_CONFIRMED).status, 'completed', 'COMPLETED → completed');
+      },
+    },
+
+    {
+      name: 'status-pending',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime(CHARGE_PENDING).status, 'pending', 'PENDING → pending — money detected, not settled');
+      },
+    },
+
+    {
+      name: 'status-expired-is-failed',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime(CHARGE_FAILED).status, 'failed', 'EXPIRED → failed');
+      },
+    },
+
+    {
+      name: 'status-resolved-is-completed',
+      async run({ assert }) {
+        // An under/overpaid charge the merchant RESOLVED is money accepted — it
+        // books the way a clean COMPLETED does
+        assert.equal(toUnifiedOneTime(chargeEndingOn('RESOLVED')).status, 'completed');
+      },
+    },
+
+    {
+      name: 'status-canceled-is-failed',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime(chargeEndingOn('CANCELED')).status, 'failed');
+      },
+    },
+
+    {
+      name: 'status-new-is-pending',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime(chargeEndingOn('NEW')).status, 'pending', 'A charge nobody has paid yet is pending, never failed');
+      },
+    },
+
+    {
+      name: 'an-unmapped-status-passes-through-lowercased',
+      async run({ assert }) {
+        // Inventing `failed` for a word we do not know would revoke a purchase
+        // that may be perfectly fine — the siblings pass their own words through
+        assert.equal(toUnifiedOneTime(chargeEndingOn('UNRESOLVED')).status, 'unresolved');
+      },
+    },
+
+    {
+      name: 'a-charge-with-no-timeline-is-unknown',
+      async run({ assert }) {
+        assert.equal(toUnifiedOneTime({ id: 'ch_bare' }).status, 'unknown', 'Absent data never claims an outcome');
+      },
+    },
+
+    // ─── Identifiers and product resolution ───
+
+    {
+      name: 'resolves-the-product-from-charge-metadata',
+      async run({ assert }) {
+        const result = toUnifiedOneTime(CHARGE_CONFIRMED);
+
+        assert.equal(result.product.id, 'launch-kit');
+        assert.equal(result.product.name, 'Starter Library');
+      },
+    },
+
+    {
+      name: 'prices-from-config-not-from-the-charge',
+      async run({ assert }) {
+        // The catalog is the price of record, the way every sibling reads it —
+        // a charge's local amount can carry a discount off it
+        const result = toUnifiedOneTime(CHARGE_CONFIRMED);
+
+        assert.equal(result.payment.price, 49.99);
+      },
+    },
+
+    {
+      name: 'unknown-product-degrades-without-throwing',
+      async run({ assert }) {
+        const result = toUnifiedOneTime({ id: 'ch_x', metadata: { productId: 'not-in-catalog' }, timeline: [{ status: 'COMPLETED' }] });
+
+        assert.equal(result.product.id, 'not-in-catalog');
+        assert.equal(result.payment.price, 0);
+      },
+    },
+
+    {
+      name: 'carries-the-order-and-the-resource',
+      async run({ assert }) {
+        const result = toUnifiedOneTime(CHARGE_CONFIRMED, { eventName: 'charge:confirmed', eventId: '_test-evt-charge-confirmed' });
+
+        assert.equal(result.payment.provider, 'coinbase');
+        assert.equal(result.payment.orderId, '_test-order-coinbase-1');
+        assert.equal(result.payment.resourceId, '8f783fa6-eaa3-4460-af64-cac26b183ed1');
+        assert.equal(result.payment.updatedBy.event.name, 'charge:confirmed');
+        assert.equal(result.payment.updatedBy.event.id, '_test-evt-charge-confirmed');
+        assert.ok(result.payment.updatedBy.date.timestampUNIX > 0, 'The write stamps when it happened');
+      },
+    },
+
+    {
+      name: 'getUid-and-getOrderId-read-the-charge-record',
+      async run({ assert }) {
+        assert.equal(Coinbase.getUid(CHARGE_CONFIRMED), '_test-coinbase-buyer');
+        assert.equal(Coinbase.getOrderId(CHARGE_CONFIRMED), '_test-order-coinbase-1');
+
+        // A charge carrying nothing answers nothing, never undefined
+        assert.equal(Coinbase.getUid({}), null);
+        assert.equal(Coinbase.getOrderId({}), null);
+      },
+    },
+
+    {
+      name: 'buildMetadata-is-the-one-shape-the-readers-expect',
+      async run({ assert }) {
+        const metadata = Coinbase.buildMetadata('u1', 'ord-1', 'launch-kit');
+
+        assert.deepEqual(metadata, { uid: 'u1', orderId: 'ord-1', productId: 'launch-kit' });
+        assert.equal(Coinbase.getUid({ metadata }), 'u1', 'What the intent writes is what the pipeline reads');
+        assert.equal(Coinbase.getOrderId({ metadata }), 'ord-1');
+      },
+    },
+
+    // ─── There is no subscription half ───
+
+    {
+      name: 'a-charge-is-never-a-subscription',
+      async run({ assert }) {
+        // Fabricating one would grant recurring access off a single crypto
+        // payment, so the bug stops here instead
+        let threw = false;
+
+        try {
+          Coinbase.toUnifiedSubscription(CHARGE_CONFIRMED, { config: MOCK_CONFIG });
+        } catch (e) {
+          threw = true;
+          assert.match(e.message, /no subscriptions/i, 'The refusal says why');
+        }
+
+        assert.ok(threw, 'toUnifiedSubscription() must refuse');
+      },
+    },
+  ],
+});

package/test/helpers/payment/discount-codes.test.js

@@ -0,0 +1,141 @@
+/**
+ * Test: what validate() hands the rest of the system
+ * ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+ *
+ * A validate() result is not just read — `POST /payments/intent` WRITES it into
+ * `payments-intents/{orderId}` (`intent/post.js`, the `discount:` field). Firestore
+ * refuses a document containing an `undefined` value and firebase-admin throws
+ * SYNCHRONOUSLY when it validates the data, with no `ignoreUndefinedProperties`
+ * set anywhere in this framework. That throw lands AFTER the provider has already
+ * created the real checkout session, so a single undefined-valued key on the result
+ * turns every discounted checkout into a 500 with a live session stranded behind it.
+ *
+ * The rule this pins: a code carries the ONE shape it has (percent or amount) and
+ * the result never carries a key whose value is undefined — for every entry in the
+ * table, so a code added tomorrow is covered without touching this file.
+ *
+ * Run: npx omega test framework:helpers/payment/discount-codes
+ *
+ * firebase-admin's document validation is the real thing here, not a stand-in: it
+ * runs synchronously inside set(), before any I/O, so the check needs no live
+ * Firestore. The returned promise is deliberately never awaited (the write itself
+ * is not the subject) and its rejection is swallowed.
+ */
+const admin = require('firebase-admin');
+const discountCodes = require('../../../dist/manager/libraries/payment/discount-codes.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const { DISCOUNT_CODES, validate } = discountCodes;
+
+/**
+ * The runner has already initialized the admin app; outside it a demo project
+ * needs no credentials for the synchronous validation this exercises.
+ */
+function firestore() {
+  if (!admin.apps.length) {
+    admin.initializeApp({ projectId: 'demo-discount-codes' });
+  }
+
+  return admin.firestore();
+}
+
+/**
+ * Ask firebase-admin to accept the document `POST /payments/intent` writes.
+ * Returns the synchronous error it refused with, or null.
+ */
+function refusedBy(discount) {
+  const ref = firestore().doc('payments-intents/_test-discount-writable');
+
+  try {
+    const write = ref.set({ discount: discount }, { merge: true });
+
+    if (write && typeof write.catch === 'function') {
+      write.catch(() => {});
+    }
+
+    return null;
+  } catch (e) {
+    return e;
+  }
+}
+
+module.exports = defineCases({
+  description: 'Discount codes: the validate() contract',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'the-table-is-not-empty-so-this-suite-covers-something',
+      async run({ assert }) {
+        assert.ok(Object.keys(DISCOUNT_CODES).length > 1, 'Several codes should be seeded');
+      },
+    },
+
+    {
+      name: 'every-code-validates-into-a-firestore-writable-object',
+      async run({ assert }) {
+        for (const code of Object.keys(DISCOUNT_CODES)) {
+          const result = validate(code);
+
+          assert.equal(result.valid, true, `${code} should validate (eligibility is skipped with no user)`);
+
+          const refusal = refusedBy(result);
+
+          assert.equal(
+            refusal,
+            null,
+            `${code}: the intent route writes this object — Firestore refused it: ${refusal?.message?.split('\n')[0]}`
+          );
+        }
+      },
+    },
+
+    {
+      name: 'a-validated-code-carries-only-the-shape-it-has',
+      async run({ assert }) {
+        for (const [code, entry] of Object.entries(DISCOUNT_CODES)) {
+          const result = validate(code);
+
+          if (entry.percent !== undefined) {
+            assert.equal(result.percent, entry.percent, `${code} should report its percent`);
+            assert.equal('amount' in result, false, `${code} is percent-based — it must not carry an amount key at all`);
+          } else {
+            assert.equal(result.amount, entry.amount, `${code} should report its amount`);
+            assert.equal('percent' in result, false, `${code} is amount-based — it must not carry a percent key at all`);
+          }
+
+          for (const [key, value] of Object.entries(result)) {
+            assert.notEqual(value, undefined, `${code}.${key} is undefined — Firestore refuses the whole document`);
+          }
+        }
+      },
+    },
+
+    {
+      name: 'every-table-entry-declares-exactly-one-shape',
+      async run({ assert }) {
+        // The readers downstream branch on the shape (the providers' coupon
+        // params, the order email's promo line) — a code carrying both, or
+        // neither, has no defined meaning at any of them.
+        for (const [code, entry] of Object.entries(DISCOUNT_CODES)) {
+          const shapes = [entry.percent, entry.amount].filter((v) => v !== undefined);
+
+          assert.equal(shapes.length, 1, `${code} should declare exactly one of percent/amount, found ${shapes.length}`);
+          assert.ok(shapes[0] > 0, `${code}'s discount should be a positive number`);
+        }
+      },
+    },
+
+    {
+      name: 'a-refused-code-is-writable-too',
+      async run({ assert }) {
+        // The route only persists a VALID result today, but the invalid shape is
+        // one object away from the same write path
+        const refusal = refusedBy(validate('NOT-A-REAL-CODE'));
+
+        assert.equal(refusal, null, `An invalid result should be writable too: ${refusal?.message?.split('\n')[0]}`);
+      },
+    },
+  ],
+});

package/test/helpers/payment/extract-resource.test.js

@@ -0,0 +1,113 @@
+/**
+ * Test: provider extractResource() — each library names its own webhook envelope
+ *
+ * The webhook trigger reads the resource out of the event it received to name what
+ * the event is ABOUT — the orderId a failed event belongs to, and the body the test
+ * provider answers its own lookups from. It used to read Stripe's envelope for every
+ * provider — `raw.data.object` — so a Chargebee event (`content.<type>`) or a PayPal
+ * event (`resource`) resolved to nothing at all ([#222]).
+ *
+ * Each library now names its own shape, and these assert the shape against the
+ * real fixtures each provider's route parser already reads.
+ *
+ * What the envelope must NEVER do is drive state: that comes from the provider's own
+ * lookup ([#506](https://github.com/Omega-JS-Stack/omega/issues/506)).
+ */
+const assert = require('node:assert');
+const Stripe = require('../../../dist/manager/libraries/payment/providers/stripe.js');
+const PayPal = require('../../../dist/manager/libraries/payment/providers/paypal.js');
+const Chargebee = require('../../../dist/manager/libraries/payment/providers/chargebee.js');
+const Coinbase = require('../../../dist/manager/libraries/payment/providers/coinbase.js');
+const Test = require('../../../dist/manager/libraries/payment/providers/test.js');
+
+const chargebeeSubscriptionCreated = require('../../fixtures/chargebee/webhook-subscription-created.json');
+const chargebeeInvoiceOneTime = require('../../fixtures/chargebee/invoice-one-time.json');
+const stripeCheckoutSession = require('../../fixtures/stripe/checkout-session-completed.json');
+const coinbaseChargeConfirmed = require('../../fixtures/coinbase/charge-confirmed.json');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// Stripe's fixtures are bare resources — a webhook wraps one in the event envelope
+const stripeEvent = { id: 'evt_test_session', type: 'checkout.session.completed', data: { object: stripeCheckoutSession } };
+
+module.exports = defineCases({
+  description: 'Provider extractResource() envelope shapes',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'stripe-reads-data-object',
+      async run() {
+        const resource = Stripe.extractResource(stripeEvent);
+
+        assert.equal(resource.id, stripeCheckoutSession.id, 'Stripe nests its resource at data.object');
+      },
+    },
+
+    {
+      name: 'test-provider-reads-stripes-envelope',
+      async run() {
+        // The test provider BUILDS Stripe-shaped payloads, so it reads the Stripe
+        // envelope. Without its own extractResource it fell to the empty fallback —
+        // which is the whole journey lane, since every journey runs on this provider
+        const resource = Test.extractResource(stripeEvent);
+
+        assert.equal(resource.id, stripeCheckoutSession.id, 'The test provider speaks Stripe, envelope included');
+        assert.equal(Test.extractResource({ id: 'evt_empty' }), null, 'And answers nothing the same way Stripe does');
+      },
+    },
+
+    {
+      name: 'paypal-reads-resource',
+      async run() {
+        const raw = { id: 'WH-TEST', event_type: 'BILLING.SUBSCRIPTION.ACTIVATED', resource: { id: 'I-TEST', status: 'ACTIVE' } };
+        const resource = PayPal.extractResource(raw);
+
+        assert.equal(resource.id, 'I-TEST', 'PayPal carries its resource at the top-level resource key');
+      },
+    },
+
+    {
+      name: 'coinbase-reads-the-data-inside-its-event-key',
+      async run() {
+        // Coinbase Commerce nests its charge two deep — the delivery envelope
+        // wraps an EVENT, and the charge is that event's data
+        // ([#642](https://github.com/Omega-JS-Stack/omega/issues/642))
+        const charge = Coinbase.extractResource(coinbaseChargeConfirmed);
+
+        assert.equal(charge.id, coinbaseChargeConfirmed.event.data.id, 'Coinbase carries its charge at event.data');
+        assert.equal(Coinbase.extractResource({ id: 'delivery_only' }), null, 'And answers nothing the same way its siblings do');
+      },
+    },
+
+    {
+      name: 'chargebee-reads-the-content-key-of-the-event',
+      async run() {
+        const subscription = Chargebee.extractResource(chargebeeSubscriptionCreated);
+
+        assert.equal(subscription.id, chargebeeSubscriptionCreated.content.subscription.id, 'A subscription event resolves content.subscription');
+        assert.equal(subscription.object, 'subscription', 'The resolved resource is the subscription, not the invoice beside it');
+      },
+    },
+
+    {
+      name: 'chargebee-falls-to-the-invoice-when-there-is-no-subscription',
+      async run() {
+        // The one-time lane: invoice_generated for a non-recurring invoice carries no
+        // subscription at all — the same precedence parseWebhook categorizes on
+        const raw = { id: 'ev_cb_invoice_001', event_type: 'invoice_generated', content: { invoice: chargebeeInvoiceOneTime, customer: { id: 'cb_cust_001' } } };
+        const resource = Chargebee.extractResource(raw);
+
+        assert.equal(resource.id, chargebeeInvoiceOneTime.id, 'An invoice-only event resolves content.invoice');
+      },
+    },
+
+    {
+      name: 'an-envelope-with-no-resource-extracts-nothing',
+      async run() {
+        assert.equal(Chargebee.extractResource({ id: 'ev_empty', content: {} }), null, 'Chargebee: no content key, nothing to fall back to');
+        assert.equal(Stripe.extractResource({ id: 'evt_empty' }), null, 'Stripe: no data.object, nothing to fall back to');
+        assert.equal(PayPal.extractResource({ id: 'WH-empty' }), null, 'PayPal: no resource, nothing to fall back to');
+      },
+    },
+  ],
+});

package/test/helpers/payment/fetch-failure.test.js

@@ -0,0 +1,215 @@
+/**
+ * Test: provider fetchResource() failure classification
+ *
+ * Every provider library used to swallow a failed lookup and hand back the payload
+ * the WEBHOOK carried, flagged stale — so the object whoever posted the event
+ * supplied drove real subscription state ([#506](https://github.com/Omega-JS-Stack/omega/issues/506)).
+ * No library falls back any more: a lookup that fails throws, and the throw carries
+ * the one thing the pipeline branches on — whether the provider said the resource
+ * DOES NOT EXIST (refuse and acknowledge) or simply could not be reached (defer for
+ * retry).
+ *
+ * Each provider's real fetchResource() runs here. The transport is the only thing
+ * stubbed (an HTTP client, an SDK) — reading a resource back needs live credentials;
+ * everything inward, including the classification, runs for real.
+ *
+ * Run: npx omega test backend:helpers/payment/fetch-failure
+ */
+const assert = require('node:assert');
+const Stripe = require('../../../dist/manager/libraries/payment/providers/stripe.js');
+const PayPal = require('../../../dist/manager/libraries/payment/providers/paypal.js');
+const Chargebee = require('../../../dist/manager/libraries/payment/providers/chargebee.js');
+const Coinbase = require('../../../dist/manager/libraries/payment/providers/coinbase.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const RESOURCE_ID = '_test-res-lookup';
+
+/** Run fn with a library's transport replaced by a stand-in, restored afterwards */
+async function withTransport(library, key, stub, fn) {
+  const real = library[key];
+
+  library[key] = stub;
+
+  try {
+    return await fn();
+  } finally {
+    library[key] = real;
+  }
+}
+
+/** The error a call is expected to throw, or a failure saying it did not throw */
+async function throwsFrom(fn) {
+  try {
+    await fn();
+  } catch (e) {
+    return e;
+  }
+
+  assert.fail('A failed lookup must throw — there is nothing to fall back to');
+}
+
+module.exports = defineCases({
+  description: 'Provider fetchResource() failure classification',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'chargebee-classifies-a-404-as-not-found',
+      async run() {
+        // The shape libraries/payment/providers/chargebee.js throws for a 404
+        const notThere = new Error('Chargebee API 404: Sorry, we couldn\'t find that resource');
+        notThere.statusCode = 404;
+
+        const error = await throwsFrom(() => withTransport(Chargebee, 'request', async () => {
+          throw notThere;
+        }, () => Chargebee.fetchResource('subscription', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, true, 'Chargebee answering 404 means the resource is gone');
+        assert.equal(error.provider, 'chargebee', 'the failure names the provider that was asked');
+        assert.equal(error.resourceId, RESOURCE_ID, 'and the resource it was asked about');
+        assert.match(error.message, /chargebee does not have subscription/, 'the message says the provider does not have it');
+      },
+    },
+
+    {
+      name: 'chargebee-classifies-an-unreachable-api-as-transient',
+      async run() {
+        const error = await throwsFrom(() => withTransport(Chargebee, 'request', async () => {
+          throw new Error('fetch failed');
+        }, () => Chargebee.fetchResource('subscription', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, false, 'an unreachable API is not a provider saying the resource is gone');
+        assert.match(error.message, /could not be reached/, 'the message says the lookup never got an answer');
+      },
+    },
+
+    {
+      name: 'coinbase-classifies-a-404-as-not-found',
+      async run() {
+        // Coinbase Commerce carries the status on the error the way Chargebee
+        // does, so the ONE classifier answers for it with no new rule
+        // ([#642](https://github.com/Omega-JS-Stack/omega/issues/642))
+        const notThere = new Error('Coinbase Commerce API 404: Not found');
+        notThere.statusCode = 404;
+
+        const error = await throwsFrom(() => withTransport(Coinbase, 'request', async () => {
+          throw notThere;
+        }, () => Coinbase.fetchResource('charge', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, true, 'Coinbase answering 404 means the charge is gone');
+        assert.equal(error.provider, 'coinbase', 'the failure names the provider that was asked');
+        assert.equal(error.resourceId, RESOURCE_ID, 'and the resource it was asked about');
+        assert.match(error.message, /coinbase does not have charge/, 'the message says the provider does not have it');
+      },
+    },
+
+    {
+      name: 'coinbase-classifies-an-unreachable-api-as-transient',
+      async run() {
+        const error = await throwsFrom(() => withTransport(Coinbase, 'request', async () => {
+          throw new Error('fetch failed');
+        }, () => Coinbase.fetchResource('charge', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, false, 'an unreachable API is not a provider saying the charge is gone');
+        assert.match(error.message, /could not be reached/, 'the message says the lookup never got an answer');
+      },
+    },
+
+    {
+      name: 'paypal-classifies-a-404-as-not-found',
+      async run() {
+        // PayPal carries the status in the message only — the shape its client throws
+        const error = await throwsFrom(() => withTransport(PayPal, 'request', async () => {
+          throw new Error('PayPal API 404: The specified resource does not exist.');
+        }, () => PayPal.fetchResource('subscription', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, true, 'PayPal answering 404 means the resource is gone');
+        assert.equal(error.provider, 'paypal', 'the failure names the provider that was asked');
+      },
+    },
+
+    {
+      name: 'paypal-says-an-uncaptured-order-never-moved-the-funds',
+      async run() {
+        // An order fetch IS the capture, so the caller has to be told the money
+        // did not move — the payload it used to fall back to described a captured
+        // order that never was
+        const error = await throwsFrom(() => withTransport(PayPal, 'request', async () => {
+          throw new Error('PayPal API 503: Service unavailable');
+        }, () => PayPal.fetchResource('order', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, false, 'a 503 is transient');
+        assert.match(error.message, /NOT captured/, 'the consequence of the failed capture rides on the failure');
+      },
+    },
+
+    {
+      name: 'stripe-classifies-a-missing-resource-as-not-found',
+      async run() {
+        const missing = new Error(`No such subscription: '${RESOURCE_ID}'`);
+        missing.code = 'resource_missing';
+        missing.statusCode = 404;
+
+        const sdk = {
+          subscriptions: {
+            retrieve: async () => {
+              throw missing;
+            },
+          },
+        };
+
+        const error = await throwsFrom(() => withTransport(Stripe, 'init', () => sdk,
+          () => Stripe.fetchResource('subscription', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, true, 'Stripe resource_missing means the resource is gone');
+        assert.equal(error.cause, missing, 'the provider\'s own error rides along for the logs');
+      },
+    },
+
+    {
+      name: 'stripe-classifies-an-outage-as-transient',
+      async run() {
+        const sdk = {
+          subscriptions: {
+            retrieve: async () => {
+              throw new Error('An error occurred with our connection to Stripe.');
+            },
+          },
+        };
+
+        const error = await throwsFrom(() => withTransport(Stripe, 'init', () => sdk,
+          () => Stripe.fetchResource('subscription', RESOURCE_ID, {})));
+
+        assert.equal(error.notFound, false, 'an outage is not a provider saying the resource is gone');
+      },
+    },
+
+    {
+      name: 'a-refund-miss-names-the-call-that-missed',
+      async run() {
+        // The failure names its own call site: a refund lookup thrown from
+        // getRefundDetails() used to read `fetchResource(refund/…)`, pointing
+        // whoever reads the log at a function that never ran.
+        const error = await throwsFrom(() => withTransport(PayPal, 'request', async () => {
+          throw new Error('PayPal API 404: The specified resource does not exist.');
+        }, () => PayPal.getRefundDetails({ id: 'SALE-1' }, { refundId: RESOURCE_ID, eventType: 'PAYMENT.SALE.REFUNDED' })));
+
+        assert.match(error.message, /getRefundDetails\(refund\//, 'the refund lookup names getRefundDetails, not fetchResource');
+        assert.equal(error.notFound, true, 'and still classifies — a 404 refund is gone');
+      },
+    },
+
+    {
+      name: 'an-unknown-resource-type-is-never-read-as-not-found',
+      async run() {
+        // A resource type the library does not know is a fault on THIS side. It must
+        // not masquerade as the provider affirmatively answering "no such resource",
+        // which would acknowledge the event and drop it forever.
+        const error = await throwsFrom(() => Chargebee.fetchResource('unknown-type', RESOURCE_ID, {}));
+
+        assert.equal(error.notFound, false, 'nothing was asked, so nothing was answered');
+        assert.match(error.message, /Unknown resource type/, 'the original error still surfaces');
+      },
+    },
+  ],
+});