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

package/src/invoice/api-routes-code.ts

@@ -57,6 +57,42 @@ async function invoiceCaller(req) {
   };
 }`
 
+/**
+ * The order-history line of an invoice email the provider accepted: an
+ * `order-email-sent` line of the email's purpose, keyed on the invoice, so the
+ * email is on its order's history once, whichever route sent it. The strings
+ * are data in the merchant's database, owned by teleport-gui's
+ * `order-event-types.ts` and `EmailTemplatePurpose.INVOICE_EMAIL`.
+ */
+const INVOICE_EMAIL_EVENT = { type: 'order-email-sent', purpose: 'invoice-email' }
+
+/** Who sent an invoice email, as the order's history names them. */
+const INVOICE_EMAIL_SENDERS = {
+  // The store's own code: the payment webhook's invoice step, the checkout.
+  store: { actor: '', actorType: 'system' },
+  // A signed-in admin: the admin panel's Regenerate, or an invoice issued by hand.
+  admin: { actor: 'Store admin', actorType: 'merchant' },
+}
+
+/** `recordInvoiceEmailSent(invoiceData, sender)`, as emitted source; needs `dataAccess`. */
+const RECORD_INVOICE_EMAIL_CODE = `
+var INVOICE_EMAIL_EVENT = ${JSON.stringify(INVOICE_EMAIL_EVENT)};
+var INVOICE_EMAIL_SENDERS = ${JSON.stringify(INVOICE_EMAIL_SENDERS)};
+
+// Writes the order's history line for an invoice email the provider accepted.
+// The key is the invoice's, so the line is written once per invoice email.
+async function recordInvoiceEmailSent(invoiceData, sender) {
+  if (!invoiceData.orderId) return;
+  await dataAccess.recordOrderEvent({
+    type: INVOICE_EMAIL_EVENT.type,
+    dedupeKey: INVOICE_EMAIL_EVENT.type + ':' + invoiceData.id + ':' + INVOICE_EMAIL_EVENT.purpose,
+    orderId: invoiceData.orderId,
+    payload: { purpose: INVOICE_EMAIL_EVENT.purpose, to: invoiceData.customerEmail },
+    actor: sender.actor,
+    actorType: sender.actorType,
+  });
+}`
+
 export const generateInvoiceGenerateRouteCode = (settings: UIDLInvoiceSettings): string => {
   const prefix = settings.invoicePrefix || 'INV-'
   const autoGenerate = settings.autoGenerateOnPayment !== false
@@ -92,6 +128,7 @@ var INVOICE_PREFIX = ${JSON.stringify(prefix)};
 var UNFINISHED_INVOICE_STALE_SECONDS = 900;
 
 ${INVOICE_CALLER_CODE}
+${emailEnabled ? RECORD_INVOICE_EMAIL_CODE : ''}
 
 // ---------------------------------------------------------------------------
 // Waiting for the order's line items to be fully written.
@@ -127,6 +164,21 @@ function sleepMs(ms) {
   return new Promise(function (resolve) { setTimeout(resolve, ms); });
 }
 
+// The answer for an invoice the order already has: its number and its PDF.
+function issuedInvoiceAnswer(invoice, currency) {
+  var pdfUrl = invoice.pdf_url || ('/api/invoices/' + invoice.id + '/pdf');
+  return {
+    success: true,
+    alreadyIssued: true,
+    invoiceId: invoice.id,
+    invoiceNumber: invoice.invoice_number,
+    storageUrl: pdfUrl.indexOf('/api/invoices/') === 0 ? '' : pdfUrl,
+    pdfUrl: pdfUrl,
+    total: Number(invoice.total) || 0,
+    currency: invoice.currency || currency,
+  };
+}
+
 async function hydrateOrderWhenSettled(orderId) {
   var deadline = Date.now() + SETTLE_TIMEOUT_MS;
   var lastCount = -1;
@@ -267,17 +319,7 @@ module.exports = async function handler(req, res) {
     if (!reservation.created) {
       if (Number(held.pdf_size_bytes) > 0) {
         console.info('[invoice] Order ' + body.orderId + ' already has invoice ' + held.invoice_number + ' — returning it');
-        var heldPdfUrl = held.pdf_url || ('/api/invoices/' + held.id + '/pdf');
-        res.status(200).json({
-          success: true,
-          alreadyIssued: true,
-          invoiceId: held.id,
-          invoiceNumber: held.invoice_number,
-          storageUrl: heldPdfUrl.indexOf('/api/invoices/') === 0 ? '' : heldPdfUrl,
-          pdfUrl: heldPdfUrl,
-          total: Number(held.total) || 0,
-          currency: held.currency || currency,
-        });
+        res.status(200).json(issuedInvoiceAnswer(held, currency));
         return;
       }
       // Reserved, never finished: another request is rendering it now, or the
@@ -313,7 +355,18 @@ ${
     console.info('[invoice] PDF generated: ' + pdfBuffer.length + ' bytes for ' + invoiceData.invoiceNumber);
 
     invoiceData.pdfUrl = '/api/invoices/' + invoiceData.id + '/pdf';
-    await dataAccess.storeInvoicePdf(invoiceData.id, pdfBuffer, invoiceData.pdfUrl);
+    // The PDF is written only on an invoice that has none, and the invoice's
+    // first PDF is what its email is claimed by (see storeInvoicePdf). A
+    // regeneration that gave a reserved invoice its PDF while this request
+    // rendered it — a retried payment finishing a stale reservation — emailed
+    // the buyer itself, so this request answers with that invoice and sends
+    // nothing.
+    var stored = await dataAccess.storeInvoicePdf(invoiceData.id, pdfBuffer, invoiceData.pdfUrl);
+    if (!stored.firstPdf) {
+      console.info('[invoice] Invoice ' + invoiceNumber + ' was given its PDF by a regeneration meanwhile — returning it');
+      res.status(200).json(issuedInvoiceAnswer((await dataAccess.getInvoiceById(invoiceData.id)) || held, currency));
+      return;
+    }
     console.info('[invoice] PDF stored — teleport_invoices.id=' + invoiceData.id + ', number=' + invoiceData.invoiceNumber + ', pdf_size_bytes=' + pdfBuffer.length + ', items=' + items.length + ' (accessible at ' + invoiceData.pdfUrl + ')');
 
     var safeFileName = String(invoiceNumber || invoiceData.id).replace(/[^a-zA-Z0-9._-]/g, '_') + '.pdf';
@@ -382,9 +435,11 @@ ${
   emailEnabled
     ? `
     if (invoiceData.customerEmail) {
+      var emailed = false;
       try {
         var emailResult = await emailSender.sendInvoiceEmail(invoiceData, pdfBuffer);
-        if (emailResult && emailResult.success) {
+        emailed = !!(emailResult && emailResult.success);
+        if (emailed) {
           console.info('[invoice] Email delivery OK — to=' + invoiceData.customerEmail + ', messageId=' + (emailResult.messageId || '(empty)'));
         } else {
           console.error('[invoice] Email delivery FAILED — to=' + invoiceData.customerEmail + ', error=' + (emailResult && emailResult.error ? emailResult.error : 'unknown'));
@@ -392,6 +447,13 @@ ${
       } catch (emailErr) {
         console.error('[invoice] Email delivery threw — to=' + invoiceData.customerEmail + ', error=' + (emailErr && emailErr.message ? emailErr.message : emailErr));
       }
+      if (emailed) {
+        try {
+          await recordInvoiceEmailSent(invoiceData, caller.admin ? INVOICE_EMAIL_SENDERS.admin : INVOICE_EMAIL_SENDERS.store);
+        } catch (recordErr) {
+          console.error('[invoice] Invoice ' + invoiceNumber + ' was emailed, but the order history could not record it — ' + (recordErr && recordErr.message));
+        }
+      }
     } else {
       console.info('[invoice] Skipping email delivery — invoiceData.customerEmail is empty. (Check teleport_orders.billing_email for order ' + (body.orderId || '(no orderId)') + ')');
     }
@@ -452,6 +514,37 @@ ${
 /** The roles allowed to rebuild an invoice (the admin panel is the only caller). */
 const REGENERATE_INVOICE_ROLES = INVOICE_ADMIN_ROLES
 
+/** The regenerate route's `emailFirstInvoice`, as emitted source. */
+const generateFirstInvoiceEmailCode = (): string => `${RECORD_INVOICE_EMAIL_CODE}
+
+var REGENERATE_SOURCE_REF = 'api/invoices/[id]/regenerate';
+
+// The invoice email the payment would have sent: the same sender, template,
+// attachment and link, in the buyer's language — the one stamped on the order
+// at checkout, else the store's main language, never the language of this
+// request, which is the merchant's. The sender records it in the sent-email
+// ledger; the order's history records it once the provider accepted it. A
+// failure is logged and goes no further: the merchant has the PDF either way.
+async function emailFirstInvoice(invoiceData, pdfBuffer, order) {
+  if (!invoiceData.customerEmail) return;
+  invoiceData.locale = emailLocale.normalizeEmailLocale(order && order.locale) || emailLocale.DEFAULT_EMAIL_LOCALE;
+  try {
+    var sent = await emailSender.sendInvoiceEmail(invoiceData, pdfBuffer, REGENERATE_SOURCE_REF);
+    if (!sent || !sent.success) {
+      throw new Error((sent && sent.error) || 'the email provider did not accept it');
+    }
+  } catch (sendErr) {
+    console.error('[invoice] Regenerate: invoice ' + invoiceData.invoiceNumber + ' could not be emailed to its customer — ' + (sendErr && sendErr.message));
+    return;
+  }
+  try {
+    await recordInvoiceEmailSent(invoiceData, INVOICE_EMAIL_SENDERS.admin);
+  } catch (recordErr) {
+    console.error('[invoice] Regenerate: invoice ' + invoiceData.invoiceNumber + ' was emailed, but the order history could not record it — ' + (recordErr && recordErr.message));
+  }
+}
+`
+
 /**
  * POST /api/invoices/[id]/regenerate — the admin panel's "Regenerate" action.
  *
@@ -461,23 +554,47 @@ const REGENERATE_INVOICE_ROLES = INVOICE_ADMIN_ROLES
  * against it keep pointing at a valid invoice. What a merchant corrected on the
  * invoice itself (customer details, notes, payment method) wins over the order;
  * the lines and every figure are recomputed from the order. The old PDF is
- * replaced — and its runtime-storage copy deleted — and the customer is never
- * emailed.
+ * replaced — and its runtime-storage copy deleted.
+ *
+ * The customer is emailed once: by the regeneration that gives an invoice its
+ * FIRST PDF — one whose PDF failed at payment, so the payment's invoice email
+ * never went out — and only when the store emails invoices (Invoice Email
+ * Delivery). It is the payment's email: the same sender, template, attachment,
+ * link and language, recorded in the sent-email ledger and on the order's
+ * history. Which write gives the first PDF, the database decides (see
+ * `replaceInvoice` and `storeInvoicePdf`), so a second regeneration, a double
+ * click, two requests at once or a retried payment finishing the same invoice
+ * never send it again; a failed send costs the merchant nothing.
  *
  * Unlike `/generate`, which the payment webhook calls server-to-server, this
  * route is reached from the merchant's browser only, so it checks the session
  * itself: signed in, with an admin role.
  */
-export const generateInvoiceRegenerateRouteCode = (): string => {
+export const generateInvoiceRegenerateRouteCode = (settings: UIDLInvoiceSettings): string => {
+  const emailEnabled = settings.emailDelivery?.enabled === true
+
   return `/**
  * POST /api/invoices/[id]/regenerate
  * Rebuilds one invoice from its order, in place, for the admin panel. Same
- * number, id and dates; a freshly rendered PDF replaces the old one; no email.
+ * number, id and dates; a freshly rendered PDF replaces the old one.${
+   emailEnabled
+     ? `
+ * The first PDF an invoice ever gets is emailed to its customer, once.`
+     : `
+ * No email: this store does not email invoices.`
+ }
  */
 
 var dataAccess = require('../../../../utils/invoices/data-access');
 var pdfGenerator = require('../../../../utils/invoices/pdf-generator');
 var invoiceAssembly = require('../../../../utils/invoices/invoice-assembly');
+${
+  emailEnabled
+    ? `var emailSender = require('../../../../utils/invoices/email-sender');
+var sentEmailLog = require('../../../../utils/email/sent-email-log');
+var emailLocale = require('../../../../utils/email/email-locale');`
+    : ''
+}
 
 ${generateCommonJsSessionTokenResolverCode()}
 ${ROLE_OF_TOKEN_CODE}
@@ -563,7 +680,7 @@ async function findInvoice(invoiceId) {
     throw err;
   }
 }
-
+${emailEnabled ? generateFirstInvoiceEmailCode() : ''}
 module.exports = async function handler(req, res) {
   if (req.method !== 'POST') {
     res.setHeader('Allow', 'POST');
@@ -622,7 +739,14 @@ module.exports = async function handler(req, res) {
     invoiceData.pdfSizeBytes = pdfBuffer.length;
     invoiceData.pdfUrl = '/api/invoices/' + invoiceData.id + '/pdf';
 
-    await dataAccess.replaceInvoice(invoiceData.id, invoiceData, invoiceData.items);
+${
+  emailEnabled
+    ? `    var replaced = await dataAccess.replaceInvoice(invoiceData.id, invoiceData, invoiceData.items);
+    // This regeneration gave the invoice its first PDF, so the payment's
+    // invoice email never went out: this one sends it.
+    var emailsCustomer = !!(replaced && replaced.firstPdf);`
+    : `    await dataAccess.replaceInvoice(invoiceData.id, invoiceData, invoiceData.items);`
+}
     console.info('[invoice] Regenerated ' + invoiceData.invoiceNumber + ' (id=' + invoiceData.id + ', items=' + invoiceData.items.length + ', pdf_size_bytes=' + pdfBuffer.length + ')');
 
     // The new PDF's public copy. The row already serves the new bytes through
@@ -645,7 +769,17 @@ module.exports = async function handler(req, res) {
       if (storageKey) {
         await invoiceAssembly.deleteStoredInvoicePdf(storageKey);
       }
-      res.status(500).json({ success: false, error: MESSAGES.orderNotUpdated });
+${
+  emailEnabled
+    ? `      // The invoice has its first PDF all the same — served from the database,
+      // its public copy just went — and no later regeneration will send it.
+      if (emailsCustomer) {
+        await emailFirstInvoice(invoiceData, pdfBuffer, hydrated.order);
+      }
+      await sentEmailLog.settleSentEmailLog();
+`
+    : ''
+}      res.status(500).json({ success: false, error: MESSAGES.orderNotUpdated });
       return;
     }
 
@@ -663,7 +797,18 @@ module.exports = async function handler(req, res) {
     if (previousStorageKey && previousStorageKey !== storageKey) {
       await invoiceAssembly.deleteStoredInvoicePdf(previousStorageKey);
     }
-
+${
+  emailEnabled
+    ? `
+    if (emailsCustomer) {
+      await emailFirstInvoice(invoiceData, pdfBuffer, hydrated.order);
+    }
+    // The email's ledger row is written in the background — land it before
+    // replying, a serverless function may be frozen the instant it responds.
+    await sentEmailLog.settleSentEmailLog();
+`
+    : ''
+}
     res.status(200).json({
       success: true,
       invoiceId: invoiceData.id,

package/src/invoice/data-access-code.ts

@@ -27,7 +27,7 @@ ${generateGetInvoiceByIdCode(dsType, invoicesTable)}
 
 ${generateUpdateInvoiceCode(dsType, invoicesTable)}
 
-${generateStoreInvoicePdfCode(dsType)}
+${generateStoreInvoicePdfCode(dsType, invoicesTable)}
 
 ${generateGetOrderWithItemsCode(dsType)}
 
@@ -35,6 +35,8 @@ ${generateReplaceInvoiceCode(dsType, invoicesTable, invoiceItemsTable)}
 
 ${generateLinkOrderToInvoiceCode(dsType)}
 
+${generateRecordOrderEventCode(dsType)}
+
 module.exports = {
   getClient: getClient,
   reserveInvoice: reserveInvoice,
@@ -45,6 +47,7 @@ module.exports = {
   getOrderWithItems: getOrderWithItems,
   replaceInvoice: replaceInvoice,
   linkOrderToInvoice: linkOrderToInvoice,
+  recordOrderEvent: recordOrderEvent,
 };
 `
 }
@@ -356,18 +359,47 @@ ${cutoff}
 }`
 }
 
-// Puts the rendered PDF on the reserved row; `pdf_size_bytes` is what marks
-// the invoice finished (see `claimStaleInvoice`).
-function generateStoreInvoicePdfCode(dsType: string): string {
-  const pdfData = dsType === 'supabase' ? `pdfBuffer.toString('base64')` : 'pdfBuffer'
-  return `
+// Puts the rendered PDF on the reserved row — only while the row has none —
+// and resolves to `{ firstPdf }`: whether this write gave the invoice its
+// first PDF. `pdf_size_bytes` marks the invoice finished (see
+// `claimStaleInvoice`), and the invoice's first PDF is what its email is
+// claimed by: `replaceInvoice` writes first under the same condition, so of a
+// retried payment finishing a stale invoice and a regeneration racing it, one
+// writes the PDF and emails the buyer, and the other is told it was not first.
+function generateStoreInvoicePdfCode(dsType: string, table: string): string {
+  if (dsType === 'supabase') {
+    return `
 async function storeInvoicePdf(invoiceId, pdfBuffer, pdfUrl) {
-  return updateInvoice(invoiceId, {
-    pdf_data: ${pdfData},
+  var result = await getClient().from('${table}').update({
+    pdf_data: pdfBuffer.toString('base64'),
     pdf_size_bytes: pdfBuffer.length,
     pdf_content_type: 'application/pdf',
     pdf_url: pdfUrl,
-  });
+    updated_at: new Date().toISOString(),
+  }).eq('id', invoiceId).is('pdf_size_bytes', null).select('id');
+  if (result.error) throw new Error(result.error.message);
+  return { firstPdf: !!(result.data && result.data.length > 0) };
+}`
+  }
+
+  if (dsType === 'mysql' || dsType === 'mariadb' || dsType === 'tidb') {
+    return `
+async function storeInvoicePdf(invoiceId, pdfBuffer, pdfUrl) {
+  var [result] = await getClient().execute(
+    'UPDATE ${table} SET pdf_data = ?, pdf_size_bytes = ?, pdf_content_type = ?, pdf_url = ?, updated_at = ? WHERE id = ? AND pdf_size_bytes IS NULL',
+    [pdfBuffer, pdfBuffer.length, 'application/pdf', pdfUrl, new Date().toISOString(), invoiceId]
+  );
+  return { firstPdf: !!(result && result.affectedRows > 0) };
+}`
+  }
+
+  return `
+async function storeInvoicePdf(invoiceId, pdfBuffer, pdfUrl) {
+  var result = await getClient().query(
+    'UPDATE ${table} 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',
+    [pdfBuffer, pdfBuffer.length, 'application/pdf', pdfUrl, new Date().toISOString(), invoiceId]
+  );
+  return { firstPdf: result.rowCount > 0 };
 }`
 }
 
@@ -565,6 +597,15 @@ async function getOrderWithItems(orderId) {
 // points at it (the order, the sent-email ledger) stays valid. Postgres and
 // MySQL do it in one transaction, and Supabase undoes its steps, so a failure
 // leaves the old invoice whole.
+//
+// Resolves to `{ firstPdf }`: whether this write gave the invoice its first
+// PDF — one whose PDF never came at payment, so its buyer was never emailed
+// it. The database decides: the row is first written only where it has no PDF
+// (the `pdf_size_bytes IS NULL` that `claimStaleInvoice` reads as
+// "unfinished"), and of two regenerations racing for the same invoice the
+// second waits for the first's row lock, then finds the PDF and matches
+// nothing. `storeInvoicePdf` writes the payment's PDF under the same
+// condition, so exactly one write is ever told `firstPdf: true`.
 function generateReplaceInvoiceCode(dsType: string, table: string, itemsTable: string): string {
   if (dsType === 'supabase') {
     return `
@@ -584,18 +625,23 @@ async function replaceInvoice(invoiceId, invoiceData, items) {
   var insertedIds = (inserted || []).map(function (row) { return row.id; });
   var written = null;
   try {
-    var record = await writeInvoiceRecord(mapInvoiceReplacementToRecord(invoiceData), async function (fields) {
-      var result = await client.from('${table}').update(fields).eq('id', invoiceId).select('id');
-      if (result.error) throw new Error(result.error.message);
-      if (!result.data || result.data.length === 0) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+    var outcome = await writeInvoiceRecord(mapInvoiceReplacementToRecord(invoiceData), async function (fields) {
+      var first = await client.from('${table}').update(fields).eq('id', invoiceId).is('pdf_size_bytes', null).select('id');
+      if (first.error) throw new Error(first.error.message);
+      var firstPdf = !!(first.data && first.data.length > 0);
+      if (!firstPdf) {
+        var result = await client.from('${table}').update(fields).eq('id', invoiceId).select('id');
+        if (result.error) throw new Error(result.error.message);
+        if (!result.data || result.data.length === 0) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+      }
       written = fields;
-      return fields;
+      return { firstPdf: firstPdf };
     });
     if (previousIds.length > 0) {
       var removed = await client.from('${itemsTable}').delete().in('id', previousIds);
       if (removed.error) throw new Error(removed.error.message);
     }
-    return record;
+    return outcome;
   } catch (err) {
     if (written) {
       var restored = {};
@@ -624,12 +670,17 @@ async function replaceInvoice(invoiceId, invoiceData, items) {
       var setClauses = columns.map(function(k) { return quoteIdent(k) + ' = ?'; }).join(', ');
       var values = columns.map(function(k) { return fields[k]; });
       values.push(invoiceId);
-      var [updated] = await conn.execute('UPDATE ${table} SET ' + setClauses + ' WHERE id = ?', values);
-      if (!updated || !updated.affectedRows) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+      var update = 'UPDATE ${table} SET ' + setClauses + ' WHERE id = ?';
+      var [first] = await conn.execute(update + ' AND pdf_size_bytes IS NULL', values);
+      var firstPdf = !!(first && first.affectedRows > 0);
+      if (!firstPdf) {
+        var [updated] = await conn.execute(update, values);
+        if (!updated || !updated.affectedRows) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+      }
       await conn.execute('DELETE FROM ${itemsTable} WHERE invoice_id = ?', [invoiceId]);
       await insertInvoiceItemRows(conn, invoiceId, items);
       await conn.commit();
-      return fields;
+      return { firstPdf: firstPdf };
     } catch (err) {
       try { await conn.rollback(); } catch (_rollbackErr) {}
       throw err;
@@ -653,12 +704,16 @@ async function replaceInvoice(invoiceId, invoiceData, items) {
       values.push(invoiceId);
       // The UPDATE takes the row lock first, so two regenerations of the same
       // invoice run one after the other instead of interleaving their lines.
-      var updated = await client.query('UPDATE ${table} SET ' + setClauses + ' WHERE id = $' + values.length, values);
-      if (!updated.rowCount) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+      var update = 'UPDATE ${table} SET ' + setClauses + ' WHERE id = $' + values.length;
+      var firstPdf = (await client.query(update + ' AND pdf_size_bytes IS NULL', values)).rowCount > 0;
+      if (!firstPdf) {
+        var updated = await client.query(update, values);
+        if (!updated.rowCount) throw new Error('Invoice ' + invoiceId + ' no longer exists');
+      }
       await client.query('DELETE FROM ${itemsTable} WHERE invoice_id = $1', [invoiceId]);
       await insertInvoiceItemRows(client, invoiceId, items);
       await client.query('COMMIT');
-      return fields;
+      return { firstPdf: firstPdf };
     } catch (err) {
       try { await client.query('ROLLBACK'); } catch (_rollbackErr) {}
       throw err;
@@ -719,6 +774,69 @@ async function linkOrderToInvoice(orderId, invoiceId, invoiceNumber, pdfUrl) {
 }`
 }
 
+// One line of an order's history: a row of the activity log the editor
+// provisions (`teleport_events`) and both order timelines read. Written like
+// every line the store's workflows write — teleport-gui's
+// `constants/order-event-types.ts` owns the vocabulary — so a replay collides
+// on the UNIQUE `dedupe_key` and adds nothing. `event` is
+// `{ type, dedupeKey, orderId, payload, actor, actorType }`.
+function generateRecordOrderEventCode(dsType: string): string {
+  const row = `
+var ORDER_EVENTS_TABLE = 'teleport_events';
+var ORDER_EVENT_DEDUPE_KEY_MAX_LENGTH = 255;
+
+function orderEventRow(event) {
+  return {
+    id: require('crypto').randomUUID(),
+    event_type: event.type,
+    dedupe_key: String(event.dedupeKey).slice(0, ORDER_EVENT_DEDUPE_KEY_MAX_LENGTH),
+    order_id: event.orderId || null,
+    payload: JSON.stringify(event.payload || {}),
+    actor: event.actor || '',
+    actor_type: event.actorType,
+    // Logged; a dispatcher claims the rows it delivers itself.
+    status: 'recorded',
+  };
+}`
+
+  if (dsType === 'supabase') {
+    return `${row}
+
+async function recordOrderEvent(event) {
+  var result = await getClient()
+    .from(ORDER_EVENTS_TABLE)
+    .upsert(orderEventRow(event), { onConflict: 'dedupe_key', ignoreDuplicates: true });
+  if (result.error) throw new Error(result.error.message);
+}`
+  }
+
+  if (dsType === 'mysql' || dsType === 'mariadb' || dsType === 'tidb') {
+    return `${row}
+
+async function recordOrderEvent(event) {
+  var record = orderEventRow(event);
+  var columns = Object.keys(record);
+  var placeholders = columns.map(function() { return '?'; }).join(', ');
+  await getClient().execute(
+    'INSERT INTO ' + ORDER_EVENTS_TABLE + ' (' + columns.join(', ') + ') VALUES (' + placeholders + ') ON DUPLICATE KEY UPDATE dedupe_key = dedupe_key',
+    columns.map(function(k) { return record[k]; })
+  );
+}`
+  }
+
+  return `${row}
+
+async function recordOrderEvent(event) {
+  var record = orderEventRow(event);
+  var columns = Object.keys(record);
+  var placeholders = columns.map(function(_, i) { return '$' + (i + 1); }).join(', ');
+  await getClient().query(
+    'INSERT INTO ' + ORDER_EVENTS_TABLE + ' (' + columns.join(', ') + ') VALUES (' + placeholders + ') ON CONFLICT (dedupe_key) DO NOTHING',
+    columns.map(function(k) { return record[k]; })
+  );
+}`
+}
+
 export const getRecordMappingCode = (dsType?: string): string => `
 function mapInvoiceToRecord(data) {
   return {

package/src/invoice/email-sender-code.ts

@@ -1,4 +1,5 @@
 import { UIDLInvoiceEmailDelivery } from '@teleporthq/teleport-types'
+import { EmailSender } from '@teleporthq/teleport-shared'
 
 export const generateEmailSenderCode = (emailDelivery: UIDLInvoiceEmailDelivery): string => {
   if (!emailDelivery || !emailDelivery.enabled || !emailDelivery.provider) {
@@ -33,6 +34,8 @@ var BODY_TEMPLATE = ${JSON.stringify(bodyTemplate)};
 // Per-language copies of the subject/body (main language excluded), chosen by
 // the locale the generate route resolved for the invoice (the order's).
 var LOCALIZED_TEMPLATES = ${JSON.stringify(localizedTemplates)};
+${EmailSender.generateEmailSenderHelperCode()}
+var SENDER = __emailSender(${JSON.stringify({ from: fromEmail, name: fromName })});
 
 function resolveSecretKey(keyName) {
   var envName = SECRET_KEYS[keyName];
@@ -52,7 +55,8 @@ function buildEmailData(invoiceData) {
     subject: replacePlaceholders(copy.subject, data),
     body: replacePlaceholders(copy.body, data),
     to: invoiceData.customerEmail || '',
-    from: ${JSON.stringify(fromName ? `${fromName} <${fromEmail}>` : fromEmail)},
+    from: SENDER.header,
+    sender: SENDER,
     templateData: data,
   };
 }
@@ -63,7 +67,9 @@ function attachmentName(invoiceData) {
 
 ${generateProviderSendFunction(emailDelivery.provider)}
 
-async function sendInvoiceEmail(invoiceData, pdfBuffer) {
+// sourceRef names the route that sent it in the ledger: the payment's
+// generate route unless the caller says otherwise.
+async function sendInvoiceEmail(invoiceData, pdfBuffer, sourceRef) {
   var emailData = buildEmailData(invoiceData);
   if (!emailData.to) return { success: false, error: 'No customer email provided' };
   var result;
@@ -77,6 +83,7 @@ async function sendInvoiceEmail(invoiceData, pdfBuffer) {
     audience: 'customer',
     to: emailData.to,
     from: emailData.from,
+    fromName: emailData.sender.name,
     subject: emailData.subject,
     html: emailData.body,
     payload: emailData.templateData,
@@ -91,7 +98,7 @@ async function sendInvoiceEmail(invoiceData, pdfBuffer) {
     status: result && result.success ? 'sent' : 'failed',
     error: result && !result.success ? result.error : null,
     source: 'invoice',
-    sourceRef: 'api/invoices/generate',
+    sourceRef: sourceRef || 'api/invoices/generate',
     orderId: invoiceData.orderId,
     referenceType: 'invoice',
     referenceId: invoiceData.id,
@@ -139,9 +146,12 @@ async function sendInvoiceEmailWithProvider(emailData, invoiceData, pdfBuffer) {
     var apiKey = resolveSecretKey('apiKey');
     if (!apiKey) return { success: false, error: 'SendGrid API key not configured' };
     sgMail.setApiKey(apiKey);
+    // SendGrid reads a "Name <email>" string's name verbatim, quotes included,
+    // so a named sender goes as its two parts.
+    var sender = emailData.sender;
     var msg = {
       to: emailData.to,
-      from: emailData.from,
+      from: sender.name ? { email: sender.email, name: sender.name } : sender.email,
       subject: emailData.subject,
       html: emailData.body,
       attachments: [{
@@ -217,26 +227,6 @@ async function sendInvoiceEmailWithProvider(emailData, invoiceData, pdfBuffer) {
 
     case 'mailersend':
       return `
-// Pulls "name" and "email" out of the RFC-5322-ish \`from\` string the
-// builder assembles. Three shapes in the wild:
-//   1. "Acme Billing <billing@acme.com>"  → name="Acme Billing",  email="billing@acme.com"
-//   2. "billing@acme.com"                  → name="",             email="billing@acme.com"
-//   3. ""                                   → {}, caller handles the fallback
-// The old implementation used naive \`.replace()\` chains that produced
-// \`name="billing@acme.com"\` in case (2) — MailerSend accepts that but the
-// email then appears in the recipient's client with itself as the sender
-// name, which is ugly. Kept as a pure helper (no fallbacks baked in) so
-// the caller decides what to do when a field is missing.
-function parseFromString(from) {
-  var str = String(from || '').trim();
-  if (!str) return { name: '', email: '' };
-  var m = /^(.*)<([^<>]+)>\\s*$/.exec(str);
-  if (m) {
-    return { name: m[1].trim(), email: m[2].trim() };
-  }
-  return { name: '', email: str };
-}
-
 async function sendInvoiceEmailWithProvider(emailData, invoiceData, pdfBuffer) {
   var invoiceNumber = invoiceData && invoiceData.invoiceNumber ? invoiceData.invoiceNumber : '(no number)';
   try {
@@ -256,7 +246,7 @@ async function sendInvoiceEmailWithProvider(emailData, invoiceData, pdfBuffer) {
 
     var mailerSend = new MailerSend({ apiKey: apiKey });
 
-    var parsedFrom = parseFromString(emailData.from);
+    var parsedFrom = emailData.sender;
     if (!parsedFrom.email) {
       console.error('[invoice-email][mailersend] skip — from address is empty (set invoiceSettings.emailDelivery.fromEmail)');
       return { success: false, error: 'Sender email not configured' };

package/src/invoice/index.ts

@@ -157,7 +157,7 @@ export const generateInvoiceFiles = (
       {
         name: 'regenerate',
         fileType: FileType.JS,
-        content: generateInvoiceRegenerateRouteCode(),
+        content: generateInvoiceRegenerateRouteCode(invoiceSettings),
       },
     ],
   })