@weft-js/pay 0.1.1 → 0.1.3

package/src/server.ts

@@ -1,15 +1,14 @@
-// @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 { makeRails } from './server/rails'
+import { makeLedger } from './server/ledger'
+import { checkoutInput } from './server/catalog'
+import { checkoutFor, portalFor, webhookFor } from './server/operations'
 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'
+import { PayError, type PayRail, type Product, type PurchaseState, type RailEvent } from './index'
 
 declare module '@weft-js/start' {
   interface Context {
@@ -56,12 +55,21 @@ export function memoryPayStore(): PayStore & { clear(): void } {
   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() },
+    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()
+    },
   }
 }
 
@@ -73,7 +81,10 @@ export interface Entitlements {
 }
 
 /** 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 }
+export type PayContext = Partial<Omit<Context, 'request'>> & {
+  request: { url: string }
+  user?: { id?: string | null } | null
+}
 
 /** What `definePay` takes. */
 export interface PayOptions<P extends Product> {
@@ -109,7 +120,14 @@ export interface CheckoutInput<P extends Product = Product> {
 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> } } }
+  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. */
@@ -120,7 +138,11 @@ export interface Pay<P extends Product = Product> extends ServerExtension {
   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[] }>
+  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>
@@ -130,166 +152,38 @@ export interface Pay<P extends Product = Product> extends ServerExtension {
   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 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 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)
+    })
+  const rails = makeRails(options, slot)
+  const { railFor } = rails
+
+  const { live, entitlements, ingest } = makeLedger(store, byId, leeway)
 
   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
-    },
+    input: checkoutInput(byId),
+    checkout: checkoutFor({ options, urls, userOf, store, railFor, live, byId }),
+    portal: portalFor({ options, urls, userOf, store, railFor, live, byId }),
     entitlements,
-    forContext: ctx => entitlements(userOf(ctx)),
-    purchases: user => store.byUser(user),
+    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)
-      }
-    },
+    webhook: webhookFor(railFor, ingest),
     async refund(id) {
       const p = await store.purchase(id)
       if (!p) throw new PayError('PAY024', `no purchase \`${id}\``, 404)
@@ -297,26 +191,35 @@ export function definePay<P extends Product>(options: PayOptions<P>): Pay<P> {
       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 },
+    use(rail) {
+      rails.use(rail)
+    },
     reset() {
-      override = undefined
+      rails.use(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))
+      const { response, tags } = await pay.webhook(path, request, (d) => api.report(d))
       await api.invalidate(tags)
       return response
     },
-    context: ctx => ({ entitlements: pay.forContext(ctx) }),
+    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)
+      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)
+      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

package/src/setup.mjs

@@ -8,7 +8,7 @@ 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')}
+${PURCHASE.map((c) => `  ${c}: ${str},`).join('\n')}
   state: ${str}.notNull(),
   at: ${long}.notNull(),
   expires: ${long},
@@ -21,9 +21,12 @@ export const payEvents = ${table}('pay_events', {
 })
 `
   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' })" })}`,
+    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]()
 }
 
@@ -40,7 +43,9 @@ export const pro = product({
 })
 `
 
-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'
+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: '/' } })
@@ -77,7 +82,8 @@ export const setup = {
   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')
+    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,
@@ -86,12 +92,23 @@ export const setup = {
         ...(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.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)']),
+        ...(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',
       ],
     }