@genesis-tech/genesispay-seller 0.13.2 → 1.3.0

package/dist/products.js

@@ -1,15 +1,25 @@
+// This file deliberately keeps the product resource, strict checkout contract,
+// and ProductGate adapter together. They share one product wire model and one
+// post-settlement authority transition; splitting the gate from the resource
+// would either expose internal evidence-validation seams or duplicate the exact
+// recovery rules that prevent a paid handler from running without verification.
+//
 // `genesispay.products.*` — the merchant's catalogue over `/api/v1/products`.
 //
-// A product is what a shop sells; its payable instance is one CANONICAL
-// reusable checkout link, minted (idempotently) with `createPaymentLink`. The
-// price and asset are copied onto the link at mint and never re-read from the
-// catalogue, so editing or archiving a product cannot change what a buyer
-// already sees. Everything is scoped to the key's own account: someone else's
-// product answers 404 (GenesisPayNotFoundError), never 403 — the API is no
-// catalogue-enumeration oracle, and the SDK does not paper over that.
-import { GenesisPayConfigError } from "./errors.js";
+// A product is what a shop sells. Legacy catalogue flows expose one canonical
+// reusable link; strict 1.0 checkout creation freezes a distinct single-use
+// link. Price, asset, destination, and delivery are copied onto either payable
+// resource and never re-read from mutable catalogue presentation for authority.
+// Everything is scoped to the key's own account: someone else's product answers
+// 404 (GenesisPayNotFoundError), never 403 — the API is no catalogue-enumeration
+// oracle, and the SDK does not paper over that.
+import { parseItemTax } from "./item-tax.js";
+import { GenesisPayAmbiguousLocatorError, GenesisPayConfigError, GenesisPayContractMismatchError, GenesisPayEvidenceError, GenesisPayNotFoundError, GenesisPayRateLimitError, GenesisPayValidationError, GenesisPayVersionError, } from "./errors.js";
 import { asRecord, optionalString, requiredString, toAmountString, oneOf, } from "./resource.js";
-import { PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER } from "@genesis-tech/genesispay-protocol";
+import { GENESISPAY_SETTLEMENT_PREPARE_HEADER, GENESISPAY_SETTLEMENT_PREPARE_PARAMS_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, decodePaymentSignatureHeader, decodeSettlementPrepareParamsHeader, encodeSettlementResponseHeader, } from "@genesis-tech/genesispay-protocol";
+import { GENESISPAY_API_VERSION, GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER, GENESISPAY_REQUEST_ID_HEADER, GENESISPAY_VERSION_HEADER, validateExpectedProductContract, } from "./fulfillment.js";
+import { isStrictVersionedResponse, requireStrictResponseMetadata, } from "./strict-response.js";
+const PRODUCT_SETTLEMENT_TIMEOUT_MS = 120_000;
 export function createProductsResource(request, 
 /**
  * Applies the client's `expectedPayTo` pin to the wallet the server froze
@@ -20,7 +30,7 @@ assertPinnedDestination,
 /** The client's raw-link mapper, so link shapes cannot drift between resources. */
 toLink, 
 /** The client's origin (no trailing slash) — the base of `permalink()`. */
-baseUrl, rawGateRequest) {
+baseUrl, verifyFulfillment, rawGateRequest, strictRequest) {
     const resources = {
         create: async (input) => {
             const body = await request({
@@ -36,6 +46,7 @@ baseUrl, rawGateRequest) {
                     ...(input.sku ? { sku: input.sku } : {}),
                     ...(input.asset ? { asset: input.asset } : {}),
                     ...(input.delivery ? { delivery: input.delivery } : {}),
+                    ...(input.taxConfig ? { taxConfig: parseItemTax(input.taxConfig) } : {}),
                 },
             });
             return requireProduct(body, "POST /api/v1/products");
@@ -79,7 +90,9 @@ baseUrl, rawGateRequest) {
                 operation: `PATCH /api/v1/products/${id}`,
                 action: `update product "${id}"`,
                 notFoundMessage: notFoundMessage(id),
-                body: "delivery" in input ? { delivery: input.delivery } : { fulfilmentUrl: input.fulfilmentUrl },
+                body: "taxConfig" in input
+                    ? { taxConfig: parseItemTax(input.taxConfig), expectedTaxConfig: parseItemTax(input.expectedTaxConfig) }
+                    : "delivery" in input ? { delivery: input.delivery } : { fulfilmentUrl: input.fulfilmentUrl },
             });
             return requireProduct(body, `PATCH /api/v1/products/${id}`);
         },
@@ -119,6 +132,42 @@ baseUrl, rawGateRequest) {
                 created: record?.created === true,
             };
         },
+        assertContract: async (expectedInput) => {
+            if (!strictRequest)
+                throw new GenesisPayConfigError("This GenesisPay client cannot verify product contracts.");
+            const expected = validateExpectedProductContract(expectedInput);
+            assertPinnedDestination(expected.settlementDestination, "product contract");
+            const response = await strictRequest({
+                path: `/api/v1/products/${encodeURIComponent(expected.productId)}/contract`,
+            });
+            const body = await response.clone().json().catch(() => null);
+            if (!response.ok)
+                throwStrictProductError(response, body);
+            assertProductContractResponse(response, body, expected);
+        },
+        createCheckout: async (input, options) => {
+            if (!strictRequest)
+                throw new GenesisPayConfigError("This GenesisPay client cannot create product checkout links.");
+            const expected = validateExpectedProductContract(input?.expected);
+            assertPinnedDestination(expected.settlementDestination, "product checkout contract");
+            const idempotencyKey = requireStrictIdempotencyKey(options);
+            const response = await strictRequest({
+                method: "POST",
+                path: `/api/v1/products/${encodeURIComponent(expected.productId)}/checkouts`,
+                headers: { "Idempotency-Key": idempotencyKey },
+                body: {
+                    expected: { ...expected, grossAmountMinor: expected.grossAmountMinor.toString() },
+                    clientReferenceId: input.clientReferenceId ?? null,
+                    metadata: input.metadata ?? null,
+                    returnUrl: input.returnUrl ?? null,
+                    cancelUrl: input.cancelUrl ?? null,
+                },
+            });
+            const body = await response.clone().json().catch(() => null);
+            if (!response.ok)
+                throwStrictProductError(response, body);
+            return parseProductCheckoutResponse(response, body);
+        },
         checkoutUrl: async (publicId) => {
             const { link } = await resources.createPaymentLink(publicId);
             return link.payUrl;
@@ -149,6 +198,13 @@ baseUrl, rawGateRequest) {
                 assertPinnedDestination(rawLink.destinationWallet, "product payment link");
                 return { link: toLink(rawLink), created: record?.created === true };
             },
+            statusRequest: strictRequest
+                ? (planId) => strictRequest({
+                    path: `/api/v1/settlements/${encodeURIComponent(planId)}`,
+                })
+                : undefined,
+            verifyFulfillment,
+            assertPinnedDestination,
             request: rawGateRequest,
         }),
     };
@@ -174,6 +230,7 @@ function requireProduct(body, operation) {
 }
 export function toProduct(raw) {
     return {
+        taxConfig: parseItemTax(raw.taxConfig),
         publicId: requiredString(raw.publicId),
         name: requiredString(raw.name),
         description: optionalString(raw.description),
@@ -201,6 +258,198 @@ function toProductDelivery(raw) {
     const url = optionalString(raw.fulfilmentUrl);
     return url ? { type: "redirect", url, verifiedAt: optionalString(raw.fulfilmentVerifiedAt) } : { type: "none" };
 }
+function requireStrictIdempotencyKey(options) {
+    const value = options?.idempotencyKey;
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > 255 ||
+        value.trim() !== value) {
+        throw new GenesisPayValidationError("products.createCheckout requires an idempotencyKey with 1–255 characters and no surrounding whitespace.", [{ path: "idempotencyKey", message: "invalid idempotency key" }]);
+    }
+    return value;
+}
+function strictResponseMetadata(response, body) {
+    return requireStrictResponseMetadata(response, body, "product");
+}
+function assertProductContractResponse(response, body, expected) {
+    const metadata = strictResponseMetadata(response, body);
+    const contract = asRecord(asRecord(body)?.contract);
+    if (!contract || contract.object !== "product_contract") {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract response omitted its product_contract object.", metadata);
+    }
+    const amount = contract.grossAmountMinor;
+    if (typeof amount !== "string" ||
+        !/^(0|[1-9][0-9]*)$/.test(amount) ||
+        amount.length > 13 ||
+        BigInt(amount) <= 0n ||
+        BigInt(amount) > 1000000000000n) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract grossAmountMinor is not canonical product money.", metadata);
+    }
+    const productId = contract.productId;
+    const settlementDestination = contract.settlementDestination;
+    const network = requireStrictProductNetwork(contract.network, metadata);
+    const delivery = requireStrictProductDelivery(contract.delivery, metadata);
+    if (typeof productId !== "string" ||
+        productId.length === 0 ||
+        typeof settlementDestination !== "string" ||
+        !/^0x[0-9a-fA-F]{40}$/.test(settlementDestination)) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract omitted a typed product identity or settlement destination.", metadata);
+    }
+    const actualSku = contract.sku === null || typeof contract.sku === "string" ? contract.sku : undefined;
+    if (actualSku === undefined) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product SKU must be string or null.", metadata);
+    }
+    const mismatches = [];
+    const compare = (path, equal) => {
+        if (!equal)
+            mismatches.push(path);
+    };
+    compare("productId", productId === expected.productId);
+    compare("sku", actualSku === expected.sku);
+    compare("grossAmountMinor", amount === expected.grossAmountMinor.toString());
+    compare("settlementDestination", equalAddress(settlementDestination, expected.settlementDestination));
+    compare("network.mode", network.mode === expected.network.mode);
+    compare("network.network", network.network === expected.network.network);
+    compare("network.chainId", network.chainId === expected.network.chainId);
+    compare("network.asset", network.asset === expected.network.asset);
+    compare("network.tokenAddress", equalAddress(network.tokenAddress, expected.network.tokenAddress));
+    compare("network.minorUnitScale", network.minorUnitScale === expected.network.minorUnitScale);
+    compare("delivery.type", delivery.type === expected.delivery.type);
+    compare("delivery.url", delivery.url === expected.delivery.url);
+    if (expected.delivery.type === "gate") {
+        const actualGate = asRecord(delivery.gate);
+        compare("delivery.gate.method", actualGate?.method === expected.delivery.gate?.method);
+        compare("delivery.gate.resourceUrl", actualGate?.resourceUrl === expected.delivery.gate?.resourceUrl);
+        // The request fingerprint is deliberately not compared here: it is derived
+        // from one concrete request (method + canonical URL + body digest), so it
+        // cannot be part of the product contract the backend emits. The gate's
+        // `protect` path compares it against the actual request instead.
+    }
+    else {
+        compare("delivery.gate", delivery.gate === null);
+    }
+    if (mismatches.length > 0) {
+        throw new GenesisPayContractMismatchError(`GenesisPay product no longer matches the expected contract (${mismatches.join(", ")}).`, mismatches, metadata);
+    }
+}
+function requireStrictProductNetwork(value, metadata) {
+    const network = asRecord(value);
+    if (!network ||
+        (network.mode !== "test" && network.mode !== "live") ||
+        network.network !== "base" ||
+        (network.chainId !== 8453 && network.chainId !== 84532) ||
+        (network.asset !== "USDC" && network.asset !== "EURC") ||
+        typeof network.tokenAddress !== "string" ||
+        !/^0x[0-9a-fA-F]{40}$/.test(network.tokenAddress) ||
+        network.minorUnitScale !== 6) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract network is missing a required typed authority field.", metadata);
+    }
+    return network;
+}
+function requireStrictProductDelivery(value, metadata) {
+    const delivery = asRecord(value);
+    if (!delivery || (delivery.type !== "none" && delivery.type !== "url" && delivery.type !== "gate")) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract delivery has an unsupported type.", metadata);
+    }
+    if (delivery.type === "none") {
+        if (delivery.url !== null || delivery.gate !== null) {
+            throw new GenesisPayEvidenceError("inconsistent_evidence", "Product contract none delivery must carry null URL and gate fields.", metadata);
+        }
+        return delivery;
+    }
+    if (delivery.type === "url") {
+        if (delivery.gate !== null || requireCanonicalStrictProductUrl(delivery.url, metadata) === null) {
+            throw new GenesisPayEvidenceError("inconsistent_evidence", "Product contract URL delivery must carry one canonical URL and a null gate.", metadata);
+        }
+        return delivery;
+    }
+    if (delivery.url !== null) {
+        throw new GenesisPayEvidenceError("inconsistent_evidence", "Product contract gate delivery must carry a null delivery URL.", metadata);
+    }
+    const gate = asRecord(delivery.gate);
+    if (!gate ||
+        !["GET", "POST", "PUT", "PATCH", "DELETE"].includes(String(gate.method)) ||
+        requireCanonicalStrictProductUrl(gate.resourceUrl, metadata) === null) {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract gate delivery is missing its typed method or canonical resource URL.", metadata);
+    }
+    return delivery;
+}
+function requireCanonicalStrictProductUrl(value, metadata) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" || url.username || url.password || url.hash || url.href !== value) {
+            throw new Error("unsafe or noncanonical product authority URL");
+        }
+        return url.href;
+    }
+    catch {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product contract authority URL is unsafe or not canonically serialized.", metadata);
+    }
+}
+function parseProductCheckoutResponse(response, body) {
+    const metadata = strictResponseMetadata(response, body);
+    const root = asRecord(body);
+    if (root?.object !== "product_checkout_link" ||
+        typeof root.linkId !== "string" ||
+        !root.linkId ||
+        typeof root.payUrl !== "string" ||
+        !root.payUrl ||
+        root.productContractVersion !== GENESISPAY_API_VERSION ||
+        typeof root.created !== "boolean") {
+        throw new GenesisPayEvidenceError("malformed_evidence", "Product checkout response is missing a required typed field.", metadata);
+    }
+    return {
+        object: "product_checkout_link",
+        linkId: root.linkId,
+        payUrl: root.payUrl,
+        productContractVersion: GENESISPAY_API_VERSION,
+        created: root.created,
+        requestId: metadata.requestId,
+        apiVersion: metadata.apiVersion,
+    };
+}
+function equalAddress(actual, expected) {
+    return (typeof actual === "string" &&
+        /^0x[0-9a-fA-F]{40}$/.test(actual) &&
+        actual.toLowerCase() === expected.toLowerCase());
+}
+function throwStrictProductError(response, body) {
+    const metadata = strictResponseMetadata(response, body);
+    const root = asRecord(body);
+    const code = typeof root?.code === "string" ? root.code : null;
+    const message = typeof root?.error === "string"
+        ? root.error
+        : `GenesisPay product request failed with HTTP ${response.status}.`;
+    if (code === "unsupported_api_version") {
+        throw new GenesisPayVersionError(code, message, metadata);
+    }
+    if (code === "contract_mismatch") {
+        const mismatches = Array.isArray(root?.mismatches)
+            ? root.mismatches.filter((value) => typeof value === "string")
+            : [];
+        throw new GenesisPayContractMismatchError(message, mismatches, metadata);
+    }
+    if (code === "not_found")
+        throw new GenesisPayNotFoundError(message, metadata);
+    if (response.status === 422) {
+        const issues = Array.isArray(root?.issues)
+            ? root.issues.flatMap((entry) => {
+                const issue = asRecord(entry);
+                return typeof issue?.message === "string"
+                    ? [{ path: typeof issue.path === "string" ? issue.path : "", message: issue.message }]
+                    : [];
+            })
+            : [];
+        throw new GenesisPayValidationError(message, issues, metadata);
+    }
+    if (response.status === 429) {
+        const retry = response.headers.get("retry-after");
+        throw new GenesisPayRateLimitError(message, retry && /^\d+$/.test(retry) ? Number(retry) : null, metadata);
+    }
+    throw new GenesisPayConfigError(message, metadata);
+}
 function createProductGate(input) {
     return {
         async prime() {
@@ -209,58 +458,313 @@ function createProductGate(input) {
                 throw new GenesisPayConfigError(`Product "${input.publicId}" is not configured with gate delivery.`);
             return { product, paymentLink: await input.createPaymentLink() };
         },
-        async protect(request, handler) {
-            if (!input.request)
-                throw new GenesisPayConfigError("This GenesisPay client cannot call product gates.");
+        async protect(request, expectedInput, handler) {
             const signature = request.headers.get(PAYMENT_SIGNATURE_HEADER);
-            const url = canonicalRequestUrl(request.url);
-            const requestMethod = request.method.toUpperCase();
-            let product = null;
-            let gateResourceUrl;
-            if (signature) {
-                // A settled retry belongs to the immutable resource snapshot in its
-                // gate intent. Do not reject it because the merchant edited the live
-                // product URL after GenesisPay returned the original 402.
-                gateResourceUrl = url;
+            const settlementDeadline = signature
+                ? Date.now() + PRODUCT_SETTLEMENT_TIMEOUT_MS
+                : null;
+            const payerBroadcastRecovery = signature
+                ? signedPayerBroadcastRecoveryResponse(signature)
+                : null;
+            if (!input.request) {
+                if (payerBroadcastRecovery) {
+                    return knownBroadcastPreflightFailureResponse({
+                        settlementResponse: payerBroadcastRecovery,
+                        attemptId: null,
+                    });
+                }
+                throw new GenesisPayConfigError("This GenesisPay client cannot call product gates.");
             }
-            else {
-                const primed = await this.prime();
-                product = primed.product;
-                if (product.delivery.type !== "gate")
-                    throw new GenesisPayConfigError("Product is not a gate.");
-                if (url !== canonicalRequestUrl(product.delivery.resourceUrl) || requestMethod !== product.delivery.method) {
-                    throw new GenesisPayConfigError("Incoming request does not match the product's registered gate resource.");
+            let expected;
+            let signedAttemptId = null;
+            try {
+                expected = validateExpectedProductContract(expectedInput);
+                // MR-103: an explicit expected contract does not override the client's
+                // local destination pin, including before a signed settlement request.
+                input.assertPinnedDestination(expected.settlementDestination, "product gate contract");
+                if (expected.productId !== input.publicId) {
+                    throw new GenesisPayContractMismatchError("The product gate ID does not match expected.productId.", ["product.productId"]);
                 }
-                gateResourceUrl = product.delivery.resourceUrl;
+                if (expected.delivery.type !== "gate" || !expected.delivery.gate) {
+                    throw new GenesisPayConfigError("A product gate requires expected.delivery.type gate.");
+                }
+                signedAttemptId = signature
+                    ? resolveSignedRequestAttemptId(request.url, signature)
+                    : null;
+            }
+            catch (error) {
+                if (!payerBroadcastRecovery)
+                    throw error;
+                return knownBroadcastPreflightFailureResponse({
+                    settlementResponse: payerBroadcastRecovery,
+                    attemptId: signedAttemptId,
+                });
+            }
+            const preparationRequested = !signature &&
+                request.headers.get(GENESISPAY_SETTLEMENT_PREPARE_HEADER) === "1";
+            const expectedGate = expected.delivery.gate;
+            if (preparationRequested) {
+                const paramsHeader = request.headers.get(GENESISPAY_SETTLEMENT_PREPARE_PARAMS_HEADER);
+                const prepared = paramsHeader === null
+                    ? await readLegacyPrepareBody(request)
+                    : await readPurchaseBoundPrepareParams(request, paramsHeader, expectedGate);
+                if (!prepared.ok)
+                    return prepared.response;
+                const { payer, idempotencyKey, feeMode, authority, attemptId } = prepared;
+                const response = await input.request(input.publicId, {
+                    action: "prepare",
+                    resourceUrl: expectedGate.resourceUrl,
+                    method: expectedGate.method,
+                    requestFingerprint: expectedGate.fingerprint.slice("sha256:".length),
+                    attemptId,
+                    payer,
+                    idempotencyKey,
+                    feeMode,
+                    ...(authority ? { authority } : {}),
+                    expected: toWireExpectedProductContract(expected),
+                });
+                if (response.ok && !(await respondedWithStrictVersion(response))) {
+                    return strictNegotiationFailedResponse(response);
+                }
+                return copyResponse(response);
             }
-            const requestFingerprint = await fingerprintRequest(request);
-            const response = await input.request(input.publicId, {
+            const planId = request.headers.get("GENESISPAY-Settlement-Plan");
+            let url;
+            let requestMethod;
+            let requestFingerprint;
+            // Never read the mutable catalogue or mint a legacy link here. The
+            // challenge carries the complete expected contract so GenesisPay can
+            // compare it atomically with the exact frozen payable link before it
+            // creates an attempt. A settlement similarly belongs to that intent.
+            try {
+                url = canonicalRequestUrl(request.url);
+                requestMethod = request.method.toUpperCase();
+                requestFingerprint = await createGateRequestFingerprint(request);
+                const gateMismatches = [
+                    ...(url === expectedGate.resourceUrl ? [] : ["product.delivery.gate.resourceUrl"]),
+                    ...(requestMethod === expectedGate.method ? [] : ["product.delivery.gate.method"]),
+                    ...(requestFingerprint === expectedGate.fingerprint
+                        ? []
+                        : ["product.delivery.gate.fingerprint"]),
+                ];
+                if (gateMismatches.length > 0) {
+                    throw new GenesisPayContractMismatchError(`The request does not match the expected gate intent (${gateMismatches.join(", ")}).`, gateMismatches);
+                }
+            }
+            catch (error) {
+                if (!payerBroadcastRecovery)
+                    throw error;
+                return knownBroadcastPreflightFailureResponse({
+                    settlementResponse: payerBroadcastRecovery,
+                    attemptId: signedAttemptId,
+                });
+            }
+            const gateResourceUrl = url;
+            const transportFingerprint = requestFingerprint.slice("sha256:".length);
+            const gateBody = {
                 action: signature ? "settle" : "challenge",
                 resourceUrl: gateResourceUrl,
                 method: requestMethod,
-                requestFingerprint,
-                ...(signature ? { paymentSignature: signature } : {}),
-            });
-            if (!response.ok)
-                return copyResponse(response);
-            const payment = await response.clone().json().catch(() => null);
-            const attemptId = typeof payment?.paymentAttemptId === "string" ? payment.paymentAttemptId : null;
-            if (!attemptId)
+                requestFingerprint: transportFingerprint,
+                ...(!signature ? { expected: toWireExpectedProductContract(expected) } : {}),
+                ...(signature
+                    ? {
+                        paymentSignature: signature,
+                        ...(planId ? { planId } : {}),
+                    }
+                    : {}),
+            };
+            let response;
+            try {
+                response = settlementDeadline === null
+                    ? await input.request(input.publicId, gateBody)
+                    : await productResponseBeforeDeadline(() => input.request(input.publicId, gateBody), settlementDeadline);
+            }
+            catch (error) {
+                if (!signedAttemptId && !payerBroadcastRecovery)
+                    throw error;
+                // The request never reached a response. Whether the settlement ran at
+                // all is unknown, so the caller is told to retry or reconcile — never
+                // that the payment confirmed.
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: payerBroadcastRecovery ?? new Response(null),
+                    attemptId: signedAttemptId,
+                    requestId: null,
+                    outcome: "unknown",
+                    retryable: true,
+                });
+            }
+            if (signature &&
+                planId &&
+                response.status === 202 &&
+                settlementDeadline !== null) {
+                let polling;
+                try {
+                    polling = await pollProductSettlement({
+                        acceptanceResponse: response,
+                        planId,
+                        statusRequest: input.statusRequest,
+                        fallbackSettlementResponse: payerBroadcastRecovery,
+                        timeoutDeadline: settlementDeadline,
+                    });
+                }
+                catch {
+                    return fulfillmentUnavailableResponse({
+                        settlementResponse: payerBroadcastRecovery ?? new Response(null),
+                        attemptId: signedAttemptId,
+                        requestId: null,
+                        outcome: "unknown",
+                        retryable: true,
+                    });
+                }
+                if (!polling.settled)
+                    return polling.response;
+                try {
+                    response = await productResponseBeforeDeadline(() => input.request(input.publicId, gateBody), settlementDeadline);
+                }
+                catch {
+                    return fulfillmentUnavailableResponse({
+                        settlementResponse: signedPayerBroadcastRecoveryResponse(signature, polling.transactionHash) ?? new Response(null),
+                        attemptId: signedAttemptId,
+                        requestId: null,
+                        outcome: "unknown",
+                        retryable: true,
+                    });
+                }
+            }
+            // A challenge is the last moment before a payer is asked for money, and
+            // the only moment an un-upgraded backend can still be refused for free.
+            // Every response a payer could ACT on is checked — the 402 offer and any
+            // 2xx, since a backend that ignored `GENESISPAY-Version` may answer either
+            // and the success path below would then describe a request in which
+            // nothing was paid. A 4xx/5xx offers nothing to settle against, so it
+            // passes through as itself rather than being relabelled a version problem;
+            // reporting an outage as "upgrade your backend" sends people to the wrong
+            // runbook.
+            const payableChallenge = !signature && (response.ok || response.status === 402);
+            if (payableChallenge && !(await respondedWithStrictVersion(response))) {
+                return strictNegotiationFailedResponse(response);
+            }
+            if (!response.ok) {
+                if (payerBroadcastRecovery &&
+                    response.status < 500) {
+                    return fulfillmentUnavailableResponse({
+                        settlementResponse: payerBroadcastRecovery,
+                        attemptId: signedAttemptId,
+                        requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                        outcome: "unknown",
+                        retryable: true,
+                    });
+                }
+                if (response.status >= 500 &&
+                    (signedAttemptId || payerBroadcastRecovery)) {
+                    if (!signedAttemptId) {
+                        return fulfillmentUnavailableResponse({
+                            settlementResponse: payerBroadcastRecovery ?? new Response(null),
+                            attemptId: null,
+                            requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                            outcome: "unknown",
+                            retryable: true,
+                        });
+                    }
+                    const recovery = await classifyStrictRecoveryResponse(response, signedAttemptId);
+                    if (recovery === "copy")
+                        return copyResponse(response);
+                    // Only a backend that DECLARED a permanent evidence contradiction has
+                    // told us a payment confirmed. An unstructured 5xx may have failed
+                    // before the signature was ever verified, and a response about
+                    // another attempt (or from another API version) is not about this
+                    // payment at all — both leave the outcome unknown.
+                    const declaredPermanent = recovery === "declared_inconsistent";
+                    return fulfillmentUnavailableResponse({
+                        settlementResponse: recovery === "conflicting_identity"
+                            ? payerBroadcastRecovery ?? new Response(null)
+                            : payerBroadcastRecovery ?? response,
+                        attemptId: signedAttemptId,
+                        requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                        outcome: declaredPermanent ? "confirmed" : "unknown",
+                        retryable: !declaredPermanent,
+                    });
+                }
                 return copyResponse(response);
-            // Product data is presentation/context, never payment authority. Reading
-            // it after a signed retry is safe even if delivery has changed; GenesisPay
-            // already checked the intent's seller/product/link ownership.
-            product ??= await input.retrieve();
-            const extension = asRecord(payment?.extensions);
-            const handlerResponse = await handler(request, {
-                product: { publicId: product.publicId, sku: product.sku, quantity: 1 },
-                payment: {
+            }
+            const payment = asRecord(await response.clone().json().catch(() => null));
+            const resolvedAttempt = resolveSettlementAttemptId(response, payment);
+            if (!resolvedAttempt.ok) {
+                // A 2xx that carries no usable attempt identity did not establish a
+                // confirmation — a proxy answering 200 with its own page says nothing
+                // about this payment. Same skepticism an unstructured 5xx gets: report
+                // the outcome as unknown and point the caller at retry/reconciliation.
+                // The signed attempt id survives as the locator so the caller has
+                // something concrete to reconcile against.
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: hasConflictingAttemptIdentity(response, payment, signedAttemptId)
+                        ? new Response(null)
+                        : response,
+                    attemptId: signedAttemptId,
+                    requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                    outcome: "unknown",
+                    retryable: true,
+                });
+            }
+            const { attemptId } = resolvedAttempt;
+            if (signedAttemptId && signedAttemptId !== attemptId) {
+                // The response named a different attempt than the one this request
+                // signed for. Keep the signed attempt as the reconciliation locator:
+                // it is the attempt the caller asked about. Neither the confirmation
+                // nor the receipt for that other attempt says what happened to this one.
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: new Response(null),
+                    attemptId: signedAttemptId,
+                    requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                    outcome: "unknown",
+                    retryable: true,
+                });
+            }
+            // An attempt ID alone is a locator. Only a strict successful settlement
+            // response establishes confirmation before the independent verification
+            // succeeds; lost metadata must not turn a later outage into a money claim.
+            const settlementConfirmed = payment?.success === true && isStrictVersionedResponse(response, payment);
+            let verification;
+            try {
+                verification = await input.verifyFulfillment({
+                    locator: { attemptId },
+                    expected,
+                });
+            }
+            catch (error) {
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: response,
                     attemptId,
-                    txHash: typeof payment?.transaction === "string" ? payment.transaction : "",
-                    payer: optionalString(payment?.payer), asset: "USDC", amountMinor: toAmountString(payment?.amount),
-                    chainId: payment && Number.isInteger(payment.chainId) ? payment.chainId : 8453,
-                    simulated: false, idempotentReplay: extension?.idempotentReplay === true,
-                },
+                    requestId: authorityRequestId(error) ?? response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+                    outcome: settlementConfirmed ? "confirmed" : "unknown",
+                    retryable: !isPermanentAuthorityError(error),
+                });
+            }
+            if (!verification.verified) {
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: response,
+                    attemptId,
+                    requestId: verification.requestId,
+                    // A negative authority lookup cannot corroborate the settlement
+                    // response. Preserve that uncertainty instead of asserting payment.
+                    outcome: "unknown",
+                    retryable: verification.reason === "not_found" || verification.reason === "not_confirmed",
+                });
+            }
+            const verifiedProduct = verification.payment.product;
+            if (!verifiedProduct) {
+                return fulfillmentUnavailableResponse({
+                    settlementResponse: response,
+                    attemptId,
+                    requestId: verification.requestId,
+                    outcome: "confirmed",
+                    retryable: false,
+                });
+            }
+            const handlerResponse = await handler(request, {
+                product: { ...verifiedProduct, quantity: 1 },
+                payment: verification.payment,
                 requestFingerprint,
             });
             const out = new Headers(handlerResponse.headers);
@@ -271,10 +775,510 @@ function createProductGate(input) {
         },
     };
 }
-async function fingerprintRequest(request) {
+async function pollProductSettlement(input) {
+    if (!input.statusRequest) {
+        return {
+            settled: false,
+            response: await copyPendingSettlementResponse(input.acceptanceResponse, input.fallbackSettlementResponse),
+        };
+    }
+    const acceptance = asRecord(await productStatusBeforeDeadline(() => input.acceptanceResponse.clone().json().catch(() => null), input.timeoutDeadline));
+    const expiresAtMs = typeof acceptance?.expiresAt === "string"
+        ? Date.parse(acceptance.expiresAt)
+        : Number.NaN;
+    if (acceptance?.version !== 1 ||
+        acceptance.state !== "queued" ||
+        acceptance.planId !== input.planId ||
+        !Number.isFinite(expiresAtMs)) {
+        return {
+            settled: false,
+            response: await copyPendingSettlementResponse(input.acceptanceResponse, input.fallbackSettlementResponse),
+        };
+    }
+    const pollAfterMs = typeof acceptance.pollAfterMs === "number"
+        ? Math.min(Math.max(Math.floor(acceptance.pollAfterMs), 100), 2_000)
+        : 500;
+    const timeoutDeadline = input.timeoutDeadline;
+    let deadline = Math.min(expiresAtMs, timeoutDeadline);
+    let submittedTxHash = null;
+    let lastPendingResponse = await copyPendingSettlementResponse(input.acceptanceResponse.clone(), input.fallbackSettlementResponse);
+    // A replayed durable acceptance can be older than its issuance window while
+    // its status is already submitted or settled. Read status once in that case;
+    // repeat only inside the applicable queue/reconciliation deadline.
+    let firstPoll = true;
+    while (firstPoll || Date.now() < deadline) {
+        const replayRead = firstPoll;
+        firstPoll = false;
+        let statusResponse;
+        let status;
+        try {
+            ({ response: statusResponse, status } = await productStatusBeforeDeadline(async () => {
+                const rawResponse = await input.statusRequest(input.planId);
+                const bytes = await rawResponse.arrayBuffer();
+                const response = new Response(bytes, {
+                    status: rawResponse.status,
+                    statusText: rawResponse.statusText,
+                    headers: rawResponse.headers,
+                });
+                return {
+                    response,
+                    status: asRecord(await response.clone().json().catch(() => null)),
+                };
+            }, replayRead && deadline <= Date.now() ? timeoutDeadline : deadline));
+        }
+        catch {
+            return { settled: false, response: lastPendingResponse };
+        }
+        if (statusResponse.ok &&
+            (status?.version !== 1 || status.planId !== input.planId)) {
+            return { settled: false, response: lastPendingResponse };
+        }
+        if (statusResponse.ok &&
+            status?.state === "settled" &&
+            status.sellerTransferVerified === true &&
+            typeof status.txHash === "string" &&
+            /^0x[0-9a-fA-F]{64}$/.test(status.txHash)) {
+            return {
+                settled: true,
+                transactionHash: status.txHash,
+            };
+        }
+        if (!statusResponse.ok) {
+            return {
+                settled: false,
+                response: submittedTxHash
+                    ? lastPendingResponse
+                    : await copyResponse(statusResponse),
+            };
+        }
+        if (status?.state === "failed" || status?.state === "expired") {
+            if (submittedTxHash) {
+                return { settled: false, response: lastPendingResponse };
+            }
+            if (statusResponse.ok && status?.state === "failed") {
+                return {
+                    settled: false,
+                    response: await copyTerminalSettlementResponse(statusResponse, 409),
+                };
+            }
+            if (statusResponse.ok && status?.state === "expired") {
+                return {
+                    settled: false,
+                    response: await copyTerminalSettlementResponse(statusResponse, 410),
+                };
+            }
+        }
+        if (status?.state !== "queued" && status?.state !== "submitted") {
+            return { settled: false, response: lastPendingResponse };
+        }
+        if (status.state === "submitted") {
+            if (typeof status.txHash !== "string" ||
+                !/^0x[0-9a-fA-F]{64}$/.test(status.txHash)) {
+                return { settled: false, response: lastPendingResponse };
+            }
+            const candidate = status.txHash;
+            if (submittedTxHash &&
+                submittedTxHash.toLowerCase() !== candidate.toLowerCase()) {
+                return { settled: false, response: lastPendingResponse };
+            }
+            submittedTxHash = candidate;
+            deadline = timeoutDeadline;
+        }
+        lastPendingResponse = await copyPendingSettlementResponse(statusResponse.clone(), input.fallbackSettlementResponse);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(pollAfterMs, remainingMs)));
+    }
+    return { settled: false, response: lastPendingResponse };
+}
+async function productStatusBeforeDeadline(request, deadlineMs) {
+    const remainingMs = deadlineMs - Date.now();
+    if (remainingMs <= 0)
+        throw new Error("settlement polling deadline exceeded");
+    let timer;
+    try {
+        return await Promise.race([
+            request(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error("settlement polling deadline exceeded")), remainingMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function productResponseBeforeDeadline(request, deadlineMs) {
+    return productStatusBeforeDeadline(async () => {
+        const rawResponse = await request();
+        const bytes = await rawResponse.arrayBuffer();
+        return new Response(bytes, {
+            status: rawResponse.status,
+            statusText: rawResponse.statusText,
+            headers: rawResponse.headers,
+        });
+    }, deadlineMs);
+}
+function resolveSettlementAttemptId(response, payment) {
+    const bodyValue = payment?.paymentAttemptId;
+    const headerValue = response.headers.get(GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER);
+    const valid = (value) => typeof value === "string" && value.length > 0 && value.trim() === value;
+    if (bodyValue !== undefined && !valid(bodyValue))
+        return { ok: false };
+    if (headerValue !== null && !valid(headerValue))
+        return { ok: false };
+    if (valid(bodyValue) && valid(headerValue) && bodyValue !== headerValue) {
+        return { ok: false };
+    }
+    const attemptId = valid(bodyValue) ? bodyValue : headerValue;
+    return valid(attemptId) ? { ok: true, attemptId } : { ok: false };
+}
+function invalidPrepareRequest() {
+    return {
+        ok: false,
+        response: Response.json({ error: "Invalid settlement preparation request.", code: "invalid_request" }, { status: 422 }),
+    };
+}
+/**
+ * Legacy preparation (no params header): the request BODY is the plan
+ * parameters, so it cannot be the purchase body. Kept byte-for-byte for GET
+ * resources, hosted links and engines that predate the params header.
+ */
+async function readLegacyPrepareBody(request) {
+    const preparedBody = asRecord(await request.clone().json().catch(() => null));
+    const payer = preparedBody?.payer;
+    const idempotencyKey = preparedBody?.idempotencyKey;
+    const feeMode = preparedBody?.feeMode;
+    const authority = preparedBody?.authority;
+    const attemptId = gateAttemptIdFromUrl(request.url);
+    if (typeof payer !== "string" ||
+        !/^0x[0-9a-fA-F]{40}$/.test(payer) ||
+        (idempotencyKey !== null && typeof idempotencyKey !== "string") ||
+        (feeMode !== "collect" && feeMode !== "record_only") ||
+        !attemptId) {
+        return invalidPrepareRequest();
+    }
+    return { ok: true, payer, idempotencyKey, feeMode, authority, attemptId };
+}
+/**
+ * Purchase-bound preparation (ADR-0083): the plan parameters travel in
+ * `GENESISPAY-Settlement-Prepare-Params`, so the request itself repeats the
+ * purchase — method, URL and body. It must therefore match the expected gate
+ * intent exactly as the challenge and the signed retry do; a preparation for a
+ * different request is refused before GenesisPay freezes any authority
+ * (MR-1011). A present but malformed header is refused, never read as a body.
+ */
+async function readPurchaseBoundPrepareParams(request, paramsHeader, expectedGate) {
+    const params = decodeSettlementPrepareParamsHeader(paramsHeader);
+    const attemptId = gateAttemptIdFromUrl(request.url);
+    if (!params || !attemptId)
+        return invalidPrepareRequest();
+    let requestUrl;
+    let requestFingerprint;
+    try {
+        requestUrl = canonicalRequestUrl(request.url);
+        requestFingerprint = await createGateRequestFingerprint(request);
+    }
+    catch {
+        return invalidPrepareRequest();
+    }
+    const mismatches = [
+        ...(requestUrl === expectedGate.resourceUrl ? [] : ["product.delivery.gate.resourceUrl"]),
+        ...(request.method.toUpperCase() === expectedGate.method
+            ? []
+            : ["product.delivery.gate.method"]),
+        ...(requestFingerprint === expectedGate.fingerprint
+            ? []
+            : ["product.delivery.gate.fingerprint"]),
+    ];
+    if (mismatches.length > 0) {
+        return {
+            ok: false,
+            response: Response.json({
+                error: `The preparation request does not match the expected gate intent (${mismatches.join(", ")}).`,
+                code: "contract_mismatch",
+                mismatches,
+            }, { status: 422 }),
+        };
+    }
+    return {
+        ok: true,
+        payer: params.payer,
+        idempotencyKey: params.idempotencyKey,
+        feeMode: params.feeMode,
+        authority: params.authority,
+        attemptId,
+    };
+}
+function gateAttemptIdFromUrl(value) {
+    try {
+        const attemptId = new URL(value).searchParams.get("gp_attempt");
+        return attemptId &&
+            /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(attemptId)
+            ? attemptId
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Missing identity is inconclusive; an explicit contradiction invalidates its receipt. */
+function hasConflictingAttemptIdentity(response, body, signedAttemptId) {
+    const headerAttemptId = response.headers.get(GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER);
+    const bodyAttemptId = body?.paymentAttemptId;
+    return ((signedAttemptId !== null &&
+        ((headerAttemptId !== null && headerAttemptId !== signedAttemptId) ||
+            (bodyAttemptId !== undefined && bodyAttemptId !== signedAttemptId))) ||
+        (headerAttemptId !== null && bodyAttemptId !== undefined && headerAttemptId !== bodyAttemptId));
+}
+/**
+ * What a 5xx from a signed settlement can be trusted to mean.
+ *
+ * - `copy` — a complete strict recovery answer about THIS attempt; pass it on.
+ * - `declared_inconsistent` — the backend itself declared a permanent evidence
+ *   contradiction for this attempt, which implies a persisted confirmation.
+ * - `conflicting_identity` — the response names another attempt or another API
+ *   version; it says nothing about this payment.
+ * - `unstructured` — an opaque 5xx that may predate signature verification.
+ */
+async function classifyStrictRecoveryResponse(response, signedAttemptId) {
+    const body = asRecord(await response.clone().json().catch(() => null));
+    const error = asRecord(body?.error);
+    const headerAttemptId = response.headers.get(GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER);
+    const bodyAttemptId = body?.paymentAttemptId;
+    const headerVersion = response.headers.get(GENESISPAY_VERSION_HEADER);
+    const bodyVersion = body?.apiVersion;
+    const headerRequestId = response.headers.get(GENESISPAY_REQUEST_ID_HEADER);
+    const bodyRequestId = body?.requestId;
+    if (hasConflictingAttemptIdentity(response, body, signedAttemptId) ||
+        (headerVersion !== null && headerVersion !== GENESISPAY_API_VERSION) ||
+        (bodyVersion !== undefined && bodyVersion !== GENESISPAY_API_VERSION) ||
+        (headerRequestId !== null &&
+            bodyRequestId !== undefined &&
+            headerRequestId !== bodyRequestId)) {
+        return "conflicting_identity";
+    }
+    // Other 5xx statuses are opaque outcomes, but their explicit identities must
+    // still be checked before retaining any PAYMENT-RESPONSE during recovery.
+    if (response.status !== 503)
+        return "unstructured";
+    const retryable = error?.retryable;
+    const code = error?.code;
+    const retryHeader = response.headers.get("retry-after");
+    const cacheControl = response.headers.get("cache-control") ?? "";
+    const hasNoStore = cacheControl
+        .split(",")
+        .some((directive) => directive.trim().toLowerCase() === "no-store");
+    const requestIdIsValid = typeof bodyRequestId === "string" &&
+        bodyRequestId.length > 0 &&
+        bodyRequestId === headerRequestId;
+    const errorIsValid = typeof error?.message === "string" &&
+        (((code === "fulfillment_evidence_unavailable" ||
+            code === "settlement_outcome_unknown") &&
+            retryable === true &&
+            retryHeader === "2") ||
+            (code === "fulfillment_evidence_inconsistent" &&
+                retryable === false &&
+                retryHeader === null));
+    const completeStrictRecovery = headerAttemptId === signedAttemptId &&
+        bodyAttemptId === signedAttemptId &&
+        headerVersion === GENESISPAY_API_VERSION &&
+        bodyVersion === GENESISPAY_API_VERSION &&
+        requestIdIsValid &&
+        hasNoStore &&
+        errorIsValid;
+    if (completeStrictRecovery)
+        return "copy";
+    // A backend that has already identified a deterministic evidence
+    // contradiction must never be made retryable merely because some response
+    // metadata was lost or malformed in transit. Conflicting identities were
+    // rejected above; preserve the fail-closed permanent classification here.
+    if (code === "fulfillment_evidence_inconsistent" && retryable === false) {
+        return "declared_inconsistent";
+    }
+    return "unstructured";
+}
+function resolveSignedRequestAttemptId(requestUrl, signature) {
+    const requestAttemptId = readAttemptId(requestUrl);
+    let payloadAttemptId = null;
+    try {
+        const payloadUrl = decodePaymentSignatureHeader(signature).resource?.url;
+        payloadAttemptId = payloadUrl ? readAttemptId(payloadUrl) : null;
+    }
+    catch {
+        // The backend owns full signature validation. A malformed signature cannot
+        // supply a recovery locator, but it should still receive the normal x402
+        // error response when transport succeeds.
+    }
+    if (requestAttemptId && payloadAttemptId && requestAttemptId !== payloadAttemptId) {
+        throw new GenesisPayAmbiguousLocatorError("The signed request URL and PAYMENT-SIGNATURE carry different payment attempt IDs.");
+    }
+    return requestAttemptId ?? payloadAttemptId;
+}
+function signedPayerBroadcastRecoveryResponse(signature, knownTransactionHash) {
+    try {
+        const payment = decodePaymentSignatureHeader(signature);
+        const extensions = payment.extensions;
+        let transactionHash = knownTransactionHash ?? null;
+        if (!transactionHash && extensions) {
+            for (const key of ["txHash", "transaction", "transactionHash"]) {
+                const value = extensions[key];
+                if (typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value)) {
+                    transactionHash = value;
+                    break;
+                }
+            }
+        }
+        if (!transactionHash)
+            return null;
+        const settlement = {
+            success: false,
+            transaction: transactionHash,
+            network: payment.accepted.network,
+            amount: payment.accepted.amount,
+            errorReason: "The payer transaction may already be on-chain. Do not send another payment; retry or reconcile this attempt.",
+            extensions: {
+                authorizationVerified: false,
+                settlementVerified: false,
+                persistenceVerified: false,
+            },
+        };
+        return new Response(null, {
+            headers: {
+                [PAYMENT_RESPONSE_HEADER]: encodeSettlementResponseHeader(settlement),
+            },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function knownBroadcastPreflightFailureResponse(input) {
+    return fulfillmentUnavailableResponse({
+        settlementResponse: input.settlementResponse,
+        attemptId: input.attemptId,
+        requestId: null,
+        outcome: "unknown",
+        retryable: true,
+    });
+}
+function readAttemptId(value) {
+    try {
+        const attemptId = new URL(value).searchParams.get("gp_attempt");
+        return attemptId && attemptId.length <= 120 && attemptId.trim() === attemptId
+            ? attemptId
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Canonical SHA-256 gate intent fingerprint used in ExpectedProductContract. */
+export async function createGateRequestFingerprint(request) {
     const body = new Uint8Array(await request.clone().arrayBuffer());
     const bodyHash = await sha256(body);
-    return sha256(new TextEncoder().encode(`${request.method.toUpperCase()}\n${canonicalRequestUrl(request.url)}\n${bodyHash}`));
+    const fingerprint = await sha256(new TextEncoder().encode(`${request.method.toUpperCase()}\n${canonicalRequestUrl(request.url)}\n${bodyHash}`));
+    return `sha256:${fingerprint}`;
+}
+function isPermanentAuthorityError(error) {
+    return (error instanceof GenesisPayContractMismatchError ||
+        error instanceof GenesisPayAmbiguousLocatorError ||
+        error instanceof GenesisPayEvidenceError ||
+        error instanceof GenesisPayVersionError);
+}
+function authorityRequestId(error) {
+    if (!error || typeof error !== "object" || !("requestId" in error))
+        return null;
+    return typeof error.requestId === "string" ? error.requestId : null;
+}
+/**
+ * The one response shape a strict gate returns when it cannot fulfil.
+ *
+ * `outcome` is the money claim, and it is not cosmetic: only a settlement this
+ * SDK saw succeed may say "payment was confirmed". When the settlement outcome
+ * is unknown — no response at all, or a 5xx that carries no strict evidence of
+ * what happened — the caller is told exactly that and pointed at reconciliation,
+ * because fulfilling on a payment that may never have happened is the failure
+ * this whole surface exists to prevent (MR-804).
+ */
+function fulfillmentUnavailableResponse(input) {
+    const code = !input.retryable
+        ? "fulfillment_evidence_inconsistent"
+        : input.outcome === "unknown"
+            ? "settlement_outcome_unknown"
+            : "fulfillment_evidence_unavailable";
+    const message = !input.retryable
+        ? "Fulfillment evidence requires operator intervention. Reconcile the payment attempt before fulfilling."
+        : input.outcome === "unknown"
+            ? "The settlement outcome for this payment attempt is unknown. Retry, or reconcile the attempt with the fulfillment verification API, before fulfilling."
+            : "Payment was confirmed but fulfillment evidence is temporarily unavailable.";
+    const headers = new Headers({
+        "content-type": "application/json",
+        "cache-control": "no-store",
+        [GENESISPAY_VERSION_HEADER]: GENESISPAY_API_VERSION,
+    });
+    if (input.retryable)
+        headers.set("retry-after", "2");
+    if (input.attemptId) {
+        headers.set(GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER, input.attemptId);
+    }
+    if (input.requestId)
+        headers.set(GENESISPAY_REQUEST_ID_HEADER, input.requestId);
+    const paymentResponse = input.settlementResponse.headers.get(PAYMENT_RESPONSE_HEADER);
+    if (paymentResponse)
+        headers.set(PAYMENT_RESPONSE_HEADER, paymentResponse);
+    return Response.json({
+        error: { code, message, retryable: input.retryable },
+        paymentAttemptId: input.attemptId,
+        requestId: input.requestId,
+        apiVersion: GENESISPAY_API_VERSION,
+    }, { status: 503, headers });
+}
+/**
+ * Did this response come from a backend that actually speaks the strict API
+ * version we asked for? Reads a cloned body so the caller can still use the
+ * original response.
+ */
+async function respondedWithStrictVersion(response) {
+    const body = await response.clone().json().catch(() => null);
+    return isStrictVersionedResponse(response, body);
+}
+/**
+ * The safe answer to an un-negotiated challenge: NOT a 402. It carries no
+ * `accepts` offer and no PAYMENT-REQUIRED semantics, so no payer can settle
+ * against it and no unverifiable attempt is created.
+ *
+ * The backend a challenge reached is the backend a settlement would reach, so
+ * refusing here is also what keeps the settle path from ever meeting a 0.x
+ * dialect it cannot establish evidence against.
+ */
+function strictNegotiationFailedResponse(response) {
+    return Response.json({
+        error: {
+            code: "strict_version_unsupported",
+            message: `This GenesisPay backend did not answer ${GENESISPAY_API_VERSION}. ` +
+                "Upgrade the GenesisPay deployment before serving strict product gates; " +
+                "no payment was requested.",
+            retryable: false,
+        },
+        paymentAttemptId: null,
+        requestId: response.headers.get(GENESISPAY_REQUEST_ID_HEADER),
+        apiVersion: GENESISPAY_API_VERSION,
+    }, {
+        status: 503,
+        headers: {
+            "cache-control": "no-store",
+            [GENESISPAY_VERSION_HEADER]: GENESISPAY_API_VERSION,
+        },
+    });
+}
+function toWireExpectedProductContract(expected) {
+    return {
+        ...expected,
+        grossAmountMinor: expected.grossAmountMinor.toString(),
+    };
 }
 function canonicalRequestUrl(value) {
     const url = new URL(value);
@@ -292,4 +1296,22 @@ async function sha256(value) {
 async function copyResponse(response) {
     return new Response(await response.arrayBuffer(), { status: response.status, statusText: response.statusText, headers: response.headers });
 }
+async function copyPendingSettlementResponse(response, fallbackSettlementResponse) {
+    const headers = new Headers(response.headers);
+    const paymentResponse = headers.get(PAYMENT_RESPONSE_HEADER) ??
+        fallbackSettlementResponse?.headers.get(PAYMENT_RESPONSE_HEADER);
+    if (paymentResponse)
+        headers.set(PAYMENT_RESPONSE_HEADER, paymentResponse);
+    return new Response(await response.arrayBuffer(), {
+        status: 202,
+        headers,
+    });
+}
+async function copyTerminalSettlementResponse(response, status) {
+    const headers = new Headers(response.headers);
+    // A terminal queue status is not a settlement receipt. Never let a status
+    // endpoint's accidental success header escape through the protected gate.
+    headers.delete(PAYMENT_RESPONSE_HEADER);
+    return new Response(await response.arrayBuffer(), { status, headers });
+}
 //# sourceMappingURL=products.js.map