@omega.js/backend 0.1.0

package/test/events/payments/purchase-refunded-handler.test.js

@@ -0,0 +1,108 @@
+/**
+ * Test: the one-time purchase-refunded handler's record of the refund, and the
+ * mail it owes the customer
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212),
+ * [#673](https://github.com/Omega-JS-Stack/omega/issues/673)).
+ *
+ * The handler's log line is the operator's record: it used to name the order and
+ * nothing else, because on-write.js resolved the provider's refund details for the
+ * subscription transition only. The CUSTOMER got nothing at all — the handler was
+ * a log-only stub, so somebody refunded on a one-time purchase heard about it from
+ * their bank statement. It now sends through the same generator its subscription
+ * twin uses (`order` template, `refunded` event).
+ *
+ * The handler is called directly — the dispatch that calls it is fire-and-forget
+ * and skipped in testing mode, so the emulator journey cannot see either.
+ *
+ * The email library is RECORDED rather than run: it is an external sink (SendGrid),
+ * the same treatment the webhook harness gives the Sentry handle.
+ *
+ * Run: npx omega test backend:events/payments/purchase-refunded-handler
+ */
+const handler = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-refunded.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const ORDER_ID = '9090-8080-7070';
+
+function context(logs, sent) {
+  return {
+    before: null,
+    after: { product: { id: 'credits-100', name: '100 Credits' }, status: 'refunded' },
+    order: { id: ORDER_ID, type: 'one-time', unified: { product: { id: 'credits-100' }, payment: { price: 9.99 } } },
+    uid: '_test-purchase-refunded-uid',
+    userDoc: { auth: { uid: '_test-purchase-refunded-uid', email: 'buyer@test.dev' } },
+    ctx: {
+      log: (line) => logs.push(line),
+      error: (line) => logs.push(line),
+      Manager: {
+        config: { brand: { name: 'Test Brand' } },
+        Email: () => ({ send: async (payload) => { sent.push(payload); return { status: 'sent' }; } }),
+      },
+    },
+    refundDetails: { amount: '9.99', currency: 'USD', reason: 'requested_by_customer' },
+  };
+}
+
+module.exports = defineCases({
+  description: 'One-time purchase-refunded handler',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'records-the-amount-that-came-back',
+      async run({ assert }) {
+        const logs = [];
+
+        await handler(context(logs, []));
+
+        const line = logs.find((entry) => entry.includes('one-time/purchase-refunded'));
+
+        assert.ok(line, `The handler should log the transition, got: ${logs.join(' | ')}`);
+        assert.match(line, new RegExp(`orderId=${ORDER_ID}`), 'The line should name the order refunded');
+        assert.match(line, /amount=9\.99 USD/, 'The line should say how much came back');
+        assert.match(line, /reason=requested_by_customer/, 'The line should carry the provider reason');
+        assert.match(line, /product=credits-100/, 'The line should name what was refunded');
+      },
+    },
+
+    {
+      name: 'stays-readable-without-refund-details',
+      async run({ assert }) {
+        // A provider library with no getRefundDetails() leaves them null — the
+        // record must still say which order was refunded
+        const logs = [];
+        const ctx = context(logs, []);
+        ctx.refundDetails = null;
+
+        await handler(ctx);
+
+        const line = logs.find((entry) => entry.includes('one-time/purchase-refunded'));
+
+        assert.match(line, new RegExp(`orderId=${ORDER_ID}`), 'The line should still name the order');
+        assert.match(line, /amount=unknown USD/, 'An unresolved amount should read as unknown, never as undefined');
+      },
+    },
+
+    {
+      name: 'sends-the-refunded-email-the-subscription-twin-sends',
+      async run({ assert }) {
+        const sent = [];
+
+        await handler(context([], sent));
+
+        assert.equal(sent.length, 1, `A refunded purchase owes the customer exactly one email, got ${sent.length}`);
+
+        const email = sent[0];
+
+        assert.equal(email.template, 'order', 'It rides the one order template, like every other transition');
+        assert.deepEqual(email.categories, ['order/refunded'], 'Filed under the same category the subscription refund is');
+        assert.equal(email.data.content.event, 'refunded', 'The order template renders the refunded variant off this event');
+        assert.match(email.subject, new RegExp(ORDER_ID), 'The subject should name the order refunded');
+        assert.equal(email.data.content.id, ORDER_ID, 'The order rides the payload, so the receipt can quote it');
+        assert.equal(email.data.content._computed.refundAmount, '9.99', 'The refund amount is what the mail is about');
+        assert.equal(email.data.content._computed.refundCurrency, 'USD', 'And its currency');
+        assert.equal(email.data.content._computed.refundReason, 'requested_by_customer', 'The provider reason rides along, as the twin sends it');
+      },
+    },
+  ],
+});

package/test/events/payments/test-processor-doc-shape.test.js

@@ -0,0 +1,162 @@
+/**
+ * Test: every test processor writes the pipeline doc the ROUTE writes
+ *
+ * The test provider's cancel, refund, plan and uncancel processors skip the HTTP
+ * door and write `payments-webhooks/{eventId}` themselves — which makes them the
+ * only writers of that document besides the webhook route, and the only ones
+ * nothing verifies against it. The Stage 1 review found them spelling the metadata
+ * block `received`/`processed` where the route spells it `created`/`completed`
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * `metadata.created.timestampUNIX` is not decoration: it is the pipeline's
+ * STALENESS CLOCK — the number `processPaymentEvent()` compares against the order's
+ * last write to decide an out-of-order delivery. A synthetic doc that never wrote
+ * it handed the clock nothing, and every test-processor event rode the now-fallback
+ * as if it had just arrived. Harmless while the fallback holds, and exactly the
+ * kind of drift that stops being harmless the moment the fallback changes.
+ *
+ * Plain-node (no emulator, no network): each processor is called directly against
+ * the shared in-memory Firestore stand-in, and the document it left behind is the
+ * assertion. The route's own doc is built beside them from the SAME source the
+ * route uses, so this compares two real shapes rather than one shape and a copy of
+ * itself in a fixture.
+ *
+ * Run: npx omega test backend:events/payments/test-processor-doc-shape
+ */
+const assert = require('node:assert');
+const { buildAdmin, CONFIG } = require('./_webhook-harness.js');
+
+const cancelProcessor = require('../../../dist/manager/routes/payments/cancel/providers/test.js');
+const refundProcessor = require('../../../dist/manager/routes/payments/refund/providers/test.js');
+const planProcessor = require('../../../dist/manager/routes/payments/plan/providers/test.js');
+const uncancelProcessor = require('../../../dist/manager/routes/payments/uncancel/providers/test.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-doc-shape-uid';
+const RESOURCE_ID = '_test-doc-shape-sub';
+const ORDER_ID = '_test-doc-shape-order';
+
+const DAY = 24 * 60 * 60;
+
+/** A `$timestamp` pair from a UNIX second */
+function stamp(unix) {
+  return { timestamp: new Date(unix * 1000).toISOString(), timestampUNIX: unix };
+}
+
+/** The paid subscription every processor here acts on */
+function subscription() {
+  const nowUNIX = Math.floor(Date.now() / 1000);
+
+  return {
+    product: { id: 'premium', name: 'Premium' },
+    status: 'active',
+    expires: stamp(nowUNIX + 20 * DAY),
+    trial: { claimed: false },
+    cancellation: { pending: false },
+    payment: { provider: 'test', orderId: ORDER_ID, resourceId: RESOURCE_ID, frequency: 'monthly', price: 4.99, startDate: stamp(nowUNIX - 30 * DAY) },
+  };
+}
+
+/** The purchase record behind it */
+function order() {
+  return {
+    id: ORDER_ID,
+    type: 'subscription',
+    owner: UID,
+    productId: 'premium',
+    provider: 'test',
+    resourceId: RESOURCE_ID,
+    unified: { ...subscription(), product: { id: 'premium', name: 'Premium' } },
+  };
+}
+
+/**
+ * Run one processor against the stand-in and hand back every payments-webhooks doc
+ * it wrote
+ *
+ * @param {function} act - `(ctx) => Promise` — the processor call under test
+ * @returns {Promise<object[]>} The synthetic pipeline documents
+ */
+async function synthesize(act) {
+  const { admin, store } = buildAdmin({
+    seed: { [`payments-orders/${ORDER_ID}`]: order() },
+    authUids: [UID],
+  });
+
+  const ctx = {
+    Manager: { config: CONFIG, libraries: { admin } },
+    isProduction: () => false,
+    isTesting: () => true,
+    log: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+
+  await act(ctx);
+
+  return [...store.entries()]
+    .filter(([path]) => path.startsWith('payments-webhooks/'))
+    .map(([, data]) => data);
+}
+
+/** The four processors, each reduced to the one call that writes a pipeline doc */
+const PROCESSORS = [
+  ['cancel', (ctx) => cancelProcessor.cancelAtPeriodEnd({ resourceId: RESOURCE_ID, uid: UID, subscription: subscription(), ctx })],
+  ['refund', (ctx) => refundProcessor.processRefund({ resourceId: RESOURCE_ID, uid: UID, subscription: subscription(), ctx })],
+  ['plan', (ctx) => planProcessor.switchPlan({ resourceId: RESOURCE_ID, uid: UID, subscription: subscription(), product: CONFIG.payment.products.find((p) => p.id === 'premium'), frequency: 'monthly', ctx })],
+  ['uncancel', (ctx) => uncancelProcessor.uncancel({ resourceId: RESOURCE_ID, uid: UID, subscription: subscription(), ctx })],
+  ['refund (one-time)', (ctx) => refundProcessor.processOneTimeRefund({ resourceId: RESOURCE_ID, uid: UID, order: { ...order(), type: 'one-time' }, ctx })],
+];
+
+module.exports = defineCases({
+  description: 'Test processors write the same pipeline-doc shape the webhook route does',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'every-processor-stamps-the-staleness-clock-the-pipeline-reads',
+
+      async run() {
+        for (const [name, act] of PROCESSORS) {
+          const docs = await synthesize(act);
+
+          assert.equal(docs.length, 1, `the ${name} processor should write exactly one pipeline doc, got ${docs.length}`);
+
+          const [doc] = docs;
+
+          assert.equal(
+            typeof doc.metadata?.created?.timestampUNIX,
+            'number',
+            `the ${name} processor must stamp metadata.created.timestampUNIX — it is the number the pipeline's staleness guard compares against the order`,
+          );
+          assert.equal(typeof doc.metadata?.created?.timestamp, 'string', `the ${name} processor must stamp metadata.created.timestamp beside it`);
+          assert.ok('completed' in (doc.metadata || {}), `the ${name} processor must open metadata.completed, the slot the pipeline closes out`);
+          assert.equal(doc.metadata.completed.timestampUNIX, null, `the ${name} processor must leave metadata.completed empty — nothing has processed yet`);
+
+          assert.equal(doc.metadata.received, undefined, `the ${name} processor must not spell the arrival stamp 'received' — the route calls it 'created' and the pipeline only reads that one`);
+          assert.equal(doc.metadata.processed, undefined, `the ${name} processor must not spell the completion stamp 'processed' — the route calls it 'completed'`);
+        }
+      },
+    },
+
+    {
+      name: 'every-processor-writes-the-rest-of-the-envelope-the-pipeline-needs',
+
+      async run() {
+        for (const [name, act] of PROCESSORS) {
+          const [doc] = await synthesize(act);
+
+          assert.equal(doc.provider, 'test', `the ${name} processor's doc names the provider whose library the pipeline loads`);
+          assert.equal(doc.status, 'pending', `the ${name} processor's doc must be pending — the trigger short-circuits on anything else`);
+          assert.equal(doc.owner, UID, `the ${name} processor's doc carries the owner the event is about`);
+          assert.equal(doc.error, null, `the ${name} processor's doc opens with no error`);
+          assert.ok(doc.event?.type, `the ${name} processor's doc names an event type`);
+          assert.ok(doc.event?.category, `the ${name} processor's doc names a category — the pipeline throws without one`);
+          assert.ok(doc.event?.resourceId, `the ${name} processor's doc names the resource the event is about`);
+          assert.equal(doc.raw?.type, doc.event.type, `the ${name} processor's envelope and its parsed event must name the same event`);
+        }
+      },
+    },
+  ],
+});

package/test/events/payments/transition-order-emails.test.js

@@ -0,0 +1,185 @@
+/**
+ * Test: every payments transition that owes the customer an email actually sends
+ * one, and it names what they bought
+ * ([#774](https://github.com/Omega-JS-Stack/omega/issues/774)).
+ *
+ * Until the mailer grew its testing-mode capture there was no way to assert this
+ * offline: the webhook pipeline gates its whole handler dispatch on
+ * `ctx.isTesting()` (`shouldRunHandlers` in on-write.js — a coarse gate that also
+ * covers payment analytics and the marketing sync, so it is NOT the email seam and
+ * stays), and the webhook suites could only count the `handler skipped (testing
+ * mode)` log line. The product name a receipt exists to state
+ * ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)) was proved by
+ * nothing.
+ *
+ * So the transition is driven the way the framework already drives one in a test:
+ * the handler module is called DIRECTLY, exactly as
+ * `purchase-failed-handler.test.js` and `transition-promo-lines.test.js` do. What
+ * changes here is that the email door is NOT swapped — the REAL `Manager.Email()`
+ * runs, through the real brand, the real template data and the real MJML render,
+ * and the capture is what the assertions read.
+ *
+ * Plain-node (no emulator, no network): an order email addresses a user DOCUMENT,
+ * so the send resolves no uid against Firestore and touches nothing but the store.
+ *
+ * Run: npx omega test framework:events/payments/transition-order-emails
+ */
+const assert = require('node:assert');
+const newSubscription = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/subscription/new-subscription.js');
+const purchaseCompleted = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-completed.js');
+const checkoutDeclined = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/subscription/checkout-declined.js');
+const capture = require('../../../dist/test/utils/email-capture.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-transition-order-emails';
+const USER_DOC = {
+  auth: { uid: UID, email: `${UID}@test.dev` },
+  personal: { name: { first: 'Ordell' } },
+};
+
+/**
+ * The handlers dispatch their send fire-and-forget (on-write.js never awaits one),
+ * so a test waits for the record the same way the pipeline's own caller would see
+ * it land — by looking.
+ *
+ * @param {object} Manager - The booted Manager whose project owns the store
+ * @param {number} count - How many records to wait for
+ * @returns {Promise<object[]>} The records, once there are `count` of them
+ */
+async function waitForCaptured(Manager, count) {
+  const deadline = Date.now() + 10000;
+
+  while (Date.now() < deadline) {
+    const records = capture.readCaptured(Manager);
+
+    if (records.length >= count) {
+      return records;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  throw new Error(`Timed out waiting for ${count} captured email(s); got ${capture.readCaptured(Manager).length}`);
+}
+
+module.exports = defineCases({
+  description: 'Payment transitions send the order email their customer is owed (#774)',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a-new-subscription-emails-the-receipt-that-names-the-plan',
+
+      async run({ Manager, ctx }) {
+        capture.clearCaptured(Manager);
+
+        const after = {
+          product: { id: 'premium', name: 'Premium' },
+          payment: { price: 4.99, frequency: 'monthly', provider: 'test' },
+          status: 'active',
+        };
+
+        await newSubscription({
+          before: { product: { id: 'basic', name: 'Basic' }, status: 'active' },
+          after,
+          order: {
+            id: '_test-order-subscription',
+            type: 'subscription',
+            unified: after,
+            discount: null,
+          },
+          uid: UID,
+          userDoc: USER_DOC,
+          ctx,
+        });
+
+        const [record] = await waitForCaptured(Manager, 1);
+        const brandName = Manager.config.brand.name;
+
+        assert.deepEqual(record.to, [USER_DOC.auth.email], 'the receipt goes to the subscriber');
+        assert.equal(record.template, 'order', 'on the order template');
+        assert.match(record.subject, /Premium order #_test-order-subscription/, `the subject names the plan and the order, got: ${record.subject}`);
+
+        // The one thing a receipt exists to state (#668), and the line that tells a
+        // subscription apart from a one-time buy.
+        assert.match(record.summary, new RegExp(`${brandName} Premium`), `the summary names the product, got: ${record.summary}`);
+        assert.match(record.summary, /Billed monthly/, `and how it bills, got: ${record.summary}`);
+        assert.match(record.summary, /Total paid today \$4\.99/, `and what was charged, got: ${record.summary}`);
+
+        capture.clearCaptured(Manager);
+      },
+    },
+
+    {
+      name: 'a-one-time-purchase-emails-the-receipt-that-names-the-product',
+
+      async run({ Manager, ctx }) {
+        capture.clearCaptured(Manager);
+
+        const after = {
+          product: { id: 'credits-100', name: '100 Credits' },
+          payment: { price: 9.99, provider: 'test', resourceId: '_test-charge' },
+          status: 'completed',
+        };
+
+        await purchaseCompleted({
+          before: null,
+          after,
+          order: {
+            id: '_test-order-one-time',
+            type: 'one-time',
+            unified: after,
+            discount: null,
+          },
+          uid: UID,
+          userDoc: USER_DOC,
+          ctx,
+        });
+
+        const [record] = await waitForCaptured(Manager, 1);
+        const brandName = Manager.config.brand.name;
+
+        assert.deepEqual(record.to, [USER_DOC.auth.email], 'the receipt goes to the buyer');
+        assert.equal(record.template, 'order');
+        assert.match(record.subject, /100 Credits order #_test-order-one-time/, `the subject names the product, got: ${record.subject}`);
+
+        // The #668 shape: the row used to be labelled with the order id the header
+        // already prints, so the product appeared nowhere in the email.
+        assert.match(record.summary, new RegExp(`${brandName} 100 Credits`), `the summary names the product, got: ${record.summary}`);
+        assert.match(record.summary, /One-time purchase/, `and says it is not a subscription, got: ${record.summary}`);
+        assert.match(record.summary, /Total paid today \$9\.99/, `and what was charged, got: ${record.summary}`);
+
+        capture.clearCaptured(Manager);
+      },
+    },
+
+    {
+      name: 'a-transition-that-owes-no-email-sends-none',
+
+      async run({ Manager, ctx }) {
+        capture.clearCaptured(Manager);
+
+        // checkout-declined is log-only on purpose: the customer is standing at the
+        // checkout watching the decline, and the dunning copy its cousin sends is
+        // addressed to somebody mid-subscription ([#212]). An empty capture is the
+        // only thing that can prove a deliberate silence.
+        await checkoutDeclined({
+          before: { product: { id: 'basic', name: 'Basic' }, status: 'active' },
+          after: { product: { id: 'premium', name: 'Premium' }, status: 'suspended' },
+          order: { id: '_test-order-declined', type: 'subscription' },
+          uid: UID,
+          userDoc: USER_DOC,
+          ctx,
+        });
+
+        // A send is fire-and-forget, so absence needs a settle rather than a look:
+        // long enough for the render + append the sending transitions above finish
+        // inside, which waitForCaptured() measures at well under this.
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        assert.deepEqual(capture.readCaptured(Manager), [], 'a log-only transition emails nobody');
+      },
+    },
+  ],
+});

package/test/events/payments/transition-promo-lines.test.js

@@ -0,0 +1,192 @@
+/**
+ * Test: the promo line + totals the order-confirmation transitions compute
+ * ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+ *
+ * `new-subscription` and `purchase-completed` pre-compute `_computed` for the order
+ * email. Three shapes reach them: a percent code, a flat-amount code, and — from an
+ * order written before the amount field existed — a valid discount carrying
+ * NEITHER. The third must not render a promo line and must not throw: these
+ * handlers are dispatched fire-and-forget, so a TypeError in here silently costs
+ * the customer their confirmation email.
+ *
+ * The totals go through applyToAmount() for every shape, so `totalToday` is what
+ * was actually charged rather than the list price.
+ *
+ * Run: npx omega test framework:events/payments/transition-promo-lines
+ *
+ * The REAL transition modules run. The one thing swapped is the email door
+ * (`ctx.Manager.Email`) — sending would hit the real provider — and it is swapped
+ * on a VIEW of the Manager (`Object.create`), so the runner's own Manager is never
+ * mutated. Everything else (the discount validation, the arithmetic, the template
+ * data) is the real path.
+ */
+const newSubscription = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/subscription/new-subscription.js');
+const purchaseCompleted = require('../../../dist/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-completed.js');
+const discountCodes = require('../../../dist/manager/libraries/payment/discount-codes.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const PRICE = 49.99;
+const UID = '_test-transition-promo';
+
+// What an order written before the amount field existed looks like coming back
+// out of Firestore: valid, named, and carrying no shape either reader can use
+const LEGACY_SHAPELESS_DISCOUNT = { valid: true, code: 'LEGACYCODE', duration: 'once' };
+
+const USER_DOC = { auth: { uid: UID, email: `${UID}@example.com` } };
+
+/**
+ * A ctx whose Manager is the real one with ONLY the email door swapped, so the
+ * transition's own `sendOrderEmail()` path runs for real up to the send.
+ */
+function buildCtx(Manager, captured) {
+  const managerView = Object.create(Manager);
+
+  managerView.Email = () => ({
+    send: async (payload) => {
+      captured.sent = payload;
+      return { status: 'captured' };
+    },
+  });
+
+  return {
+    Manager: managerView,
+    log: () => {},
+    error: (message) => captured.errors.push(message),
+  };
+}
+
+async function runSubscription(Manager, discount, { isTrial = false } = {}) {
+  const captured = { errors: [] };
+  const order = {
+    id: 'ORD-PROMO-SUB',
+    type: 'subscription',
+    discount: discount,
+    unified: { product: { id: 'premium', name: 'Premium' }, payment: { price: PRICE, frequency: 'monthly' } },
+  };
+
+  await newSubscription({
+    before: {},
+    after: {
+      product: { id: 'premium', name: 'Premium' },
+      payment: { frequency: 'monthly' },
+      trial: { claimed: isTrial },
+    },
+    order,
+    uid: UID,
+    userDoc: USER_DOC,
+    ctx: buildCtx(Manager, captured),
+  });
+
+  return { computed: captured.sent?.data?.content?._computed, captured };
+}
+
+async function runOneTime(Manager, discount) {
+  const captured = { errors: [] };
+  const order = {
+    id: 'ORD-PROMO-ONE',
+    type: 'one-time',
+    discount: discount,
+    unified: { product: { id: 'credits-100', name: '100 Credits' }, payment: { price: PRICE } },
+  };
+
+  await purchaseCompleted({
+    before: {},
+    after: { product: { id: 'credits-100', name: '100 Credits' }, payment: { price: PRICE, resourceId: 'ch_test_promo' } },
+    order,
+    uid: UID,
+    userDoc: USER_DOC,
+    ctx: buildCtx(Manager, captured),
+  });
+
+  return { computed: captured.sent?.data?.content?._computed, captured };
+}
+
+module.exports = defineCases({
+  description: 'Order-confirmation transitions: promo line + totals per discount shape',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'a-percent-code-renders-a-percent-line',
+      async run({ assert, Manager }) {
+        const { computed } = await runSubscription(Manager, discountCodes.validate('WELCOME15'));
+
+        assert.ok(computed, 'The transition should have composed the email');
+        assert.equal(computed.promoCode, 'WELCOME15', 'The line names the code');
+        assert.equal(computed.promoPercent, 15, 'A percent code quotes its percent');
+        assert.equal(computed.promoSavings, '7.50', 'It saved 15% of the price');
+        assert.equal(computed.totalToday, '42.49', 'The total is what was actually charged');
+        assert.equal(computed.firstChargeAmount, '42.49', 'The first charge matches');
+        assert.equal('promoAmount' in computed, false, 'A percent code quotes no dollar amount');
+      },
+    },
+
+    {
+      name: 'an-amount-code-renders-a-money-line-and-the-discounted-total',
+      async run({ assert, Manager }) {
+        const { computed } = await runSubscription(Manager, discountCodes.validate('WELCOME10OFF'));
+
+        assert.equal(computed.promoCode, 'WELCOME10OFF', 'The line names the code');
+        assert.equal(computed.promoAmount, '10.00', 'A flat-dollar code quotes its dollars');
+        assert.equal(computed.promoSavings, '10.00', 'It saved the full $10');
+        assert.equal(computed.totalToday, '39.99', 'The receipt must not quote the list price');
+        assert.equal('promoPercent' in computed, false, 'An amount code quotes no percentage');
+      },
+    },
+
+    {
+      name: 'a-discount-with-neither-shape-renders-no-promo-line-and-does-not-throw',
+      async run({ assert, Manager }) {
+        // An order written before the amount field existed. The handler is
+        // dispatched fire-and-forget, so a throw here costs the email silently.
+        const { computed, captured } = await runSubscription(Manager, LEGACY_SHAPELESS_DISCOUNT);
+
+        assert.ok(computed, 'The email should still be composed');
+        assert.equal('promoCode' in computed, false, 'A shapeless discount renders no promo line');
+        assert.equal('promoPercent' in computed, false, 'Nothing to quote as a percentage');
+        assert.equal('promoAmount' in computed, false, 'Nothing to quote as an amount');
+        assert.equal(computed.totalToday, '49.99', 'With no usable discount the full price stands');
+        assert.deepEqual(captured.errors, [], 'The transition should log no error');
+      },
+    },
+
+    {
+      name: 'a-trial-still-charges-nothing-today',
+      async run({ assert, Manager }) {
+        const { computed } = await runSubscription(Manager, discountCodes.validate('WELCOME10OFF'), { isTrial: true });
+
+        assert.equal(computed.totalToday, '0.00', 'A trial charges nothing today');
+        assert.equal(computed.firstChargeAmount, '39.99', 'The first real charge is still the discounted one');
+      },
+    },
+
+    {
+      name: 'the-one-time-transition-behaves-the-same-for-every-shape',
+      async run({ assert, Manager }) {
+        const percent = await runOneTime(Manager, discountCodes.validate('FLASH20'));
+        assert.equal(percent.computed.promoPercent, 20, 'A percent code quotes its percent');
+        assert.equal(percent.computed.totalToday, '39.99', '20% off 49.99 is 39.99');
+
+        const amount = await runOneTime(Manager, discountCodes.validate('WELCOME10OFF'));
+        assert.equal(amount.computed.promoAmount, '10.00', 'A flat-dollar code quotes its dollars');
+        assert.equal(amount.computed.totalToday, '39.99', '$10 off 49.99 is 39.99');
+
+        const shapeless = await runOneTime(Manager, LEGACY_SHAPELESS_DISCOUNT);
+        assert.equal('promoCode' in shapeless.computed, false, 'A shapeless discount renders no promo line');
+        assert.equal(shapeless.computed.totalToday, '49.99', 'The full price stands');
+        assert.deepEqual(shapeless.captured.errors, [], 'The transition should log no error');
+      },
+    },
+
+    {
+      name: 'no-discount-at-all-is-unchanged',
+      async run({ assert, Manager }) {
+        const { computed } = await runSubscription(Manager, null);
+
+        assert.equal('promoCode' in computed, false, 'No code, no promo line');
+        assert.equal(computed.totalToday, '49.99', 'The customer pays the list price');
+      },
+    },
+  ],
+});