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

package/__tests__/invoice-billing-details.test.ts

@@ -0,0 +1,384 @@
+/* tslint:disable:function-constructor */
+import { generateInvoiceGenerateRouteCode } from '../src/invoice/api-routes-code'
+import { generatePdfGeneratorCode } from '../src/invoice/pdf-generator-code'
+import type { UIDLInvoiceSettings } from '@teleporthq/teleport-types'
+import {
+  INVOICE_TEST_APP_SECRET,
+  createInvoiceRouteRequire,
+  evaluateEmittedModule,
+  serverCallHeaders,
+} from './_helpers/load-invoice-route'
+
+/**
+ * The buyer's own invoice details on the invoice. An order whose buyer gave
+ * them (a booking's "Add invoice details") carries the address in its parts
+ * and the tax or VAT number in its metadata: the invoice is made out to them
+ * — never mixed with a shipping address — and names the VAT number. A booking
+ * order also records the tax its final price includes, so its invoice extracts
+ * it instead of adding the store's rate on top. And the template's sample
+ * customer never fills a part the buyer left out. Every piece below is the
+ * EMITTED code, run.
+ */
+
+const settingsWith = (overrides: Record<string, unknown>) =>
+  ({
+    invoicePrefix: 'INV-',
+    defaultTaxRate: 19,
+    showDiscount: false,
+    taxIncludedInPrice: false,
+    companyDetails: {},
+    template: { document: null as unknown },
+    tables: { invoicesTable: 'teleport_invoices', invoiceItemsTable: 'teleport_invoice_items' },
+    emailDelivery: { enabled: false },
+    ...overrides,
+  } as unknown as UIDLInvoiceSettings)
+
+type Row = Record<string, unknown>
+
+const BOOKING_ORDER: Row = {
+  id: 'order-bk',
+  order_number: 'ORD-1',
+  currency: 'EUR',
+  total_amount: 238,
+  shipping_amount: 0,
+  billing_name: 'Acme SRL',
+  billing_email: 'ana@example.com',
+  billing_address: 'Str. Lunga 1, 400000 Cluj, Cluj, Romania',
+  shipping_city: 'Shipped-to city',
+  tax_breakdown: JSON.stringify({
+    taxRate: 19,
+    taxIncluded: true,
+    taxDecimals: 2,
+    shippingTax: 0,
+    lines: [{ productId: 'room', variantId: '', taxRate: 19, taxIncluded: true }],
+  }),
+  metadata: JSON.stringify({
+    bookingId: 'b1',
+    bookingReference: 'BK-1',
+    billingTaxId: 'RO12345678',
+    billingStreet: 'Str. Lunga 1',
+    billingCity: 'Cluj',
+    billingPostalCode: '400000',
+    billingRegion: 'Cluj',
+    billingCountry: 'Romania',
+  }),
+}
+const BOOKING_ITEMS: Row[] = [
+  {
+    product_id: 'room',
+    product_name: 'Double room',
+    quantity: 1,
+    unit_price: 238,
+    total_price: 238,
+  },
+]
+
+async function runHandler(
+  settings: UIDLInvoiceSettings,
+  order: Row,
+  items: Row[],
+  body: Row
+): Promise<{ status: number; invoice: Row }> {
+  const code = generateInvoiceGenerateRouteCode(settings)
+  let invoice: Row = {}
+  const handler = evaluateEmittedModule<(req: unknown, res: unknown) => Promise<void>>(
+    code,
+    createInvoiceRouteRequire(settings, {
+      dataAccess: {
+        getOrderWithItems: async (orderId: string) =>
+          orderId === order.id ? { order, items } : null,
+        reserveInvoice: async (invoiceData: Row) => {
+          invoice = invoiceData
+          return { invoice: invoiceData, created: true }
+        },
+        storeInvoicePdf: async () => ({ firstPdf: true }),
+        updateInvoice: async () => ({}),
+      },
+      pdfGenerator: {
+        generateInvoicePdf: async () => Buffer.from('%PDF-1.4 fake'),
+        COMPANY_DETAILS: {},
+      },
+    })
+  )
+  let status = 0
+  const res = {
+    status(statusCode: number) {
+      status = statusCode
+      return this
+    },
+    json() {
+      return this
+    },
+    setHeader() {
+      /* unused */
+    },
+    end() {
+      /* unused */
+    },
+  }
+  await handler({ method: 'POST', headers: serverCallHeaders(), body }, res)
+  return { status, invoice }
+}
+
+interface PdfGeneratorModule {
+  buildInvoiceDataScope: (invoiceData: Row) => { invoiceData: Record<string, Row> }
+  buildInvoiceHtml: (invoiceData: Row) => string
+}
+
+function loadPdfGenerator(
+  settings: UIDLInvoiceSettings,
+  templateUidl: unknown
+): PdfGeneratorModule {
+  const code = generatePdfGeneratorCode(settings, templateUidl, {})
+  const moduleObject = { exports: {} as Record<string, unknown> }
+  new Function('require', 'module', 'exports', `${code}; return module.exports;`)(
+    require,
+    moduleObject,
+    moduleObject.exports
+  )
+  return moduleObject.exports as unknown as PdfGeneratorModule
+}
+
+describe('/api/invoices/generate — the buyer’s own invoice details', () => {
+  const originalFetch = globalThis.fetch
+  const originalConnString = process.env.TELEPORT_DB_CONNECTION_STRING
+  const originalDatabaseUrl = process.env.DATABASE_URL
+  const originalAppSecret = process.env.NEXTAUTH_SECRET
+
+  beforeAll(() => {
+    globalThis.fetch = (async () => {
+      throw new Error('runtime storage not configured in tests')
+    }) as unknown as typeof fetch
+    delete process.env.TELEPORT_DB_CONNECTION_STRING
+    delete process.env.DATABASE_URL
+    process.env.NEXTAUTH_SECRET = INVOICE_TEST_APP_SECRET
+  })
+
+  afterAll(() => {
+    globalThis.fetch = originalFetch
+    if (originalAppSecret === undefined) {
+      delete process.env.NEXTAUTH_SECRET
+    } else {
+      process.env.NEXTAUTH_SECRET = originalAppSecret
+    }
+    if (originalConnString !== undefined) {
+      process.env.TELEPORT_DB_CONNECTION_STRING = originalConnString
+    }
+    if (originalDatabaseUrl !== undefined) {
+      process.env.DATABASE_URL = originalDatabaseUrl
+    }
+  })
+
+  it('makes the invoice out to the address parts and VAT number the order carries', async () => {
+    const run = await runHandler(settingsWith({}), BOOKING_ORDER, BOOKING_ITEMS, {
+      orderId: 'order-bk',
+    })
+    expect(run.status).toBe(200)
+    expect(run.invoice).toMatchObject({
+      customerName: 'Acme SRL',
+      customerAddress: 'Str. Lunga 1',
+      customerCity: 'Cluj',
+      customerZip: '400000',
+      customerState: 'Cluj',
+      customerCountry: 'Romania',
+      customerVat: 'RO12345678',
+    })
+  })
+
+  it('extracts the tax a booking price includes, so the invoice totals what was charged', async () => {
+    // The store adds 19% on top of its products; the booking's price already holds it.
+    const run = await runHandler(settingsWith({}), BOOKING_ORDER, BOOKING_ITEMS, {
+      orderId: 'order-bk',
+    })
+    expect(run.invoice.total).toBe(238)
+    expect(run.invoice.taxAmount).toBeCloseTo(38, 2)
+    expect(run.invoice.subtotal).toBeCloseTo(200, 2)
+  })
+
+  it('keeps the order’s own billing and shipping address when it carries no parts', async () => {
+    const order = {
+      ...BOOKING_ORDER,
+      tax_breakdown: null,
+      billing_address: 'Main St 5',
+      shipping_city: 'Springfield',
+      shipping_country: 'United States',
+      metadata: JSON.stringify({ billingTaxId: 'US-99' }),
+    }
+    const run = await runHandler(settingsWith({ defaultTaxRate: 0 }), order, BOOKING_ITEMS, {
+      orderId: 'order-bk',
+    })
+    expect(run.invoice).toMatchObject({
+      customerAddress: 'Main St 5',
+      customerCity: 'Springfield',
+      customerCountry: 'United States',
+      customerVat: 'US-99',
+    })
+  })
+
+  it('bills a store order shipped elsewhere at its billing address, under its company', async () => {
+    // The store checkout's "Billing Details", as its order records them; the
+    // goods go to someone else, in another town.
+    const storeOrder: Row = {
+      id: 'order-store',
+      order_number: 'ORD-7',
+      currency: 'USD',
+      total_amount: 40,
+      shipping_amount: 0,
+      billing_name: 'Ana Billing',
+      billing_email: 'ana@example.test',
+      billing_address: '1 Billing Street, Suite 4',
+      shipping_name: 'Ben Recipient',
+      shipping_address: '12 Delivery Lane',
+      shipping_city: 'Lyon',
+      shipping_state: 'Rhone',
+      shipping_zip: '69001',
+      shipping_country: 'FR',
+      metadata: JSON.stringify({
+        billingStreet: '1 Billing Street, Suite 4',
+        billingCompany: 'Acme Widgets Ltd',
+        billingCity: 'Halifax',
+        billingRegion: 'NS',
+        billingPostalCode: 'B3H 1A1',
+        billingCountry: 'CA',
+      }),
+    }
+    const items = [{ product_id: 'mug', product_name: 'Mug', quantity: 2, unit_price: 20 }]
+    const run = await runHandler(settingsWith({ defaultTaxRate: 0 }), storeOrder, items, {
+      orderId: 'order-store',
+    })
+    expect(run.status).toBe(200)
+    expect(run.invoice).toMatchObject({
+      customerName: 'Ana Billing',
+      customerCompany: 'Acme Widgets Ltd',
+      customerAddress: '1 Billing Street, Suite 4',
+      customerCity: 'Halifax',
+      customerState: 'NS',
+      customerZip: 'B3H 1A1',
+      customerCountry: 'CA',
+    })
+
+    const withoutCompany = await runHandler(
+      settingsWith({ defaultTaxRate: 0 }),
+      { ...storeOrder, metadata: JSON.stringify({ billingStreet: '1 Billing Street' }) },
+      items,
+      { orderId: 'order-store' }
+    )
+    expect(withoutCompany.invoice.customerCompany).toBe('')
+  })
+
+  it('reads no metadata that is not a JSON object, and lets the caller’s VAT win', async () => {
+    for (const metadata of ['not json', '[1,2]', null]) {
+      const run = await runHandler(
+        settingsWith({ defaultTaxRate: 0 }),
+        { ...BOOKING_ORDER, metadata, tax_breakdown: null },
+        BOOKING_ITEMS,
+        { orderId: 'order-bk' }
+      )
+      expect([metadata, run.status]).toEqual([metadata, 200])
+      expect([metadata, run.invoice.customerVat, run.invoice.customerCity]).toEqual([
+        metadata,
+        '',
+        'Shipped-to city',
+      ])
+    }
+    const stated = await runHandler(settingsWith({}), BOOKING_ORDER, BOOKING_ITEMS, {
+      orderId: 'order-bk',
+      customerVat: 'EDITED-1',
+    })
+    expect(stated.invoice.customerVat).toBe('EDITED-1')
+  })
+})
+
+describe('invoice PDF renderer — the buyer, never the template’s sample', () => {
+  const settings = settingsWith({})
+  const templated = loadPdfGenerator(settings, {
+    name: 'invoice-template',
+    node: {
+      type: 'element',
+      content: {
+        elementType: 'context',
+        attrs: {
+          Customer: {
+            type: 'static',
+            content: { name: 'Jane Smith', city: 'San Francisco', state: 'CA', vat: 'US1' },
+          },
+          Payment: { type: 'static', content: { method: 'Card', intentId: 'pi_sample' } },
+        },
+        children: [],
+      },
+    },
+  })
+
+  it('leaves out what the buyer did not give, and flags the lines that show', () => {
+    const { invoiceData } = templated.buildInvoiceDataScope({
+      customerName: 'Acme SRL',
+      customerVat: 'RO12345678',
+      currency: 'EUR',
+      items: [],
+    })
+    expect(invoiceData.Customer).toMatchObject({
+      name: 'Acme SRL',
+      city: '',
+      state: '',
+      vat: 'RO12345678',
+      hasVat: 'true',
+      hasZip: 'false',
+      hasCountry: 'false',
+    })
+    expect(invoiceData.Payment.intentId).toBe('')
+  })
+
+  it('prints the company under the name only for a buyer who gave one', () => {
+    const withCompany = templated.buildInvoiceDataScope({
+      customerName: 'Ana Billing',
+      customerCompany: 'Acme Widgets Ltd',
+      items: [],
+    }).invoiceData.Customer
+    expect(withCompany).toMatchObject({ company: 'Acme Widgets Ltd', hasCompany: 'true' })
+    const withoutCompany = templated.buildInvoiceDataScope({ customerName: 'Ana', items: [] })
+      .invoiceData.Customer
+    expect(withoutCompany).toMatchObject({ company: '', hasCompany: 'false' })
+
+    // The template's company line, gated on its flag like the editor builds it.
+    const text = (children: unknown[]) => ({
+      type: 'element',
+      content: { elementType: 'text', semanticType: 'p', children },
+    })
+    const billTo = loadPdfGenerator(settings, {
+      name: 'invoice-template',
+      node: {
+        type: 'element',
+        content: {
+          elementType: 'container',
+          children: [
+            text([{ type: 'expr', content: 'invoiceData?.Customer?.name' }]),
+            {
+              type: 'conditional',
+              content: {
+                reference: { type: 'expr', content: 'invoiceData?.Customer?.hasCompany' },
+                condition: { conditions: [{ operation: '=', operand: 'true' }] },
+                node: text([{ type: 'expr', content: 'invoiceData?.Customer?.company' }]),
+              },
+            },
+          ],
+        },
+      },
+    })
+    expect(
+      billTo.buildInvoiceHtml({
+        customerName: 'Ana',
+        customerCompany: 'Acme Widgets Ltd',
+        items: [],
+      })
+    ).toContain('Acme Widgets Ltd')
+    expect(billTo.buildInvoiceHtml({ customerName: 'Ana', items: [] })).not.toContain('Acme')
+
+    // And the built-in layout used when a store has no template.
+    const fallback = loadPdfGenerator(settings, null).buildInvoiceHtml({
+      customerName: 'Ana Billing',
+      customerCompany: 'Acme Widgets Ltd',
+      items: [],
+    })
+    expect(fallback).toContain('<strong>Ana Billing</strong><br/>Acme Widgets Ltd<br/>')
+  })
+})

package/__tests__/invoice-data-access-replace.test.ts

@@ -21,6 +21,8 @@ interface DataAccess {
     invoiceNumber: string,
     pdfUrl: string
   ) => Promise<boolean>
+  recordOrderEvent: (event: Row) => Promise<void>
+  storeInvoicePdf: (id: string, pdf: Buffer, pdfUrl: string) => Promise<Row>
 }
 
 interface Statement {
@@ -153,6 +155,96 @@ describe('invoice data-access — replaceInvoice', () => {
     )
     expect(released()).toBe(2)
   })
+
+  it('tells the regeneration that gave the invoice its first PDF, by writing only a row without one', async () => {
+    const { dataAccess, statements } = loadPostgres()
+    expect(await dataAccess.replaceInvoice('inv-1', INVOICE_DATA, ITEMS)).toEqual({
+      firstPdf: true,
+    })
+
+    const updates = statements.filter((statement) => statement.sql.startsWith('UPDATE'))
+    expect(updates).toHaveLength(1)
+    expect(updates[0].sql).toMatch(/ WHERE id = \$\d+ AND pdf_size_bytes IS NULL$/)
+  })
+
+  it('rewrites an invoice that already had a PDF all the same, and says it was not the first', async () => {
+    const { dataAccess, statements } = loadPostgres((sql) =>
+      sql.endsWith('AND pdf_size_bytes IS NULL') ? { rowCount: 0 } : { rowCount: 1 }
+    )
+    expect(await dataAccess.replaceInvoice('inv-1', INVOICE_DATA, ITEMS)).toEqual({
+      firstPdf: false,
+    })
+
+    const updates = statements.filter((statement) => statement.sql.startsWith('UPDATE'))
+    expect(updates).toHaveLength(2)
+    expect(updates[1].sql).toMatch(/ WHERE id = \$\d+$/)
+    expect(updates[1].values).toEqual(updates[0].values)
+    expect(statements.map((statement) => statement.sql)).toContain('COMMIT')
+  })
+})
+
+/** The emitted MySQL data access over a mysql2 stub; `affected` answers each UPDATE. */
+function loadMysql(affected: (sql: string) => number) {
+  const statements: string[] = []
+  const connection = {
+    beginTransaction: async () => statements.push('BEGIN'),
+    commit: async () => statements.push('COMMIT'),
+    rollback: async () => statements.push('ROLLBACK'),
+    release: (): void => undefined,
+    execute: async (sql: string) => {
+      statements.push(sql)
+      return [{ affectedRows: sql.startsWith('UPDATE') ? affected(sql) : 1, insertId: 1 }]
+    },
+  }
+  const mysqlStub = {
+    createPool: () => ({ getConnection: async () => connection, execute: connection.execute }),
+  }
+  const code = `${generateDataAccessCode(SETTINGS, 'mysql', null)}\n${getRecordMappingCode(
+    'mysql'
+  )}`
+  const moduleObject = { exports: {} as unknown }
+  const dataAccess = new Function(
+    'require',
+    'module',
+    'exports',
+    `${code}; return module.exports;`
+  )(
+    (id: string) => (id === 'mysql2/promise' ? mysqlStub : require(id)),
+    moduleObject,
+    moduleObject.exports
+  ) as DataAccess
+  return { dataAccess, statements }
+}
+
+describe('invoice data-access — replaceInvoice on MySQL', () => {
+  it('tells the regeneration that gave the invoice its first PDF', async () => {
+    const { dataAccess, statements } = loadMysql(() => 1)
+    expect(await dataAccess.replaceInvoice('inv-1', INVOICE_DATA, ITEMS)).toEqual({
+      firstPdf: true,
+    })
+    const updates = statements.filter((sql) => sql.startsWith('UPDATE'))
+    expect(updates).toHaveLength(1)
+    expect(updates[0]).toMatch(/ WHERE id = \? AND pdf_size_bytes IS NULL$/)
+  })
+
+  it('rewrites an invoice that already had a PDF, and says it was not the first', async () => {
+    const { dataAccess, statements } = loadMysql((sql) =>
+      sql.endsWith('AND pdf_size_bytes IS NULL') ? 0 : 1
+    )
+    expect(await dataAccess.replaceInvoice('inv-1', INVOICE_DATA, ITEMS)).toEqual({
+      firstPdf: false,
+    })
+    expect(statements.filter((sql) => sql.startsWith('UPDATE'))).toHaveLength(2)
+    expect(statements).toContain('COMMIT')
+  })
+
+  it('reports an invoice that disappeared', async () => {
+    const { dataAccess, statements } = loadMysql(() => 0)
+    await expect(dataAccess.replaceInvoice('inv-1', INVOICE_DATA, ITEMS)).rejects.toThrow(
+      'Invoice inv-1 no longer exists'
+    )
+    expect(statements).toContain('ROLLBACK')
+  })
 })
 
 type SupabaseResult = { data: unknown; error: { message: string } | null }
@@ -162,9 +254,14 @@ type SupabaseResult = { data: unknown; error: { message: string } | null }
  * `failOn(op, table, nth)` fails the nth (1-based) call of that operation on
  * that table.
  */
-function loadSupabase(failOn: (op: string, table: string, nth: number) => boolean = () => false) {
+function loadSupabase(
+  failOn: (op: string, table: string, nth: number) => boolean = () => false,
+  storedInvoice: Row = {}
+) {
   const store: Record<string, Row[]> = {
-    teleport_invoices: [{ id: 'inv-1', invoice_number: 'INV-0004', total: 90, notes: 'old' }],
+    teleport_invoices: [
+      { id: 'inv-1', invoice_number: 'INV-0004', total: 90, notes: 'old', ...storedInvoice },
+    ],
     teleport_invoice_items: [{ id: 'old-1', invoice_id: 'inv-1', name: 'Old lamp' }],
   }
   const counts: Record<string, number> = {}
@@ -225,6 +322,11 @@ function loadSupabase(failOn: (op: string, table: string, nth: number) => boolea
           filters.push((row) => values.includes(row[column]))
           return builder
         },
+        // `is(column, null)`: SQL NULL, which an absent column also reads as.
+        is: (column: string, value: unknown) => {
+          filters.push((row) => (value === null ? row[column] == null : row[column] === value))
+          return builder
+        },
         maybeSingle: () => {
           single = true
           return builder
@@ -294,6 +396,35 @@ describe('invoice data-access — replaceInvoice on Supabase (no transactions)',
     )
     expect(lineNames()).toEqual(['Old lamp'])
   })
+
+  it('tells the regeneration that gave the invoice its first PDF', async () => {
+    const { dataAccess, invoice } = loadSupabase()
+    expect(
+      await dataAccess.replaceInvoice('inv-1', { ...INVOICE_DATA, pdfSizeBytes: 2048 }, ITEMS)
+    ).toEqual({ firstPdf: true })
+    expect(invoice()).toMatchObject({ total: 105, pdf_size_bytes: 2048 })
+  })
+
+  it('rewrites an invoice that already had a PDF, and says it was not the first', async () => {
+    const { dataAccess, invoice } = loadSupabase(() => false, { pdf_size_bytes: 1024 })
+    expect(
+      await dataAccess.replaceInvoice('inv-1', { ...INVOICE_DATA, pdfSizeBytes: 2048 }, ITEMS)
+    ).toEqual({ firstPdf: false })
+    expect(invoice()).toMatchObject({ total: 105, pdf_size_bytes: 2048 })
+  })
+
+  it('puts the invoice back without its PDF when a later step fails, so the next regeneration is the first', async () => {
+    const { dataAccess, invoice } = loadSupabase(
+      (op, table, nth) => op === 'delete' && table === 'teleport_invoice_items' && nth === 1
+    )
+    await expect(
+      dataAccess.replaceInvoice('inv-1', { ...INVOICE_DATA, pdfSizeBytes: 2048 }, ITEMS)
+    ).rejects.toThrow('delete teleport_invoice_items failed')
+    expect(invoice().pdf_size_bytes == null).toBe(true)
+    expect(
+      await dataAccess.replaceInvoice('inv-1', { ...INVOICE_DATA, pdfSizeBytes: 2048 }, ITEMS)
+    ).toEqual({ firstPdf: true })
+  })
 })
 
 describe('invoice data-access — linkOrderToInvoice', () => {
@@ -327,6 +458,46 @@ describe('invoice data-access — linkOrderToInvoice', () => {
   })
 })
 
+describe('invoice data-access — recordOrderEvent', () => {
+  it("writes the order's history line once per key", async () => {
+    const { dataAccess, statements } = loadPostgres()
+    await dataAccess.recordOrderEvent({
+      type: 'order-email-sent',
+      dedupeKey: 'order-email-sent:inv-1:invoice-email',
+      orderId: 'order-1',
+      payload: { purpose: 'invoice-email', to: 'ana@buyer.test' },
+      actor: 'Store admin',
+      actorType: 'merchant',
+    })
+
+    const [statement] = statements
+    expect(statement.sql).toBe(
+      'INSERT INTO teleport_events (id, event_type, dedupe_key, order_id, payload, actor, actor_type, status) ' +
+        'VALUES ($1, $2, $3, $4, $5, $6, $7, $8) ON CONFLICT (dedupe_key) DO NOTHING'
+    )
+    expect(statement.values.slice(1)).toEqual([
+      'order-email-sent',
+      'order-email-sent:inv-1:invoice-email',
+      'order-1',
+      '{"purpose":"invoice-email","to":"ana@buyer.test"}',
+      'Store admin',
+      'merchant',
+      'recorded',
+    ])
+  })
+
+  it('keeps the key within the column', async () => {
+    const { dataAccess, statements } = loadPostgres()
+    await dataAccess.recordOrderEvent({
+      type: 'order-email-sent',
+      dedupeKey: 'k'.repeat(300),
+      actorType: 'merchant',
+    })
+    expect(String(statements[0].values[2])).toHaveLength(255)
+    expect(statements[0].values[3]).toBeNull()
+  })
+})
+
 describe('invoice data-access — every dialect exports the regeneration helpers', () => {
   it.each(['postgresql', 'mysql', 'supabase'])('%s', (dialect) => {
     const code = generateDataAccessCode(SETTINGS, dialect as never, null)
@@ -334,7 +505,70 @@ describe('invoice data-access — every dialect exports the regeneration helpers
     expect(code).toContain(
       'async function linkOrderToInvoice(orderId, invoiceId, invoiceNumber, pdfUrl)'
     )
+    expect(code).toContain('async function recordOrderEvent(event)')
     expect(code).toContain('replaceInvoice: replaceInvoice,')
     expect(code).toContain('linkOrderToInvoice: linkOrderToInvoice,')
+    expect(code).toContain('recordOrderEvent: recordOrderEvent,')
+  })
+})
+
+/**
+ * `storeInvoicePdf` — the payment's PDF, written only on an invoice that has
+ * none, so the invoice's first PDF (and with it its email) goes to exactly one
+ * of the payment and a regeneration, as `replaceInvoice` claims it.
+ */
+describe('invoice data-access — storeInvoicePdf writes only the first PDF', () => {
+  const PDF = Buffer.from('%PDF-1.4 INV-0004')
+
+  it('Postgres: one statement, on a row without a PDF', async () => {
+    const { dataAccess, statements } = loadPostgres()
+    expect(await dataAccess.storeInvoicePdf('inv-1', PDF, '/api/invoices/inv-1/pdf')).toEqual({
+      firstPdf: true,
+    })
+    expect(statements).toHaveLength(1)
+    expect(statements[0].sql).toBe(
+      'UPDATE teleport_invoices SET pdf_data = $1, pdf_size_bytes = $2, pdf_content_type = $3, ' +
+        'pdf_url = $4, updated_at = $5 WHERE id = $6 AND pdf_size_bytes IS NULL'
+    )
+    expect(statements[0].values).toEqual([
+      PDF,
+      PDF.length,
+      'application/pdf',
+      '/api/invoices/inv-1/pdf',
+      expect.any(String),
+      'inv-1',
+    ])
+  })
+
+  it('Postgres: an invoice that already has a PDF keeps it, and is not the first', async () => {
+    const { dataAccess } = loadPostgres(() => ({ rowCount: 0 }))
+    expect(await dataAccess.storeInvoicePdf('inv-1', PDF, '/api/invoices/inv-1/pdf')).toEqual({
+      firstPdf: false,
+    })
+  })
+
+  it('MySQL: the same condition, and the rows it changed', async () => {
+    const first = loadMysql(() => 1)
+    expect(await first.dataAccess.storeInvoicePdf('inv-1', PDF, '/x')).toEqual({ firstPdf: true })
+    expect(first.statements).toEqual([
+      'UPDATE teleport_invoices SET pdf_data = ?, pdf_size_bytes = ?, pdf_content_type = ?, ' +
+        'pdf_url = ?, updated_at = ? WHERE id = ? AND pdf_size_bytes IS NULL',
+    ])
+    const later = loadMysql(() => 0)
+    expect(await later.dataAccess.storeInvoicePdf('inv-1', PDF, '/x')).toEqual({ firstPdf: false })
+  })
+
+  it('Supabase: one filtered update', async () => {
+    const first = loadSupabase()
+    expect(await first.dataAccess.storeInvoicePdf('inv-1', PDF, '/x')).toEqual({ firstPdf: true })
+    expect(first.invoice()).toMatchObject({
+      pdf_data: PDF.toString('base64'),
+      pdf_size_bytes: PDF.length,
+      pdf_url: '/x',
+    })
+
+    const later = loadSupabase(() => false, { pdf_size_bytes: 1024, pdf_url: '/regenerated' })
+    expect(await later.dataAccess.storeInvoicePdf('inv-1', PDF, '/x')).toEqual({ firstPdf: false })
+    expect(later.invoice()).toMatchObject({ pdf_size_bytes: 1024, pdf_url: '/regenerated' })
   })
 })

package/__tests__/invoice-order-items-settle.test.ts

@@ -120,7 +120,7 @@ async function runHandler(options: {
       insertedItems.push(...items)
       return { invoice: invoiceData, created: true }
     },
-    storeInvoicePdf: async () => ({}),
+    storeInvoicePdf: async () => ({ firstPdf: true }),
     updateInvoice: async () => ({}),
   }