@aglyn/plugins-commerce 1.0.0-beta.290 → 1.0.0-beta.292

package/src/lib/server/quote-email.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/quote-email.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { siteContactEmail, resolveHostToken, type HostTokenSource } from '@aglyn/aglyn/app-utils/host-tokens'\nimport { resolveBrandingProfile } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport {\n  emailThreadAfterSend,\n  isEmailConfigured,\n  mintEmailMessageId,\n  nextThreadHeaders,\n  PLATFORM_EMAIL_PALETTE,\n  readEmailThread,\n  resolveEmailColor,\n  sendEmail,\n  type EmailTheme,\n  type RenderedHostEmail,\n  type SendEmailOptions,\n  type SendEmailResult,\n  type SendingIdentityVerdict,\n} from '@aglyn/shared-util-email'\nimport {\n  firebaseAdmin,\n  hostSendingIdentity,\n  meterHostEmail,\n  renderHostEmailWithTokens,\n  siteEmailFrame,\n  transactionalAddressSuppression,\n} from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\nimport { QUOTE_EMAIL_KEY, quoteEmailContent, type QuoteEmailColors } from '../utils/quote-email-content'\nimport type { quotePdfFile } from './commerce-pdf'\nimport type { CommercePdfFile } from './pdf-response'\n\n/*==========================================\n * SENDING THE QUOTE EMAIL (AGL-4097). Loaded only by the console's Send\n * quote (`POST commerce/quote { action: 'send' }`), so the renderer, the PDF\n * writer and sharp stay out of every other request.\n *\n * One email, the `quote-sent` catalog key in the site's theme and its header\n * and footer (or the site's own design of it), with the quote's PDF attached:\n *\n *   - FROM the site's sending identity, under the site's name;\n *   - REPLY-TO the site's contact email (its listing's, else its support\n *     email), else the email of the person sending, so a reply reaches the\n *     business either way, as an inbox reply's does;\n *   - IN THE CUSTOMER'S CONVERSATION: a `Message-ID` minted on the sending\n *     domain, and, when the quote already has a conversation (an earlier\n *     send, or a request's confirmation), `In-Reply-To` and `References`\n *     from it, else the root of the one it starts in `References`\n *     (`nextThreadHeaders`). The provider's own id is returned beside ours,\n *     because a provider may replace a caller's `Message-ID` (in production\n *     one does), and a replaced one can then be traced;\n *   - METERED as a site's transactional email;\n *   - REFUSED only for an address that bounced for good or reported mail as\n *     spam (`transactionalAddressSuppression`): the customer asked for the\n *     quote, so an unsubscribe from the site's newsletter does not stop it,\n *     as it does not stop a receipt (AGL-4098).\n *\n * The route decides everything about the quote (who may send, the link, the\n * stage); this module only says the email and sends it.\n *=========================================*/\n\n/** What the route hands over for one send. */\nexport interface QuoteDeliveryInput {\n  hostId: string\n  quoteId: string\n  /** The quote as it stands, after any pay link replacement this send made. */\n  order: CommerceModel.HostOrder\n  host: Record<string, unknown>\n  store: Record<string, unknown> | null\n  owner: { id?: string; org?: unknown } | null\n  to: string\n  /** The subject as typed; empty takes the default. */\n  subject: string\n  message: string\n  payUrl: string\n  proofUrl: (proofId: string) => string | null\n  linkReplaced: boolean\n  /** The sending member's email: the Reply-To when the site has no contact email. */\n  senderEmail: string | null\n  atMs: number\n}\n\nexport type QuoteDeliveryResult =\n  | {\n      sent: true\n      messageId: string\n      providerId: string | null\n      subject: string\n      replyTo: string | null\n      thread: CommerceModel.QuoteEmailThread\n    }\n  | { sent: false; status: number; error: string }\n\n/** The calls the send makes, injectable for specs. */\nexport interface QuoteMailerDeps {\n  configured(): boolean\n  sendingIdentity(hostId: string): Promise<SendingIdentityVerdict>\n  render(hostId: string, key: string, tokens: Record<string, string>): Promise<RenderedHostEmail | null>\n  /** The site's email theme, for the colors the composed proof markup draws with. */\n  theme(hostId: string): Promise<EmailTheme | null>\n  /** The quote's PDF; loads the PDF writer and sharp only here. */\n  quotePdf(input: Parameters<typeof quotePdfFile>[0]): Promise<CommercePdfFile>\n  send(options: SendEmailOptions): Promise<SendEmailResult>\n  meter(hostId: string): Promise<void>\n  /** The bounce and complaint list only: a quote is mail the customer asked for. */\n  suppression(email: string): Promise<'suppressed-platform' | null>\n}\n\nexport function defaultQuoteMailerDeps(): QuoteMailerDeps {\n  const firestore = () => firebaseAdmin.app().firestore()\n  return {\n    configured: () => isEmailConfigured(),\n    sendingIdentity: (hostId) => hostSendingIdentity(hostId),\n    render: (hostId, key, tokens) => renderHostEmailWithTokens(firestore(), hostId, key, tokens),\n    theme: async (hostId) => (await siteEmailFrame(firestore(), hostId, QUOTE_EMAIL_KEY)).theme,\n    quotePdf: async (input) => (await import('./commerce-pdf')).quotePdfFile(input),\n    send: (options) => sendEmail(options),\n    meter: async (hostId) => {\n      await meterHostEmail(hostId)\n    },\n    suppression: (email) => transactionalAddressSuppression(email),\n  }\n}\n\n/** What the console's Send quote reaches: whether mail can go, whether this address may be mailed, and the send. */\nexport interface QuoteMailer {\n  configured(): boolean\n  suppression(email: string): Promise<'suppressed-platform' | null>\n  deliver(input: QuoteDeliveryInput): Promise<QuoteDeliveryResult>\n}\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\n/** The business's name as its documents print it. */\nexport function quoteBusinessName(host: Record<string, unknown>): string {\n  const named = resolveHostToken('businessName', host as HostTokenSource)\n  return String(named ?? '').trim() || String(host['name'] ?? '').trim()\n}\n\n/**\n * Who a reply reaches: the site's contact email, else the person sending, as\n * an inbox reply answers to them. Null only when neither is an address.\n */\nexport function quoteReplyTo(host: Record<string, unknown>, senderEmail: string | null | undefined): string | null {\n  const contact = siteContactEmail(host as never)\n  if (contact && EMAIL.test(contact)) return contact\n  const sender = String(senderEmail ?? '').trim()\n  return EMAIL.test(sender) ? sender : null\n}\n\n/** The theme's colors for the composed proof markup, the platform's where the site's cannot answer. */\nfunction proofColors(theme: EmailTheme | null): QuoteEmailColors {\n  const read = (token: string) =>\n    resolveEmailColor(token, theme?.palette) ?? resolveEmailColor(token, PLATFORM_EMAIL_PALETTE) ?? 'inherit'\n  return { border: read('divider'), muted: read('text.secondary') }\n}\n\n/** A refused send in the words the console shows. */\nfunction refusalOf(result: Extract<SendEmailResult, { sent: false }>): { status: number; error: string } {\n  switch (result.reason) {\n    case 'unconfigured':\n      return { status: 503, error: 'Email isn’t set up here, so the quote wasn’t sent.' }\n    case 'rate-limited':\n      return { status: 429, error: 'Too many emails are going out right now. Try again in a minute.' }\n    case 'suppressed':\n    case 'undeliverable':\n      return { status: 409, error: 'This address can’t receive email, so the quote wasn’t sent. Copy the pay link and send it another way.' }\n    case 'unverified-domain':\n      return { status: 409, error: 'This site’s sending domain isn’t verified, so the quote wasn’t sent. Check Email settings.' }\n    case 'suspended':\n      return { status: 423, error: 'This site can’t send email right now, so the quote wasn’t sent.' }\n    case 'held-for-review':\n      return { status: 409, error: `The email was held for review, so it hasn’t gone out yet.${result.detail ? ` ${result.detail}` : ''}` }\n    default:\n      return { status: 502, error: 'The quote email could not be sent. Try again.' }\n  }\n}\n\n/** The quote email, said and sent. */\nexport function quoteMailer(deps: QuoteMailerDeps = defaultQuoteMailerDeps()): QuoteMailer {\n  return {\n    configured: () => deps.configured(),\n    suppression: (email) => deps.suppression(email),\n    deliver: async (input) => {\n      const { hostId, quoteId, order, host } = input\n      const businessName = quoteBusinessName(host)\n      const subject = input.subject || CommerceModel.quoteEmailDefaultSubject(order, businessName, quoteId)\n      const [identity, theme] = await Promise.all([\n        deps.sendingIdentity(hostId),\n        deps.theme(hostId).catch(() => null),\n      ])\n\n      const content = quoteEmailContent({\n        order,\n        quoteId,\n        businessName,\n        currency: String(input.store?.['currency'] ?? 'USD'),\n        subject,\n        message: input.message,\n        payUrl: input.payUrl,\n        proofUrl: input.proofUrl,\n        linkReplaced: input.linkReplaced,\n        colors: proofColors(theme),\n        radius: theme?.buttonRadius,\n      })\n\n      // The PDF is what the email says is attached; without it nothing goes.\n      let pdf: CommercePdfFile\n      try {\n        pdf = await deps.quotePdf({\n          hostId,\n          quoteId,\n          order,\n          host,\n          store: input.store,\n          owner: input.owner,\n          payUrl: input.payUrl,\n        })\n      } catch (error) {\n        console.error('[commerce/quote-email] the PDF could not be made', { hostId, quoteId, error })\n        return { sent: false, status: 500, error: 'The quote’s PDF could not be made, so nothing was sent. Try again.' }\n      }\n\n      const rendered = await deps.render(hostId, QUOTE_EMAIL_KEY, content.tokens)\n      const thread = readEmailThread(order.quote?.emailThread)\n      const siteHost = String(host['cname'] ?? '').trim() || null\n      const messageId = mintEmailMessageId([identity?.domain, identity?.from, siteHost], {\n        label: 'quote',\n        atMs: input.atMs,\n      })\n      const replyTo = quoteReplyTo(host, input.senderEmail)\n\n      const result = await deps.send({\n        to: input.to,\n        // The subject as sent, whatever a design's own says: it is what keeps\n        // the conversation together, and it was typed for this send.\n        subject,\n        text: rendered?.text || content.text,\n        ...(rendered?.html ? { html: rendered.html } : {}),\n        headers: nextThreadHeaders(thread, messageId),\n        ...(replyTo ? { replyTo } : {}),\n        fromName: resolveBrandingProfile(input.owner?.org as never).fromName,\n        sendingIdentity: identity,\n        audience: 'tenant',\n        context: 'quote',\n        attachments: [\n          {\n            filename: pdf.filename,\n            contentType: 'application/pdf',\n            content: Buffer.from(pdf.bytes).toString('base64'),\n          },\n        ],\n      })\n      if (!result.sent) return { sent: false, ...refusalOf(result as Extract<SendEmailResult, { sent: false }>) }\n      // Cost meter (AGL-1438), as every transactional site email.\n      await deps.meter(hostId).catch((error) => console.error('[commerce/quote-email] not metered', error))\n      return {\n        sent: true,\n        messageId,\n        providerId: (result as Extract<SendEmailResult, { sent: true }>).id ?? null,\n        subject,\n        replyTo,\n        thread: emailThreadAfterSend(thread, { messageId, subject }),\n      }\n    },\n  }\n}\n"],"names":["siteContactEmail","resolveHostToken","resolveBrandingProfile","emailThreadAfterSend","isEmailConfigured","mintEmailMessageId","nextThreadHeaders","PLATFORM_EMAIL_PALETTE","readEmailThread","resolveEmailColor","sendEmail","firebaseAdmin","hostSendingIdentity","meterHostEmail","renderHostEmailWithTokens","siteEmailFrame","transactionalAddressSuppression","CommerceModel","QUOTE_EMAIL_KEY","quoteEmailContent","defaultQuoteMailerDeps","firestore","app","configured","sendingIdentity","hostId","render","key","tokens","theme","quotePdf","input","quotePdfFile","send","options","meter","suppression","email","EMAIL","quoteBusinessName","host","named","String","trim","quoteReplyTo","senderEmail","contact","test","sender","proofColors","read","token","palette","border","muted","refusalOf","result","reason","status","error","detail","quoteMailer","deps","deliver","order","quoteId","businessName","subject","quoteEmailDefaultSubject","identity","Promise","all","catch","content","currency","store","message","payUrl","proofUrl","linkReplaced","colors","radius","buttonRadius","pdf","owner","console","sent","rendered","thread","quote","emailThread","siteHost","messageId","domain","from","label","atMs","replyTo","to","text","html","headers","fromName","org","audience","context","attachments","filename","contentType","Buffer","bytes","toString","providerId","id"],"mappings":"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"}

package/src/lib/server/quote-link-token.d.ts

@@ -37,3 +37,14 @@ export declare function quotePayLinkUrl(host: {
     cname?: unknown;
     subdomain?: unknown;
 } | null | undefined, hostId: string, quoteId: string, version: number): string | null;
+/**
+ * The absolute address of one of the current revision's proofs, behind the
+ * same signed link as the page (`GET /api/commerce/quote-proof`, AGL-4096),
+ * or null when the site has no public address or no signing secret. What the
+ * quote email draws a proof image from (AGL-4097); a link the business
+ * replaces stops serving it, with the page.
+ */
+export declare function quoteProofLinkUrl(host: {
+    cname?: unknown;
+    subdomain?: unknown;
+} | null | undefined, hostId: string, quoteId: string, version: number, proofId: string): string | null;

package/src/lib/server/quote-link-token.js

@@ -93,5 +93,26 @@ function signQuoteLink(hostId, quoteId, version) {
     if (!origin || !token) return null;
     return `${origin}${quotePageHref(quoteId, token)}`;
 }
+/**
+ * The absolute address of one of the current revision's proofs, behind the
+ * same signed link as the page (`GET /api/commerce/quote-proof`, AGL-4096),
+ * or null when the site has no public address or no signing secret. What the
+ * quote email draws a proof image from (AGL-4097); a link the business
+ * replaces stops serving it, with the page.
+ */ export function quoteProofLinkUrl(host, hostId, quoteId, version, proofId) {
+    const origin = hostPublicOrigin({
+        cname: typeof (host == null ? void 0 : host.cname) === 'string' ? host.cname : null,
+        subdomain: typeof (host == null ? void 0 : host.subdomain) === 'string' ? host.subdomain : null
+    });
+    const token = mintQuoteLinkToken(hostId, quoteId, version);
+    if (!origin || !token || !proofId) return null;
+    const query = new URLSearchParams({
+        hostId,
+        q: quoteId,
+        t: token,
+        file: proofId
+    });
+    return `${origin}/api/commerce/quote-proof?${query.toString()}`;
+}
 
 //# sourceMappingURL=quote-link-token.js.map

package/src/lib/server/quote-link-token.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/quote-link-token.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { hostPublicOrigin } from '@aglyn/aglyn/server'\nimport { createHmac, timingSafeEqual } from 'crypto'\nimport { quotePageHref } from '../constants/quote-page'\nimport { tokenSigningSecret } from './download'\n\n/**\n * A quote's pay link (AGL-4094): `/pay-quote?q=<quoteId>&t=<token>` on the\n * business's own site, where the customer sees the quote and pays it.\n *\n * The token is `<version>.<signature>`: the quote's link version\n * (`quote.linkVersion`, absent reading as 1) and the first 32 hex characters of\n * `HMAC(quote-link:hostId:quoteId:version)` under the commerce\n * `TOKEN_SIGNING_SECRET`. A pure function of what the quote already holds, so\n * nothing is stored per link and every message that carried the link carries\n * the same working one. The `quote-link:` prefix keeps it from being replayed\n * as an order-status, download or supplier token, which sign other payloads\n * under the same secret.\n *\n * NO EXPIRY. A quote is paid when the customer is ready, and a link that died\n * first would be a quote they could not pay. The version is what retires a\n * link: replacing it bumps the version on the quote, and a link signed for an\n * older version still verifies, so its page can say the quote was replaced,\n * without showing any of it.\n */\nconst SIGNATURE_LENGTH = 32\nconst MAX_VERSION = 1_000_000\n\nfunction signQuoteLink(hostId: string, quoteId: string, version: number): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`quote-link:${hostId}:${quoteId}:${version}`)\n    .digest('hex')\n    .slice(0, SIGNATURE_LENGTH)\n}\n\n/** The token's two halves, or null for a token not shaped like one. */\nexport function parseQuoteLinkToken(token: string): { version: number; signature: string } | null {\n  const match = /^([1-9]\\d{0,6})\\.([0-9a-f]{32})$/.exec(String(token ?? ''))\n  if (!match) return null\n  const version = Number(match[1])\n  if (!Number.isSafeInteger(version) || version > MAX_VERSION) return null\n  return { version, signature: match[2] }\n}\n\n/** The token for one version of a quote's link, or null when the signing secret is unset. */\nexport function mintQuoteLinkToken(hostId: string, quoteId: string, version: number): string | null {\n  if (!hostId || !quoteId || !Number.isSafeInteger(version) || version < 1 || version > MAX_VERSION) {\n    return null\n  }\n  try {\n    return `${version}.${signQuoteLink(hostId, quoteId, version)}`\n  } catch {\n    return null\n  }\n}\n\n/**\n * Checks a presented token in constant time and answers the link version it\n * was signed for, or null for a token that is wrong, malformed or unverifiable\n * (no secret). The caller compares the version with the quote's own.\n */\nexport function verifyQuoteLinkToken(hostId: string, quoteId: string, token: string): number | null {\n  if (!hostId || !quoteId) return null\n  const parsed = parseQuoteLinkToken(token)\n  if (!parsed) return null\n  let expected: string\n  try {\n    expected = signQuoteLink(hostId, quoteId, parsed.version)\n  } catch {\n    return null\n  }\n  const a = Buffer.from(parsed.signature)\n  const b = Buffer.from(expected)\n  if (a.length !== b.length) return null\n  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b)) ? parsed.version : null\n}\n\n/**\n * The absolute pay link for a quote at a link version, or null when either\n * half is missing: a site with no public address, or no signing secret. What\n * the console copies, and what a quote or invoice email puts in front of the\n * customer.\n */\nexport function quotePayLinkUrl(\n  host: { cname?: unknown; subdomain?: unknown } | null | undefined,\n  hostId: string,\n  quoteId: string,\n  version: number,\n): string | null {\n  const origin = hostPublicOrigin({\n    cname: typeof host?.cname === 'string' ? host.cname : null,\n    subdomain: typeof host?.subdomain === 'string' ? host.subdomain : null,\n  })\n  const token = mintQuoteLinkToken(hostId, quoteId, version)\n  if (!origin || !token) return null\n  return `${origin}${quotePageHref(quoteId, token)}`\n}\n"],"names":["hostPublicOrigin","createHmac","timingSafeEqual","quotePageHref","tokenSigningSecret","SIGNATURE_LENGTH","MAX_VERSION","signQuoteLink","hostId","quoteId","version","update","digest","slice","parseQuoteLinkToken","token","match","exec","String","Number","isSafeInteger","signature","mintQuoteLinkToken","verifyQuoteLinkToken","parsed","expected","a","Buffer","from","b","length","Uint8Array","quotePayLinkUrl","host","origin","cname","subdomain"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,sBAAqB;AACtD,SAASC,UAAU,EAAEC,eAAe,QAAQ,SAAQ;AACpD,SAASC,aAAa,QAAQ,6BAAyB;AACvD,SAASC,kBAAkB,QAAQ,gBAAY;AAE/C;;;;;;;;;;;;;;;;;;CAkBC,GACD,MAAMC,mBAAmB;AACzB,MAAMC,cAAc;AAEpB,SAASC,cAAcC,MAAc,EAAEC,OAAe,EAAEC,OAAe;IACrE,OAAOT,WAAW,UAAUG,sBACzBO,MAAM,CAAC,CAAC,WAAW,EAAEH,OAAO,CAAC,EAAEC,QAAQ,CAAC,EAAEC,SAAS,EACnDE,MAAM,CAAC,OACPC,KAAK,CAAC,GAAGR;AACd;AAEA,qEAAqE,GACrE,OAAO,SAASS,oBAAoBC,KAAa;IAC/C,MAAMC,QAAQ,mCAAmCC,IAAI,CAACC,OAAOH,gBAAAA,QAAS;IACtE,IAAI,CAACC,OAAO,OAAO;IACnB,MAAMN,UAAUS,OAAOH,KAAK,CAAC,EAAE;IAC/B,IAAI,CAACG,OAAOC,aAAa,CAACV,YAAYA,UAAUJ,aAAa,OAAO;IACpE,OAAO;QAAEI;QAASW,WAAWL,KAAK,CAAC,EAAE;IAAC;AACxC;AAEA,2FAA2F,GAC3F,OAAO,SAASM,mBAAmBd,MAAc,EAAEC,OAAe,EAAEC,OAAe;IACjF,IAAI,CAACF,UAAU,CAACC,WAAW,CAACU,OAAOC,aAAa,CAACV,YAAYA,UAAU,KAAKA,UAAUJ,aAAa;QACjG,OAAO;IACT;IACA,IAAI;QACF,OAAO,GAAGI,QAAQ,CAAC,EAAEH,cAAcC,QAAQC,SAASC,UAAU;IAChE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASa,qBAAqBf,MAAc,EAAEC,OAAe,EAAEM,KAAa;IACjF,IAAI,CAACP,UAAU,CAACC,SAAS,OAAO;IAChC,MAAMe,SAASV,oBAAoBC;IACnC,IAAI,CAACS,QAAQ,OAAO;IACpB,IAAIC;IACJ,IAAI;QACFA,WAAWlB,cAAcC,QAAQC,SAASe,OAAOd,OAAO;IAC1D,EAAE,eAAM;QACN,OAAO;IACT;IACA,MAAMgB,IAAIC,OAAOC,IAAI,CAACJ,OAAOH,SAAS;IACtC,MAAMQ,IAAIF,OAAOC,IAAI,CAACH;IACtB,IAAIC,EAAEI,MAAM,KAAKD,EAAEC,MAAM,EAAE,OAAO;IAClC,OAAO5B,gBAAgB,IAAI6B,WAAWL,IAAI,IAAIK,WAAWF,MAAML,OAAOd,OAAO,GAAG;AAClF;AAEA;;;;;CAKC,GACD,OAAO,SAASsB,gBACdC,IAAiE,EACjEzB,MAAc,EACdC,OAAe,EACfC,OAAe;IAEf,MAAMwB,SAASlC,iBAAiB;QAC9BmC,OAAO,QAAOF,wBAAAA,KAAME,KAAK,MAAK,WAAWF,KAAKE,KAAK,GAAG;QACtDC,WAAW,QAAOH,wBAAAA,KAAMG,SAAS,MAAK,WAAWH,KAAKG,SAAS,GAAG;IACpE;IACA,MAAMrB,QAAQO,mBAAmBd,QAAQC,SAASC;IAClD,IAAI,CAACwB,UAAU,CAACnB,OAAO,OAAO;IAC9B,OAAO,GAAGmB,SAAS/B,cAAcM,SAASM,QAAQ;AACpD"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/quote-link-token.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { hostPublicOrigin } from '@aglyn/aglyn/server'\nimport { createHmac, timingSafeEqual } from 'crypto'\nimport { quotePageHref } from '../constants/quote-page'\nimport { tokenSigningSecret } from './download'\n\n/**\n * A quote's pay link (AGL-4094): `/pay-quote?q=<quoteId>&t=<token>` on the\n * business's own site, where the customer sees the quote and pays it.\n *\n * The token is `<version>.<signature>`: the quote's link version\n * (`quote.linkVersion`, absent reading as 1) and the first 32 hex characters of\n * `HMAC(quote-link:hostId:quoteId:version)` under the commerce\n * `TOKEN_SIGNING_SECRET`. A pure function of what the quote already holds, so\n * nothing is stored per link and every message that carried the link carries\n * the same working one. The `quote-link:` prefix keeps it from being replayed\n * as an order-status, download or supplier token, which sign other payloads\n * under the same secret.\n *\n * NO EXPIRY. A quote is paid when the customer is ready, and a link that died\n * first would be a quote they could not pay. The version is what retires a\n * link: replacing it bumps the version on the quote, and a link signed for an\n * older version still verifies, so its page can say the quote was replaced,\n * without showing any of it.\n */\nconst SIGNATURE_LENGTH = 32\nconst MAX_VERSION = 1_000_000\n\nfunction signQuoteLink(hostId: string, quoteId: string, version: number): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`quote-link:${hostId}:${quoteId}:${version}`)\n    .digest('hex')\n    .slice(0, SIGNATURE_LENGTH)\n}\n\n/** The token's two halves, or null for a token not shaped like one. */\nexport function parseQuoteLinkToken(token: string): { version: number; signature: string } | null {\n  const match = /^([1-9]\\d{0,6})\\.([0-9a-f]{32})$/.exec(String(token ?? ''))\n  if (!match) return null\n  const version = Number(match[1])\n  if (!Number.isSafeInteger(version) || version > MAX_VERSION) return null\n  return { version, signature: match[2] }\n}\n\n/** The token for one version of a quote's link, or null when the signing secret is unset. */\nexport function mintQuoteLinkToken(hostId: string, quoteId: string, version: number): string | null {\n  if (!hostId || !quoteId || !Number.isSafeInteger(version) || version < 1 || version > MAX_VERSION) {\n    return null\n  }\n  try {\n    return `${version}.${signQuoteLink(hostId, quoteId, version)}`\n  } catch {\n    return null\n  }\n}\n\n/**\n * Checks a presented token in constant time and answers the link version it\n * was signed for, or null for a token that is wrong, malformed or unverifiable\n * (no secret). The caller compares the version with the quote's own.\n */\nexport function verifyQuoteLinkToken(hostId: string, quoteId: string, token: string): number | null {\n  if (!hostId || !quoteId) return null\n  const parsed = parseQuoteLinkToken(token)\n  if (!parsed) return null\n  let expected: string\n  try {\n    expected = signQuoteLink(hostId, quoteId, parsed.version)\n  } catch {\n    return null\n  }\n  const a = Buffer.from(parsed.signature)\n  const b = Buffer.from(expected)\n  if (a.length !== b.length) return null\n  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b)) ? parsed.version : null\n}\n\n/**\n * The absolute pay link for a quote at a link version, or null when either\n * half is missing: a site with no public address, or no signing secret. What\n * the console copies, and what a quote or invoice email puts in front of the\n * customer.\n */\nexport function quotePayLinkUrl(\n  host: { cname?: unknown; subdomain?: unknown } | null | undefined,\n  hostId: string,\n  quoteId: string,\n  version: number,\n): string | null {\n  const origin = hostPublicOrigin({\n    cname: typeof host?.cname === 'string' ? host.cname : null,\n    subdomain: typeof host?.subdomain === 'string' ? host.subdomain : null,\n  })\n  const token = mintQuoteLinkToken(hostId, quoteId, version)\n  if (!origin || !token) return null\n  return `${origin}${quotePageHref(quoteId, token)}`\n}\n\n/**\n * The absolute address of one of the current revision's proofs, behind the\n * same signed link as the page (`GET /api/commerce/quote-proof`, AGL-4096),\n * or null when the site has no public address or no signing secret. What the\n * quote email draws a proof image from (AGL-4097); a link the business\n * replaces stops serving it, with the page.\n */\nexport function quoteProofLinkUrl(\n  host: { cname?: unknown; subdomain?: unknown } | null | undefined,\n  hostId: string,\n  quoteId: string,\n  version: number,\n  proofId: string,\n): string | null {\n  const origin = hostPublicOrigin({\n    cname: typeof host?.cname === 'string' ? host.cname : null,\n    subdomain: typeof host?.subdomain === 'string' ? host.subdomain : null,\n  })\n  const token = mintQuoteLinkToken(hostId, quoteId, version)\n  if (!origin || !token || !proofId) return null\n  const query = new URLSearchParams({ hostId, q: quoteId, t: token, file: proofId })\n  return `${origin}/api/commerce/quote-proof?${query.toString()}`\n}\n"],"names":["hostPublicOrigin","createHmac","timingSafeEqual","quotePageHref","tokenSigningSecret","SIGNATURE_LENGTH","MAX_VERSION","signQuoteLink","hostId","quoteId","version","update","digest","slice","parseQuoteLinkToken","token","match","exec","String","Number","isSafeInteger","signature","mintQuoteLinkToken","verifyQuoteLinkToken","parsed","expected","a","Buffer","from","b","length","Uint8Array","quotePayLinkUrl","host","origin","cname","subdomain","quoteProofLinkUrl","proofId","query","URLSearchParams","q","t","file","toString"],"mappings":"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"}

package/src/lib/server/quote-pay.d.ts

@@ -69,12 +69,17 @@ export interface LoadedQuote {
     order: CommerceModel.HostOrder;
     storeName: string;
     store: FirebaseFirestore.DocumentSnapshot;
+    /** A quote, or an order's invoice (only for a route that opens invoices). */
+    kind: CommerceModel.OrderPayLinkKind;
 }
 /**
  * The quote a link names, after its token: the quote, the replaced answer for
  * a link to an older version, or the one not-found answer for everything else.
+ * With `invoices`, a draft order's invoice too (AGL-4099).
  */
-export declare function loadLinkedQuote(deps: QuotePayDeps, hostId: string, quoteId: string, token: string): Promise<{
+export declare function loadLinkedQuote(deps: QuotePayDeps, hostId: string, quoteId: string, token: string, options?: {
+    invoices?: boolean;
+}): Promise<{
     loaded: LoadedQuote;
 } | {
     outcome: QuoteLinkOutcome;
@@ -88,12 +93,12 @@ export declare function quoteLinkParams(source: Record<string, unknown>): {
 };
 /** `GET /api/commerce/quote-view`: the quote page's data. */
 export declare function handleQuoteView(deps: QuotePayDeps, req: PluginApiRequest): Promise<QuoteLinkOutcome>;
-/** The Checkout Session a quote's Pay opens, as form params. Pure over its inputs. */
+/** The Checkout Session a quote's (or an invoice's) Pay opens, as form params. Pure over its inputs. */
 export declare function buildQuoteSessionParams(input: {
     hostId: string;
     quoteId: string;
     order: CommerceModel.HostOrder;
-    charge: CommerceModel.QuoteCheckoutCharge;
+    charge: CommerceModel.QuoteCheckoutCharge & Partial<Pick<CommerceModel.InvoiceCheckoutCharge, 'shippingOptions' | 'shippingCountries'>>;
     accountId: string;
     feeCents: number;
     taxRateId: string;

package/src/lib/server/quote-pay.js

@@ -30,7 +30,8 @@ import { orderStatusUrl } from "./order-status-token.js";
 import { ensureCheckoutDomain } from "./payment-method-domains.js";
 import { verifyQuoteLinkToken } from "./quote-link-token.js";
 /*==========================================
- * THE CUSTOMER'S QUOTE PAGE AND ITS PAY BUTTON (AGL-4094).
+ * THE CUSTOMER'S QUOTE PAGE AND ITS PAY BUTTON (AGL-4094), AND AN
+ * INVOICE'S (AGL-4099).
  *
  *   GET  /api/commerce/quote-view?hostId=&q=<quoteId>&t=<token>
  *        → 200 QuotePageView | 200 { state: 'replaced', storeName } | 404
@@ -53,6 +54,16 @@ import { verifyQuoteLinkToken } from "./quote-link-token.js";
  *
  * The payment completes in `billing-webhook.ts`, which turns this same
  * document into the order (`paidQuoteOrder`); nothing here marks it paid.
+ *
+ * AN INVOICE'S LINK IS THIS ONE (AGL-4099). A draft order the business sent
+ * an invoice for opens on the same page from the same kind of link (its
+ * version on `payLink.version`, `commerce-invoices.ts`), as "Invoice #N" with
+ * no proofs or approval, and Pay opens the same kind of fresh session from
+ * its stored lines, discount, tax and the shipping rates it was made with.
+ * Its webhook is the draft branch it always completed through, which flips
+ * the draft to paid without restamping its list fields. The proof and answer
+ * routes stay a quote's alone: `loadLinkedQuote` opens an invoice only for
+ * the routes that ask (`{ invoices: true }`).
  *=========================================*/ /** Lookups and presses one address may make per site, per ten minutes. */ export const QUOTE_VIEW_LOOKUPS_PER_WINDOW = 60;
 export const QUOTE_PAY_PRESSES_PER_WINDOW = 20;
 export const QUOTE_WINDOW_MS = 10 * 60000;
@@ -95,6 +106,13 @@ const NOT_FOUND = {
         error: 'We could not find that quote. Check the link you were sent.'
     }
 };
+/** The not-found answer of a route an invoice's link reaches too: it names neither. */ const NOT_FOUND_ANY = {
+    status: 404,
+    body: {
+        error: 'We could not find that quote or invoice. Check the link you were sent.'
+    }
+};
+/** `quote` or `invoice`, as the customer reads it. */ const nounOf = (kind)=>kind === 'invoice' ? 'invoice' : 'quote';
 function bodyOf(req) {
     const raw = req.body;
     if (typeof raw === 'string') {
@@ -137,11 +155,13 @@ function headerOf(req, name) {
 /**
  * The quote a link names, after its token: the quote, the replaced answer for
  * a link to an older version, or the one not-found answer for everything else.
- */ export async function loadLinkedQuote(deps, hostId, quoteId, token) {
+ * With `invoices`, a draft order's invoice too (AGL-4099).
+ */ export async function loadLinkedQuote(deps, hostId, quoteId, token, options = {}) {
     var _hostSnapshot_data, _resolveHostToken;
+    const notFound = options.invoices ? NOT_FOUND_ANY : NOT_FOUND;
     const version = verifyQuoteLinkToken(hostId, quoteId, token);
     if (version === null) return {
-        outcome: NOT_FOUND
+        outcome: notFound
     };
     const hostRef = deps.firestore().collection('hosts').doc(hostId);
     const [hostSnapshot, store, orderSnapshot] = await Promise.all([
@@ -150,17 +170,18 @@ function headerOf(req, name) {
         hostRef.collection('orders').doc(quoteId).get()
     ]);
     if (!hostSnapshot.exists || !orderSnapshot.exists) return {
-        outcome: NOT_FOUND
+        outcome: notFound
     };
     const order = orderSnapshot.data();
-    if (!CommerceModel.isQuote(order) || !order.quote) return {
-        outcome: NOT_FOUND
+    const kind = CommerceModel.orderPayLinkKind(order);
+    if (kind === null || kind === 'invoice' && !options.invoices) return {
+        outcome: notFound
     };
     const host = (_hostSnapshot_data = hostSnapshot.data()) != null ? _hostSnapshot_data : {};
     const storeName = String((_resolveHostToken = resolveHostToken('businessName', host)) != null ? _resolveHostToken : '');
-    const current = CommerceModel.quoteLinkVersion(order.quote);
+    const current = CommerceModel.orderPayLinkVersion(order);
     if (version > current) return {
-        outcome: NOT_FOUND
+        outcome: notFound
     };
     if (version < current) {
         return {
@@ -168,9 +189,10 @@ function headerOf(req, name) {
                 status: 410,
                 body: {
                     state: 'replaced',
+                    kind,
                     storeName,
                     replaced: true,
-                    error: `This quote was updated, and ${storeName || 'the business'} sent you a newer link.`
+                    error: `This ${nounOf(kind)} was updated, and ${storeName || 'the business'} sent you a newer link.`
                 }
             }
         };
@@ -181,7 +203,8 @@ function headerOf(req, name) {
             host,
             order,
             storeName,
-            store
+            store,
+            kind
         }
     };
 }
@@ -215,39 +238,51 @@ function headerOf(req, name) {
     };
     const refused = await limitedQuoteLink(deps, req, `commerce-quote-view:${hostId}`, QUOTE_VIEW_LOOKUPS_PER_WINDOW);
     if (refused) return refused;
-    const linked = await loadLinkedQuote(deps, hostId, quoteId, token);
+    const linked = await loadLinkedQuote(deps, hostId, quoteId, token, {
+        invoices: true
+    });
     if ('outcome' in linked) {
         // The replaced page is a page, not a failure: answered as data.
         if (linked.outcome.status === 410) {
-            const { storeName } = linked.outcome.body;
+            const { storeName, kind } = linked.outcome.body;
             return {
                 status: 200,
                 body: {
                     state: 'replaced',
+                    kind,
                     storeName
                 }
             };
         }
         return linked.outcome;
     }
-    const { host, order, storeName, store } = linked.loaded;
-    const view = CommerceModel.buildQuotePageView({
+    const { host, order, storeName, store, kind } = linked.loaded;
+    const currency = String((_store_get = store.get('currency')) != null ? _store_get : 'USD');
+    const receiptUrl = order.status === 'pending' ? null : orderStatusUrl(host, hostId, quoteId);
+    const view = kind === 'quote' ? CommerceModel.buildQuotePageView({
         order,
         orderId: quoteId,
         storeName,
-        currency: String((_store_get = store.get('currency')) != null ? _store_get : 'USD'),
-        receiptUrl: CommerceModel.isUnpaidQuote(order) ? null : orderStatusUrl(host, hostId, quoteId)
+        currency,
+        receiptUrl
+    }) : CommerceModel.buildInvoicePageView({
+        order,
+        orderId: quoteId,
+        storeName,
+        currency,
+        receiptUrl
     });
     return {
         status: 200,
         body: view
     };
 }
-/** The Checkout Session a quote's Pay opens, as form params. Pure over its inputs. */ export function buildQuoteSessionParams(input) {
-    var _ref;
+/** The Checkout Session a quote's (or an invoice's) Pay opens, as form params. Pure over its inputs. */ export function buildQuoteSessionParams(input) {
+    var _order_quote, _charge_shippingOptions, _ref;
     var _quote_customer;
     const { charge, order } = input;
-    const quote = order.quote;
+    const invoice = CommerceModel.orderPayLinkKind(order) === 'invoice';
+    const quote = (_order_quote = order.quote) != null ? _order_quote : {};
     const params = new URLSearchParams(_extends({
         mode: 'payment'
     }, checkoutSessionCardAuthenticationParams('payment'), charge.taxAtPayment ? {
@@ -267,7 +302,14 @@ function headerOf(req, name) {
     // Shipping the business priced for the quote's ship-to, charged as the one
     // option, with the address asked for where it ships (and where Stripe Tax
     // reads the tax from). The quote's own address stands when it asks nothing.
-    if (charge.shippingCents > 0) {
+    // An invoiced draft offers the rates it was made with, and the buyer picks
+    // one, as on the draft's first link (AGL-4099).
+    const rates = (_charge_shippingOptions = charge.shippingOptions) != null ? _charge_shippingOptions : [];
+    if (rates.length > 0) {
+        var _charge_shippingCountries;
+        CommerceModel.appendShippingAddressCollectionParams(params, ((_charge_shippingCountries = charge.shippingCountries) == null ? void 0 : _charge_shippingCountries.length) ? charge.shippingCountries : CommerceModel.CHECKOUT_SHIPPING_COUNTRIES);
+        CommerceModel.appendCheckoutShippingParams(params, rates);
+    } else if (charge.shippingCents > 0) {
         var _ref1;
         var _quote_shipTo;
         const country = String((_ref1 = (_quote_shipTo = quote.shipTo) == null ? void 0 : _quote_shipTo.country) != null ? _ref1 : '').toUpperCase();
@@ -282,7 +324,7 @@ function headerOf(req, name) {
             }
         ]);
     }
-    const shippingFloorCents = charge.shippingCents;
+    const shippingFloorCents = rates.length > 0 ? CommerceModel.shippingFloorCents(rates) : charge.shippingCents;
     for (const [key, value] of Object.entries(CommerceModel.destinationChargeParams({
         accountId: input.accountId,
         feeCents: input.feeCents,
@@ -292,7 +334,7 @@ function headerOf(req, name) {
     }))){
         params.set(key, value);
     }
-    const email = String((_ref = (_quote_customer = quote.customer) == null ? void 0 : _quote_customer.email) != null ? _ref : '').trim();
+    const email = String((_ref = invoice ? order.customerEmail : (_quote_customer = quote.customer) == null ? void 0 : _quote_customer.email) != null ? _ref : '').trim();
     if (email) params.set('customer_email', email);
     const separator = input.returnUrl.includes('?') ? '&' : '?';
     params.set('success_url', `${input.returnUrl}${separator}session_id={CHECKOUT_SESSION_ID}`);
@@ -303,9 +345,18 @@ function headerOf(req, name) {
     params.set('metadata[type]', 'commerce-draft');
     params.set('metadata[hostId]', input.hostId);
     params.set('metadata[orderId]', input.quoteId);
-    params.set('metadata[quoteId]', input.quoteId);
-    params.set('metadata[quoteLinkVersion]', String(CommerceModel.quoteLinkVersion(quote)));
-    params.set('metadata[quoteUpdatedAtMs]', String(Number(quote.updatedAtMs) || 0));
+    if (invoice) {
+        // An invoice's link version, which the draft branch compares as a
+        // quote's (AGL-4099), and the promotion the draft was priced with, which
+        // it counts once the draft is paid (no hold: the draft's lapsed with its
+        // first session).
+        params.set('metadata[payLinkVersion]', String(CommerceModel.orderPayLinkVersion(order)));
+        if (order.discountId) params.set('metadata[discountId]', String(order.discountId));
+    } else {
+        params.set('metadata[quoteId]', input.quoteId);
+        params.set('metadata[quoteLinkVersion]', String(CommerceModel.quoteLinkVersion(quote)));
+        params.set('metadata[quoteUpdatedAtMs]', String(Number(quote.updatedAtMs) || 0));
+    }
     params.set('metadata[feeCents]', String(input.feeCents));
     // A tax charged as its own line is invisible to Stripe's tax total; this
     // witness is what records it as the business's tax.
@@ -362,20 +413,24 @@ const refusal = (status, reason, error, extra = {})=>({
     };
     const refused = await limitedQuoteLink(deps, req, `commerce-quote-pay:${hostId}`, QUOTE_PAY_PRESSES_PER_WINDOW);
     if (refused) return refused;
-    const linked = await loadLinkedQuote(deps, hostId, quoteId, token);
+    const linked = await loadLinkedQuote(deps, hostId, quoteId, token, {
+        invoices: true
+    });
     if ('outcome' in linked) return linked.outcome;
-    const { hostRef, host, order, storeName, store } = linked.loaded;
+    const { hostRef, host, order, storeName, store, kind } = linked.loaded;
+    const noun = nounOf(kind);
     // Every refusal the customer can be given is above the claim, so none of
     // them spends the press. `v` is the edit of the quote the page showed: a
     // quote changed since is shown again before it is paid, never charged unseen.
+    // An invoice is not edited, so it sends none.
     const seen = Number(bodyOf(req)['v']);
-    if (Number.isFinite(seen) && seen > 0 && seen !== (Number((_order_quote = order.quote) == null ? void 0 : _order_quote.updatedAtMs) || 0)) {
+    if (kind === 'quote' && Number.isFinite(seen) && seen > 0 && seen !== (Number((_order_quote = order.quote) == null ? void 0 : _order_quote.updatedAtMs) || 0)) {
         return refusal(409, 'updated', QUOTE_UPDATED_MESSAGE);
     }
-    const blocked = CommerceModel.quotePayRefusal(order, quoteId);
-    if (blocked) return refusal(409, blocked, CommerceModel.quotePayRefusalMessage(blocked, storeName));
+    const blocked = CommerceModel.invoicePayRefusal(order, quoteId);
+    if (blocked) return refusal(409, blocked, CommerceModel.invoicePayRefusalMessage(blocked, storeName, kind));
     const owner = await deps.orgForHost(hostId);
-    const unavailable = refusal(409, 'payments-unavailable', `${storeName || 'This business'} can’t take payments online right now. Contact them to pay this quote.`);
+    const unavailable = refusal(409, 'payments-unavailable', `${storeName || 'This business'} can’t take payments online right now. Contact them to pay this ${noun}.`);
     if (!checkEntitlement(owner == null ? void 0 : owner.org, 'commerce')) return unavailable;
     const ownerUid = owner == null ? void 0 : (_owner_org = owner.org) == null ? void 0 : _owner_org.ownerUid;
     const profile = ownerUid ? await deps.firestore().collection('profiles').doc(String(ownerUid)).get() : null;
@@ -385,17 +440,20 @@ const refusal = (status, reason, error, extra = {})=>({
         chargesEnabled: profile == null ? void 0 : profile.get('stripeChargesEnabled'),
         accountLivemode: profile == null ? void 0 : profile.get('stripeAccountLivemode')
     }, {
-        subject: `quote ${quoteId} on host ${hostId}`
+        subject: `${noun} ${quoteId} on host ${hostId}`
     });
     if (!ready) return unavailable;
     const taxSettings = (_store_get = store.get('tax')) != null ? _store_get : {};
     if (CommerceModel.storefrontTaxDecision({
         settings: taxSettings
     }).kind === 'undecided') {
-        return refusal(409, 'tax-undecided', CommerceModel.quotePayRefusalMessage('tax-undecided', storeName));
+        return refusal(409, 'tax-undecided', CommerceModel.invoicePayRefusalMessage('tax-undecided', storeName, kind));
     }
-    const charge = CommerceModel.quoteCheckoutCharge(order, quoteId);
-    const feeCents = resolveTransactionFeeCents(owner == null ? void 0 : owner.org, charge.feeProductType, charge.goodsCents, charge.totalCents);
+    const charge = CommerceModel.invoiceCheckoutCharge(order, quoteId);
+    // The fee is sized on the most the buyer can pay, as a draft's first link
+    // sized it on its dearest rate.
+    const dearestRateCents = charge.shippingOptions.reduce((most, rate)=>Math.max(most, rate.amountCents), 0);
+    const feeCents = resolveTransactionFeeCents(owner == null ? void 0 : owner.org, charge.feeProductType, charge.goodsCents, charge.totalCents + dearestRateCents);
     const nativeMode = await deps.nativeMode(String((_ref = owner == null ? void 0 : owner.id) != null ? _ref : ''));
     const site = host;
     const origin = siteReturnOrigin({
@@ -407,8 +465,11 @@ const refusal = (status, reason, error, extra = {})=>({
         requestHost: headerOf(req, 'host')
     });
     const returnUrl = `${origin}${quotePageHref(quoteId, token)}`;
+    // A draft's first session (the one its paymentLinkUrl opens) is closed
+    // here too, so the draft has one way to pay from the first press on.
     const openedFor = (_order_checkoutSessionId = order.checkoutSessionId) != null ? _order_checkoutSessionId : '';
     const openedAtEdit = Number((_order_quote1 = order.quote) == null ? void 0 : _order_quote1.updatedAtMs) || 0;
+    const openedAtVersion = CommerceModel.orderPayLinkVersion(order);
     const claimed = await claimAttempt(deps.firestore(), {
         kind: 'commerce-quote-pay',
         scopeId: `${hostId}:${quoteId}`,
@@ -438,7 +499,7 @@ const refusal = (status, reason, error, extra = {})=>({
             const previous = await deps.expireSession(openedFor);
             if (previous === 'complete') {
                 await claim.release();
-                return refusal(409, 'paid', 'This quote has just been paid. Your receipt is on its way.', {
+                return refusal(409, 'paid', `This ${noun} has just been paid. Your receipt is on its way.`, {
                     confirming: true
                 });
             }
@@ -519,29 +580,30 @@ const refusal = (status, reason, error, extra = {})=>({
             var _current_quote;
             const snapshot = await transaction.get(orderRef);
             const current = snapshot.exists ? snapshot.data() : null;
-            if (!current || !CommerceModel.isQuote(current)) return {
-                outcome: NOT_FOUND,
+            if (!current || CommerceModel.orderPayLinkKind(current) !== kind) return {
+                outcome: NOT_FOUND_ANY,
                 displaced: ''
             };
-            if (!CommerceModel.isUnpaidQuote(current)) {
+            if (current.status !== 'pending') {
+                const closed = current.status === 'cancelled' || current.status === 'refunded';
                 return {
-                    outcome: refusal(409, 'paid', CommerceModel.quotePayRefusalMessage('paid', storeName)),
+                    outcome: refusal(409, closed ? 'closed' : 'paid', CommerceModel.invoicePayRefusalMessage(closed ? 'closed' : 'paid', storeName, kind)),
                     displaced: ''
                 };
             }
-            if (CommerceModel.quoteLinkVersion(current.quote) !== CommerceModel.quoteLinkVersion(order.quote)) {
+            if (CommerceModel.orderPayLinkVersion(current) !== openedAtVersion) {
                 return {
                     outcome: {
                         status: 410,
                         body: {
                             replaced: true,
-                            error: `This quote was updated, and ${storeName || 'the business'} sent you a newer link.`
+                            error: `This ${noun} was updated, and ${storeName || 'the business'} sent you a newer link.`
                         }
                     },
                     displaced: ''
                 };
             }
-            if ((Number((_current_quote = current.quote) == null ? void 0 : _current_quote.updatedAtMs) || 0) !== openedAtEdit) {
+            if (kind === 'quote' && (Number((_current_quote = current.quote) == null ? void 0 : _current_quote.updatedAtMs) || 0) !== openedAtEdit) {
                 return {
                     outcome: refusal(409, 'updated', QUOTE_UPDATED_MESSAGE),
                     displaced: ''