@strav/stripe 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @stravigor/stripe
+
+Stripe billing for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Subscriptions, one-time charges, checkout sessions, invoices, payment methods, and webhooks.
+
+## Install
+
+```bash
+bun add @stravigor/stripe
+bun strav install stripe
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { StripeProvider } from '@stravigor/stripe'
+
+app.use(new StripeProvider())
+```
+
+## Usage
+
+```ts
+import { stripe } from '@stravigor/stripe'
+
+// Create a customer
+const customer = await stripe.createOrGetCustomer(user)
+
+// Start a subscription
+const subscription = await stripe
+  .newSubscription('default', 'price_xxx')
+  .create(user)
+
+// Checkout session
+const checkout = await stripe
+  .newCheckout()
+  .item('price_xxx')
+  .successUrl('/success')
+  .cancelUrl('/cancel')
+  .create(user)
+```
+
+## Billable Mixin
+
+```ts
+import { billable } from '@stravigor/stripe'
+
+class User extends billable(BaseModel) {
+  // adds subscription, invoice, and payment helpers
+}
+```
+
+## Webhooks
+
+```ts
+import { stripeWebhook, onWebhookEvent } from '@stravigor/stripe'
+
+onWebhookEvent('customer.subscription.updated', async (event) => {
+  // handle subscription changes
+})
+
+router.post('/stripe/webhook', stripeWebhook())
+```
+
+## Documentation
+
+See the full [Stripe billing guide](../../guides/stripe.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@strav/stripe",
+  "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": {
+    "@strav/kernel": "0.1.0",
+    "@strav/database": "0.1.0",
+    "@strav/http": "0.1.0"
+  },
+  "dependencies": {
+    "stripe": "^17.4.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/billable.ts

@@ -0,0 +1,287 @@
+import type Stripe from 'stripe'
+import type { BaseModel } from '@stravigor/database'
+import type { NormalizeConstructor } from '@stravigor/kernel'
+import { extractUserId } from '@stravigor/database'
+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 StripeManager from './stripe_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/database'
+ * import { billable } from '@stravigor/stripe'
+ *
+ * class User extends billable(BaseModel) {
+ *   declare id: number
+ *   declare email: string
+ * }
+ *
+ * // Composable with other mixins:
+ * import { compose } from '@stravigor/kernel'
+ * 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 StripeManager.stripe.paymentIntents.create({
+        amount,
+        currency: options?.currency ?? StripeManager.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 StripeManager.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 StripeManager.stripe.billingPortal.sessions.create({
+        customer: customer.stripeId,
+        return_url: returnUrl ?? StripeManager.config.urls.success,
+      })
+      return session.url
+    }
+  }
+}
+
+/** The instance type of any billable model. */
+export type BillableInstance = InstanceType<ReturnType<typeof billable>>

package/src/checkout_builder.ts

@@ -0,0 +1,130 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/database'
+import StripeManager from './stripe_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 = StripeManager.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 StripeManager.stripe.checkout.sessions.create(params)
+  }
+}

package/src/customer.ts

@@ -0,0 +1,156 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/database'
+import StripeManager from './stripe_manager.ts'
+import type { CustomerData } from './types.ts'
+
+/**
+ * Static helper for managing Stripe customer records.
+ *
+ * All methods are static. Database access goes through StripeManager.db.
+ *
+ * @example
+ * const customer = await Customer.createOrGet(user)
+ * const methods = await Customer.paymentMethods(user)
+ */
+export default class Customer {
+  private static get sql() {
+    return StripeManager.db.sql
+  }
+
+  private static get fk() {
+    return StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.stripe.paymentMethods.list({
+      customer: customer.stripeId,
+      type,
+    })
+    return result.data
+  }
+
+  /** Detach a payment method from Stripe. */
+  static async deletePaymentMethod(paymentMethodId: string): Promise<void> {
+    await StripeManager.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,31 @@
+import { StravError } from '@stravigor/kernel'
+
+/** Base error class for all Stripe billing errors. */
+export class StripeError extends StravError {}
+
+/** Thrown when webhook signature verification fails. */
+export class WebhookSignatureError extends StripeError {
+  constructor() {
+    super('Stripe webhook signature verification failed.')
+  }
+}
+
+/** Thrown when a user has no Stripe customer record. */
+export class CustomerNotFoundError extends StripeError {
+  constructor() {
+    super('No Stripe customer found for this user.')
+  }
+}
+
+/** Thrown when a subscription is not found. */
+export class SubscriptionNotFoundError extends StripeError {
+  constructor(name: string) {
+    super(`No subscription named "${name}" found for this user.`)
+  }
+}
+
+/** Thrown when a payment method operation fails on Stripe. */
+export class PaymentMethodError extends StripeError {}
+
+/** Thrown when a subscription creation fails on Stripe. */
+export class SubscriptionCreationError extends StripeError {}