@aglyn/plugins-commerce 1.0.0-beta.289 → 1.0.0-beta.291

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

@@ -55,19 +55,50 @@ export interface QuotePayDeps {
     now(): number;
 }
 export declare function defaultQuotePayDeps(): QuotePayDeps;
-type Outcome = {
+/** A link route's answer: a status, a JSON body and any extra headers. */
+export type QuoteLinkOutcome = {
     status: number;
     body: Record<string, unknown>;
     headers?: Record<string, string>;
 };
+/** The rate limit a link route spends per address per site, BEFORE the token is checked. */
+export declare function limitedQuoteLink(deps: QuotePayDeps, req: PluginApiRequest, key: string, limit: number): Promise<QuoteLinkOutcome | null>;
+export interface LoadedQuote {
+    hostRef: FirebaseFirestore.DocumentReference;
+    host: Record<string, unknown>;
+    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, options?: {
+    invoices?: boolean;
+}): Promise<{
+    loaded: LoadedQuote;
+} | {
+    outcome: QuoteLinkOutcome;
+}>;
+/** The link's site, quote and token from a query or a body, and whether all three are there. */
+export declare function quoteLinkParams(source: Record<string, unknown>): {
+    hostId: string;
+    quoteId: string;
+    token: string;
+    complete: boolean;
+};
 /** `GET /api/commerce/quote-view`: the quote page's data. */
-export declare function handleQuoteView(deps: QuotePayDeps, req: PluginApiRequest): Promise<Outcome>;
-/** The Checkout Session a quote's Pay opens, as form params. Pure over its inputs. */
+export declare function handleQuoteView(deps: QuotePayDeps, req: PluginApiRequest): Promise<QuoteLinkOutcome>;
+/** 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;
@@ -75,9 +106,10 @@ export declare function buildQuoteSessionParams(input: {
     paymentMethods: CommerceModel.StorefrontPaymentMethodControls;
 }): URLSearchParams;
 /** `POST /api/commerce/quote-pay`: a fresh Checkout Session for the quote. */
-export declare function handleQuotePay(deps: QuotePayDeps, req: PluginApiRequest): Promise<Outcome>;
+export declare function handleQuotePay(deps: QuotePayDeps, req: PluginApiRequest): Promise<QuoteLinkOutcome>;
+/** Sends a link route's answer, never cached or indexed. */
+export declare function sendQuoteLinkOutcome(res: Parameters<PluginApiHandler>[1], outcome: QuoteLinkOutcome): void;
 /** `GET /api/commerce/quote-view`. */
 export declare const quoteViewHandler: PluginApiHandler;
 /** `POST /api/commerce/quote-pay`. */
 export declare const quotePayHandler: PluginApiHandler;
-export {};

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') {
@@ -113,7 +131,7 @@ function headerOf(req, name) {
     const value = (_headers_name_toLowerCase = headers[name.toLowerCase()]) != null ? _headers_name_toLowerCase : headers[name];
     return String(Array.isArray(value) ? (_value_ = value[0]) != null ? _value_ : '' : value != null ? value : '').trim();
 }
-async function limited(deps, req, key, limit) {
+/** The rate limit a link route spends per address per site, BEFORE the token is checked. */ export async function limitedQuoteLink(deps, req, key, limit) {
     var _readClientIp;
     var _req_socket;
     const ip = (_readClientIp = readClientIp(req.headers, {
@@ -137,11 +155,13 @@ async function limited(deps, req, key, limit) {
 /**
  * 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.
- */ 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 @@ async function limited(deps, req, key, limit) {
         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 @@ async function limited(deps, req, key, limit) {
                 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,11 +203,12 @@ async function limited(deps, req, key, limit) {
             host,
             order,
             storeName,
-            store
+            store,
+            kind
         }
     };
 }
-function linkParams(req, source) {
+/** The link's site, quote and token from a query or a body, and whether all three are there. */ export function quoteLinkParams(source) {
     var _source_hostId, _source_q, _source_t;
     const hostId = String((_source_hostId = source['hostId']) != null ? _source_hostId : '');
     const quoteId = String((_source_q = source['q']) != null ? _source_q : '').slice(0, 200);
@@ -206,48 +229,60 @@ function linkParams(req, source) {
             error: 'Method not allowed'
         }
     };
-    const { hostId, quoteId, token, complete } = linkParams(req, (_req_query = req.query) != null ? _req_query : {});
+    const { hostId, quoteId, token, complete } = quoteLinkParams((_req_query = req.query) != null ? _req_query : {});
     if (!complete) return {
         status: 400,
         body: {
             error: 'This link is incomplete.'
         }
     };
-    const refused = await limited(deps, req, `commerce-quote-view:${hostId}`, QUOTE_VIEW_LOOKUPS_PER_WINDOW);
+    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 linkParams(req, source) {
     // 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 linkParams(req, source) {
             }
         ]);
     }
-    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 linkParams(req, source) {
     }))){
         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 linkParams(req, source) {
     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.
@@ -346,7 +397,7 @@ const refusal = (status, reason, error, extra = {})=>({
             error: 'Payments are not configured.'
         }
     };
-    const { hostId, quoteId, token, complete } = linkParams(req, bodyOf(req));
+    const { hostId, quoteId, token, complete } = quoteLinkParams(bodyOf(req));
     if (!complete) return {
         status: 400,
         body: {
@@ -360,22 +411,26 @@ const refusal = (status, reason, error, extra = {})=>({
             error: 'Paying needs an Idempotency-Key header.'
         }
     };
-    const refused = await limited(deps, req, `commerce-quote-pay:${hostId}`, QUOTE_PAY_PRESSES_PER_WINDOW);
+    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: ''
@@ -581,7 +643,7 @@ const refusal = (status, reason, error, extra = {})=>({
         };
     }
 }
-function send(res, outcome) {
+/** Sends a link route's answer, never cached or indexed. */ export function sendQuoteLinkOutcome(res, outcome) {
     var _outcome_headers;
     res.setHeader('Cache-Control', 'private, no-store');
     res.setHeader('X-Robots-Tag', 'noindex, nofollow');
@@ -590,10 +652,10 @@ function send(res, outcome) {
 }
 /** `GET /api/commerce/quote-view`. */ export const quoteViewHandler = async (req, res)=>{
     try {
-        return send(res, await handleQuoteView(defaultQuotePayDeps(), req));
+        return sendQuoteLinkOutcome(res, await handleQuoteView(defaultQuotePayDeps(), req));
     } catch (error) {
         console.error('quote view failed', error);
-        return send(res, {
+        return sendQuoteLinkOutcome(res, {
             status: 500,
             body: {
                 error: 'This quote could not be loaded. Try again.'
@@ -601,6 +663,6 @@ function send(res, outcome) {
         });
     }
 };
-/** `POST /api/commerce/quote-pay`. */ export const quotePayHandler = async (req, res)=>send(res, await handleQuotePay(defaultQuotePayDeps(), req));
+/** `POST /api/commerce/quote-pay`. */ export const quotePayHandler = async (req, res)=>sendQuoteLinkOutcome(res, await handleQuotePay(defaultQuotePayDeps(), req));
 
 //# sourceMappingURL=quote-pay.js.map