@stravigor/cashier 0.1.0

package/src/subscription_builder.ts

@@ -0,0 +1,176 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/core/helpers'
+import CashierManager from './cashier_manager.ts'
+import Customer from './customer.ts'
+import Subscription from './subscription.ts'
+import SubscriptionItem from './subscription_item.ts'
+import type { SubscriptionData } from './types.ts'
+
+interface PendingItem {
+  price: string
+  quantity?: number
+}
+
+/**
+ * Fluent builder for creating Stripe subscriptions.
+ *
+ * @example
+ * const sub = await new SubscriptionBuilder('pro', 'price_xxx')
+ *   .trialDays(14)
+ *   .coupon('LAUNCH20')
+ *   .create(user)
+ */
+export default class SubscriptionBuilder {
+  private _name: string
+  private _items: PendingItem[] = []
+  private _trialDays?: number
+  private _trialUntil?: Date
+  private _skipTrial = false
+  private _coupon?: string
+  private _promotionCode?: string
+  private _metadata: Record<string, string> = {}
+  private _paymentBehavior: Stripe.SubscriptionCreateParams.PaymentBehavior = 'default_incomplete'
+  private _quantity?: number
+  private _anchorBillingCycleOn?: number
+
+  constructor(name: string, ...prices: string[]) {
+    this._name = name
+    for (const price of prices) {
+      this._items.push({ price })
+    }
+  }
+
+  /** Set the default quantity for all items (unless overridden per-item). */
+  quantity(qty: number): this {
+    this._quantity = qty
+    return this
+  }
+
+  /** Add a price with an explicit quantity. */
+  plan(price: string, quantity?: number): this {
+    this._items.push({ price, quantity })
+    return this
+  }
+
+  /** Set a trial period in days. */
+  trialDays(days: number): this {
+    this._trialDays = days
+    return this
+  }
+
+  /** Set a specific trial end date. */
+  trialUntil(date: Date): this {
+    this._trialUntil = date
+    return this
+  }
+
+  /** Skip any trial period. */
+  skipTrial(): this {
+    this._skipTrial = true
+    return this
+  }
+
+  /** Apply a coupon to the subscription. */
+  coupon(couponId: string): this {
+    this._coupon = couponId
+    return this
+  }
+
+  /** Apply a promotion code. */
+  promotionCode(code: string): this {
+    this._promotionCode = code
+    return this
+  }
+
+  /** Add custom metadata to the Stripe subscription. */
+  metadata(data: Record<string, string>): this {
+    this._metadata = { ...this._metadata, ...data }
+    return this
+  }
+
+  /** Anchor the billing cycle to a specific timestamp. */
+  anchorBillingCycleOn(timestamp: number): this {
+    this._anchorBillingCycleOn = timestamp
+    return this
+  }
+
+  /** Set the payment behavior (default: 'default_incomplete'). */
+  paymentBehavior(behavior: Stripe.SubscriptionCreateParams.PaymentBehavior): this {
+    this._paymentBehavior = behavior
+    return this
+  }
+
+  /**
+   * Create the subscription on Stripe and record it locally.
+   * Returns the local SubscriptionData.
+   */
+  async create(user: unknown): Promise<SubscriptionData> {
+    // 1. Ensure Stripe customer exists
+    const customer = await Customer.createOrGet(user)
+
+    // 2. Build Stripe params
+    const items: Stripe.SubscriptionCreateParams.Item[] = this._items.map((item) => ({
+      price: item.price,
+      quantity: item.quantity ?? this._quantity,
+    }))
+
+    const params: Stripe.SubscriptionCreateParams = {
+      customer: customer.stripeId,
+      items,
+      payment_behavior: this._paymentBehavior,
+      expand: ['latest_invoice.payment_intent', 'pending_setup_intent'],
+      metadata: {
+        strav_user_id: String(extractUserId(user)),
+        strav_name: this._name,
+        ...this._metadata,
+      },
+    }
+
+    // Trial logic
+    if (!this._skipTrial) {
+      if (this._trialUntil) {
+        params.trial_end = Math.floor(this._trialUntil.getTime() / 1000)
+      } else if (this._trialDays) {
+        params.trial_end = Math.floor(Date.now() / 1000) + this._trialDays * 86400
+      }
+    }
+
+    if (this._coupon) params.coupon = this._coupon
+    if (this._promotionCode) params.promotion_code = this._promotionCode
+    if (this._anchorBillingCycleOn) {
+      params.billing_cycle_anchor = this._anchorBillingCycleOn
+    }
+
+    // 3. Create on Stripe
+    const stripeSub = await CashierManager.stripe.subscriptions.create(params)
+
+    // 4. Record locally
+    const trialEndsAt = stripeSub.trial_end ? new Date(stripeSub.trial_end * 1000) : null
+
+    const localSub = await Subscription.create({
+      user,
+      name: this._name,
+      stripeId: stripeSub.id,
+      stripeStatus: stripeSub.status,
+      stripePriceId: this._items[0]?.price ?? null,
+      quantity: this._items[0]?.quantity ?? this._quantity ?? null,
+      trialEndsAt,
+    })
+
+    // 5. Record subscription items
+    for (const item of stripeSub.items.data) {
+      await SubscriptionItem.create({
+        subscriptionId: localSub.id,
+        stripeId: item.id,
+        stripeProductId:
+          typeof item.price.product === 'string'
+            ? item.price.product
+            : item.price.product.id,
+        stripePriceId: item.price.id,
+        quantity: item.quantity ?? null,
+      })
+    }
+
+    return localSub
+  }
+}

package/src/subscription_item.ts

@@ -0,0 +1,172 @@
+import CashierManager from './cashier_manager.ts'
+import type { SubscriptionItemData, SubscriptionData } from './types.ts'
+
+/**
+ * Static helper for managing subscription item records (multi-plan subscriptions).
+ *
+ * @example
+ * const items = await SubscriptionItem.findBySubscription(sub.id)
+ * await SubscriptionItem.add(sub, sub.id, 'price_addon', 2)
+ */
+export default class SubscriptionItem {
+  private static get sql() {
+    return CashierManager.db.sql
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  /** Find all items belonging to a subscription. */
+  static async findBySubscription(subscriptionId: number): Promise<SubscriptionItemData[]> {
+    const rows = await SubscriptionItem.sql`
+      SELECT * FROM "subscription_item"
+      WHERE "subscription_id" = ${subscriptionId}
+      ORDER BY "created_at" ASC
+    `
+    return rows.map((r: any) => SubscriptionItem.hydrate(r))
+  }
+
+  /** Find by Stripe subscription item ID. */
+  static async findByStripeId(stripeId: string): Promise<SubscriptionItemData | null> {
+    const rows = await SubscriptionItem.sql`
+      SELECT * FROM "subscription_item" WHERE "stripe_id" = ${stripeId} LIMIT 1
+    `
+    return rows.length > 0 ? SubscriptionItem.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Create / Update
+  // ---------------------------------------------------------------------------
+
+  /** Create a local subscription item record. */
+  static async create(data: {
+    subscriptionId: number
+    stripeId: string
+    stripeProductId: string
+    stripePriceId: string
+    quantity?: number | null
+  }): Promise<SubscriptionItemData> {
+    const rows = await SubscriptionItem.sql`
+      INSERT INTO "subscription_item"
+        ("subscription_id", "stripe_id", "stripe_product_id", "stripe_price_id", "quantity")
+      VALUES (${data.subscriptionId}, ${data.stripeId}, ${data.stripeProductId},
+              ${data.stripePriceId}, ${data.quantity ?? null})
+      RETURNING *
+    `
+    return SubscriptionItem.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Add a new price/item to an existing Stripe subscription and record it locally. */
+  static async add(
+    sub: SubscriptionData,
+    localSubId: number,
+    priceId: string,
+    quantity?: number
+  ): Promise<SubscriptionItemData> {
+    const stripeItem = await CashierManager.stripe.subscriptionItems.create({
+      subscription: sub.stripeId,
+      price: priceId,
+      quantity: quantity ?? 1,
+    })
+
+    return SubscriptionItem.create({
+      subscriptionId: localSubId,
+      stripeId: stripeItem.id,
+      stripeProductId:
+        typeof stripeItem.price.product === 'string'
+          ? stripeItem.price.product
+          : stripeItem.price.product.id,
+      stripePriceId: stripeItem.price.id,
+      quantity: stripeItem.quantity ?? null,
+    })
+  }
+
+  /** Swap an existing item to a different price. */
+  static async swap(item: SubscriptionItemData, newPriceId: string): Promise<void> {
+    await CashierManager.stripe.subscriptionItems.update(item.stripeId, {
+      price: newPriceId,
+      proration_behavior: 'create_prorations',
+    })
+
+    await SubscriptionItem.sql`
+      UPDATE "subscription_item"
+      SET "stripe_price_id" = ${newPriceId}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${item.stripeId}
+    `
+  }
+
+  /** Update quantity for an item on Stripe and locally. */
+  static async updateQuantity(item: SubscriptionItemData, quantity: number): Promise<void> {
+    await CashierManager.stripe.subscriptionItems.update(item.stripeId, { quantity })
+
+    await SubscriptionItem.sql`
+      UPDATE "subscription_item"
+      SET "quantity" = ${quantity}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${item.stripeId}
+    `
+  }
+
+  /** Remove an item from the Stripe subscription and delete locally. */
+  static async remove(item: SubscriptionItemData): Promise<void> {
+    await CashierManager.stripe.subscriptionItems.del(item.stripeId)
+    await SubscriptionItem.sql`
+      DELETE FROM "subscription_item" WHERE "stripe_id" = ${item.stripeId}
+    `
+  }
+
+  /** Report metered usage for a subscription item. */
+  static async reportUsage(
+    item: SubscriptionItemData,
+    quantity: number,
+    options?: { timestamp?: number }
+  ): Promise<void> {
+    await CashierManager.stripe.subscriptionItems.createUsageRecord(item.stripeId, {
+      quantity,
+      ...(options?.timestamp ? { timestamp: options.timestamp } : {}),
+    })
+  }
+
+  /** Sync all items from Stripe into the local table for a subscription. */
+  static async syncFromStripe(sub: SubscriptionData, localSubId: number): Promise<void> {
+    const stripeSub = await CashierManager.stripe.subscriptions.retrieve(sub.stripeId, {
+      expand: ['items.data.price.product'],
+    })
+
+    // Delete existing local items
+    await SubscriptionItem.sql`
+      DELETE FROM "subscription_item" WHERE "subscription_id" = ${localSubId}
+    `
+
+    // Re-create from Stripe data
+    for (const item of stripeSub.items.data) {
+      await SubscriptionItem.create({
+        subscriptionId: localSubId,
+        stripeId: item.id,
+        stripeProductId:
+          typeof item.price.product === 'string'
+            ? item.price.product
+            : item.price.product.id,
+        stripePriceId: item.price.id,
+        quantity: item.quantity ?? null,
+      })
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): SubscriptionItemData {
+    return {
+      id: row.id as number,
+      subscriptionId: row.subscription_id as number,
+      stripeId: row.stripe_id as string,
+      stripeProductId: row.stripe_product_id as string,
+      stripePriceId: row.stripe_price_id as string,
+      quantity: (row.quantity as number) ?? null,
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,97 @@
+import type Stripe from 'stripe'
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface CashierConfig {
+  /** Stripe secret key. */
+  secret: string
+  /** Stripe publishable key (passed to frontend). */
+  key: string
+  /** Stripe webhook signing secret. */
+  webhookSecret: string
+  /** Default currency code (lowercase). */
+  currency: string
+  /** The user model's primary key property name (e.g. 'id', 'uid'). */
+  userKey: string
+  /** URL prefix for Checkout success/cancel. */
+  urls: {
+    success: string
+    cancel: string
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Data Records
+// ---------------------------------------------------------------------------
+
+export interface CustomerData {
+  id: number
+  userId: string | number
+  stripeId: string
+  pmType: string | null
+  pmLastFour: string | null
+  trialEndsAt: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface SubscriptionData {
+  id: number
+  userId: string | number
+  name: string
+  stripeId: string
+  stripeStatus: string
+  stripePriceId: string | null
+  quantity: number | null
+  trialEndsAt: Date | null
+  endsAt: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface SubscriptionItemData {
+  id: number
+  subscriptionId: number
+  stripeId: string
+  stripeProductId: string
+  stripePriceId: string
+  quantity: number | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface ReceiptData {
+  id: number
+  userId: string | number
+  stripeId: string
+  amount: number
+  currency: string
+  description: string | null
+  receiptUrl: string | null
+  createdAt: Date
+}
+
+// ---------------------------------------------------------------------------
+// Subscription Status
+// ---------------------------------------------------------------------------
+
+export const SubscriptionStatus = {
+  Active: 'active',
+  Canceled: 'canceled',
+  Incomplete: 'incomplete',
+  IncompleteExpired: 'incomplete_expired',
+  PastDue: 'past_due',
+  Paused: 'paused',
+  Trialing: 'trialing',
+  Unpaid: 'unpaid',
+} as const
+
+export type SubscriptionStatusValue = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus]
+
+// ---------------------------------------------------------------------------
+// Webhook
+// ---------------------------------------------------------------------------
+
+export type WebhookEventHandler = (event: Stripe.Event) => void | Promise<void>

package/src/webhook.ts

@@ -0,0 +1,168 @@
+import type Stripe from 'stripe'
+import type Context from '@stravigor/core/http/context'
+import type { Handler } from '@stravigor/core/http'
+import CashierManager from './cashier_manager.ts'
+import Customer from './customer.ts'
+import Subscription from './subscription.ts'
+import SubscriptionItem from './subscription_item.ts'
+import { WebhookSignatureError } from './errors.ts'
+import type { WebhookEventHandler } from './types.ts'
+
+/** Registry of custom webhook event handlers. */
+const customHandlers = new Map<string, WebhookEventHandler[]>()
+
+/**
+ * Register a custom handler for a Stripe webhook event type.
+ *
+ * @example
+ * import { onWebhookEvent } from '@stravigor/cashier/webhook'
+ *
+ * onWebhookEvent('invoice.payment_failed', async (event) => {
+ *   const invoice = event.data.object as Stripe.Invoice
+ *   // Send notification to user...
+ * })
+ */
+export function onWebhookEvent(eventType: string, handler: WebhookEventHandler): void {
+  const handlers = customHandlers.get(eventType) ?? []
+  handlers.push(handler)
+  customHandlers.set(eventType, handlers)
+}
+
+/**
+ * Create a route handler for Stripe webhooks.
+ *
+ * Verifies the Stripe signature, dispatches built-in handlers to keep
+ * local DB in sync, then calls any custom handlers registered via
+ * `onWebhookEvent()`.
+ *
+ * @example
+ * import { stripeWebhook } from '@stravigor/cashier/webhook'
+ * router.post('/stripe/webhook', stripeWebhook())
+ */
+export function stripeWebhook(): Handler {
+  return async (ctx: Context): Promise<Response> => {
+    const signature = ctx.header('stripe-signature')
+    if (!signature) {
+      return ctx.json({ error: 'Missing stripe-signature header' }, 400)
+    }
+
+    const rawBody = await ctx.request.text()
+    const webhookSecret = CashierManager.config.webhookSecret
+
+    let event: Stripe.Event
+    try {
+      event = CashierManager.stripe.webhooks.constructEvent(rawBody, signature, webhookSecret)
+    } catch {
+      throw new WebhookSignatureError()
+    }
+
+    // Dispatch built-in handlers
+    await handleBuiltinEvent(event)
+
+    // Dispatch custom handlers
+    const handlers = customHandlers.get(event.type) ?? []
+    for (const handler of handlers) {
+      await handler(event)
+    }
+
+    return ctx.json({ received: true }, 200)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Built-in event handling: keeps local DB in sync with Stripe
+// ---------------------------------------------------------------------------
+
+async function handleBuiltinEvent(event: Stripe.Event): Promise<void> {
+  switch (event.type) {
+    // ---- Customer Events ----
+
+    case 'customer.updated': {
+      const stripeCustomer = event.data.object as Stripe.Customer
+      const defaultPm = stripeCustomer.invoice_settings?.default_payment_method
+      if (defaultPm && typeof defaultPm !== 'string') {
+        await Customer.updateDefaultPaymentMethod(stripeCustomer.id, defaultPm)
+      }
+      break
+    }
+
+    case 'customer.deleted': {
+      const stripeCustomer = event.data.object as Stripe.Customer
+      const customer = await Customer.findByStripeId(stripeCustomer.id)
+      if (customer) {
+        // Clean up all local subscription records
+        const subs = await Subscription.findByUser(customer.userId)
+        for (const sub of subs) {
+          await Subscription.delete(sub.id)
+        }
+        await Customer.deleteByStripeId(stripeCustomer.id)
+      }
+      break
+    }
+
+    // ---- Subscription Events ----
+
+    case 'customer.subscription.created': {
+      const stripeSub = event.data.object as Stripe.Subscription
+      const customerId =
+        typeof stripeSub.customer === 'string' ? stripeSub.customer : stripeSub.customer.id
+      const customer = await Customer.findByStripeId(customerId)
+
+      if (customer) {
+        const existing = await Subscription.findByStripeId(stripeSub.id)
+        if (!existing) {
+          const name = stripeSub.metadata?.strav_name ?? 'default'
+          const localSub = await Subscription.create({
+            user: customer.userId,
+            name,
+            stripeId: stripeSub.id,
+            stripeStatus: stripeSub.status,
+            stripePriceId: stripeSub.items.data[0]?.price.id ?? null,
+            quantity: stripeSub.items.data[0]?.quantity ?? null,
+            trialEndsAt: stripeSub.trial_end ? new Date(stripeSub.trial_end * 1000) : null,
+          })
+          await SubscriptionItem.syncFromStripe(localSub, localSub.id)
+        }
+      }
+      break
+    }
+
+    case 'customer.subscription.updated': {
+      const stripeSub = event.data.object as Stripe.Subscription
+
+      const endsAt = stripeSub.cancel_at
+        ? new Date(stripeSub.cancel_at * 1000)
+        : stripeSub.canceled_at
+          ? new Date(stripeSub.current_period_end * 1000)
+          : null
+
+      await Subscription.syncStripeStatus(stripeSub.id, stripeSub.status, endsAt)
+
+      // Sync items and metadata
+      const localSub = await Subscription.findByStripeId(stripeSub.id)
+      if (localSub) {
+        await SubscriptionItem.syncFromStripe(localSub, localSub.id)
+
+        // Update price_id, quantity, and trial from first item
+        const firstItem = stripeSub.items.data[0]
+        if (firstItem) {
+          await CashierManager.db.sql`
+            UPDATE "subscription"
+            SET "stripe_price_id" = ${firstItem.price.id},
+                "quantity" = ${firstItem.quantity ?? null},
+                "trial_ends_at" = ${stripeSub.trial_end ? new Date(stripeSub.trial_end * 1000) : null},
+                "updated_at" = NOW()
+            WHERE "stripe_id" = ${stripeSub.id}
+          `
+        }
+      }
+      break
+    }
+
+    case 'customer.subscription.deleted': {
+      const stripeSub = event.data.object as Stripe.Subscription
+      await Subscription.syncStripeStatus(stripeSub.id, 'canceled', new Date())
+      break
+    }
+  }
+}

package/stubs/config/cashier.ts

@@ -0,0 +1,27 @@
+import { env } from '@stravigor/core/helpers'
+
+export default {
+  /** Stripe secret key. */
+  secret: env('STRIPE_SECRET', ''),
+
+  /** Stripe publishable key. */
+  key: env('STRIPE_KEY', ''),
+
+  /** Stripe webhook signing secret. */
+  webhookSecret: env('STRIPE_WEBHOOK_SECRET', ''),
+
+  /** Default currency for charges. */
+  currency: 'usd',
+
+  /**
+   * The user model's primary key property (determines FK column name).
+   * 'id' → user_id, 'uid' → user_uid, etc.
+   */
+  userKey: 'id',
+
+  /** URLs for Stripe Checkout success/cancel redirects. */
+  urls: {
+    success: env('APP_URL', 'http://localhost:3000') + '/billing/success',
+    cancel: env('APP_URL', 'http://localhost:3000') + '/billing/cancel',
+  },
+}

package/stubs/schemas/customer.ts

@@ -0,0 +1,12 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('customer', {
+  archetype: Archetype.Component,
+  parent: 'user',
+  fields: {
+    stripeId: t.varchar(255).required().unique().index(),
+    pmType: t.varchar(50).nullable(),
+    pmLastFour: t.varchar(4).nullable(),
+    trialEndsAt: t.timestamptz().nullable(),
+  },
+})

package/stubs/schemas/receipt.ts

@@ -0,0 +1,13 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('receipt', {
+  archetype: Archetype.Event,
+  parent: 'user',
+  fields: {
+    stripeId: t.varchar(255).required().unique().index(),
+    amount: t.integer().required(),
+    currency: t.varchar(3).required(),
+    description: t.text().nullable(),
+    receiptUrl: t.text().nullable(),
+  },
+})

package/stubs/schemas/subscription.ts

@@ -0,0 +1,15 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('subscription', {
+  archetype: Archetype.Component,
+  parent: 'user',
+  fields: {
+    name: t.varchar(255).required().index(),
+    stripeId: t.varchar(255).required().unique().index(),
+    stripeStatus: t.varchar(50).required(),
+    stripePriceId: t.varchar(255).nullable(),
+    quantity: t.integer().nullable(),
+    trialEndsAt: t.timestamptz().nullable(),
+    endsAt: t.timestamptz().nullable(),
+  },
+})

package/stubs/schemas/subscription_item.ts

@@ -0,0 +1,12 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('subscription_item', {
+  archetype: Archetype.Component,
+  parent: 'subscription',
+  fields: {
+    stripeId: t.varchar(255).required().unique().index(),
+    stripeProductId: t.varchar(255).required().index(),
+    stripePriceId: t.varchar(255).required().index(),
+    quantity: t.integer().nullable(),
+  },
+})