@genesis-tech/genesispay-seller 0.13.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,201 @@
 # Changelog
 
+## 1.3.0 — purchase-bound settlement preparation
+
+Additive; requires protocol `^0.5.0`.
+
+- Product gates (`products.gate(...).protect`) and the generic
+  `createPaymentGate(...).wrap` accept settlement-preparation parameters from
+  `GENESISPAY-Settlement-Prepare-Params` when `GENESISPAY-Settlement-Prepare: 1`
+  is present. The request body is then the purchase body, so a route may parse
+  and validate it before calling the gate (ADR-0083).
+- In that mode a product gate recomputes the canonical method, resource URL and
+  request fingerprint and requires them to equal the expected gate intent. A
+  mismatch answers `422 { code: "contract_mismatch", mismatches }` and nothing
+  is forwarded to GenesisPay; a present but malformed params header answers
+  `422 { code: "invalid_request" }` and is never replaced by the body.
+- The generic gate binds no request fingerprint; in header mode it treats the
+  body as opaque purchase content and never reads it.
+- Without the params header both gates behave exactly as in 1.2.1: the body
+  carries the plan parameters (GET resources, hosted links, older engines).
+- The `prepare` action sent to GenesisPay is unchanged.
+- Document the beta lock on new mandate authority. A locked deployment answers
+  HTTP `409` `mandate_authority_locked_for_beta` (no `Retry-After`) for
+  `mandates.create`, the `contract_mandate_v1` proposal/activation helpers,
+  `mandates.proposeContractUsage` and `plans.create`.
+  `mandates.submitContractUsage`, revocation, reads and the x402 payment gate
+  are unaffected. Documentation only; no SDK source change and no publication.
+
+## 1.2.1 — settlement ambiguity and terminal polling fixes
+
+- Preserve a payer-supplied transaction hash when a custom settlement verifier
+  throws, returning a non-success reconciliation response instead of losing the
+  locator.
+- Map asynchronously polled `failed` and `expired` product settlements to HTTP
+  409 and 410. Terminal status never looks like successful resource delivery,
+  never runs the protected handler, and never forwards `PAYMENT-RESPONSE`.
+- Require synchronous facilitator success to carry a full transaction hash,
+  exact network, exact integer minor amount, exact known payer and both explicit
+  authorization/settlement verification flags before the paid handler runs.
+- Document the already-exported experimental `contract_mandate_v1` helpers:
+  `mandates.createContractSubscription`, `createContractPerUse`,
+  `proposeContractUsage`, `submitContractUsage`, and `getContractUsage`, plus
+  their result/input types. They independently rebuild typed data and fail
+  closed on inconsistent authority. Their presence does not enable backend
+  admission or grant Mainnet clearance.
+
+## 1.2.0 — hosted checkout documents and asynchronous settlement
+
+Built on the strict 1.1.0 SDK and protocol 0.4 contract; no npm publication is
+part of this change. Strict creation still requires an idempotency key and
+versioned responses, and only `fulfillment.verify()` grants payment authority.
+
+### Added
+
+- The facilitator settlement adapter accepts versioned HTTP 202 queue
+  acceptance, polls the same-origin seller-key status URL, and reports success
+  only after GenesisPay verifies the seller transfer and returns its real hash.
+- Strict product gates poll seller-scoped settlement status after 202 and retry
+  the gate request only after seller confirmation. `queued` and `submitted`
+  never authorize resource delivery; failed, expired, malformed and timed-out
+  status remains fail-closed.
+- `settlementPollTimeoutMs` configures the facilitator adapter's bounded poll
+  window (120 seconds by default). Legacy synchronous 200 settlement remains
+  compatible.
+
+- Plan-aware x402 gates advertise a preparation handshake, proxy exact
+  pre-sign authority through the GenesisPay facilitator, and submit the returned
+  plan id with settlement. Signed-first clients receive an upgrade refusal
+  before broadcast; current on-chain transfers are unchanged (MR-1011).
+
+- **`genesispay.checkoutDocuments.list()`** lists the seller's immutable formal
+  invoices and enhanced receipts created after confirmed, non-simulated hosted
+  human checkout payments.
+- **`genesispay.checkoutDocuments.get(publicId)`** retrieves one document; the
+  authenticated API also exposes `GET /api/v1/checkout-documents/:publicId/pdf`.
+- Products and checkout requests expose explicit inclusive `taxConfig`; product
+  updates and `checkout.updateTax()` use `expectedTaxConfig` conflict detection.
+- New manual invoices use inclusive per-line tax and produce an invoice/receipt
+  pair after real payment. Existing finalized documents stay immutable.
+
+### Safety
+
+- Checkout documents are read-only snapshots, not the manual
+  `genesispay.invoices.*` lifecycle. A missing `invoiceNumber` means an honest
+  enhanced receipt rather than a guessed or incomplete formal invoice.
+- New standalone checkout requests are single-use; repeat purchases use products.
+  Legacy generic reusable links close after payment, preserving their history.
+
+## 1.1.0 — durable fulfillment notifications (release candidate)
+
+- Add typed `payment.fulfilled` notifications with strict envelope/evidence shape
+  checks after raw-body HMAC verification. Wire amounts remain strings;
+  authenticated `fulfillment.verify` is still required for economic authority.
+- Add `fulfillment.listAttempts` with scoped, versioned keyset discovery for
+  missing-notification recovery. Historical candidates never authorize fulfillment.
+- Document stable source event IDs, nine-send retry cycles, explicit replay and
+  attempt/intent-keyed atomic credit handling across webhook and reconciliation.
+
+## 1.0.0 — strict fulfilment authority
+
+Breaking authority contract. Existing tolerant checkout, product, entitlement,
+and webhook views remain available for display, correlation, and migration, but
+they are not proof that a seller may fulfil an order.
+
+### Added
+
+- `genesispay.fulfillment.verify({ locator, expected })`, the only public SDK
+  path that returns strict payment authority. It always retrieves evidence from
+  the seller-authenticated GenesisPay API; no public method accepts a
+  caller-created evidence object.
+- Exact `ExpectedProductContract`, `ExpectedPaymentLinkContract`,
+  `FulfillmentLocator`, `FulfillmentVerification`, and `VerifiedPayment` types.
+  Money is `bigint` minor units in application code and bounded canonical
+  decimal strings on the wire.
+- Explicit `GENESISPAY-Version: 2026-08-26` negotiation plus matching
+  `GENESISPAY-Request-Id` and version metadata on successful and negative
+  results.
+- Typed `GenesisPayContractMismatchError`,
+  `GenesisPayAmbiguousLocatorError`, `GenesisPayEvidenceError`, and
+  `GenesisPayVersionError`. Every SDK error now exposes nullable `requestId` and
+  `apiVersion` properties; they are null only when no versioned response exists.
+- `products.assertContract(expected)` and idempotent
+  `products.createCheckout({ expected, ... }, { idempotencyKey })`. The latter
+  returns an explicit `product_checkout_link` with `linkId`, never an ambiguous
+  checkout `id`.
+- `createGateRequestFingerprint(request)` and the breaking
+  `products.gate(id).protect(request, expected, handler)` signature. A product
+  handler now receives only strictly verified payment/product fields.
+
+### Safety
+
+- Strict fee validation distinguishes a supported 100%-of-gross record-only
+  quote from an authorized deduction: the former preserves the full seller
+  payment; the latter must leave a positive seller amount. Quotes above gross
+  fail closed in both backend and SDK.
+- The configured `expectedPayTo` pin also guards strict product contract checks,
+  checkout creation and gate protection, authenticated checkout retrieval, and
+  strict fulfillment verification. Missing/conflicting retrieved destinations
+  fail closed; a caller's expected contract cannot override the pin. Historical
+  reconciliation after wallet rotation uses a client pinned to the original
+  order destination. Clients without a pin retain their existing behavior.
+- Strict `checkout.create` errors preserve request/version correlation from
+  response headers or body while retaining validation, rate-limit and other
+  typed HTTP errors, including interrupted or non-JSON error responses.
+- MR-102/MR-103: mode, Base network, chain, asset, token address, and six-decimal
+  scale are cross-validated against the SDK's audited USDC/EURC deployment
+  registry before a result can be verified.
+- MR-202: locator identity, exact gross amount, frozen destination, product/SKU,
+  and complete delivery or gate intent must match the expected immutable
+  contract. Contract mismatches throw and include the mismatched field paths.
+- MR-804: verified evidence requires the literal `simulated: false` and the
+  supported authority provenance version. Historical evidence without that
+  provenance fails closed instead of inheriting a default.
+- Known missing/null/wrong-typed fields, noncanonical or oversized money,
+  settlement arithmetic contradictions, unsafe/noncanonical URLs, unknown
+  payment channels, and unsupported versions fail closed. Unknown additive
+  fields remain forward compatible.
+- Direct `checkout.create` now requires `{ idempotencyKey }` and sends both
+  `Idempotency-Key` and the strict API version. There is no idempotency-free
+  money-creation overload in 1.0.
+- A product gate never defaults asset/chain or fabricates `simulated: false`.
+  Its initial challenge sends the complete validated expected contract for an
+  atomic pre-attempt comparison against the exact frozen payable link. Evidence
+  failure after settlement returns a `503` recovery response that preserves
+  a matching `PAYMENT-RESPONSE` and carries the attempt ID when one is known; permanent
+  inconsistencies are explicitly `retryable: false`.
+- Signed gate recovery cross-checks attempt IDs in the request URL, payment
+  payload, settlement body, and settlement header. A post-commit transport loss
+  returns a retryable recovery response using that locator; a settlement that
+  names a different attempt than the signed one never reaches verification or
+  the paid handler and drops that other attempt's receipt. Both this case and
+  body/header contradictions report an unknown, retryable outcome.
+- Interrupted verification response streams remain transient, while completed
+  malformed evidence stays permanent. Missing strict settlement metadata or a
+  negative `not_found`/`not_confirmed` verification never claims confirmation.
+- Strict backend creation and gate calls reject a seller key whose mode does
+  not match the payment chain before exposing or settling that payment,
+  including product checkout idempotent replay.
+- Confirmed gate retries can recover after their original authorization expires,
+  with signature and on-chain replay verification and no repeat broadcast/fee.
+  Failed/expired attempts remain terminal, including on archived links.
+- Verified network contracts no longer expose the mutable shared asset registry.
+  URL-delivery examples use entitlement verification to honor revocation/expiry.
+- Successful entitlement lookups must report a valid entitlement; payer-authorized
+  fees must leave a positive seller amount. Contradictory evidence is rejected.
+- Conflicting recovery identities discard unrelated receipts on 503, other 5xx
+  and contradictory 2xx responses, while retaining the signed attempt locator.
+- Frozen fee terms and the amount actually collected are deliberately separate:
+  a non-collecting payment may have nonzero configured fee terms with a zero
+  settled fee.
+
+### Migration
+
+Use webhook, browser-return, link, or entitlement identifiers only as locators.
+Pass an immutable expected contract to `fulfillment.verify`, fulfil only on
+`verified: true`, and alert on typed mismatch/evidence/version errors using their
+request ID. Pin this major exactly until the matching strict backend is deployed.
+
 ## 0.13.2 — clean recovery package
 
 No API or runtime behaviour change from `0.13.0`. This immutable patch release