@genesis-tech/genesispay-seller 0.8.0 → 0.11.0

package/CHANGELOG.md

@@ -1,10 +1,68 @@
 # Changelog
 
+## 0.11.0 — product-backed x402 resource gates
+
+### Added
+
+- **`delivery` on `genesispay.products.create()` and `.update()`**. A product
+  can now be a redirect entitlement, a registered HTTP resource gate, or have
+  no delivery. The flat `fulfilmentUrl` fields remain compatible with existing
+  redirect integrations.
+- **`genesispay.products.gate(productId)`**. `prime()` resolves the registered
+  gate product and canonical reusable payment link; `protect(request, handler)`
+  performs the x402 challenge/settlement exchange and runs the handler only
+  after GenesisPay confirms payment. Use `purchase.payment.attemptId` as the
+  idempotency key because confirmed payment retries may run a handler again.
+- **`genesispay.entitlements.verify(entitlementId)`**. This seller-authorized
+  hard check is for a redirect product's redemption handler; require a valid,
+  non-simulated entitlement for the expected product before granting access.
+
+### Safety
+
+- Product gates bind the pending attempt to the registered URL, upper-case HTTP
+  method, and a SHA-256 fingerprint of the raw request body. GenesisPay receives
+  the fingerprint, not the request data.
+- Gate purchases never mint redirect entitlements. Redirect products retain
+  their signed 30-day redemption URLs unchanged.
+- A product gate always derives amount, asset, destination and fees from the
+  canonical product link; callers cannot supply those money fields.
+
+## 0.9.0 — BREAKING: every identifier is now `genesispay`
+
+The legacy/visible name split is retired. This release renames the
+public surface with **no compatibility window** — the old names are not accepted
+alongside the new ones. Update all of the following at once:
+
+- Client and errors renamed: `PeerPay` → `GenesisPay`, `PeerPay*Error` →
+  `GenesisPay*Error` (including `PeerPaySignatureVerificationError`).
+- Webhook signature header `PEERPAY-SIGNATURE` → `GENESISPAY-SIGNATURE`.
+  **Verification fails silently if you do not update this** — the old header
+  simply stops arriving.
+- Seller API keys now use the `gp_sk_` prefix. Keys issued as `pp_sk_` are
+  rejected and must be reissued from the dashboard.
+- Environment variables `PEERPAY_*` → `GENESISPAY_*`.
+- Checkout return parameters `peerpay_link_id` / `peerpay_status` →
+  `genesispay_link_id` / `genesispay_status`.
+- `genesispay-settlement` module renamed to `genesispay-settlement`.
+
+### Also in this release — a real fix, not a rename
+
+`PRODUCTION_FACILITATOR_BASE_URL` pointed at `peerpay-app-production.up.railway.app`,
+a Railway-generated hostname that **never existed** — production has exactly one
+domain. Any live key used via the zero-config path (`new GenesisPay({ apiKey })`
+with no `baseUrl`) therefore resolved to a dead host. Both defaults now use the
+custom domains, which are ours and survive a Railway service rename:
+
+- live keys → `https://genesispay.finance`
+- `DEFAULT_FACILITATOR_BASE_URL` → `https://dev.genesispay.finance`
+
+Everything else in this release is a rename.
+
 ## Unreleased — renamed to `@genesis-tech/genesispay-seller`
 
-The `@genesis-tech/peerpay-seller` name was versioned here through 0.8.0 but
-never published to npm, so the first release carries the product's own name
-(ADR-0044). Every version below describes work done under the old name.
+The legacy `@genesis-tech/genesispay-seller` name was versioned here through 0.8.0
+but never published to npm, so the first npm release carried the product's own
+name (ADR-0044). 0.8.0 was published on 2026-08-07. Every version below describes work done under the old name.
 
 ## 0.8.0
 
@@ -13,9 +71,9 @@ subscription surfaces.
 
 ### Added
 
-- **`peerpay.customers.*`** — create, list, retrieve, update, and archive
+- **`genesispay.customers.*`** — create, list, retrieve, update, and archive
   reusable billing contacts.
-- **`peerpay.invoices.*`** — create/update drafts, finalize an immutable invoice,
+- **`genesispay.invoices.*`** — create/update drafts, finalize an immutable invoice,
   retrieve/list it, send it through the configured email provider, void it, or
   mark it uncollectible.
 - Finalized invoice responses include the hosted invoice URL, PDF URL, exact
@@ -40,7 +98,7 @@ Additive and backward compatible; no existing handler changes meaning.
 ### Added
 
 - **`amount` and `asset` on the `payment.confirmed` / `link.paid` payload**
-  (`PeerPayPaymentEventData["link"]`). `event.data.link.asset` names the
+  (`GenesisPayPaymentEventData["link"]`). `event.data.link.asset` names the
   currency; `event.data.link.amount` is the field whose name matches its value.
   `amountUsdcMinor` is unchanged — same integer minor units, same name.
 - **`attempt.chainId` on the same payload** — the chain `attempt.txHash` is on.
@@ -101,14 +159,14 @@ and backward compatible: nothing is removed and no existing call changes meaning
 ### Behaviour changes
 
 - `checkout.create` with **both** `amount` and `amountUsdc` set to *different*
-  amounts throws `PeerPayValidationError` and never sends the request. Equal
+  amounts throws `GenesisPayValidationError` and never sends the request. Equal
   values are fine — `"5.0"` and `"5.00"` compare as the same money, since the
   check is on minor units rather than on the strings. The server enforces the
   same rule (422) for callers that do not use this SDK.
 - `checkout.create` with **neither** field is still a **compile** error:
   `CheckoutAmountInput` is a union requiring one of the two names, so the
   guarantee the required `amountUsdc` property gave is not traded away. It also
-  throws `PeerPayValidationError` at runtime, for JavaScript callers.
+  throws `GenesisPayValidationError` at runtime, for JavaScript callers.
 - Every create request sends the amount under **both** names. A backend older
   than 0.6.0 only knows `amountUsdc` and ignores `amount`, so 0.6.0 works
   unchanged against one.
@@ -132,7 +190,7 @@ real operation.
 
 ### Added
 
-- **`peerpay.mandates.list({ planId?, status?, limit?, startingAfter? })`** —
+- **`genesispay.mandates.list({ planId?, status?, limit?, startingAfter? })`** —
   until now a mandate id arrived only on the `mandate.active` webhook, so a
   missed delivery meant a customer who wanted to cancel could not be served:
   `revoke` needs that id and there was no way to look it up. Returns
@@ -143,7 +201,7 @@ real operation.
   - `planId` takes the plan's **`publicId`**. An unknown or foreign plan returns
     an empty page rather than a 404, so it cannot be used to probe for plans.
 - **`subscriptionPlanId` on `Mandate`** and on the mandate webhook payload
-  (`PeerPayMandateEventData`). Without it a `mandate.active` handler knew *that*
+  (`GenesisPayMandateEventData`). Without it a `mandate.active` handler knew *that*
   someone subscribed but not *to what*. `null` means the mandate was proposed
   directly rather than through a plan checkout — a valid state, not missing data.
   The server sets it only in the hosted `/subscribe/:planId` flow, so a mandate
@@ -152,7 +210,7 @@ real operation.
 ### Behaviour changes
 
 - A **400** whose body carries structured `issues` now throws
-  `PeerPayValidationError` instead of `PeerPayConfigError` — the new list
+  `GenesisPayValidationError` instead of `GenesisPayConfigError` — the new list
   endpoint reports invalid query parameters that way. A 400 *without* `issues`
   is unchanged.
 
@@ -168,18 +226,18 @@ Additive except where noted under *Behaviour changes*.
 
 ### Added
 
-- **`peerpay.plans.*`** — `create`, `list`, `retrieve`, `archive` against the new
+- **`genesispay.plans.*`** — `create`, `list`, `retrieve`, `archive` against the new
   `/api/v1/plans`. Subscription plans existed before but were reachable only from
   the dashboard, which is what actually blocked building subscriptions
   programmatically. Every plan carries **`checkoutUrl`**, the hosted
   `/subscribe/:publicId` flow to hand a customer — you no longer assemble it.
-- **`peerpay.mandates.*`** — `create`, `retrieve`, `charge`, `revoke`. There is
+- **`genesispay.mandates.*`** — `create`, `retrieve`, `charge`, `revoke`. There is
   deliberately **no `activate`**: activating a mandate needs the payer's
   signature, not the seller key, so it belongs in the payer's frontend.
   `mandates.create` returns `{ mandate, permitTypedData, spender }`, and
   `permitTypedData` is passed through verbatim — a signature covers those exact
   bytes, so the SDK must not reshape them.
-- **`peerpay.checkout.simulatePayment(publicId, { payerWallet? })`** — mints a
+- **`genesispay.checkout.simulatePayment(publicId, { payerWallet? })`** — mints a
   confirmed payment in test mode and fires the real `payment.confirmed` /
   `link.paid` webhooks, so the paid path is testable without testnet USDC and
   wallet UX. Test keys only (a live key gets 403), and the endpoint does not
@@ -192,29 +250,29 @@ Additive except where noted under *Behaviour changes*.
   this flag is the only honest signal. Real payments report `false`.
 - **Typed webhook events.** `constructEvent` now returns a union discriminated on
   `type`, so `if (event.type === "payment.confirmed")` narrows `event.data` with
-  no cast. Also exported: `PEERPAY_EVENT_TYPES`, `isKnownPeerPayEventType`,
-  `PeerPayEventType`, and `PeerPayAnyEvent`/`PeerPayUnknownEvent` for handlers
+  no cast. Also exported: `GENESISPAY_EVENT_TYPES`, `isKnownGenesisPayEventType`,
+  `GenesisPayEventType`, and `GenesisPayAnyEvent`/`GenesisPayUnknownEvent` for handlers
   that want to model the open world.
   - An **unknown event type is still accepted**, verified and returned — a newer
     server must never make an older SDK reject deliveries. Only the signature or
     a malformed envelope can reject.
-  - `PeerPayEvent` has no `{ type: string }` fallback member on purpose:
+  - `GenesisPayEvent` has no `{ type: string }` fallback member on purpose:
     TypeScript disables discriminant narrowing for *every* member of a union as
-    soon as one member's discriminant is a non-literal. Use `PeerPayAnyEvent`
+    soon as one member's discriminant is a non-literal. Use `GenesisPayAnyEvent`
     (assignable from any known event, no cast) when you need the open type.
-- **`PeerPayValidationError`** (422, with structured `issues: [{path, message}]`)
-  and **`PeerPayRateLimitError`** (429, with `retryAfterSeconds` from
+- **`GenesisPayValidationError`** (422, with structured `issues: [{path, message}]`)
+  and **`GenesisPayRateLimitError`** (429, with `retryAfterSeconds` from
   `Retry-After`).
 
 ### Behaviour changes
 
-- A 422 or 429 previously surfaced as `PeerPayConfigError`. They now throw the
-  two classes above. If you branch on `PeerPayConfigError` to catch bad input,
-  update that branch — both new classes extend `Error`, not `PeerPayConfigError`.
+- A 422 or 429 previously surfaced as `GenesisPayConfigError`. They now throw the
+  two classes above. If you branch on `GenesisPayConfigError` to catch bad input,
+  update that branch — both new classes extend `Error`, not `GenesisPayConfigError`.
 - **`expectedPayTo` now also covers created objects.** It previously guarded only
   the `/api/v1/seller` config lookup, while `checkout.create` and `plans.create`
   each freeze their own `destinationWallet` — the addresses money actually moves
-  to. Both now throw `PeerPayNetworkSafetyError` on a mismatch. If you set the
+  to. Both now throw `GenesisPayNetworkSafetyError` on a mismatch. If you set the
   pin and create links for a wallet other than the pinned one, those calls will
   start failing (which is the point).
 - **An unknown `plan.status` now degrades to `archived`, not `active`.** A status
@@ -247,21 +305,21 @@ call signature changes.
   `publicId` back to a buyer.
 - **Return / cancel URLs** — `checkout.create` accepts `returnUrl` and `cancelUrl`.
   After a confirmed payment the hosted checkout shows an explicit "back to …"
-  button with `?peerpay_link_id=<publicId>&peerpay_status=paid` appended (existing
+  button with `?genesispay_link_id=<publicId>&genesispay_status=paid` appended (existing
   query parameters on your URL are preserved). Deliberately not an automatic
   timed redirect: the payer should be able to see the on-chain confirmation before
   leaving. Both must be `https` (`http` is accepted for localhost only).
 - **`checkout.retrieve(publicId)`** — reads a link's current state, including a
   `paid` boolean and `confirmedPaymentCount`, for polling without a raw fetch
-  against `/api/v1/links/:publicId`. A 404 throws the new `PeerPayNotFoundError`
-  rather than `PeerPayConfigError`, so an unknown id is distinguishable from a
+  against `/api/v1/links/:publicId`. A 404 throws the new `GenesisPayNotFoundError`
+  rather than `GenesisPayConfigError`, so an unknown id is distinguishable from a
   broken key or an unreachable backend.
 - **`constructEvent(rawBody, signatureHeader, secret, opts?)`** — webhook signature
-  verification, exported as a free function and as `peerpay.webhooks.constructEvent`.
+  verification, exported as a free function and as `genesispay.webhooks.constructEvent`.
   Constant-time comparison, a replay window on the signature timestamp (default
   300 s, rejecting future timestamps as well as stale ones), and support for
   multiple `v1=` values so an endpoint secret can be rotated without dropped
-  deliveries. Throws `PeerPaySignatureVerificationError`; no error message
+  deliveries. Throws `GenesisPaySignatureVerificationError`; no error message
   contains the secret or the expected signature.
 
 ### Note on `constructEvent` being async
@@ -273,7 +331,7 @@ Workers and Bun. Remember the `await`.
 ### Gotchas worth knowing before you upgrade
 
 - `constructEvent` returns a **Promise** (see above).
-- The `?peerpay_link_id=…&peerpay_status=paid` parameters appended to your
+- The `?genesispay_link_id=…&genesispay_status=paid` parameters appended to your
   `returnUrl` are a UI hint, **not** proof of payment — they are unsigned and a
   payer can navigate to that URL without paying. Fulfil on the webhook or on
   `checkout.retrieve().paid`.
@@ -298,20 +356,20 @@ Workers and Bun. Remember the `await`.
 
 ### Added
 
-- **`PeerPay` client** — a Stripe-like entry point that configures from just the
-  seller API key. The key prefix (`pp_sk_test_…` / `pp_sk_live_…`) determines the
+- **`GenesisPay` client** — a Stripe-like entry point that configures from just the
+  seller API key. The key prefix (`gp_sk_test_…` / `gp_sk_live_…`) determines the
   mode and base URL; the payout wallet and network are resolved from the key via the
-  new PeerPay backend endpoint `GET /api/v1/seller` and cached (single-flight, 5-min
+  new GenesisPay backend endpoint `GET /api/v1/seller` and cached (single-flight, 5-min
   TTL, failures never cached).
-  - `peerpay.checkout.create({ title, amountUsdc, … })` → hosted `payUrl` (the wallet
+  - `genesispay.checkout.create({ title, amountUsdc, … })` → hosted `payUrl` (the wallet
     is defaulted server-side from the key).
-  - `peerpay.gate({ amountUsdc }).wrap(handler)` → x402 gate with `payTo` + network
+  - `genesispay.gate({ amountUsdc }).wrap(handler)` → x402 gate with `payTo` + network
     resolved from the key and settlement auto-wired.
 - Money-safety, all fail-closed: no `402` with a null destination; `503` when the
   backend is unreachable (the paid handler never runs); asset-integrity check
   (backend USDC/chainId must match the SDK's native table); mode↔network check (a
   `live` key must not resolve to a testnet); optional `expectedPayTo` pin.
-- Exports: `PeerPay`, `PeerPayConfigError`, `PeerPayNetworkSafetyError`, and the
+- Exports: `GenesisPay`, `GenesisPayConfigError`, `GenesisPayNetworkSafetyError`, and the
   related types.
 
 ### Requirements
@@ -321,10 +379,10 @@ Workers and Bun. Remember the `await`.
 
 ### Unchanged
 
-- The low-level `createPaymentGate` / `peerPaySettlement` primitives are untouched and
+- The low-level `createPaymentGate` / `genesisPaySettlement` primitives are untouched and
   remain exported. This release is purely additive.
 
 ## 0.1.0
 
 - Initial release: framework-agnostic x402 payment gate (`createPaymentGate`,
-  `peerPaySettlement`).
+  `genesisPaySettlement`).

package/README.md

@@ -1,6 +1,6 @@
 # @genesis-tech/genesispay-seller
 
-Framework-agnostic x402 payment gate for sellers, powered by GenesisPay (formerly PeerDirect).
+Framework-agnostic x402 payment gate for sellers, powered by GenesisPay (formerly GenesisPay).
 
 Wrap any Web-standard `(Request) => Response` handler and it becomes a paid
 endpoint:
@@ -21,21 +21,21 @@ speaks the Fetch API.
 npm install @genesis-tech/genesispay-seller
 ```
 
-## Quick start (legacy `PeerPay` client — recommended)
+## Quick start (legacy `GenesisPay` client — recommended)
 
-The `PeerPay` client configures from **just the seller API key**. The key prefix
-(`pp_sk_test_…` / `pp_sk_live_…`) determines the mode and base URL, and the payout
+The `GenesisPay` client configures from **just the seller API key**. The key prefix
+(`gp_sk_test_…` / `gp_sk_live_…`) determines the mode and base URL, and the payout
 wallet + network are resolved from the key via the GenesisPay backend and cached.
 
 ```ts
-import { PeerPay } from "@genesis-tech/genesispay-seller";
+import { GenesisPay } from "@genesis-tech/genesispay-seller";
 
-const peerpay = new PeerPay({ apiKey: process.env.PEERPAY_SELLER_API_KEY! });
+const genesispay = new GenesisPay({ apiKey: process.env.GENESISPAY_SELLER_API_KEY! });
 
 // Human hosted checkout — the wallet is defaulted server-side from the key.
 // `metadata` and `clientReferenceId` come back on retrieve() and on the webhook,
 // so you never need your own table just to map a link back to a buyer:
-const { publicId, payUrl } = await peerpay.checkout.create({
+const { publicId, payUrl } = await genesispay.checkout.create({
   title: "50 credits",
   amount: "5.00", // decimal string in `asset` — see "Amounts and assets" below
   clientReferenceId: order.id,
@@ -45,13 +45,13 @@ const { publicId, payUrl } = await peerpay.checkout.create({
 });
 
 // Poll for settlement:
-const session = await peerpay.checkout.retrieve(publicId);
+const session = await genesispay.checkout.retrieve(publicId);
 if (session.paid) fulfil(session.clientReferenceId);
-// An unknown id throws PeerPayNotFoundError, not PeerPayConfigError — so a
+// An unknown id throws GenesisPayNotFoundError, not GenesisPayConfigError — so a
 // typo'd id is distinguishable from a broken key or an unreachable backend.
 
 // Agent x402 gate — payTo + network resolved from the key, settlement auto-wired:
-export const GET = peerpay.gate({ amountUsdc: "0.02" }).wrap(
+export const GET = genesispay.gate({ amountUsdc: "0.02" }).wrap(
   async () => Response.json({ data: "the good stuff" }),
 );
 ```
@@ -63,7 +63,7 @@ amount is therefore a decimal dollar string — never a number:
 
 ```ts
 // 5 USDC / 5 dollars:
-await peerpay.checkout.create({ title: "Credits", amount: "5.00" });
+await genesispay.checkout.create({ title: "Credits", amount: "5.00" });
 ```
 
 Buyers can use EUR or USD in the Privy/MoonPay flow; MoonPay converts the local
@@ -77,7 +77,7 @@ breaks.
 
 You may pass both, and the SDK sends both on the wire so a backend older than
 0.6.0 still finds the field it knows. Passing **two different amounts** throws
-`PeerPayValidationError` before the request leaves your process — a link for
+`GenesisPayValidationError` before the request leaves your process — a link for
 money you did not mean must not be created because one field quietly won.
 
 `gate({ amountUsdc })` keeps its name deliberately: an x402 gate prices a request
@@ -89,20 +89,20 @@ Prefer a webhook over polling. Verification is one call — it checks the HMAC i
 constant time and enforces a replay window on the signature timestamp:
 
 ```ts
-import { constructEvent, PeerPaySignatureVerificationError } from "@genesis-tech/genesispay-seller";
+import { constructEvent, GenesisPaySignatureVerificationError } from "@genesis-tech/genesispay-seller";
 
 export async function POST(request: Request) {
   const rawBody = await request.text(); // raw — never re-serialize before verifying
   try {
     const event = await constructEvent(
       rawBody,
-      request.headers.get("PEERPAY-SIGNATURE") ?? "",
-      process.env.PEERPAY_WEBHOOK_SECRET!,
+      request.headers.get("GENESISPAY-SIGNATURE") ?? "",
+      process.env.GENESISPAY_WEBHOOK_SECRET!,
     );
     if (event.type === "payment.confirmed") await fulfil(event.data);
     return new Response(null, { status: 204 });
   } catch (error) {
-    if (error instanceof PeerPaySignatureVerificationError) {
+    if (error instanceof GenesisPaySignatureVerificationError) {
       return new Response("invalid signature", { status: 400 });
     }
     throw error;
@@ -113,7 +113,7 @@ export async function POST(request: Request) {
 `constructEvent` is **async** — unlike Stripe's synchronous equivalent. It is built
 on WebCrypto rather than `node:crypto` so the SDK also runs on Edge, Workers and
 Bun. It is available as a free function (a webhook route rarely has a client in
-scope) and as `peerpay.webhooks.constructEvent(…)`. Default replay tolerance is
+scope) and as `genesispay.webhooks.constructEvent(…)`. Default replay tolerance is
 300 s in both directions; override with `{ toleranceSeconds }`. Multiple `v1=`
 values in the header are all checked, so you can rotate an endpoint secret without
 dropping deliveries.
@@ -172,14 +172,14 @@ build a draft, then finalize it. Finalization freezes the billing details and
 creates exactly one single-use payment link; a draft cannot be paid or emailed.
 
 ```ts
-const customer = await peerpay.customers.create({
+const customer = await genesispay.customers.create({
   name: "Ada Lovelace",
   email: "ada@example.com",
   companyName: "Analytical Engines Ltd",
   countryCode: "GB",
 });
 
-const draft = await peerpay.invoices.create({
+const draft = await genesispay.invoices.create({
   customerId: customer.publicId,
   asset: "EURC",
   dueAt: "2026-08-31T23:59:59.999Z",
@@ -189,8 +189,8 @@ const draft = await peerpay.invoices.create({
   ],
 });
 
-const invoice = await peerpay.invoices.finalize(draft.publicId);
-await peerpay.invoices.send(invoice.publicId, {
+const invoice = await genesispay.invoices.finalize(draft.publicId);
+await genesispay.invoices.send(invoice.publicId, {
   idempotencyKey: `invoice-${invoice.publicId}-initial`,
 });
 
@@ -212,7 +212,7 @@ customers. You do **not** need your own billing cron — renewals run on our
 scheduler.
 
 ```ts
-const plan = await peerpay.plans.create({
+const plan = await genesispay.plans.create({
   title: "Pro",
   amountPerPeriod: "9.00",
   periodDays: 30,
@@ -224,7 +224,7 @@ redirect(plan.checkoutUrl);
 
 The customer signs one permit there; after that, renewals are charged without
 further signatures and emit `subscription.renewed` (or `subscription.past_due`).
-`peerpay.mandates.*` exposes the per-payer authorizations underneath —
+`genesispay.mandates.*` exposes the per-payer authorizations underneath —
 `create`, `retrieve`, `charge` (per-use metering) and `revoke`.
 
 There is deliberately **no `mandates.activate`**: activation requires the payer's
@@ -237,7 +237,7 @@ server holding your secret key.
 let startingAfter: string | undefined;
 let hasMore = true;
 while (hasMore) {
-  const page = await peerpay.mandates.list({
+  const page = await genesispay.mandates.list({
     planId: plan.publicId,
     status: "active",
     startingAfter,
@@ -245,7 +245,7 @@ while (hasMore) {
   const match = page.mandates.find(
     (m) => m.payerWallet.toLowerCase() === wallet.toLowerCase(),
   );
-  if (match) return peerpay.mandates.revoke(match.id);
+  if (match) return genesispay.mandates.revoke(match.id);
   startingAfter = page.mandates.at(-1)?.id;
   hasMore = page.hasMore;
 }
@@ -259,21 +259,123 @@ Note: failed renewals are reported as events, but there is no automatic dunning
 (retry escalation, grace periods) yet — build that on
 `subscription.past_due` / `mandate.charge_failed` for now.
 
+### Products
+
+A product is a catalogue entry; its payable instance is **one canonical
+reusable checkout link**, minted idempotently — mint again (even concurrently)
+and you get the same link with `created: false`.
+
+```ts
+const product = await genesispay.products.create({
+  name: "Market data report",
+  price: "2.00",
+  sku: "MDR-1",
+  // A redirect product creates a signed, expiring entitlement on every sale.
+  delivery: {
+    type: "redirect",
+    url: "https://your-site.example/download",
+    verifiedAt: null,
+  },
+});
+
+const { link, created } = await genesispay.products.createPaymentLink(
+  product.publicId,
+);
+// Share link.payUrl — every sale of this product settles through it.
+```
+
+A confirmed purchase fires the `product.purchased` webhook. Its payload
+carries the buyer's entitlement — `entitlement.redemptionPath` is a signed,
+expiring redirect (~30 days) to your fulfilment URL, with `gp_*` parameters
+(`gp_entitlement`, `gp_attempt`, `gp_simulated`, …) you can verify server-side
+via `GET /api/v1/entitlements/verify`. Always check `simulated`: test-mode
+purchases deliver end to end, marked, so your handler must not book them as
+revenue.
+
+Use the SDK rather than trusting `gp_*` query parameters from the browser:
+
+```ts
+const verified = await genesispay.entitlements.verify(entitlementId);
+if (
+  !verified.valid ||
+  verified.entitlement.simulated ||
+  verified.entitlement.productId !== product.publicId
+) {
+  throw new Error("invalid entitlement");
+}
+// Insert verified.entitlement.publicId under a unique constraint, then fulfil.
+```
+
+### Product-backed API gate
+
+For an API you operate, define the resource and its price once in the catalogue.
+The product link—not browser input or route code—is the authority for the USDC
+amount, Base network, destination, fee snapshot and product metadata:
+
+```ts
+const forecast = await genesispay.products.create({
+  name: "Forecast API call",
+  price: "0.02",
+  sku: "prediction-forecast-v1",
+  delivery: {
+    type: "gate",
+    method: "POST",
+    resourceUrl: "https://predictionengine.xyz/api/v1/forecast",
+  },
+});
+
+await genesispay.products.gate(forecast.publicId).prime();
+```
+
+Protect the route with that product. Validate request shape before calling
+`protect`, and make handler effects idempotent by `purchase.payment.attemptId`:
+
+```ts
+const forecastGate = genesispay.products.gate("prod_...");
+
+export async function POST(request: Request) {
+  const rawBody = await request.clone().text();
+  validateForecastJson(rawBody); // invalid requests never create a payment attempt
+
+  return forecastGate.protect(request, async (_request, purchase) => {
+    const cached = await readForecast(purchase.payment.attemptId);
+    if (cached) return Response.json(cached);
+
+    const result = await runForecast(rawBody);
+    await saveForecastOnce(purchase.payment.attemptId, result);
+    return Response.json(result);
+  });
+}
+```
+
+On the initial request, `protect` returns the standard `402 Payment Required`.
+GenesisPay creates a pending attempt before that response and advertises a
+reserved `gp_attempt` value in the x402 resource URL. On the signed retry, the
+SDK sends only the request fingerprint to GenesisPay; it never sends forecast
+inputs. A confirmed replay returns the same payment receipt with
+`idempotentReplay: true`; handlers may therefore execute more than once and
+must keep their own result cache.
+
+`products.list({ includeArchived: true })`, `products.retrieve`,
+`products.archive` complete the namespace. Archiving stops **new** link mints;
+the existing canonical link stays payable. The price is copied onto the link
+at mint — a later catalogue edit never changes what a buyer already sees.
+
 ### Testing the paid path
 
 ```ts
-const session = await peerpay.checkout.simulatePayment(publicId);
+const session = await genesispay.checkout.simulatePayment(publicId);
 // session.paid === true, and the real webhooks have fired.
 ```
 
-Test keys only — a `pp_sk_live_…` key gets a 403, and on a mainnet deployment the
+Test keys only — a `gp_sk_live_…` key gets a 403, and on a mainnet deployment the
 endpoint does not exist at all. The resulting attempt has `txHash: null` (no
 transaction happened) and `simulated: true`; branch on that flag rather than on
 the missing hash, because a *pending real* attempt has no hash either.
 
 ### Redirect parameters are not proof of payment
 
-The hosted checkout appends `?peerpay_link_id=…&peerpay_status=paid` to your
+The hosted checkout appends `?genesispay_link_id=…&genesispay_status=paid` to your
 `returnUrl`. Those parameters are a **UI hint only** — they are not signed, and a
 payer can navigate to that URL directly without paying. Fulfil on the
 `payment.confirmed` webhook or on `checkout.retrieve(publicId).paid`, never on the
@@ -306,14 +408,14 @@ no wallet returns a `402` `payment_not_configured` — the paid handler never ru
 without a valid destination. It also refuses to advertise a wallet whose network
 doesn't match the SDK's native-USDC table or the key mode.
 
-The low-level `createPaymentGate` / `peerPaySettlement` primitives below remain
+The low-level `createPaymentGate` / `genesisPaySettlement` primitives below remain
 available for advanced cases (custom wallet/network per gate, self-hosting).
 
 ## Quick start (Next.js route handler)
 
 ```ts
 // app/api/premium/route.ts
-import { createPaymentGate, peerPaySettlement } from "@genesis-tech/genesispay-seller";
+import { createPaymentGate, genesisPaySettlement } from "@genesis-tech/genesispay-seller";
 
 const gate = createPaymentGate({
   amountUsdc: "0.10",
@@ -322,9 +424,9 @@ const gate = createPaymentGate({
   network: "base-sepolia", // or "base" for mainnet
 });
 
-const verifySettlement = peerPaySettlement({
-  facilitatorBaseUrl: "https://your-peerpay-instance.example",
-  apiKey: process.env.PEERPAY_SELLER_KEY!, // pp_sk_...
+const verifySettlement = genesisPaySettlement({
+  facilitatorBaseUrl: "https://your-genesispay-instance.example",
+  apiKey: process.env.GENESISPAY_SELLER_KEY!, // gp_sk_...
 });
 
 export const GET = gate.wrap(
@@ -350,7 +452,7 @@ export const GET = gate.wrap(
 
 ```ts
 import { Hono } from "hono";
-import { createPaymentGate, peerPaySettlement } from "@genesis-tech/genesispay-seller";
+import { createPaymentGate, genesisPaySettlement } from "@genesis-tech/genesispay-seller";
 
 const gate = createPaymentGate({
   amountUsdc: "0.05",
@@ -362,9 +464,9 @@ const gate = createPaymentGate({
 const gated = gate.wrap(
   async () => Response.json({ ok: true }),
   {
-    verifySettlement: peerPaySettlement({
-      facilitatorBaseUrl: "https://your-peerpay-instance.example",
-      apiKey: process.env.PEERPAY_SELLER_KEY!,
+    verifySettlement: genesisPaySettlement({
+      facilitatorBaseUrl: "https://your-genesispay-instance.example",
+      apiKey: process.env.GENESISPAY_SELLER_KEY!,
     }),
   },
 );
@@ -392,12 +494,12 @@ The same wrapped handler drops straight into `Bun.serve({ fetch: gated })`.
 | `maxTimeoutSeconds` | no | Advertised authorization validity window (default 300). |
 
 `gate.wrap(handler, { verifySettlement })` requires a settlement hook. Use the
-built-in `peerPaySettlement({ facilitatorBaseUrl, apiKey })`, which POSTs the
+built-in `genesisPaySettlement({ facilitatorBaseUrl, apiKey })`, which POSTs the
 payment to GenesisPay's facilitator (`/api/v1/facilitator/settle`). GenesisPay
 broadcasts the EIP-3009 authorization on-chain, verifies the USDC transfer,
 and returns the receipt. `facilitatorBaseUrl` is optional and defaults to the
 public development facilitator (`DEFAULT_FACILITATOR_BASE_URL`,
-`https://peerpay-app-development.up.railway.app`), so you can omit it in dev —
+`https://dev.genesispay.finance`), so you can omit it in dev —
 set it explicitly for production. Or supply your own hook:
 
 ```ts
@@ -425,5 +527,5 @@ const verifySettlement: VerifySettlement = async ({ payment, requirement }) => {
 - The gate performs structural validation only (amount, destination, network,
   validity window). Actual money movement and on-chain verification happen in
   your `verifySettlement` hook.
-- Get a seller API key (`pp_sk_...`) from your GenesisPay dashboard under
+- Get a seller API key (`gp_sk_...`) from your GenesisPay dashboard under
   Developers.