@weft-js/pay 0.0.0-stage → 0.1.1

package/src/index.ts

@@ -0,0 +1,181 @@
+// @weft-js/pay (PLAN §4.4, research 10): the catalog, and what a `pay.rail` provider implements. Safe in the client graph: nothing
+// here reaches a rail or a server. App code names products and plans; a rail is one line in `plugins`. `@weft-js/pay/server`
+// holds the ledger, and `checkout()` never grants anything: the grant arrives from a verified rail event.
+//
+//   export const pro = product({ id: 'pro', kind: 'subscription', use: 'digital', plans: { month: { usd: 999 } }, grants: ['pro'] })
+//   <button onClick={() => checkout({ product: 'pro', plan: 'month' })}>Go Pro · {price(pro, 'month').display}</button>
+
+/** How a product is paid for: a subscription renews, a one-time purchase stays, a consumable is used up. */
+export type ProductKind = 'subscription' | 'one-time' | 'consumable'
+/** What the buyer gets: app stores care, and `physical` goods ship. */
+export type ProductUse = 'digital' | 'physical' | 'service'
+/** How often a subscription bills. */
+export type Interval = 'day' | 'week' | 'month' | 'year'
+
+/** Minor units per ISO currency: `{ usd: 999 }` is $9.99. Integers, always (PAY008). */
+export type Amounts = Record<string, number>
+
+/** A subscription's billing option: `Amounts`, with an optional trial and an interval when the plan's name isn't one. */
+export interface Plan { [currency: string]: unknown; trialDays?: number; interval?: Interval }
+
+/** What `product()` takes. `G` is the entitlements it grants and `P` the names of its plans. */
+export interface ProductDef<G extends string = string, P extends string = string> {
+  id: string
+  kind: ProductKind
+  use: ProductUse
+  /** Display name at checkout. Default: the id. */
+  name?: string
+  /** A subscription's billing options: `{ month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } }`. */
+  plans?: Record<P, Plan>
+  /** A one-time or consumable product's price. */
+  price?: Amounts
+  /** The entitlements a live purchase of this product gives. */
+  grants?: readonly G[]
+  /** One-time and physical goods: collect an address. */
+  shipping?: boolean
+}
+
+/** A checked, frozen product, as `product()` returns it. */
+export interface Product<G extends string = string, P extends string = string> extends ProductDef<G, P> {
+  readonly grants: readonly G[]
+}
+
+const INTERVALS: readonly string[] = ['day', 'week', 'month', 'year']
+const META = new Set(['trialDays', 'interval'])
+
+/** Thrown with a stable `code`. `answer` is the shape @weft-js/start sends any plugin's error to the client in. */
+export class PayError extends Error {
+  override name = 'PayError'
+  constructor(readonly code: string, message: string, readonly status = 400) {
+    super(message)
+  }
+  get answer() { return { code: this.code, message: this.message, status: this.status } }
+}
+
+const amounts = (p: object) => Object.entries(p).filter(([k]) => !META.has(k)) as [string, number][]
+
+function checkAmounts(id: string, list: [string, unknown][]) {
+  if (!list.length) throw new PayError('PAY008', `\`${id}\` has no amount: give one in minor units with its currency, like \`{ usd: 999 }\``)
+  for (const [currency, n] of list) {
+    if (!/^[a-z]{3}$/.test(currency)) throw new PayError('PAY008', `\`${id}\`: \`${currency}\` isn't a lowercase ISO currency`)
+    if (!Number.isSafeInteger(n) || (n as number) < 0) throw new PayError('PAY008', `\`${id}\`: ${currency} ${String(n)} isn't whole minor units (999 is $9.99)`)
+  }
+}
+
+/** One thing you sell. The only place products are defined, and safe in the client graph: it holds no rail's ids. */
+export function product<const G extends string = never, const P extends string = never>(def: ProductDef<G, P>): Product<G, P> {
+  const { id, kind, plans, price: amount } = def
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw new PayError('PAY021', `product id \`${id}\` must be lowercase letters, digits and dashes`)
+  if (kind === 'subscription') {
+    if (!plans || !Object.keys(plans).length) throw new PayError('PAY021', `subscription \`${id}\` has no \`plans\``)
+    if (amount) throw new PayError('PAY021', `subscription \`${id}\` is priced per plan: drop \`price\``)
+    for (const [name, p] of Object.entries<Plan>(plans)) {
+      checkAmounts(`${id}.${name}`, amounts(p))
+      if (intervalOf(name, p) === null) throw new PayError('PAY021', `plan \`${id}.${name}\` is no interval: name it \`month\` or \`year\`, or add \`interval\``)
+    }
+  } else {
+    if (plans) throw new PayError('PAY021', `\`${id}\` is ${kind}: \`plans\` are for subscriptions, so use \`price\``)
+    checkAmounts(id, Object.entries(amount ?? {}))
+  }
+  return Object.freeze({ ...def, grants: Object.freeze([...(def.grants ?? [])]) })
+}
+
+const intervalOf = (name: string, p: Plan): Interval | null => p.interval ?? (INTERVALS.includes(name) ? (name as Interval) : null)
+
+/** One figure to show a buyer, as `price()` returns it. */
+export interface Price {
+  amount: number
+  currency: string
+  /** Formatted for the reader's locale: `$9.99`. */
+  display: string
+  plan?: string
+  interval?: Interval
+  trialDays?: number
+}
+
+/** The figure in major units, by the currency's own exponent: JPY has none, KWD has three. */
+function formatted(amount: number, currency: string, locale?: string) {
+  const f = new Intl.NumberFormat(locale, { style: 'currency', currency: currency.toUpperCase() })
+  return f.format(amount / 10 ** (f.resolvedOptions().maximumFractionDigits ?? 2))
+}
+
+/** The price of a product or one of its plans. The first currency listed, unless you name one. */
+export function price<P extends string>(p: Product<string, P>, plan?: P, options: { currency?: string; locale?: string } = {}): Price {
+  const row: Record<string, unknown> | undefined = plan === undefined ? (p.price ?? (p.plans && Object.values(p.plans)[0] as Plan)) : p.plans?.[plan]
+  const name = plan ?? (p.plans ? Object.keys(p.plans)[0] : undefined)
+  if (!row) throw new PayError('PAY021', `\`${p.id}\` has no plan \`${String(plan)}\``)
+  const list = amounts(row)
+  const pick = options.currency ? list.find(([c]) => c === options.currency) : list[0]
+  if (!pick) throw new PayError('PAY021', `\`${p.id}\` has no ${options.currency} price`)
+  const [currency, amount] = pick
+  const plain = { amount, currency, display: formatted(amount, currency, options.locale) }
+  if (!name) return plain
+  const meta = row as Plan
+  return { ...plain, plan: name, interval: intervalOf(name, meta)!, ...(meta.trialDays ? { trialDays: meta.trialDays } : {}) }
+}
+
+/** What a query reads, tagged so a verified event pokes it: `tags: (_, ctx) => [entitlementTag(ctx.user.id)]`. */
+export const entitlementTag = (user: string) => `entitlements:${user}`
+
+// ---- pay.rail@1 ---------------------------------------------------------------------------------------------------
+
+/** What a purchase is doing now, on any rail (research 10 §3). */
+export type PurchaseState = 'pending' | 'active' | 'trial' | 'grace' | 'billing-retry' | 'paused' | 'expired' | 'refunded' | 'revoked'
+
+/** One line a rail charges for, from the catalog. It never comes from the client. */
+export interface CheckoutLine {
+  product: string
+  plan?: string
+  name: string
+  amount: number
+  currency: string
+  mode: 'subscription' | 'payment'
+  interval?: Interval
+  trialDays?: number
+  quantity: number
+  shipping?: boolean
+}
+
+/** What `checkout` asks of a rail: who is buying, what, and where the buyer comes back to. */
+export interface CheckoutRequest {
+  /** Who is buying: attached to the rail's records, and read back from its events. */
+  user: string
+  /** This user's id on the rail, when a purchase gave one. */
+  customer?: string
+  line: CheckoutLine
+  successUrl: string
+  cancelUrl: string
+  /** The same click twice gives one session. */
+  idempotencyKey: string
+}
+
+/** A rail's event, normalised. `checkout` and these are all that a rail and the ledger say to each other. */
+export interface RailEvent {
+  /** The rail's own id for the event: what makes a redelivery a no-op. */
+  id: string
+  /** The rail's own clock, in ms: events arrive out of order, and this orders them. */
+  at: number
+  /** The rail's id for the purchase: a subscription, a payment. */
+  purchase: string
+  state: PurchaseState
+  /** Set when the rail's event carries them; an event for a purchase nobody knows without them is dropped. */
+  user?: string
+  product?: string
+  plan?: string
+  customer?: string
+  /** When a paid period ends, in ms. */
+  expires?: number
+}
+
+/**
+ * `pay.rail@1`. A provider implements this and declares it for the `server` side. `verify` is the only way in for an
+ * event: it gets the exact bytes received, and throws `PayError('PAY011', …)` for anything it can't prove.
+ */
+export interface PayRail {
+  readonly id: string
+  checkout(request: CheckoutRequest): Promise<{ url: string }>
+  /** Where a buyer manages or cancels. */
+  portal(request: { customer: string; returnUrl: string }): Promise<{ url: string }>
+  verify(request: { body: string; headers: Headers }): RailEvent[] | Promise<RailEvent[]>
+  refund?(request: { purchase: string }): Promise<void>
+}

package/src/server.ts

@@ -0,0 +1,328 @@
+// @weft-js/pay/server (research 10 §3, 37): one ledger for every rail. A rail's `verify` turns the bytes it received into events;
+// `ingest` folds them into `purchases`; entitlements are read from those, against the catalog, so nothing else can grant
+// anything. `src/pay.server.ts` default-exports what `definePay` returns, and that value is a `server.extension`: it is
+// how this package reaches the server, through the slot any plugin can use. No line of @weft-js/start names payments.
+//
+// Delivery is at least once, in any order. An event applies by the rail's own clock, so an old one changes nothing and a
+// repeat lands on what it already wrote; `mark` comes last, because a crash before it should redeliver. A failure answers
+// 500 for the same reason. A terminal state wins a tie: a refund and a renewal in the same second is a refund.
+
+import type { Context } from '@weft-js/start'
+import type { ServerExtension } from '@weft-js/start/extension'
+import { entitlementTag, PayError, type CheckoutLine, type Interval, type PayRail, type Plan, type Product, type PurchaseState, type RailEvent } from './index'
+
+declare module '@weft-js/start' {
+  interface Context {
+    /** What this user holds, from verified rail events. Await it. */
+    entitlements: Entitlements
+  }
+  interface FnOptions {
+    /** Entitlements this call needs, on the server: a typed 403 otherwise. */
+    requires?: readonly string[]
+  }
+}
+
+/** One row of the ledger: where a purchase stands now, whatever rail it came through. */
+export interface Purchase {
+  /** `<rail>:<rail's id>`. */
+  id: string
+  rail: string
+  /** Null until an event names them: a dispute can arrive before the payment it disputes. */
+  user: string | null
+  product: string | null
+  plan: string | null
+  state: PurchaseState
+  /** The rail's time of the last event applied. */
+  at: number
+  expires: number | null
+  customer: string | null
+}
+
+/** Where the ledger lives. `drizzlePayStore` in `@weft-js/start/pay/drizzle`, or write these five for any database. */
+export interface PayStore {
+  /** Not durable: refused on a production server (PAY016). */
+  readonly memory?: boolean
+  seen(event: string): Promise<boolean>
+  mark(event: string, at: number): Promise<void>
+  purchase(id: string): Promise<Purchase | null>
+  /** Insert or replace by `id`. */
+  save(purchase: Purchase): Promise<void>
+  byUser(user: string): Promise<Purchase[]>
+}
+
+/** A ledger in memory, for dev and tests: `clear` empties it. */
+export function memoryPayStore(): PayStore & { clear(): void } {
+  const events = new Set<string>()
+  const rows = new Map<string, Purchase>()
+  return {
+    memory: true,
+    seen: e => Promise.resolve(events.has(e)),
+    mark(e) { events.add(e); return Promise.resolve() },
+    purchase: id => Promise.resolve(rows.get(id) ?? null),
+    save(p) { rows.set(p.id, p); return Promise.resolve() },
+    byUser: user => Promise.resolve([...rows.values()].filter(p => p.user === user)),
+    clear() { events.clear(); rows.clear() },
+  }
+}
+
+/** What one user holds, from the ledger and the catalog. */
+export interface Entitlements {
+  /** Await it: a promise is always truthy (PAY015). */
+  has(id: string): Promise<boolean>
+  list(): Promise<string[]>
+}
+
+/** What pay reads of `ctx`: the request's URL, and what `user` reads, `user.id` by default. A real `ctx` fits, and so does a test's. */
+export type PayContext = Partial<Omit<Context, 'request'>> & { request: { url: string }; user?: { id?: string | null } | null }
+
+/** What `definePay` takes. */
+export interface PayOptions<P extends Product> {
+  /** `import * as catalog from './pay/catalog'`, or a list. */
+  catalog: readonly P[] | Record<string, P>
+  store: PayStore
+  /** Paths or URLs a buyer comes back to. They never come from the client. */
+  urls: { success: string; cancel: string; portal?: string }
+  /** Who a request is. Default `ctx.user?.id`. */
+  user?: (ctx: PayContext) => string | null | undefined
+  /** With several rails bound, the one that takes payments. One rail needs no choosing. */
+  rail?: string
+  /** The `pay.rail` slot. Default the generated `weft:slot/pay.rail`, as any consumer of a slot reads it. */
+  slot?: () => Promise<{ load(key: string): Promise<unknown>; providers?: Record<string, unknown> }>
+  /** Absolute origin for `urls`, behind a proxy. Default the request's. */
+  origin?: string
+  /** How long past a paid period access lasts, while a late renewal event arrives. Default 3 days. */
+  leeway?: number
+}
+
+/** The server log: @weft-js/start passes its own. */
+export type PayReport = (d: { code: string; severity: string; message: string }) => void
+
+/** What a client may ask for: names only. The catalog supplies every amount. */
+export interface CheckoutInput<P extends Product = Product> {
+  product: P['id']
+  plan?: string
+  currency?: string
+  quantity?: number
+}
+
+/** What `definePay` returns: the ledger's calls, and a `server.extension` that carries them to the server. */
+export interface Pay<P extends Product = Product> extends ServerExtension {
+  readonly catalog: readonly P[]
+  /** For a mutation's `input`: the catalog decides what can be bought, and the client sends only names. */
+  readonly input: { readonly '~standard': { version: 1; vendor: 'weft'; validate(v: unknown): { value: CheckoutInput<P> } | { issues: { message: string }[] }; types?: { input: CheckoutInput<P>; output: CheckoutInput<P> } } }
+  /** The hosted checkout's URL, for this buyer. Grants nothing. */
+  checkout(ctx: PayContext, input: CheckoutInput<P>): Promise<string>
+  /** Where this buyer manages or cancels. */
+  portal(ctx: PayContext): Promise<string>
+  /** Read for a user id, as a webhook or a job would. In a request, `ctx.entitlements`. */
+  entitlements(user: string): Entitlements
+  /** `ctx.entitlements` for this context. */
+  forContext(ctx: PayContext): Entitlements
+  purchases(user: string): Promise<Purchase[]>
+  /** One verified delivery. `tags` go on to the app's live readers. */
+  webhook(rail: string, request: Request, report?: PayReport): Promise<{ response: Response; tags: string[] }>
+  /** Apply events that have been verified. Anything else must go through `webhook`. */
+  ingest(rail: string, events: RailEvent[], report?: PayReport): Promise<string[]>
+  refund(purchase: string): Promise<void>
+  /** A rail in place of the slot: `fakePay`. */
+  use(rail: PayRail | undefined): void
+  /** Back to the slot, with an empty ledger if it can be emptied: `net.extension` calls this after each test. */
+  reset(): void
+}
+
+const ACCESS: ReadonlySet<PurchaseState> = new Set(['active', 'trial', 'grace'])
+const FINAL: ReadonlySet<PurchaseState> = new Set(['refunded', 'revoked'])
+const DAY = 86_400_000
+const BODY = 1 << 20
+
+const hex = async (s: string) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s)))].map(b => b.toString(16).padStart(2, '0')).join('')
+const issue = (message: string) => ({ issues: [{ message }] })
+const errorMessage = (e: unknown) => String((e as Error | null)?.message ?? e)
+
+/** The one ledger of an app: `src/pay.server.ts` default-exports what this returns. */
+export function definePay<P extends Product>(options: PayOptions<P>): Pay<P> {
+  const catalog = (Array.isArray(options.catalog) ? options.catalog : Object.values(options.catalog)) as P[]
+  const byId = new Map(catalog.map(p => [p.id, p]))
+  const { store, urls, leeway = 3 * DAY } = options
+  const userOf = options.user ?? (ctx => ctx?.user?.id)
+  const slot = options.slot ?? (() => {
+    // A generated module, declared in .weft/slots.d.ts only once bound: an expect-error would be wrong in one case or the other.
+    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- the cast is what lets this compile when the slot isn't declared
+    return import('weft:slot/pay.rail' as string)
+  })
+  let override: PayRail | undefined
+  const rails = new Map<string, Promise<PayRail>>()
+
+  async function railFor(key?: string): Promise<PayRail> {
+    if (override) return override
+    const { load, providers = {} } = await slot()
+    const bound = Object.keys(providers).filter(k => providers[k])
+    if (!bound.length) throw new PayError('P101', '`pay.rail` has no provider: add one to `plugins` in weft.config.ts', 500)
+    const pick = key ?? options.rail ?? (bound.length === 1 ? bound[0] : undefined)
+    if (!pick || !bound.includes(pick)) throw new PayError('PAY022', pick ? `no rail \`${pick}\` is bound (${bound.join(', ')})` : `${bound.join(' and ')} are both bound: set \`rail\` in \`definePay\``, 500)
+    let r = rails.get(pick)
+    if (!r) rails.set(pick, (r = load(pick) as Promise<PayRail>))
+    return r
+  }
+
+  function lineOf(input: CheckoutInput<P>): CheckoutLine {
+    const p = byId.get(input.product)
+    if (!p) throw new PayError('PAY021', `no product \`${input.product}\``, 404)
+    const subscription = p.kind === 'subscription'
+    const name = subscription ? input.plan ?? Object.keys(p.plans!)[0] : undefined
+    const row: Plan | undefined = subscription ? p.plans![name as keyof typeof p.plans] : p.price
+    if (!row) throw new PayError('PAY021', `\`${p.id}\` has no plan \`${input.plan}\``, 404)
+    const currency = input.currency ?? Object.keys(row).find(k => k !== 'trialDays' && k !== 'interval')!
+    const amount = row[currency]
+    if (typeof amount !== 'number') throw new PayError('PAY021', `\`${p.id}\` has no ${currency} price`, 404)
+    return {
+      product: p.id, name: p.name ?? p.id, amount, currency, mode: subscription ? 'subscription' : 'payment', quantity: subscription ? 1 : input.quantity ?? 1,
+      ...(subscription ? { plan: name!, interval: (row.interval ?? name) as Interval, ...(row.trialDays ? { trialDays: row.trialDays } : {}) } : {}),
+      ...(p.shipping ? { shipping: true } : {}),
+    }
+  }
+
+  const live = (p: Purchase) => ACCESS.has(p.state) && (p.expires === null || Date.now() < p.expires + leeway)
+
+  async function granted(user: string) {
+    const out = new Set<string>()
+    for (const p of await store.byUser(user)) if (live(p)) for (const g of byId.get(p.product!)?.grants ?? []) out.add(g)
+    return [...out].sort()
+  }
+
+  const entitlements = (user: string | null | undefined): Entitlements => {
+    let list: Promise<string[]> | undefined
+    const read = () => (list ??= user ? granted(user) : Promise.resolve([]))
+    return { has: id => read().then(l => l.includes(id)), list: read }
+  }
+
+  /** One event onto its purchase. Identity always merges; state moves only forward on the rail's clock. */
+  async function apply(rail: string, e: RailEvent, report?: PayReport): Promise<string | null> {
+    const id = `${rail}:${e.purchase}`
+    const had = await store.purchase(id)
+    const newer = !had || e.at > had.at || (e.at === had.at && (!FINAL.has(had.state) || FINAL.has(e.state)))
+    const next: Purchase = {
+      id, rail,
+      user: had?.user ?? e.user ?? null, product: had?.product ?? e.product ?? null, plan: e.plan ?? had?.plan ?? null, customer: e.customer ?? had?.customer ?? null,
+      state: newer ? e.state : had.state, at: newer ? e.at : had.at, expires: newer ? e.expires ?? had?.expires ?? null : had.expires,
+    }
+    await store.save(next)
+    if (next.product && !byId.has(next.product)) report?.({ code: 'PAY021', severity: 'warning', message: `purchase \`${id}\` is for \`${next.product}\`, which isn't in the catalog: it grants nothing` })
+    return next.user && entitlementTag(next.user)
+  }
+
+  async function ingest(rail: string, events: RailEvent[], report?: PayReport) {
+    const tags = new Set<string>()
+    for (const e of events) {
+      const key = `${rail}:${e.id}`
+      if (await store.seen(key)) continue
+      const tag = await apply(rail, e, report)
+      await store.mark(key, e.at)
+      if (tag) tags.add(tag)
+    }
+    return [...tags]
+  }
+
+  const pay: Pay<P> = {
+    catalog,
+    input: {
+      '~standard': {
+        version: 1,
+        vendor: 'weft',
+        validate(v: unknown) {
+          const { product, plan, currency, quantity } = (v && typeof v === 'object' ? v : {}) as Partial<Record<keyof CheckoutInput, unknown>>
+          if (typeof product !== 'string') return issue('`product` is required')
+          const p = byId.get(product)
+          if (!p) return issue(`no product \`${product}\``)
+          if (plan !== undefined && (typeof plan !== 'string' || !p.plans || !(plan in p.plans))) return issue(`\`${p.id}\` has no plan \`${typeof plan === 'string' ? plan : JSON.stringify(plan)}\``)
+          if (currency !== undefined && typeof currency !== 'string') return issue('`currency` is a string')
+          if (quantity !== undefined && !(typeof quantity === 'number' && Number.isInteger(quantity) && quantity > 0 && quantity < 1000)) return issue('`quantity` is a whole number under 1000')
+          return { value: { product, ...(plan !== undefined && { plan }), ...(currency !== undefined && { currency }), ...(quantity !== undefined && { quantity }) } }
+        },
+      },
+    },
+    async checkout(ctx, input) {
+      const user = userOf(ctx)
+      if (!user) throw new PayError('PAY010', 'Sign in before buying: a purchase has to belong to someone', 401)
+      const line = lineOf(input)
+      const rail = await railFor()
+      const mine = await store.byUser(user)
+      if (line.mode === 'subscription' && mine.some(p => p.product === line.product && live(p))) throw new PayError('PAY023', `You already have \`${line.product}\``, 409)
+      const origin = options.origin ?? new URL(ctx.request.url).origin
+      const customer = mine.find(p => p.customer && p.rail === rail.id)?.customer ?? undefined
+      const idempotencyKey = await hex(JSON.stringify([user, line, Math.floor(Date.now() / 60_000)]))
+      const { url } = await rail.checkout({ user, ...(customer && { customer }), line, successUrl: new URL(urls.success, origin).href, cancelUrl: new URL(urls.cancel, origin).href, idempotencyKey })
+      return url
+    },
+    async portal(ctx) {
+      const user = userOf(ctx)
+      if (!user) throw new PayError('PAY010', 'Sign in first', 401)
+      const rail = await railFor()
+      const customer = (await store.byUser(user)).find(p => p.customer && p.rail === rail.id)?.customer
+      if (!customer) throw new PayError('PAY024', 'Nothing to manage yet: this user has bought nothing here', 404)
+      const origin = options.origin ?? new URL(ctx.request.url).origin
+      return (await rail.portal({ customer, returnUrl: new URL(urls.portal ?? urls.cancel, origin).href })).url
+    },
+    entitlements,
+    forContext: ctx => entitlements(userOf(ctx)),
+    purchases: user => store.byUser(user),
+    ingest,
+    async webhook(key, request, report) {
+      const plain = (body: string, status: number) => ({ response: new Response(body, { status, headers: { 'content-type': 'text/plain' } }), tags: [] })
+      if (request.method !== 'POST') return plain('Method not allowed', 405)
+      let rail: PayRail
+      try { rail = await railFor(key) } catch { return plain('Not found', 404) }
+      if (Number(request.headers.get('content-length') ?? 0) > BODY) return plain('Too large', 413)
+      const body = await request.text() // the exact bytes: a parsed and re-encoded body can't be verified
+      if (body.length > BODY) return plain('Too large', 413)
+      let events: RailEvent[]
+      try {
+        events = await rail.verify({ body, headers: request.headers })
+      } catch (e) {
+        // A retry can't fix this one, and the reason stays in the log: a forger learns nothing.
+        report?.({ code: (e as { code?: string } | null)?.code ?? 'PAY011', severity: 'error', message: `a ${key} webhook failed verification: ${errorMessage(e)}` })
+        return plain('Bad signature', 400)
+      }
+      try {
+        return { response: new Response('{"received":true}', { headers: { 'content-type': 'application/json' } }), tags: await ingest(rail.id, events, report) }
+      } catch (e) {
+        report?.({ code: 'E_PAY', severity: 'error', message: `a ${key} webhook failed, and it will be redelivered: ${errorMessage(e)}` })
+        return plain('Try again', 500)
+      }
+    },
+    async refund(id) {
+      const p = await store.purchase(id)
+      if (!p) throw new PayError('PAY024', `no purchase \`${id}\``, 404)
+      const rail = await railFor(p.rail)
+      if (!rail.refund) throw new PayError('PAY022', `\`${rail.id}\` can't refund from here`, 501)
+      await rail.refund({ purchase: id.slice(p.rail.length + 1) })
+    },
+    use(rail) { override = rail },
+    reset() {
+      override = undefined
+      ;(store as { clear?(): void }).clear?.()
+    },
+
+    // ---- what makes this a `server.extension` ---------------------------------------------------------------------
+    async handle(request, path, api) {
+      const { response, tags } = await pay.webhook(path, request, d => api.report(d))
+      await api.invalidate(tags)
+      return response
+    },
+    context: ctx => ({ entitlements: pay.forContext(ctx) }),
+    async guard(fn, ctx) {
+      for (const id of (fn.def.requires as readonly string[] | undefined) ?? []) if (!(await ctx.entitlements.has(id))) throw new PayError('ENTITLEMENT_REQUIRED', `This needs \`${id}\``, 403)
+    },
+    options: ['requires'],
+    personal: ['entitlements'],
+    check(dev) {
+      if (store.memory && !dev) throw new PayError('PAY016', 'The ledger is in memory: every purchase is gone on the next deploy. Pass a durable `store` to `definePay`', 500)
+    },
+  }
+  return pay
+}
+
+/** The `server.extension` provider: `src/pay.server.ts` already built it, so this hands it over. */
+export const extension = (app: Pay): ServerExtension => app
+
+export type { PayRail, RailEvent } from './index'

package/src/setup.mjs

@@ -0,0 +1,99 @@
+// What `weft add pay` writes, as data: `weft add` does the writing, so a dry run and a refusal come for free. Plain JS
+// strings, because this loads with the config. `run` only describes: the plugin never touches the disk.
+
+const PURCHASE = ['user', 'product', 'plan']
+
+/** `purchases` and `pay_events`, as `drizzlePayStore` reads them: times in ms, so a 32-bit integer won't do. */
+function tables(engine) {
+  const columns = ({ table, id, str, long }) => `export const purchases = ${table}('purchases', {
+  id: ${id}.primaryKey(),
+  rail: ${str}.notNull(),
+${PURCHASE.map(c => `  ${c}: ${str},`).join('\n')}
+  state: ${str}.notNull(),
+  at: ${long}.notNull(),
+  expires: ${long},
+  customer: ${str},
+})
+
+export const payEvents = ${table}('pay_events', {
+  id: ${id}.primaryKey(),
+  at: ${long}.notNull(),
+})
+`
+  return {
+    sqlite: () => `import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n\n${columns({ table: 'sqliteTable', id: 'text()', str: 'text()', long: 'integer()' })}`,
+    postgres: () => `import { bigint, pgTable, text } from 'drizzle-orm/pg-core'\n\n${columns({ table: 'pgTable', id: 'text()', str: 'text()', long: "bigint({ mode: 'number' })" })}`,
+    mysql: () => `import { bigint, mysqlTable, varchar } from 'drizzle-orm/mysql-core'\n\n${columns({ table: 'mysqlTable', id: 'varchar({ length: 191 })', str: 'varchar({ length: 191 })', long: "bigint({ mode: 'number' })" })}`,
+  }[engine]()
+}
+
+const catalog = `import { product } from '@weft-js/pay'
+
+// What you sell. Amounts are minor units (999 is $9.99), and no rail's ids belong here: this file reaches the client.
+export const pro = product({
+  id: 'pro',
+  kind: 'subscription',
+  use: 'digital',
+  name: 'Pro',
+  plans: { month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } },
+  grants: ['pro'],
+})
+`
+
+const ledger = store => `${store === 'drizzle' ? "import { drizzlePayStore } from '@weft-js/pay/drizzle'\nimport { definePay } from '@weft-js/pay/server'\nimport { db } from '#/db/index.server'\nimport { payEvents, purchases } from '#/db/schema'\n" : "import { definePay, memoryPayStore } from '@weft-js/pay/server'\n"}import * as catalog from './pay/catalog'
+
+// Served at /_weft/x/pay/<rail>, the webhook URL to give your provider. A verified event is the only grant.
+export default definePay({ catalog, store: ${store === 'drizzle' ? 'drizzlePayStore(db, { purchases, payEvents })' : 'memoryPayStore()'}, urls: { success: '/', cancel: '/' } })
+`
+
+const functions = `import { entitlementTag } from '@weft-js/pay'
+import { mutation, query, redirect } from '@weft-js/start'
+import pay from '../pay.server'
+
+/** What the signed-in user holds, live: a verified event pokes this user's tag. Render from it; enforce with \`requires\`. */
+export const entitlements = query({
+  auth: 'user',
+  tags: (_, ctx) => [entitlementTag(ctx.user.id)],
+  run: ({ ctx }) => ctx.entitlements.list(),
+})
+
+/** \`checkout({ product: 'pro', plan: 'month' })\`: on to the rail's page. It grants nothing. */
+export const checkout = mutation({
+  auth: 'user',
+  input: pay.input,
+  run: async ({ input, ctx }) => redirect(await pay.checkout(ctx, input), 303),
+})
+
+/** Where a buyer manages or cancels. */
+export const portal = mutation({
+  auth: 'user',
+  run: async ({ ctx }) => redirect(await pay.portal(ctx), 303),
+})
+`
+
+export const setup = {
+  with: ['@weft-js/pay/stripe'],
+  needs: ['db', 'auth'],
+  run({ engine, layer, read }) {
+    const drizzle = layer === 'drizzle'
+    const env = read('src/env.server.ts') ?? ''
+    if (!env.includes('STRIPE_SECRET_KEY') && !/server: \{\n/.test(env)) throw new Error('src/env.server.ts has no `server: {` block to add the Stripe keys to')
+    return {
+      files: {
+        'src/pay/catalog.ts': catalog,
+        'src/pay.server.ts': ledger(drizzle ? 'drizzle' : 'memory'),
+        'src/server/pay.ts': functions,
+        ...(drizzle && { 'src/db/pay.schema.ts': tables(engine) }),
+      },
+      edits: {
+        ...(!env.includes('STRIPE_SECRET_KEY') && { 'src/env.server.ts': env.replace('server: {\n', 'server: {\n    STRIPE_SECRET_KEY: z.string().min(1),\n    STRIPE_WEBHOOK_SECRET: z.string().min(1),\n') }),
+        ...(drizzle && { 'src/db/schema.ts': `${read('src/db/schema.ts').trimEnd()}\n\nexport * from './pay.schema'\n` }),
+      },
+      env: { STRIPE_SECRET_KEY: 'sk_test_placeholder', STRIPE_WEBHOOK_SECRET: 'whsec_placeholder' },
+      next: [
+        ...(drizzle ? ['`weft db generate`, then reload: the migration applies on the next request'] : ['`src/pay.server.ts` starts on `memoryPayStore()`: write a `PayStore` on your data layer (PAY016)']),
+        'put your real test keys in .env, and give Stripe the webhook URL /_weft/x/pay/stripe',
+      ],
+    }
+  },
+}