@teleporthq/teleport-plugin-next-workflows 0.44.0 → 0.44.1

package/__tests__/invoice-regenerate-email.test.ts

@@ -0,0 +1,288 @@
+import {
+  BUYER,
+  ORDER_ID,
+  SECOND_BUYER,
+  SECOND_ORDER_ID,
+  PostmarkMessage,
+  historyLines,
+  invoiceOf,
+  ledgerRows,
+  openStore,
+  payWhilePdfServiceIsDown,
+  runsAsTheStore,
+  seedPaidOrder,
+} from './_helpers/invoice-store'
+
+/**
+ * Regenerate emails the buyer the invoice their payment could not.
+ *
+ * When the PDF service is down at payment, the order is still paid and its
+ * invoice row stays reserved without a PDF, so the payment's invoice email
+ * never goes out. The merchant then gets the PDF with the admin panel's
+ * Regenerate — and that regeneration, the FIRST to give the invoice a PDF,
+ * emails the buyer, once, when the store emails invoices.
+ *
+ * Everything here is the code the store runs, as emitted: the payment's
+ * `/api/invoices/generate`, the admin panel's `/api/invoices/[id]/regenerate`,
+ * the data access, the assembly, the PDF client, the invoice sender, the
+ * sent-email ledger and the locale module. Only what lies outside the store is
+ * faked: its Postgres database, the PDF service and the email provider.
+ */
+
+describe('Regenerate emails the buyer the invoice their payment could not', () => {
+  runsAsTheStore()
+
+  it('no PDF before: the regeneration that gives the invoice its PDF emails the buyer once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    expect(store.emails).toHaveLength(0)
+
+    const regenerated = await store.regenerate(String(invoice.id))
+
+    expect(regenerated.status).toBe(200)
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(store.emails).toHaveLength(1)
+    const [email] = store.emails
+    expect(email.To).toBe(BUYER)
+    expect(email.From).toBe('Lumen Pottery <shop@lumen.test>')
+    expect(email.Attachments).toEqual([
+      {
+        Name: 'INV-0001.pdf',
+        Content: Buffer.from('%PDF-1.4 INV-0001').toString('base64'),
+        ContentType: 'application/pdf',
+      },
+    ])
+
+    // The sent-email ledger: the row the payment's email writes, naming the
+    // route that sent it.
+    expect(ledgerRows(store)).toEqual([
+      expect.objectContaining({
+        email_type: 'invoice-email',
+        audience: 'customer',
+        recipient_email: BUYER,
+        from_email: 'shop@lumen.test',
+        from_name: 'Lumen Pottery',
+        status: 'sent',
+        provider: 'postmark',
+        source: 'invoice',
+        source_ref: 'api/invoices/[id]/regenerate',
+        order_id: ORDER_ID,
+        reference_type: 'invoice',
+        reference_id: invoice.id,
+      }),
+    ])
+    // The order's history: one "email sent" line, by the store admin.
+    expect(historyLines(store)).toEqual([
+      expect.objectContaining({
+        event_type: 'order-email-sent',
+        dedupe_key: 'order-email-sent:' + String(invoice.id) + ':invoice-email',
+        order_id: ORDER_ID,
+        payload: JSON.stringify({ purpose: 'invoice-email', to: BUYER }),
+        actor: 'Store admin',
+        actor_type: 'merchant',
+        status: 'recorded',
+      }),
+    ])
+  })
+
+  it.each([
+    [
+      'served from the database',
+      false,
+      (invoiceId: string) => '/api/invoices/' + invoiceId + '/pdf',
+    ],
+    ['in runtime storage', true, () => 'https://cdn.test/INV-0001.pdf'],
+  ])(
+    'sends exactly the email the payment would have sent — sender, template, attachment, language, and the link of a PDF %s',
+    async (_, storageConfigured, expectedLink) => {
+      // A payment the PDF service served: the invoice email it sends.
+      const paidOk = openStore()
+      paidOk.storage.configured = storageConfigured
+      seedPaidOrder(paidOk.db, ORDER_ID)
+      expect((await paidOk.pay(ORDER_ID)).status).toBe(200)
+      expect(paidOk.emails).toHaveLength(1)
+      const atPayment = paidOk.emails[0]
+      const paidInvoiceId = String(invoiceOf(paidOk, ORDER_ID).id)
+
+      // The same order, paid while the PDF service was down, then regenerated.
+      const paidDown = openStore()
+      paidDown.storage.configured = storageConfigured
+      seedPaidOrder(paidDown.db, ORDER_ID)
+      const invoice = await payWhilePdfServiceIsDown(paidDown, ORDER_ID)
+      expect((await paidDown.regenerate(String(invoice.id))).status).toBe(200)
+      expect(paidDown.emails).toHaveLength(1)
+      const atRegeneration = paidDown.emails[0]
+
+      // Nothing differs but the invoice's own id, inside a database link.
+      const sameLink = (message: PostmarkMessage, id: string): PostmarkMessage => ({
+        ...message,
+        HtmlBody: message.HtmlBody.split(id).join('<invoice id>'),
+      })
+      expect(sameLink(atRegeneration, String(invoice.id))).toEqual(
+        sameLink(atPayment, paidInvoiceId)
+      )
+      // The buyer's language (the order is Spanish), not the merchant's German admin.
+      expect(atRegeneration.Subject).toBe('Factura INV-0001')
+      expect(atRegeneration.HtmlBody).toBe(
+        '<p>Hola Ana Pop, factura INV-0001 por €100.00: ' +
+          expectedLink(String(invoice.id)) +
+          '</p>'
+      )
+    }
+  )
+
+  it("an order with no language of its own gets the store's main language, never the merchant's", async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID, { locale: null })
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    await store.regenerate(String(invoice.id))
+
+    expect(store.emails.map((email) => email.Subject)).toEqual(['Invoice INV-0001'])
+  })
+
+  it('had a PDF: only the invoice that never had one is emailed', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    seedPaidOrder(store.db, SECOND_ORDER_ID, {}, SECOND_BUYER)
+    // The first order's invoice was issued and emailed at payment.
+    expect((await store.pay(ORDER_ID)).status).toBe(200)
+    const issued = invoiceOf(store, ORDER_ID)
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER])
+    // The second order's was not: the PDF service was down.
+    const unfinished = await payWhilePdfServiceIsDown(store, SECOND_ORDER_ID)
+
+    expect((await store.regenerate(String(issued.id))).status).toBe(200)
+    expect((await store.regenerate(String(unfinished.id))).status).toBe(200)
+
+    // The payment's email, then the unfinished invoice's — nothing for the
+    // invoice that already had its PDF.
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER, SECOND_BUYER])
+    // Each email is on its own order's history once: the payment's, by the
+    // store, and the regeneration's, by the admin.
+    expect(historyLines(store).map((line) => [line.order_id, line.actor_type])).toEqual([
+      [ORDER_ID, 'system'],
+      [SECOND_ORDER_ID, 'merchant'],
+    ])
+  })
+
+  it('a second regeneration never emails again', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.emails).toHaveLength(1)
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+
+  it('two overlapping regenerations (a double click) email once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    // Both requests read the invoice without a PDF and render before either
+    // writes: the PDF service answers neither until it has both.
+    let releaseRenders: () => void = () => undefined
+    store.pdfService.hold = new Promise((resolve) => {
+      releaseRenders = resolve
+    })
+    const first = store.regenerate(String(invoice.id))
+    const second = store.regenerate(String(invoice.id))
+    while (store.pdfService.renders < 2) {
+      await new Promise((resolve) => setImmediate(resolve))
+    }
+    releaseRenders()
+    const answers = await Promise.all([first, second])
+
+    expect(answers.map((answer) => answer.status)).toEqual([200, 200])
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+
+  it('Invoice Email Delivery off: the same regeneration emails nobody', async () => {
+    const delivering = openStore()
+    seedPaidOrder(delivering.db, ORDER_ID)
+    const deliveredInvoice = await payWhilePdfServiceIsDown(delivering, ORDER_ID)
+    await delivering.regenerate(String(deliveredInvoice.id))
+    expect(delivering.emails).toHaveLength(1)
+
+    const silent = openStore({ emailDelivery: false })
+    seedPaidOrder(silent.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(silent, ORDER_ID)
+    const regenerated = await silent.regenerate(String(invoice.id))
+
+    expect(regenerated.status).toBe(200)
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(silent.emails).toHaveLength(0)
+    expect(ledgerRows(silent)).toHaveLength(0)
+    expect(historyLines(silent)).toHaveLength(0)
+    // The route does not even load the sender.
+    expect(silent.routeCode).not.toContain('email-sender')
+  })
+
+  it('a refused email still regenerates the invoice, is logged, and is never sent again', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    store.provider.refuses = true
+
+    const regenerated = await store.regenerate(String(invoice.id))
+
+    // The merchant has the PDF, and the order links to it.
+    expect(regenerated.status).toBe(200)
+    expect(regenerated.body).toMatchObject({ success: true, invoiceNumber: 'INV-0001' })
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(store.db.row('teleport_orders', ORDER_ID)).toMatchObject({
+      invoice_id: invoice.id,
+      invoice_number: 'INV-0001',
+      invoice_pdf_url: '/api/invoices/' + String(invoice.id) + '/pdf',
+    })
+    // The provider was asked once and refused: the ledger says so, the
+    // order's history does not claim an email went out, the log names it.
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toEqual([
+      expect.objectContaining({
+        status: 'failed',
+        error_message: '422 The From address is not a confirmed sender signature',
+      }),
+    ])
+    expect(historyLines(store)).toHaveLength(0)
+    expect(store.errors).toContainEqual(
+      expect.stringContaining('invoice INV-0001 could not be emailed to its customer')
+    )
+
+    store.provider.refuses = false
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.emails).toHaveLength(1)
+  })
+
+  it('an order that cannot be updated still gets its invoice emailed, once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    store.db.failNext(/^UPDATE teleport_orders SET invoice_id = \$1/, 'Connection terminated')
+
+    const failed = await store.regenerate(String(invoice.id))
+
+    // The invoice has its PDF, so its buyer is emailed it, with the link the
+    // database serves it from.
+    expect(failed.status).toBe(500)
+    expect(store.emails).toHaveLength(1)
+    expect(store.emails[0].HtmlBody).toContain('/api/invoices/' + String(invoice.id) + '/pdf')
+    expect(ledgerRows(store)).toHaveLength(1)
+
+    // Regenerating again links the order, and emails nobody.
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.db.row('teleport_orders', ORDER_ID)).toMatchObject({ invoice_id: invoice.id })
+    expect(store.emails).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+})

package/__tests__/invoice-regenerate-route.test.ts

@@ -16,8 +16,10 @@ import {
  *
  * Every test runs the EMITTED route against the REAL emitted assembly, with
  * the database, the PDF service and the session stubbed: a regenerated invoice
- * must be priced by exactly the code that issued it, keep its identity, take
- * the merchant's corrections over the order, and never email anybody.
+ * must be priced by exactly the code that issued it, keep its identity and
+ * take the merchant's corrections over the order. These run a store that does
+ * not email invoices; the one email a regeneration can send is proved in
+ * `invoice-regenerate-email.test.ts`.
  */
 
 const SETTINGS = {
@@ -27,7 +29,7 @@ const SETTINGS = {
   companyDetails: {},
   template: { document: null as unknown },
   tables: { invoicesTable: 'teleport_invoices', invoiceItemsTable: 'teleport_invoice_items' },
-  emailDelivery: { enabled: true, provider: 'postmark' },
+  emailDelivery: { enabled: false },
 } as unknown as UIDLInvoiceSettings
 
 type Row = Record<string, unknown>
@@ -190,7 +192,7 @@ async function run(options: RunOptions = {}): Promise<Harness> {
 
   const token = options.token === undefined ? { role: 'admin', id: 'u1' } : options.token
   const handler = evaluateEmittedModule<(req: unknown, res: unknown) => Promise<void>>(
-    generateInvoiceRegenerateRouteCode(),
+    generateInvoiceRegenerateRouteCode(SETTINGS),
     createInvoiceRouteRequire(SETTINGS, {
       dataAccess,
       pdfGenerator,
@@ -333,9 +335,9 @@ describe('/api/invoices/[id]/regenerate', () => {
     })
   })
 
-  it('never emails the customer', async () => {
+  it('never emails the customer of a store that does not email invoices', async () => {
     // The route does not even load the sender: a require of it would throw here.
-    const code = generateInvoiceRegenerateRouteCode()
+    const code = generateInvoiceRegenerateRouteCode(SETTINGS)
     expect(code).not.toContain('email-sender')
     expect(code).not.toContain('sendInvoiceEmail')
   })
@@ -402,7 +404,7 @@ describe('/api/invoices/generate — remembers where its PDF is stored', () => {
         invoiceData.invoiceNumber = 'INV-0009'
         return { invoice: invoiceData, created: true }
       },
-      storeInvoicePdf: async () => ({}),
+      storeInvoicePdf: async () => ({ firstPdf: true }),
       updateInvoice: async (id: string, fields: Row) => {
         updates.push({ id, fields })
         return fields

package/__tests__/invoice-reservation.test.ts

@@ -61,7 +61,7 @@ async function run(
     },
     storeInvoicePdf: async (id: string, pdf: Buffer) => {
       stored.push({ id, bytes: pdf.length })
-      return {}
+      return { firstPdf: true }
     },
     updateInvoice: async () => ({}),
   }

package/__tests__/invoice-tender.test.ts

@@ -86,7 +86,7 @@ async function runHandler(order: Row, items: Row[], body: Row): Promise<HandlerR
       invoice = invoiceData
       return { invoice: invoiceData, created: true }
     },
-    storeInvoicePdf: async () => ({}),
+    storeInvoicePdf: async () => ({ firstPdf: true }),
     updateInvoice: async () => ({}),
   }
   const pdfGeneratorStub = {

package/__tests__/segment-splitter-checkout-order.test.ts

@@ -0,0 +1,306 @@
+import type { UIDLWorkflow, UIDLWorkflowEdge, UIDLWorkflowNode } from '@teleporthq/teleport-types'
+import { splitIntoSegments } from '../src/segment-splitter'
+import type { WorkflowSegment } from '../src/types'
+
+// Every server segment the browser reaches is one awaited round trip. A
+// checkout is one long chain of server steps with a refusal branch (a toast, a
+// reset) at almost every gate, all at the same depth as the chain's next step.
+// Ordered by depth alone, each refusal step sat between two server steps of the
+// chain and cut it into one more round trip; the loop over the cart lines held
+// everything after it in a depth-only order. Built here the way the editor's
+// checkout builds Place Order, with synthetic ids and labels.
+
+type Kind = 'client' | 'server' | 'gate' | 'loop' | 'custom-node' | 'navigate'
+
+const TYPE: Record<Kind, string> = {
+  client: 'state-update-local-state',
+  server: 'data-raw-query',
+  gate: 'general-if-statement',
+  loop: 'general-loop',
+  'custom-node': 'general-custom-node',
+  navigate: 'navigation-go-to-page',
+}
+
+const ENV: Record<Kind, UIDLWorkflowNode['executionEnv']> = {
+  client: 'client',
+  server: 'server',
+  gate: 'universal',
+  loop: 'universal',
+  'custom-node': 'universal',
+  navigate: 'client',
+}
+
+const buildWorkflow = (
+  steps: Array<[string, Kind]>,
+  links: Array<[string, string, string?, string?]>
+): UIDLWorkflow => {
+  const edges: UIDLWorkflowEdge[] = links.map(([source, target, sourceHandle, targetHandle]) => ({
+    id: `${source}->${target}`,
+    source,
+    target,
+    ...(sourceHandle ? { sourceHandle } : {}),
+    ...(targetHandle ? { targetHandle } : {}),
+  }))
+  // The editor's step numbers: breadth-first depth from the trigger.
+  const depth = new Map<string, number>()
+  const queue: Array<[string, number]> = [['trigger', 0]]
+  while (queue.length > 0) {
+    const [id, d] = queue.shift() as [string, number]
+    if (depth.has(id)) {
+      continue
+    }
+    depth.set(id, d)
+    edges.filter((e) => e.source === id).forEach((e) => queue.push([e.target, d + 1]))
+  }
+  return {
+    id: 'place-order',
+    name: 'Place Order',
+    trigger: { type: 'event-form-submitted', nodeId: 'trigger' },
+    nodes: steps.map(([id, kind]) => ({
+      id,
+      type: TYPE[kind],
+      label: id,
+      config: {},
+      executionEnv: ENV[kind],
+      stepNumber: depth.get(id) || 0,
+    })),
+    edges,
+  } as unknown as UIDLWorkflow
+}
+
+// A gate whose condition reads a server step, its refusal branch three or four
+// browser steps long, its accepted branch the rest of the chain.
+const placeOrder = buildWorkflow(
+  [
+    ['setBusy', 'client'],
+    ['formValid', 'gate'],
+    ['formToast', 'client'],
+    ['fetchStock', 'server'],
+    ['checkStock', 'server'],
+    ['inStock', 'gate'],
+    ['stockToast', 'client'],
+    ['stockReset', 'client'],
+    ['resolveUser', 'custom-node'],
+    ['loadDiscounts', 'server'],
+    ['countOrders', 'server'],
+    ['recheckVoucher', 'server'],
+    ['voucherValid', 'gate'],
+    ['forgetVoucher', 'client'],
+    ['voucherToast', 'client'],
+    ['voucherReset', 'client'],
+    ['voucherClear', 'client'],
+    ['priceOrder', 'server'],
+    ['assemble', 'server'],
+    ['checkAddress', 'server'],
+    ['canBill', 'gate'],
+    ['billToast', 'client'],
+    ['billReset', 'client'],
+    ['createOrder', 'server'],
+    ['redeem', 'server'],
+    ['redeemed', 'gate'],
+    ['cancelOrder', 'server'],
+    ['redeemToast', 'client'],
+    ['orderNumber', 'server'],
+    ['eachLine', 'loop'],
+    ['buildLine', 'server'],
+    ['saveLine', 'server'],
+    ['decrementStock', 'server'],
+    ['recordPlaced', 'custom-node'],
+    ['saveDetails', 'server'],
+    ['settled', 'gate'],
+    ['markSettled', 'server'],
+    ['clearCart', 'client'],
+    ['emailPayload', 'server'],
+    ['sendEmail', 'server'],
+    ['goToOrder', 'navigate'],
+    ['redirectUrls', 'server'],
+    ['charge', 'server'],
+    ['opened', 'gate'],
+    ['cancelRefused', 'server'],
+    ['refusedToast', 'client'],
+    ['recordCheckout', 'server'],
+    ['sendToCheckout', 'navigate'],
+  ],
+  [
+    ['trigger', 'setBusy'],
+    ['setBusy', 'formValid'],
+    ['formValid', 'formToast', 'false'],
+    ['formValid', 'fetchStock', 'true'],
+    ['fetchStock', 'checkStock'],
+    ['checkStock', 'inStock'],
+    ['inStock', 'stockToast', 'false'],
+    ['stockToast', 'stockReset'],
+    ['inStock', 'resolveUser', 'true'],
+    ['resolveUser', 'loadDiscounts'],
+    ['loadDiscounts', 'countOrders'],
+    ['countOrders', 'recheckVoucher'],
+    ['recheckVoucher', 'voucherValid'],
+    ['voucherValid', 'forgetVoucher', 'false'],
+    ['forgetVoucher', 'voucherToast'],
+    ['voucherToast', 'voucherReset'],
+    ['voucherReset', 'voucherClear'],
+    ['voucherValid', 'priceOrder', 'true'],
+    ['priceOrder', 'assemble'],
+    ['assemble', 'checkAddress'],
+    ['checkAddress', 'canBill'],
+    ['canBill', 'billToast', 'false'],
+    ['billToast', 'billReset'],
+    ['canBill', 'createOrder', 'true'],
+    ['createOrder', 'redeem'],
+    ['redeem', 'redeemed'],
+    ['redeemed', 'cancelOrder', 'false'],
+    ['cancelOrder', 'redeemToast'],
+    ['redeemed', 'orderNumber', 'true'],
+    ['orderNumber', 'eachLine'],
+    ['eachLine', 'buildLine', 'loop', 'loop-body-in'],
+    ['buildLine', 'saveLine'],
+    ['saveLine', 'eachLine', 'loop-body-out', 'loop-back'],
+    ['eachLine', 'decrementStock', 'exit'],
+    ['decrementStock', 'recordPlaced'],
+    ['recordPlaced', 'saveDetails'],
+    ['saveDetails', 'settled'],
+    ['settled', 'markSettled', 'true'],
+    ['markSettled', 'clearCart'],
+    ['clearCart', 'emailPayload'],
+    ['emailPayload', 'sendEmail'],
+    ['sendEmail', 'goToOrder'],
+    ['settled', 'redirectUrls', 'false'],
+    ['redirectUrls', 'charge'],
+    ['charge', 'opened'],
+    ['opened', 'cancelRefused', 'false'],
+    ['cancelRefused', 'refusedToast'],
+    ['opened', 'recordCheckout', 'true'],
+    ['recordCheckout', 'sendToCheckout'],
+  ]
+)
+
+const REFUSALS = [
+  'formToast',
+  'stockToast',
+  'stockReset',
+  'forgetVoucher',
+  'voucherToast',
+  'voucherReset',
+  'voucherClear',
+  'billToast',
+  'billReset',
+  'cancelOrder',
+  'redeemToast',
+  'cancelRefused',
+  'refusedToast',
+]
+const CASH_ONLY = ['markSettled', 'clearCart', 'emailPayload', 'sendEmail', 'goToOrder']
+const ONLINE_ONLY = ['redirectUrls', 'charge', 'opened', 'recordCheckout', 'sendToCheckout']
+
+// The server segments an order that every gate accepts calls, in order.
+const roundTrips = (segments: WorkflowSegment[], skipped: string[]): string[][] =>
+  segments
+    .filter((s) => s.env === 'server')
+    .map((s) => s.nodes.map((n) => n.id).filter((id) => !skipped.includes(id)))
+    .filter((ids) => ids.length > 0)
+
+const segmentOf = (segments: WorkflowSegment[], id: string): WorkflowSegment =>
+  segments.find((s) => s.nodes.some((n) => n.id === id)) as WorkflowSegment
+
+describe('splitIntoSegments — a checkout waits on as few server round trips as it can', () => {
+  const segments = splitIntoSegments(placeOrder)
+
+  it('calls the server once between each pair of steps that need the browser', () => {
+    // Browser steps on the accepted path: resolveUser (custom node) and
+    // recordPlaced (custom node) — plus clearCart for a cash order.
+    expect(roundTrips(segments, [...REFUSALS, ...ONLINE_ONLY])).toEqual([
+      ['fetchStock', 'checkStock', 'inStock'],
+      [
+        'loadDiscounts',
+        'countOrders',
+        'recheckVoucher',
+        'voucherValid',
+        'priceOrder',
+        'assemble',
+        'checkAddress',
+        'canBill',
+        'createOrder',
+        'redeem',
+        'redeemed',
+        'orderNumber',
+        'eachLine',
+        'buildLine',
+        'saveLine',
+        'decrementStock',
+      ],
+      ['saveDetails', 'settled', 'markSettled'],
+      ['emailPayload', 'sendEmail'],
+    ])
+    expect(roundTrips(segments, [...REFUSALS, ...CASH_ONLY])).toHaveLength(3)
+  })
+
+  it('decides every gate that reads a server step inside the server route', () => {
+    // A gate the browser decides is one a crafted request can answer: the
+    // route then takes the browser's word for which branch was skipped.
+    for (const gate of ['inStock', 'voucherValid', 'canBill', 'redeemed', 'settled', 'opened']) {
+      expect(segmentOf(segments, gate).env).toBe('server')
+    }
+    // A refusal step on the server shares its gate's route, which skips it itself.
+    expect(segmentOf(segments, 'cancelOrder')).toBe(segmentOf(segments, 'redeemed'))
+    expect(segmentOf(segments, 'cancelRefused')).toBe(segmentOf(segments, 'opened'))
+  })
+
+  it('keeps the loop and its body in one segment, in order', () => {
+    const loopSegment = segmentOf(segments, 'eachLine')
+    const ids = loopSegment.nodes.map((n) => n.id)
+    expect(ids.slice(ids.indexOf('eachLine'), ids.indexOf('eachLine') + 3)).toEqual([
+      'eachLine',
+      'buildLine',
+      'saveLine',
+    ])
+    expect(ids.indexOf('decrementStock')).toBeGreaterThan(ids.indexOf('saveLine'))
+  })
+
+  it('runs every step after everything it depends on', () => {
+    const order = segments.flatMap((s) => s.nodes.map((n) => n.id))
+    for (const e of placeOrder.edges) {
+      if (e.targetHandle === 'loop-back' || e.source === 'trigger') {
+        continue
+      }
+      expect([e.source, order.indexOf(e.source) < order.indexOf(e.target)]).toEqual([
+        e.source,
+        true,
+      ])
+    }
+  })
+})
+
+describe('splitIntoSegments — a server route runs its steps by step number', () => {
+  it('never puts a step in the segment of an input with a later step number', () => {
+    // `total` hangs off the trigger (step 1) but reads `line3` (step 3): the
+    // route, which sorts its segment by step, would run it before that value.
+    const workflow = {
+      id: 'w',
+      name: 'w',
+      trigger: { type: 'event-element-clicked', nodeId: 'trigger' },
+      nodes: [
+        { id: 'line1', type: 'data-select', stepNumber: 1, executionEnv: 'server', config: {} },
+        { id: 'line2', type: 'data-select', stepNumber: 2, executionEnv: 'server', config: {} },
+        { id: 'line3', type: 'data-select', stepNumber: 3, executionEnv: 'server', config: {} },
+        {
+          id: 'total',
+          type: 'data-create-item',
+          stepNumber: 1,
+          executionEnv: 'server',
+          config: { columnMappings: [{ value: { type: 'workflowContext', nodeId: 'line3' } }] },
+        },
+      ],
+      edges: [
+        { id: 'e0', source: 'trigger', target: 'line1' },
+        { id: 'e1', source: 'line1', target: 'line2' },
+        { id: 'e2', source: 'line2', target: 'line3' },
+        { id: 'e3', source: 'trigger', target: 'total' },
+      ],
+    } as unknown as UIDLWorkflow
+    const segments = splitIntoSegments(workflow)
+    expect(segments.map((s) => [s.env, s.nodes.map((n) => n.id)])).toEqual([
+      ['server', ['line1', 'line2', 'line3']],
+      ['server', ['total']],
+    ])
+  })
+})