@stravigor/cashier 0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@stravigor/cashier",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Stripe billing for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": ["src/", "stubs/", "package.json", "tsconfig.json"],
+  "peerDependencies": {
+    "@stravigor/core": "0.2.5"
+  },
+  "dependencies": {
+    "stripe": "^17.4.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/billable.ts

@@ -0,0 +1,291 @@
+import type Stripe from 'stripe'
+import type BaseModel from '@stravigor/core/orm/base_model'
+import type { NormalizeConstructor } from '@stravigor/core/helpers'
+import { extractUserId } from '@stravigor/core/helpers'
+import Customer from './customer.ts'
+import Subscription from './subscription.ts'
+import SubscriptionBuilder from './subscription_builder.ts'
+import CheckoutBuilder from './checkout_builder.ts'
+import Invoice from './invoice.ts'
+import PaymentMethod from './payment_method.ts'
+import CashierManager from './cashier_manager.ts'
+import type { CustomerData, SubscriptionData } from './types.ts'
+
+// ---------------------------------------------------------------------------
+// Bound builders (auto-pass user to .create())
+// ---------------------------------------------------------------------------
+
+class BoundSubscriptionBuilder extends SubscriptionBuilder {
+  private _user: unknown
+
+  constructor(user: unknown, name: string, ...prices: string[]) {
+    super(name, ...prices)
+    this._user = user
+  }
+
+  override async create(user?: unknown): Promise<SubscriptionData> {
+    return super.create(user ?? this._user)
+  }
+}
+
+class BoundCheckoutBuilder extends CheckoutBuilder {
+  private _user: unknown
+
+  constructor(user: unknown) {
+    super()
+    this._user = user
+  }
+
+  override async create(user?: unknown): Promise<Stripe.Checkout.Session> {
+    return super.create(user ?? this._user)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mixin
+// ---------------------------------------------------------------------------
+
+/**
+ * Mixin that adds billing methods to a BaseModel subclass.
+ *
+ * @example
+ * import { BaseModel } from '@stravigor/core/orm'
+ * import { billable } from '@stravigor/cashier'
+ *
+ * class User extends billable(BaseModel) {
+ *   declare id: number
+ *   declare email: string
+ * }
+ *
+ * // Composable with other mixins:
+ * import { compose } from '@stravigor/core/helpers'
+ * class User extends compose(BaseModel, softDeletes, billable) { }
+ *
+ * const user = await User.find(1)
+ * await user.subscribe('pro', 'price_xxx')
+ * await user.subscribed('pro') // true
+ */
+export function billable<T extends NormalizeConstructor<typeof BaseModel>>(Base: T) {
+  return class Billable extends Base {
+    // ----- Customer -----
+
+    /** Get or create the Stripe customer record for this user. */
+    async createOrGetStripeCustomer(
+      params?: Stripe.CustomerCreateParams
+    ): Promise<CustomerData> {
+      return Customer.createOrGet(this, params)
+    }
+
+    /** Get the local customer record. */
+    async customer(): Promise<CustomerData | null> {
+      return Customer.findByUser(this)
+    }
+
+    /** Get the Stripe customer ID. */
+    async stripeId(): Promise<string | null> {
+      const customer = await Customer.findByUser(this)
+      return customer?.stripeId ?? null
+    }
+
+    /** Check if the user has a Stripe customer record. */
+    async hasStripeId(): Promise<boolean> {
+      return (await Customer.findByUser(this)) !== null
+    }
+
+    // ----- Subscriptions -----
+
+    /**
+     * Start building a new subscription.
+     *
+     * @example
+     * await user.newSubscription('pro', 'price_xxx').trialDays(14).create()
+     * await user.newSubscription('enterprise', 'price_a', 'price_b').create()
+     */
+    newSubscription(name: string, ...prices: string[]): BoundSubscriptionBuilder {
+      return new BoundSubscriptionBuilder(this, name, ...prices)
+    }
+
+    /**
+     * Create a subscription immediately (shorthand).
+     *
+     * @example
+     * await user.subscribe('pro', 'price_xxx')
+     */
+    async subscribe(name: string, priceId: string): Promise<SubscriptionData> {
+      return new BoundSubscriptionBuilder(this, name, priceId).create()
+    }
+
+    /** Get a specific subscription by name. */
+    async subscription(name: string = 'default'): Promise<SubscriptionData | null> {
+      return Subscription.findByName(this, name)
+    }
+
+    /** Get all subscriptions. */
+    async subscriptions(): Promise<SubscriptionData[]> {
+      return Subscription.findByUser(this)
+    }
+
+    /** Check if the user has a valid subscription with the given name. */
+    async subscribed(name: string = 'default'): Promise<boolean> {
+      const sub = await Subscription.findByName(this, name)
+      return sub !== null && Subscription.valid(sub)
+    }
+
+    /** Check if the user is on a trial for the given subscription. */
+    async onTrial(name: string = 'default'): Promise<boolean> {
+      const sub = await Subscription.findByName(this, name)
+      if (sub) return Subscription.onTrial(sub)
+
+      // Also check customer-level trial (generic trial)
+      const customer = await Customer.findByUser(this)
+      return (
+        customer?.trialEndsAt !== null &&
+        customer?.trialEndsAt !== undefined &&
+        customer.trialEndsAt.getTime() > Date.now()
+      )
+    }
+
+    /** Check if the user has an active subscription to a specific price ID. */
+    async subscribedToPrice(priceId: string): Promise<boolean> {
+      const subs = await Subscription.findByUser(this)
+      return subs.some((sub) => Subscription.valid(sub) && sub.stripePriceId === priceId)
+    }
+
+    /** Check if the subscription is on a grace period. */
+    async onGracePeriod(name: string = 'default'): Promise<boolean> {
+      const sub = await Subscription.findByName(this, name)
+      return sub !== null && Subscription.onGracePeriod(sub)
+    }
+
+    // ----- One-time Charges -----
+
+    /**
+     * Create a one-time charge.
+     *
+     * @example
+     * await user.charge(2500, 'pm_xxx', { description: 'Pro-rated upgrade' })
+     */
+    async charge(
+      amount: number,
+      paymentMethodId: string,
+      options?: {
+        currency?: string
+        description?: string
+        metadata?: Record<string, string>
+      }
+    ): Promise<Stripe.PaymentIntent> {
+      const customer = await Customer.createOrGet(this)
+      return CashierManager.stripe.paymentIntents.create({
+        amount,
+        currency: options?.currency ?? CashierManager.config.currency,
+        customer: customer.stripeId,
+        payment_method: paymentMethodId,
+        confirm: true,
+        automatic_payment_methods: {
+          enabled: true,
+          allow_redirects: 'never',
+        },
+        description: options?.description,
+        metadata: {
+          strav_user_id: String(extractUserId(this)),
+          ...options?.metadata,
+        },
+      })
+    }
+
+    /** Refund a payment intent (fully or partially). */
+    async refund(paymentIntentId: string, amount?: number): Promise<Stripe.Refund> {
+      return CashierManager.stripe.refunds.create({
+        payment_intent: paymentIntentId,
+        ...(amount ? { amount } : {}),
+      })
+    }
+
+    // ----- Payment Methods -----
+
+    /** List all payment methods for this user. */
+    async paymentMethods(
+      type?: Stripe.PaymentMethodListParams.Type
+    ): Promise<Stripe.PaymentMethod[]> {
+      return PaymentMethod.list(this, type)
+    }
+
+    /** Get the default payment method. */
+    async defaultPaymentMethod(): Promise<Stripe.PaymentMethod | null> {
+      const customer = await Customer.findByUser(this)
+      if (!customer) return null
+      const methods = await PaymentMethod.list(this)
+      return methods[0] ?? null
+    }
+
+    /** Set a payment method as default. */
+    async setDefaultPaymentMethod(paymentMethodId: string): Promise<void> {
+      return PaymentMethod.setDefault(this, paymentMethodId)
+    }
+
+    /** Create a Stripe SetupIntent for collecting payment info without charging. */
+    async createSetupIntent(
+      params?: Stripe.SetupIntentCreateParams
+    ): Promise<Stripe.SetupIntent> {
+      return Customer.createSetupIntent(this, params)
+    }
+
+    // ----- Checkout -----
+
+    /**
+     * Create a Stripe Checkout session.
+     *
+     * @example
+     * const session = await user.checkout([{ price: 'price_xxx', quantity: 1 }])
+     */
+    async checkout(
+      items: Array<{ price: string; quantity?: number }>
+    ): Promise<Stripe.Checkout.Session> {
+      const builder = new CheckoutBuilder(items)
+      return builder.create(this)
+    }
+
+    /**
+     * Start building a checkout session fluently.
+     *
+     * @example
+     * const session = await user.newCheckout()
+     *   .item('price_xxx', 2)
+     *   .mode('subscription')
+     *   .subscriptionName('pro')
+     *   .create()
+     */
+    newCheckout(): BoundCheckoutBuilder {
+      return new BoundCheckoutBuilder(this)
+    }
+
+    // ----- Invoices -----
+
+    /** List Stripe invoices for this user. */
+    async invoices(params?: Stripe.InvoiceListParams): Promise<Stripe.Invoice[]> {
+      return Invoice.list(this, params)
+    }
+
+    /** Preview the upcoming invoice. */
+    async upcomingInvoice(
+      params?: Stripe.InvoiceRetrieveUpcomingParams
+    ): Promise<Stripe.UpcomingInvoice | null> {
+      return Invoice.upcoming(this, params)
+    }
+
+    // ----- Billing Portal -----
+
+    /** Create a Stripe Customer Portal session URL. */
+    async billingPortalUrl(returnUrl?: string): Promise<string> {
+      const customer = await Customer.createOrGet(this)
+      const session = await CashierManager.stripe.billingPortal.sessions.create({
+        customer: customer.stripeId,
+        return_url: returnUrl ?? CashierManager.config.urls.success,
+      })
+      return session.url
+    }
+  }
+}
+
+/** The instance type of any billable model. */
+export type BillableInstance = InstanceType<ReturnType<typeof billable>>

package/src/cashier_manager.ts

@@ -0,0 +1,80 @@
+import Stripe from 'stripe'
+import { inject } from '@stravigor/core/core'
+import type Configuration from '@stravigor/core/config/configuration'
+import type Database from '@stravigor/core/database/database'
+import { ConfigurationError } from '@stravigor/core/exceptions/errors'
+import { toSnakeCase } from '@stravigor/core/schema'
+import type { CashierConfig } from './types.ts'
+
+@inject
+export default class CashierManager {
+  private static _db: Database
+  private static _config: CashierConfig
+  private static _stripe: Stripe
+  private static _userFkColumn: string
+
+  constructor(db: Database, config: Configuration) {
+    CashierManager._db = db
+
+    const userKey = config.get('cashier.userKey', 'id') as string
+    CashierManager._userFkColumn = `user_${toSnakeCase(userKey)}`
+
+    const secret = config.get('cashier.secret', '') as string
+
+    CashierManager._config = {
+      secret,
+      key: config.get('cashier.key', '') as string,
+      webhookSecret: config.get('cashier.webhookSecret', '') as string,
+      currency: config.get('cashier.currency', 'usd') as string,
+      userKey,
+      urls: {
+        success: config.get('cashier.urls.success', '/billing/success') as string,
+        cancel: config.get('cashier.urls.cancel', '/billing/cancel') as string,
+      },
+    }
+
+    if (secret) {
+      CashierManager._stripe = new Stripe(secret)
+    }
+  }
+
+  static get db(): Database {
+    if (!CashierManager._db) {
+      throw new ConfigurationError(
+        'CashierManager not configured. Resolve it through the container first.'
+      )
+    }
+    return CashierManager._db
+  }
+
+  static get config(): CashierConfig {
+    if (!CashierManager._config) {
+      throw new ConfigurationError(
+        'CashierManager not configured. Resolve it through the container first.'
+      )
+    }
+    return CashierManager._config
+  }
+
+  static get stripe(): Stripe {
+    if (!CashierManager._stripe) {
+      throw new ConfigurationError(
+        'CashierManager not configured. Ensure STRIPE_SECRET is set.'
+      )
+    }
+    return CashierManager._stripe
+  }
+
+  /** The FK column name on cashier tables (e.g. `user_id`, `user_uid`). */
+  static get userFkColumn(): string {
+    return CashierManager._userFkColumn ?? 'user_id'
+  }
+
+  /** Reset internal state (useful for testing). */
+  static reset(): void {
+    CashierManager._db = undefined as any
+    CashierManager._config = undefined as any
+    CashierManager._stripe = undefined as any
+    CashierManager._userFkColumn = undefined as any
+  }
+}

package/src/checkout_builder.ts

@@ -0,0 +1,130 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/core/helpers'
+import CashierManager from './cashier_manager.ts'
+import Customer from './customer.ts'
+
+interface CheckoutLineItem {
+  price: string
+  quantity?: number
+}
+
+/**
+ * Fluent builder for creating Stripe Checkout sessions.
+ *
+ * @example
+ * const session = await new CheckoutBuilder()
+ *   .item('price_xxx', 2)
+ *   .mode('subscription')
+ *   .subscriptionName('pro')
+ *   .create(user)
+ */
+export default class CheckoutBuilder {
+  private _items: CheckoutLineItem[] = []
+  private _mode: Stripe.Checkout.SessionCreateParams.Mode = 'payment'
+  private _successUrl?: string
+  private _cancelUrl?: string
+  private _allowPromotionCodes = false
+  private _metadata: Record<string, string> = {}
+  private _subscriptionName?: string
+  private _trialDays?: number
+  private _customerEmail?: string
+
+  constructor(items?: CheckoutLineItem[]) {
+    if (items) this._items = items
+  }
+
+  /** Add a line item. */
+  item(price: string, quantity?: number): this {
+    this._items.push({ price, quantity: quantity ?? 1 })
+    return this
+  }
+
+  /** Set checkout mode: 'payment' | 'subscription' | 'setup'. */
+  mode(mode: Stripe.Checkout.SessionCreateParams.Mode): this {
+    this._mode = mode
+    return this
+  }
+
+  /** Set success URL. Overrides config default. */
+  successUrl(url: string): this {
+    this._successUrl = url
+    return this
+  }
+
+  /** Set cancel URL. Overrides config default. */
+  cancelUrl(url: string): this {
+    this._cancelUrl = url
+    return this
+  }
+
+  /** Allow promotion codes in the checkout page. */
+  allowPromotionCodes(allow = true): this {
+    this._allowPromotionCodes = allow
+    return this
+  }
+
+  /** Set custom metadata. */
+  metadata(data: Record<string, string>): this {
+    this._metadata = { ...this._metadata, ...data }
+    return this
+  }
+
+  /** Name the subscription (stored in metadata, used by webhook handler). */
+  subscriptionName(name: string): this {
+    this._subscriptionName = name
+    this._mode = 'subscription'
+    return this
+  }
+
+  /** Add trial days (subscription mode only). */
+  trialDays(days: number): this {
+    this._trialDays = days
+    return this
+  }
+
+  /** Pre-fill customer email (for guest users without a Stripe customer). */
+  email(email: string): this {
+    this._customerEmail = email
+    return this
+  }
+
+  /**
+   * Create the Stripe Checkout Session.
+   * If user is provided, attaches to their Stripe customer.
+   */
+  async create(user?: unknown): Promise<Stripe.Checkout.Session> {
+    const config = CashierManager.config
+
+    const params: Stripe.Checkout.SessionCreateParams = {
+      mode: this._mode,
+      line_items: this._items.map((i) => ({
+        price: i.price,
+        quantity: i.quantity,
+      })),
+      success_url: this._successUrl ?? config.urls.success,
+      cancel_url: this._cancelUrl ?? config.urls.cancel,
+      allow_promotion_codes: this._allowPromotionCodes || undefined,
+      metadata: {
+        ...(this._subscriptionName ? { strav_name: this._subscriptionName } : {}),
+        ...this._metadata,
+      },
+    }
+
+    if (user) {
+      const customer = await Customer.createOrGet(user)
+      params.customer = customer.stripeId
+      params.metadata!.strav_user_id = String(extractUserId(user))
+    } else if (this._customerEmail) {
+      params.customer_email = this._customerEmail
+    }
+
+    if (this._trialDays && this._mode === 'subscription') {
+      params.subscription_data = {
+        trial_period_days: this._trialDays,
+        metadata: params.metadata,
+      }
+    }
+
+    return CashierManager.stripe.checkout.sessions.create(params)
+  }
+}

package/src/customer.ts

@@ -0,0 +1,157 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/core/helpers'
+import CashierManager from './cashier_manager.ts'
+import type { CustomerData } from './types.ts'
+
+/**
+ * Static helper for managing Stripe customer records.
+ *
+ * All methods are static. Database access goes through CashierManager.db.
+ *
+ * @example
+ * const customer = await Customer.createOrGet(user)
+ * const methods = await Customer.paymentMethods(user)
+ */
+export default class Customer {
+  private static get sql() {
+    return CashierManager.db.sql
+  }
+
+  private static get fk() {
+    return CashierManager.userFkColumn
+  }
+
+  /** Find a customer record by user (model instance or ID). */
+  static async findByUser(user: unknown): Promise<CustomerData | null> {
+    const userId = extractUserId(user)
+    const fk = Customer.fk
+    const rows = await Customer.sql.unsafe(
+      `SELECT * FROM "customer" WHERE "${fk}" = $1 LIMIT 1`,
+      [userId]
+    )
+    return rows.length > 0 ? Customer.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  /** Find a customer record by Stripe customer ID. */
+  static async findByStripeId(stripeId: string): Promise<CustomerData | null> {
+    const rows = await Customer.sql`
+      SELECT * FROM "customer" WHERE "stripe_id" = ${stripeId} LIMIT 1
+    `
+    return rows.length > 0 ? Customer.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  /**
+   * Get or create the Stripe customer + local record for a user.
+   * Optionally pass params forwarded to `stripe.customers.create()`.
+   */
+  static async createOrGet(
+    user: unknown,
+    params?: Stripe.CustomerCreateParams
+  ): Promise<CustomerData> {
+    const existing = await Customer.findByUser(user)
+    if (existing) return existing
+
+    const userId = extractUserId(user)
+    const stripeCustomer = await CashierManager.stripe.customers.create({
+      metadata: { strav_user_id: String(userId) },
+      ...params,
+    })
+
+    const fk = Customer.fk
+    const rows = await Customer.sql.unsafe(
+      `INSERT INTO "customer" ("${fk}", "stripe_id")
+       VALUES ($1, $2)
+       RETURNING *`,
+      [userId, stripeCustomer.id]
+    )
+    return Customer.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Update the default payment method on the local record. */
+  static async updateDefaultPaymentMethod(
+    stripeCustomerId: string,
+    paymentMethod: Stripe.PaymentMethod
+  ): Promise<void> {
+    await Customer.sql`
+      UPDATE "customer"
+      SET "pm_type" = ${paymentMethod.type},
+          "pm_last_four" = ${paymentMethod.card?.last4 ?? null},
+          "updated_at" = NOW()
+      WHERE "stripe_id" = ${stripeCustomerId}
+    `
+  }
+
+  /** Create a Stripe SetupIntent for the customer. */
+  static async createSetupIntent(
+    user: unknown,
+    params?: Stripe.SetupIntentCreateParams
+  ): Promise<Stripe.SetupIntent> {
+    const customer = await Customer.createOrGet(user)
+    return CashierManager.stripe.setupIntents.create({
+      customer: customer.stripeId,
+      ...params,
+    })
+  }
+
+  /** List all payment methods for a user's Stripe customer. */
+  static async paymentMethods(
+    user: unknown,
+    type: Stripe.PaymentMethodListParams.Type = 'card'
+  ): Promise<Stripe.PaymentMethod[]> {
+    const customer = await Customer.findByUser(user)
+    if (!customer) return []
+    const result = await CashierManager.stripe.paymentMethods.list({
+      customer: customer.stripeId,
+      type,
+    })
+    return result.data
+  }
+
+  /** Detach a payment method from Stripe. */
+  static async deletePaymentMethod(paymentMethodId: string): Promise<void> {
+    await CashierManager.stripe.paymentMethods.detach(paymentMethodId)
+  }
+
+  /** Sync trial_ends_at on the local record. */
+  static async updateTrialEndsAt(
+    stripeCustomerId: string,
+    trialEndsAt: Date | null
+  ): Promise<void> {
+    await Customer.sql`
+      UPDATE "customer"
+      SET "trial_ends_at" = ${trialEndsAt},
+          "updated_at" = NOW()
+      WHERE "stripe_id" = ${stripeCustomerId}
+    `
+  }
+
+  /** Delete the local customer record. Does NOT delete from Stripe. */
+  static async deleteByUser(user: unknown): Promise<void> {
+    const userId = extractUserId(user)
+    const fk = Customer.fk
+    await Customer.sql.unsafe(`DELETE FROM "customer" WHERE "${fk}" = $1`, [userId])
+  }
+
+  /** Delete the local customer record by Stripe ID. */
+  static async deleteByStripeId(stripeId: string): Promise<void> {
+    await Customer.sql`DELETE FROM "customer" WHERE "stripe_id" = ${stripeId}`
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): CustomerData {
+    const fk = Customer.fk
+    return {
+      id: row.id as number,
+      userId: row[fk] as string | number,
+      stripeId: row.stripe_id as string,
+      pmType: (row.pm_type as string) ?? null,
+      pmLastFour: (row.pm_last_four as string) ?? null,
+      trialEndsAt: (row.trial_ends_at as Date) ?? null,
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import { StravError } from '@stravigor/core/exceptions/strav_error'
+
+/** Base error class for all Cashier errors. */
+export class CashierError extends StravError {}
+
+/** Thrown when webhook signature verification fails. */
+export class WebhookSignatureError extends CashierError {
+  constructor() {
+    super('Stripe webhook signature verification failed.')
+  }
+}
+
+/** Thrown when a user has no Stripe customer record. */
+export class CustomerNotFoundError extends CashierError {
+  constructor() {
+    super('No Stripe customer found for this user.')
+  }
+}
+
+/** Thrown when a subscription is not found. */
+export class SubscriptionNotFoundError extends CashierError {
+  constructor(name: string) {
+    super(`No subscription named "${name}" found for this user.`)
+  }
+}