@strav/payment 1.0.0-alpha.28 → 1.0.0-alpha.30

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@strav/payment",
-  "version": "1.0.0-alpha.28",
-  "description": "Strav payment module — provider-agnostic payment abstraction. Normalized DTOs, multi-provider routing, ledger schema, webhook dispatcher. Stripe and Omise drivers ship as subpath imports (`@strav/payment/stripe`, `@strav/payment/omise`). Paddle support comes in a later release.",
+  "version": "1.0.0-alpha.30",
+  "description": "Strav payment module — provider-agnostic payment abstraction. Normalized DTOs, multi-provider routing, ledger schema, webhook dispatcher, Cashier-style Billable mixin. Stripe and Omise drivers ship as subpath imports (`@strav/payment/stripe`, `@strav/payment/omise`). Paddle support comes in a later release.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,9 +21,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.28",
-    "@strav/http": "1.0.0-alpha.28",
-    "@strav/kernel": "1.0.0-alpha.28",
+    "@strav/database": "1.0.0-alpha.30",
+    "@strav/http": "1.0.0-alpha.30",
+    "@strav/kernel": "1.0.0-alpha.30",
     "stripe": "^18.0.0",
     "omise": "^0.12.0"
   },

package/src/billable.ts

@@ -0,0 +1,284 @@
+/**
+ * `billable()` — Cashier-style billing mixin for app models.
+ *
+ * Layers customer / charge / subscription convenience methods onto a
+ * domain model (typically `User`) so the call sites read as:
+ *
+ *   const user = await users.findOrFail(id)
+ *   await user.createCustomer(payments, { email: user.email })
+ *   await user.charge(payments, { amount: 4900, currency: 'usd', ... })
+ *   const subs = await user.subscriptions(payments.ledger!)
+ *
+ * **Manager + ledger are passed explicitly per call.** No static
+ * singleton, no implicit container lookup — Strav favours explicit
+ * injection. The trade-off is a bit more typing at the call site for
+ * compile-time clarity about which provider the call touches and
+ * which DB the read hits.
+ *
+ * **Storage contract.** A billable needs somewhere to remember the
+ * customer id Stripe / Omise minted for it. The default lives on a
+ * `payment_customers: Record<provider, string>` JSON field — apps
+ * that already have a `payment_customers` column get persistence for
+ * free. Apps with a different schema override `paymentCustomerId()`
+ * + `setPaymentCustomerId()` directly:
+ *
+ *   class User extends billable(Model) {
+ *     stripe_customer_id?: string | null
+ *     override paymentCustomerId(provider: string): string | undefined {
+ *       return provider === 'stripe' ? this.stripe_customer_id ?? undefined : undefined
+ *     }
+ *     override async setPaymentCustomerId(provider: string, id: string) {
+ *       if (provider === 'stripe') this.stripe_customer_id = id
+ *     }
+ *   }
+ *
+ * The setter is sync OR async — apps that want to persist immediately
+ * `await users.save(this)` inside the setter. Apps that prefer batch
+ * saves leave the setter sync and call `save()` themselves.
+ *
+ * Two factory forms:
+ *   - `class User extends Billable { ... }` — the base class itself,
+ *     handy for new domain models.
+ *   - `class User extends billable(BaseModel) { ... }` — the mixin
+ *     form, for apps already extending another base (`Model`,
+ *     `AuthenticatableUser`, …).
+ */
+
+import type {
+  CreateChargeInput,
+  CreateCustomerInput,
+  CreateSubscriptionInput,
+  PaymentCharge,
+  PaymentCustomer,
+  PaymentMethod,
+  PaymentSubscription,
+} from './dto/index.ts'
+import type { PaymentLedger } from './ledger/payment_ledger.ts'
+import type { PaymentInvoiceRow, PaymentSubscriptionRow } from './ledger/payment_ledger_models.ts'
+import type { PaymentManager } from './payment_manager.ts'
+
+const ACTIVE_SUBSCRIPTION_STATUSES = new Set(['active', 'trialing', 'past_due'])
+
+export interface BillableStorage {
+  /** The provider-side customer id for `provider`, or `undefined` when not yet provisioned. */
+  paymentCustomerId(provider: string): string | undefined
+  /**
+   * Persist `id` as this billable's customer id with `provider`. Sync
+   * OR async — apps that hit the DB inside the setter return the
+   * persistence promise.
+   */
+  setPaymentCustomerId(provider: string, id: string): void | Promise<void>
+}
+
+/**
+ * Base class form — `class User extends Billable { ... }`. Subclasses
+ * MUST also declare `static schema = ...` if they extend `Model`
+ * (the mixin form does this in the chain automatically).
+ *
+ * Override `paymentCustomerId()` / `setPaymentCustomerId()` to use a
+ * storage layout other than the default `payment_customers` map.
+ */
+export class Billable implements BillableStorage {
+  /**
+   * Default storage — apps that have a `payment_customers` jsonb
+   * column on their model get this for free. The mixin reads /
+   * writes through here unless the subclass overrides.
+   */
+  payment_customers?: Record<string, string>
+
+  paymentCustomerId(provider: string): string | undefined {
+    return this.payment_customers?.[provider]
+  }
+
+  setPaymentCustomerId(provider: string, id: string): void {
+    this.payment_customers = { ...(this.payment_customers ?? {}), [provider]: id }
+  }
+
+  // ─── Customer ─────────────────────────────────────────────────────────
+
+  /**
+   * Fetch the current `PaymentCustomer` for `provider` (default:
+   * `manager.config.default`). Returns `null` when no customer id is
+   * stored — useful for "user hasn't paid yet" branches.
+   */
+  async customer(manager: PaymentManager, provider?: string): Promise<PaymentCustomer | null> {
+    const p = provider ?? manager.config.default
+    const cid = this.paymentCustomerId(p)
+    if (cid === undefined) return null
+    return manager.use(p).customers.retrieve(cid)
+  }
+
+  /**
+   * Create a customer with `manager.use(provider).customers.create(input)`
+   * and persist the returned id via `setPaymentCustomerId(provider, id)`.
+   * Apps usually call this once during checkout / onboarding.
+   */
+  async createCustomer(
+    manager: PaymentManager,
+    input: CreateCustomerInput,
+    provider?: string,
+  ): Promise<PaymentCustomer> {
+    const p = provider ?? manager.config.default
+    const created = await manager.use(p).customers.create(input)
+    await this.setPaymentCustomerId(p, created.id)
+    return created
+  }
+
+  /**
+   * Return the existing customer (if any) or create + persist one.
+   * Idempotent under retries when `input.idempotencyKey` is set on
+   * drivers with the `idempotency` capability.
+   */
+  async customerOrCreate(
+    manager: PaymentManager,
+    input: CreateCustomerInput,
+    provider?: string,
+  ): Promise<PaymentCustomer> {
+    const existing = await this.customer(manager, provider)
+    if (existing !== null) return existing
+    return this.createCustomer(manager, input, provider)
+  }
+
+  // ─── Charges + subscriptions + payment methods ────────────────────────
+
+  /**
+   * One-shot charge against this billable's customer. The mixin
+   * injects `customer` from storage so callers omit it.
+   *
+   * Apps that explicitly want to charge a different customer reach
+   * `manager.charges.create(...)` directly — the mixin is sugar, not
+   * a gate.
+   */
+  async charge(
+    manager: PaymentManager,
+    input: Omit<CreateChargeInput, 'customer'>,
+    provider?: string,
+  ): Promise<PaymentCharge> {
+    const p = provider ?? manager.config.default
+    return manager.use(p).charges.create({
+      ...input,
+      customer: this.requireCustomerId(p),
+    })
+  }
+
+  /** Subscribe this billable to `price`. Same omitted-customer ergonomics as `charge()`. */
+  async subscribe(
+    manager: PaymentManager,
+    input: Omit<CreateSubscriptionInput, 'customer'>,
+    provider?: string,
+  ): Promise<PaymentSubscription> {
+    const p = provider ?? manager.config.default
+    return manager.use(p).subscriptions.create({
+      ...input,
+      customer: this.requireCustomerId(p),
+    })
+  }
+
+  /** Payment methods attached to this billable's customer. */
+  async paymentMethods(manager: PaymentManager, provider?: string): Promise<PaymentMethod[]> {
+    const p = provider ?? manager.config.default
+    const cid = this.paymentCustomerId(p)
+    if (cid === undefined) return []
+    const result = await manager.use(p).paymentMethods.list(cid)
+    return result.data
+  }
+
+  // ─── Ledger reads ─────────────────────────────────────────────────────
+
+  /**
+   * Subscriptions stored in the local ledger for this billable's
+   * customer (newest first). Returns an empty array when there's no
+   * customer id yet.
+   *
+   * Reads `payment_subscription` joined by `(provider,
+   * customer_provider_id)`. Honours the tenant the caller is in
+   * (RLS).
+   */
+  async subscriptions(ledger: PaymentLedger, provider: string): Promise<PaymentSubscriptionRow[]> {
+    const cid = this.paymentCustomerId(provider)
+    if (cid === undefined) return []
+    return ledger.subscriptionsForCustomer(provider, cid)
+  }
+
+  /** Invoices for this billable's customer (newest first, default 50). */
+  async invoices(
+    ledger: PaymentLedger,
+    provider: string,
+    options: { limit?: number } = {},
+  ): Promise<PaymentInvoiceRow[]> {
+    const cid = this.paymentCustomerId(provider)
+    if (cid === undefined) return []
+    return ledger.invoicesForCustomer(provider, cid, options)
+  }
+
+  /**
+   * `true` when the billable has at least one subscription whose
+   * status is `active` / `trialing` / `past_due`. Cancelled, ended,
+   * and incomplete don't count.
+   */
+  async hasActiveSubscription(ledger: PaymentLedger, provider: string): Promise<boolean> {
+    const subs = await this.subscriptions(ledger, provider)
+    return subs.some((s) => ACTIVE_SUBSCRIPTION_STATUSES.has(s.status))
+  }
+
+  /**
+   * `true` when the billable has an active subscription on the
+   * given `priceProviderId`. Useful for entitlement checks
+   * (`if (await user.subscribedToPrice(ledger, 'price_pro')) { ... }`).
+   */
+  async subscribedToPrice(
+    ledger: PaymentLedger,
+    priceProviderId: string,
+    provider: string,
+  ): Promise<boolean> {
+    const subs = await this.subscriptions(ledger, provider)
+    return subs.some(
+      (s) => s.price_provider_id === priceProviderId && ACTIVE_SUBSCRIPTION_STATUSES.has(s.status),
+    )
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────
+
+  private requireCustomerId(provider: string): string {
+    const cid = this.paymentCustomerId(provider)
+    if (cid === undefined) {
+      throw new Error(
+        `Billable: no customer id stored for provider "${provider}". Call createCustomer() / customerOrCreate() first.`,
+      )
+    }
+    return cid
+  }
+}
+
+// Constructor type used by the mixin form.
+// biome-ignore lint/suspicious/noExplicitAny: mixin signatures need any[] constructor args.
+type Ctor<T = object> = new (...args: any[]) => T
+
+/**
+ * Mixin form — `class User extends billable(Model) { ... }`.
+ *
+ * Layers every `Billable` method onto `Base` and threads the same
+ * default-storage contract. Apps with a `payment_customers` jsonb
+ * column work zero-config; apps with a different layout override the
+ * two storage hooks on the subclass.
+ *
+ * Why both this and the `Billable` base class — apps that need a
+ * fresh class extend `Billable` directly; apps that already extend
+ * `Model` / a domain base reach for `billable(Model)`. The two share
+ * the same Billable prototype so behaviour is identical.
+ */
+export function billable<TBase extends Ctor>(Base: TBase): TBase & Ctor<Billable> {
+  abstract class _Billable extends (Base as Ctor) {}
+  // Copy every Billable method (own props of the prototype) onto the
+  // mixin chain. We mutate the chain directly instead of `extends
+  // Billable` because Billable doesn't share `Base`'s ancestry —
+  // multiple-extends isn't a thing in JS.
+  for (const key of Object.getOwnPropertyNames(Billable.prototype)) {
+    if (key === 'constructor') continue
+    const desc = Object.getOwnPropertyDescriptor(Billable.prototype, key)
+    if (desc !== undefined) {
+      Object.defineProperty(_Billable.prototype, key, desc)
+    }
+  }
+  return _Billable as unknown as TBase & Ctor<Billable>
+}

package/src/index.ts

@@ -10,6 +10,7 @@
 //   `@strav/payment-omise`. The `MockDriver` in `./drivers` is
 //   for tests and as the reference implementation.
 
+export { Billable, type BillableStorage, billable } from './billable.ts'
 export type * from './dto/index.ts'
 export {
   extractCardToken,

package/src/ledger/payment_ledger.ts

@@ -29,13 +29,14 @@
  */
 
 // biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject() metadata.
-import {
-  PostgresDatabase,
-  quoteIdent,
-  type DatabaseExecutor,
-} from '@strav/database'
+import { type DatabaseExecutor, PostgresDatabase, quoteIdent } from '@strav/database'
 import { inject, ulid } from '@strav/kernel'
 import type { NormalizedWebhookEvent } from '../dto/payment_event.ts'
+import {
+  PaymentCustomerRow,
+  PaymentInvoiceRow,
+  PaymentSubscriptionRow,
+} from './payment_ledger_models.ts'
 import { paymentCustomerSchema } from './schemas/payment_customer_schema.ts'
 import { paymentInvoiceSchema } from './schemas/payment_invoice_schema.ts'
 import { paymentSubscriptionSchema } from './schemas/payment_subscription_schema.ts'
@@ -65,10 +66,7 @@ export class PaymentLedger {
    * during `normalize`). When `_fields` is absent the upsert
    * no-ops (apps still get the event, just no local mirror).
    */
-  async applyEvent(
-    event: NormalizedWebhookEvent,
-    executor?: DatabaseExecutor,
-  ): Promise<void> {
+  async applyEvent(event: NormalizedWebhookEvent, executor?: DatabaseExecutor): Promise<void> {
     const fields = (event as { _fields?: Record<string, unknown> })._fields
     if (!fields) return
     const exec = executor ?? this.db
@@ -100,6 +98,67 @@ export class PaymentLedger {
     }
   }
 
+  // ─── Reads ────────────────────────────────────────────────────────────
+  //
+  // Lightweight query helpers for the `billable()` mixin and for app
+  // code that wants to render "this user's billing history" without
+  // pulling in a Repository. All reads honour the same `app.tenant_id`
+  // session setting the upserts do, so tenancy is implicit.
+
+  /**
+   * Find a customer row by (`provider`, `provider_id`). Returns
+   * `null` when no row exists — typical for billables that haven't
+   * been charged through this provider yet.
+   */
+  async customerByProviderId(
+    provider: string,
+    providerId: string,
+  ): Promise<PaymentCustomerRow | null> {
+    const table = quoteIdent(paymentCustomerSchema.name)
+    const row = await this.db.queryOne<Record<string, unknown>>(
+      `SELECT * FROM ${table} WHERE "provider" = $1 AND "provider_id" = $2`,
+      [provider, providerId],
+    )
+    return row === null ? null : hydrate(PaymentCustomerRow, row)
+  }
+
+  /** Subscriptions for `(provider, customer_provider_id)`, newest first. */
+  async subscriptionsForCustomer(
+    provider: string,
+    customerProviderId: string,
+  ): Promise<PaymentSubscriptionRow[]> {
+    const table = quoteIdent(paymentSubscriptionSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table}
+       WHERE "provider" = $1 AND "customer_provider_id" = $2
+       ORDER BY "created_at" DESC`,
+      [provider, customerProviderId],
+    )
+    return rows.map((r) => hydrate(PaymentSubscriptionRow, r))
+  }
+
+  /**
+   * Invoices for `(provider, customer_provider_id)`. Returned newest
+   * first. `limit` defaults to 50 — apps rendering long lists pass a
+   * higher number or paginate at the app layer.
+   */
+  async invoicesForCustomer(
+    provider: string,
+    customerProviderId: string,
+    options: { limit?: number } = {},
+  ): Promise<PaymentInvoiceRow[]> {
+    const limit = options.limit ?? 50
+    const table = quoteIdent(paymentInvoiceSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table}
+       WHERE "provider" = $1 AND "customer_provider_id" = $2
+       ORDER BY "created_at" DESC
+       LIMIT $3`,
+      [provider, customerProviderId, limit],
+    )
+    return rows.map((r) => hydrate(PaymentInvoiceRow, r))
+  }
+
   private async upsertCustomer(
     exec: DatabaseExecutor,
     provider: string,
@@ -138,10 +197,10 @@ export class PaymentLedger {
     providerId: string,
   ): Promise<void> {
     const table = quoteIdent(paymentCustomerSchema.name)
-    await exec.execute(
-      `DELETE FROM ${table} WHERE "provider" = $1 AND "provider_id" = $2`,
-      [provider, providerId],
-    )
+    await exec.execute(`DELETE FROM ${table} WHERE "provider" = $1 AND "provider_id" = $2`, [
+      provider,
+      providerId,
+    ])
   }
 
   private async upsertSubscription(
@@ -252,6 +311,13 @@ function nullable(v: unknown): string | null {
   return v
 }
 
+/** Materialise a SELECT row into the matching Model subclass. */
+function hydrate<T extends object>(Ctor: new () => T, row: Record<string, unknown>): T {
+  const instance = new Ctor()
+  Object.assign(instance, row)
+  return instance
+}
+
 function toDate(v: unknown): Date | null {
   if (v === null || v === undefined) return null
   if (v instanceof Date) return v