@weft-js/pay 0.1.1 → 0.1.3

package/src/index.ts

@@ -1,9 +1,4 @@
-// @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>
+// `checkout()` never grants anything: the grant arrives from a verified rail event.
 
 /** 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'
@@ -16,7 +11,11 @@ export type Interval = 'day' | 'week' | 'month' | 'year'
 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 }
+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> {
@@ -36,7 +35,10 @@ export interface ProductDef<G extends string = string, P extends string = string
 }
 
 /** A checked, frozen product, as `product()` returns it. */
-export interface Product<G extends string = string, P extends string = string> extends ProductDef<G, P> {
+export interface Product<G extends string = string, P extends string = string> extends ProductDef<
+  G,
+  P
+> {
   readonly grants: readonly G[]
 }
 
@@ -46,41 +48,73 @@ 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) {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status = 400,
+  ) {
     super(message)
   }
-  get answer() { return { code: this.code, message: this.message, status: this.status } }
+  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 }\``)
+  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)`)
+    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> {
+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 (!/^[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\``)
+    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\``)
+      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\``)
+    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)
+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 {
@@ -100,8 +134,15 @@ function formatted(amount: number, currency: string, locale?: string) {
 }
 
 /** 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]
+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)
@@ -111,7 +152,12 @@ export function price<P extends string>(p: Product<string, P>, plan?: P, options
   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 } : {}) }
+  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)]`. */
@@ -119,8 +165,17 @@ 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'
+/** What a purchase is doing now, on any rail. */
+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 {

package/src/server/catalog.ts

@@ -0,0 +1,80 @@
+import { PayError, type CheckoutLine, type Interval, type Plan, type Product } from '../index'
+import type { CheckoutInput, Pay } from '../server'
+
+const issue = (message: string) => ({ issues: [{ message }] })
+
+/** Resolve a checkout line from the catalog. */
+export function lineOf<P extends Product>(
+  byId: Map<string, P>,
+  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 } : {}),
+  }
+}
+
+/** Validate checkout input against this catalog. */
+export function checkoutInput<P extends Product>(byId: Map<string, P>): Pay<P>['input'] {
+  return {
+    '~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 }),
+          },
+        }
+      },
+    },
+  }
+}

package/src/server/ledger.ts

@@ -0,0 +1,69 @@
+import { entitlementTag, type Product, type PurchaseState, type RailEvent } from '../index'
+import type { Entitlements, PayReport, PayStore, Purchase } from '../server'
+
+const ACCESS: ReadonlySet<PurchaseState> = new Set(['active', 'trial', 'grace'])
+const FINAL: ReadonlySet<PurchaseState> = new Set(['refunded', 'revoked'])
+
+/** Derive access and apply verified events against one store. */
+export function makeLedger<P extends Product>(
+  store: PayStore,
+  byId: Map<string, P>,
+  leeway: number,
+) {
+  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]
+  }
+
+  return { live, entitlements, ingest }
+}

package/src/server/operations.ts

@@ -0,0 +1,142 @@
+import { PayError, type PayRail, type Product, type RailEvent } from '../index'
+import type {
+  CheckoutInput,
+  PayContext,
+  PayOptions,
+  PayReport,
+  PayStore,
+  Purchase,
+} from '../server'
+import { lineOf } from './catalog'
+
+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 errorMessage = (e: unknown) => String((e as Error | null)?.message ?? e)
+
+type Services<P extends Product> = {
+  options: PayOptions<P>
+  urls: PayOptions<P>['urls']
+  userOf: (ctx: PayContext) => string | null | undefined
+  store: PayStore
+  railFor: (key?: string) => Promise<PayRail>
+  live: (purchase: Purchase) => boolean
+  byId: Map<string, P>
+}
+
+/** Create the checkout operation for this pay instance. */
+export function checkoutFor<P extends Product>({
+  options,
+  urls,
+  userOf,
+  store,
+  railFor,
+  live,
+  byId,
+}: Services<P>) {
+  async function checkout(ctx: PayContext, input: CheckoutInput<P>) {
+    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(byId, 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
+  }
+  return checkout
+}
+
+/** Create the portal operation for this pay instance. */
+export function portalFor<P extends Product>({
+  options,
+  urls,
+  userOf,
+  store,
+  railFor,
+}: Services<P>) {
+  async function portal(ctx: PayContext) {
+    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
+  }
+  return portal
+}
+
+/** Create the verified delivery operation for this pay instance. */
+export function webhookFor(
+  railFor: (key?: string) => Promise<PayRail>,
+  ingest: (rail: string, events: RailEvent[], report?: PayReport) => Promise<string[]>,
+) {
+  async function webhook(key: string, request: Request, report?: PayReport) {
+    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)
+    }
+  }
+  return webhook
+}

package/src/server/rails.ts

@@ -0,0 +1,45 @@
+import { PayError, type PayRail, type Product } from '../index'
+import type { PayOptions } from '../server'
+
+/** Keep one override and provider cache for this pay instance. */
+export function makeRails<P extends Product>(
+  options: PayOptions<P>,
+  slot: () => Promise<{
+    load: (key: string) => Promise<unknown>
+    providers?: Record<string, unknown>
+  }>,
+) {
+  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
+  }
+
+  return {
+    railFor,
+    use: (rail: PayRail | undefined) => {
+      override = rail
+    },
+  }
+}