@stravigor/cashier 0.1.0

package/src/helpers.ts

@@ -0,0 +1,110 @@
+import type Stripe from 'stripe'
+import CashierManager from './cashier_manager.ts'
+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 Receipt from './receipt.ts'
+import type { CustomerData, SubscriptionData, ReceiptData } from './types.ts'
+
+/**
+ * Cashier helper object — the primary convenience API.
+ *
+ * @example
+ * import { cashier } from '@stravigor/cashier'
+ *
+ * // Direct Stripe instance access
+ * cashier.stripe.customers.list()
+ *
+ * // Subscription builder
+ * await cashier.newSubscription('pro', 'price_xxx').trialDays(14).create(user)
+ *
+ * // Checkout builder
+ * const session = await cashier.newCheckout().item('price_xxx').mode('payment').create(user)
+ */
+export const cashier = {
+  /** Direct access to the configured Stripe SDK instance. */
+  get stripe(): Stripe {
+    return CashierManager.stripe
+  },
+
+  /** The Stripe publishable key (for frontend use). */
+  get key(): string {
+    return CashierManager.config.key
+  },
+
+  /** The configured default currency. */
+  get currency(): string {
+    return CashierManager.config.currency
+  },
+
+  // ----- Customer -----
+
+  /** Get or create a Stripe customer for a user. */
+  createOrGetCustomer(user: unknown, params?: Stripe.CustomerCreateParams): Promise<CustomerData> {
+    return Customer.createOrGet(user, params)
+  },
+
+  /** Find the local customer record for a user. */
+  findCustomer(user: unknown): Promise<CustomerData | null> {
+    return Customer.findByUser(user)
+  },
+
+  // ----- Subscriptions -----
+
+  /** Start building a new subscription. */
+  newSubscription(name: string, ...prices: string[]): SubscriptionBuilder {
+    return new SubscriptionBuilder(name, ...prices)
+  },
+
+  /** Find a user's subscription by name. */
+  subscription(user: unknown, name: string = 'default'): Promise<SubscriptionData | null> {
+    return Subscription.findByName(user, name)
+  },
+
+  /** Check if a user has a valid subscription. */
+  async subscribed(user: unknown, name: string = 'default'): Promise<boolean> {
+    const sub = await Subscription.findByName(user, name)
+    return sub !== null && Subscription.valid(sub)
+  },
+
+  // ----- Checkout -----
+
+  /** Start building a Stripe Checkout session. */
+  newCheckout(): CheckoutBuilder {
+    return new CheckoutBuilder()
+  },
+
+  // ----- Invoices -----
+
+  /** List invoices for a user. */
+  invoices(user: unknown, params?: Stripe.InvoiceListParams): Promise<Stripe.Invoice[]> {
+    return Invoice.list(user, params)
+  },
+
+  /** Preview the upcoming invoice. */
+  upcomingInvoice(user: unknown): Promise<Stripe.UpcomingInvoice | null> {
+    return Invoice.upcoming(user)
+  },
+
+  // ----- Payment Methods -----
+
+  /** List payment methods for a user. */
+  paymentMethods(user: unknown): Promise<Stripe.PaymentMethod[]> {
+    return PaymentMethod.list(user)
+  },
+
+  /** Set a payment method as default. */
+  setDefaultPaymentMethod(user: unknown, paymentMethodId: string): Promise<void> {
+    return PaymentMethod.setDefault(user, paymentMethodId)
+  },
+
+  // ----- Receipts -----
+
+  /** List receipts for a user. */
+  receipts(user: unknown): Promise<ReceiptData[]> {
+    return Receipt.findByUser(user)
+  },
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+// Manager
+export { default, default as CashierManager } from './cashier_manager.ts'
+
+// Static helpers
+export { default as Customer } from './customer.ts'
+export { default as Subscription } from './subscription.ts'
+export { default as SubscriptionItem } from './subscription_item.ts'
+export { default as Invoice } from './invoice.ts'
+export { default as PaymentMethod } from './payment_method.ts'
+export { default as Receipt } from './receipt.ts'
+
+// Builders
+export { default as SubscriptionBuilder } from './subscription_builder.ts'
+export { default as CheckoutBuilder } from './checkout_builder.ts'
+
+// Mixin
+export { billable } from './billable.ts'
+export type { BillableInstance } from './billable.ts'
+
+// Helper
+export { cashier } from './helpers.ts'
+
+// Webhook
+export { stripeWebhook, onWebhookEvent } from './webhook.ts'
+
+// Errors
+export {
+  CashierError,
+  WebhookSignatureError,
+  CustomerNotFoundError,
+  SubscriptionNotFoundError,
+} from './errors.ts'
+
+// Types
+export type {
+  CashierConfig,
+  CustomerData,
+  SubscriptionData,
+  SubscriptionItemData,
+  ReceiptData,
+  SubscriptionStatusValue,
+  WebhookEventHandler,
+} from './types.ts'
+export { SubscriptionStatus } from './types.ts'

package/src/invoice.ts

@@ -0,0 +1,69 @@
+import type Stripe from 'stripe'
+import CashierManager from './cashier_manager.ts'
+import Customer from './customer.ts'
+
+/**
+ * Static helper for Stripe invoice operations.
+ *
+ * @example
+ * const invoices = await Invoice.list(user)
+ * const upcoming = await Invoice.upcoming(user)
+ * const pdf = await Invoice.pdfUrl('in_xxx')
+ */
+export default class Invoice {
+  /** List invoices for a user. */
+  static async list(
+    user: unknown,
+    params?: Stripe.InvoiceListParams
+  ): Promise<Stripe.Invoice[]> {
+    const customer = await Customer.findByUser(user)
+    if (!customer) return []
+
+    const result = await CashierManager.stripe.invoices.list({
+      customer: customer.stripeId,
+      limit: 24,
+      ...params,
+    })
+    return result.data
+  }
+
+  /** Get the upcoming invoice preview (prorations, next charge). */
+  static async upcoming(
+    user: unknown,
+    params?: Stripe.InvoiceRetrieveUpcomingParams
+  ): Promise<Stripe.UpcomingInvoice | null> {
+    const customer = await Customer.findByUser(user)
+    if (!customer) return null
+
+    try {
+      return await CashierManager.stripe.invoices.retrieveUpcoming({
+        customer: customer.stripeId,
+        ...params,
+      })
+    } catch {
+      return null
+    }
+  }
+
+  /** Retrieve a specific invoice by Stripe ID. */
+  static async find(invoiceId: string): Promise<Stripe.Invoice> {
+    return CashierManager.stripe.invoices.retrieve(invoiceId)
+  }
+
+  /** Get the hosted invoice URL for payment. */
+  static async hostedUrl(invoiceId: string): Promise<string | null> {
+    const invoice = await CashierManager.stripe.invoices.retrieve(invoiceId)
+    return invoice.hosted_invoice_url ?? null
+  }
+
+  /** Get the invoice PDF download URL. */
+  static async pdfUrl(invoiceId: string): Promise<string | null> {
+    const invoice = await CashierManager.stripe.invoices.retrieve(invoiceId)
+    return invoice.invoice_pdf ?? null
+  }
+
+  /** Void an invoice. */
+  static async void_(invoiceId: string): Promise<Stripe.Invoice> {
+    return CashierManager.stripe.invoices.voidInvoice(invoiceId)
+  }
+}

package/src/payment_method.ts

@@ -0,0 +1,53 @@
+import type Stripe from 'stripe'
+import CashierManager from './cashier_manager.ts'
+import Customer from './customer.ts'
+
+/**
+ * Static helper for managing Stripe payment methods.
+ *
+ * @example
+ * const methods = await PaymentMethod.list(user)
+ * await PaymentMethod.setDefault(user, 'pm_xxx')
+ */
+export default class PaymentMethod {
+  /** List all payment methods for a user. */
+  static async list(
+    user: unknown,
+    type: Stripe.PaymentMethodListParams.Type = 'card'
+  ): Promise<Stripe.PaymentMethod[]> {
+    return Customer.paymentMethods(user, type)
+  }
+
+  /** Retrieve a single payment method from Stripe. */
+  static async find(paymentMethodId: string): Promise<Stripe.PaymentMethod> {
+    return CashierManager.stripe.paymentMethods.retrieve(paymentMethodId)
+  }
+
+  /** Set a payment method as the customer's default. */
+  static async setDefault(user: unknown, paymentMethodId: string): Promise<void> {
+    const customer = await Customer.createOrGet(user)
+
+    // Attach if not already attached
+    try {
+      await CashierManager.stripe.paymentMethods.attach(paymentMethodId, {
+        customer: customer.stripeId,
+      })
+    } catch {
+      // Already attached — ignore
+    }
+
+    // Set as default on Stripe
+    await CashierManager.stripe.customers.update(customer.stripeId, {
+      invoice_settings: { default_payment_method: paymentMethodId },
+    })
+
+    // Update local record
+    const pm = await CashierManager.stripe.paymentMethods.retrieve(paymentMethodId)
+    await Customer.updateDefaultPaymentMethod(customer.stripeId, pm)
+  }
+
+  /** Detach a payment method from the customer. */
+  static async delete(paymentMethodId: string): Promise<void> {
+    return Customer.deletePaymentMethod(paymentMethodId)
+  }
+}

package/src/receipt.ts

@@ -0,0 +1,84 @@
+import { extractUserId } from '@stravigor/core/helpers'
+import CashierManager from './cashier_manager.ts'
+import type { ReceiptData } from './types.ts'
+
+/**
+ * Static helper for managing one-time payment receipts.
+ *
+ * @example
+ * const receipt = await Receipt.create({ user, stripeId: pi.id, amount: 2500, currency: 'usd' })
+ * const receipts = await Receipt.findByUser(user)
+ */
+export default class Receipt {
+  private static get sql() {
+    return CashierManager.db.sql
+  }
+
+  private static get fk() {
+    return CashierManager.userFkColumn
+  }
+
+  /** Record a one-time payment receipt. */
+  static async create(data: {
+    user: unknown
+    stripeId: string
+    amount: number
+    currency: string
+    description?: string | null
+    receiptUrl?: string | null
+  }): Promise<ReceiptData> {
+    const userId = extractUserId(data.user)
+    const fk = Receipt.fk
+    const rows = await Receipt.sql.unsafe(
+      `INSERT INTO "receipt" ("${fk}", "stripe_id", "amount", "currency", "description", "receipt_url")
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING *`,
+      [
+        userId,
+        data.stripeId,
+        data.amount,
+        data.currency,
+        data.description ?? null,
+        data.receiptUrl ?? null,
+      ]
+    )
+    return Receipt.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Find all receipts for a user, newest first. */
+  static async findByUser(user: unknown): Promise<ReceiptData[]> {
+    const userId = extractUserId(user)
+    const fk = Receipt.fk
+    const rows = await Receipt.sql.unsafe(
+      `SELECT * FROM "receipt" WHERE "${fk}" = $1 ORDER BY "created_at" DESC`,
+      [userId]
+    )
+    return rows.map((r: any) => Receipt.hydrate(r))
+  }
+
+  /** Find a receipt by Stripe payment intent ID. */
+  static async findByStripeId(stripeId: string): Promise<ReceiptData | null> {
+    const rows = await Receipt.sql`
+      SELECT * FROM "receipt" WHERE "stripe_id" = ${stripeId} LIMIT 1
+    `
+    return rows.length > 0 ? Receipt.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): ReceiptData {
+    const fk = Receipt.fk
+    return {
+      id: row.id as number,
+      userId: row[fk] as string | number,
+      stripeId: row.stripe_id as string,
+      amount: row.amount as number,
+      currency: row.currency as string,
+      description: (row.description as string) ?? null,
+      receiptUrl: (row.receipt_url as string) ?? null,
+      createdAt: row.created_at as Date,
+    }
+  }
+}

package/src/subscription.ts

@@ -0,0 +1,276 @@
+import { extractUserId } from '@stravigor/core/helpers'
+import CashierManager from './cashier_manager.ts'
+import type { SubscriptionData } from './types.ts'
+import { SubscriptionStatus } from './types.ts'
+
+/**
+ * Static helper for managing subscription records.
+ *
+ * @example
+ * const sub = await Subscription.findByName(user, 'pro')
+ * if (sub && Subscription.active(sub)) { ... }
+ */
+export default class Subscription {
+  private static get sql() {
+    return CashierManager.db.sql
+  }
+
+  private static get fk() {
+    return CashierManager.userFkColumn
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  /** Find a subscription by user + name (e.g. 'default', 'pro'). */
+  static async findByName(user: unknown, name: string): Promise<SubscriptionData | null> {
+    const userId = extractUserId(user)
+    const fk = Subscription.fk
+    const rows = await Subscription.sql.unsafe(
+      `SELECT * FROM "subscription" WHERE "${fk}" = $1 AND "name" = $2 LIMIT 1`,
+      [userId, name]
+    )
+    return rows.length > 0 ? Subscription.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  /** Find all subscriptions for a user. */
+  static async findByUser(user: unknown): Promise<SubscriptionData[]> {
+    const userId = extractUserId(user)
+    const fk = Subscription.fk
+    const rows = await Subscription.sql.unsafe(
+      `SELECT * FROM "subscription" WHERE "${fk}" = $1 ORDER BY "created_at" DESC`,
+      [userId]
+    )
+    return rows.map((r: any) => Subscription.hydrate(r))
+  }
+
+  /** Find by Stripe subscription ID. */
+  static async findByStripeId(stripeId: string): Promise<SubscriptionData | null> {
+    const rows = await Subscription.sql`
+      SELECT * FROM "subscription" WHERE "stripe_id" = ${stripeId} LIMIT 1
+    `
+    return rows.length > 0 ? Subscription.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Create / Update
+  // ---------------------------------------------------------------------------
+
+  /** Create a local subscription record. */
+  static async create(data: {
+    user: unknown
+    name: string
+    stripeId: string
+    stripeStatus: string
+    stripePriceId?: string | null
+    quantity?: number | null
+    trialEndsAt?: Date | null
+    endsAt?: Date | null
+  }): Promise<SubscriptionData> {
+    const userId = extractUserId(data.user)
+    const fk = Subscription.fk
+    const rows = await Subscription.sql.unsafe(
+      `INSERT INTO "subscription"
+         ("${fk}", "name", "stripe_id", "stripe_status", "stripe_price_id", "quantity", "trial_ends_at", "ends_at")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       RETURNING *`,
+      [
+        userId,
+        data.name,
+        data.stripeId,
+        data.stripeStatus,
+        data.stripePriceId ?? null,
+        data.quantity ?? null,
+        data.trialEndsAt ?? null,
+        data.endsAt ?? null,
+      ]
+    )
+    return Subscription.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Update subscription status from a Stripe webhook event. */
+  static async syncStripeStatus(
+    stripeId: string,
+    status: string,
+    endsAt?: Date | null
+  ): Promise<void> {
+    if (endsAt !== undefined) {
+      await Subscription.sql`
+        UPDATE "subscription"
+        SET "stripe_status" = ${status}, "ends_at" = ${endsAt}, "updated_at" = NOW()
+        WHERE "stripe_id" = ${stripeId}
+      `
+    } else {
+      await Subscription.sql`
+        UPDATE "subscription"
+        SET "stripe_status" = ${status}, "updated_at" = NOW()
+        WHERE "stripe_id" = ${stripeId}
+      `
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Status Checks (pure functions on SubscriptionData)
+  // ---------------------------------------------------------------------------
+
+  /** Whether the subscription is valid (active, trialing, or on grace period). */
+  static valid(sub: SubscriptionData): boolean {
+    return Subscription.active(sub) || Subscription.onTrial(sub) || Subscription.onGracePeriod(sub)
+  }
+
+  /** Whether the Stripe status is active, trialing, or past_due. */
+  static active(sub: SubscriptionData): boolean {
+    return (
+      sub.stripeStatus === SubscriptionStatus.Active ||
+      sub.stripeStatus === SubscriptionStatus.Trialing ||
+      sub.stripeStatus === SubscriptionStatus.PastDue
+    )
+  }
+
+  /** Whether the subscription is currently in a trial period. */
+  static onTrial(sub: SubscriptionData): boolean {
+    return sub.trialEndsAt !== null && sub.trialEndsAt.getTime() > Date.now()
+  }
+
+  /** Whether the subscription is canceled but still within its grace period. */
+  static onGracePeriod(sub: SubscriptionData): boolean {
+    return sub.endsAt !== null && sub.endsAt.getTime() > Date.now()
+  }
+
+  /** Whether the subscription has been canceled (ends_at is set). */
+  static canceled(sub: SubscriptionData): boolean {
+    return sub.endsAt !== null
+  }
+
+  /** Whether the subscription has ended (canceled and past grace period). */
+  static ended(sub: SubscriptionData): boolean {
+    return Subscription.canceled(sub) && !Subscription.onGracePeriod(sub)
+  }
+
+  /** Whether the subscription is past due. */
+  static pastDue(sub: SubscriptionData): boolean {
+    return sub.stripeStatus === SubscriptionStatus.PastDue
+  }
+
+  /** Whether the subscription is recurring (not trial, not canceled). */
+  static recurring(sub: SubscriptionData): boolean {
+    return !Subscription.onTrial(sub) && !Subscription.canceled(sub)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mutations (Stripe API + local DB)
+  // ---------------------------------------------------------------------------
+
+  /** Cancel the subscription at period end (grace period). */
+  static async cancel(sub: SubscriptionData): Promise<SubscriptionData> {
+    const stripeSub = await CashierManager.stripe.subscriptions.update(sub.stripeId, {
+      cancel_at_period_end: true,
+    })
+
+    const endsAt = new Date(stripeSub.current_period_end * 1000)
+    await Subscription.sql`
+      UPDATE "subscription"
+      SET "stripe_status" = ${stripeSub.status}, "ends_at" = ${endsAt}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${sub.stripeId}
+    `
+    return { ...sub, stripeStatus: stripeSub.status, endsAt }
+  }
+
+  /** Cancel immediately (no grace period). */
+  static async cancelNow(sub: SubscriptionData): Promise<SubscriptionData> {
+    await CashierManager.stripe.subscriptions.cancel(sub.stripeId)
+    const now = new Date()
+    await Subscription.sql`
+      UPDATE "subscription"
+      SET "stripe_status" = 'canceled', "ends_at" = ${now}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${sub.stripeId}
+    `
+    return { ...sub, stripeStatus: 'canceled', endsAt: now }
+  }
+
+  /** Resume a canceled-but-on-grace-period subscription. */
+  static async resume(sub: SubscriptionData): Promise<SubscriptionData> {
+    if (!Subscription.onGracePeriod(sub)) {
+      throw new Error('Cannot resume a subscription that is not within its grace period.')
+    }
+
+    const stripeSub = await CashierManager.stripe.subscriptions.update(sub.stripeId, {
+      cancel_at_period_end: false,
+    })
+
+    await Subscription.sql`
+      UPDATE "subscription"
+      SET "stripe_status" = ${stripeSub.status}, "ends_at" = ${null}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${sub.stripeId}
+    `
+    return { ...sub, stripeStatus: stripeSub.status, endsAt: null }
+  }
+
+  /** Swap the subscription to a different price (prorates by default). */
+  static async swap(sub: SubscriptionData, newPriceId: string): Promise<SubscriptionData> {
+    const stripeSub = await CashierManager.stripe.subscriptions.retrieve(sub.stripeId)
+    const itemId = stripeSub.items.data[0]?.id
+    if (!itemId) throw new Error('Subscription has no items to swap.')
+
+    const updated = await CashierManager.stripe.subscriptions.update(sub.stripeId, {
+      items: [{ id: itemId, price: newPriceId }],
+      proration_behavior: 'create_prorations',
+      cancel_at_period_end: false,
+    })
+
+    await Subscription.sql`
+      UPDATE "subscription"
+      SET "stripe_price_id" = ${newPriceId},
+          "stripe_status" = ${updated.status},
+          "ends_at" = ${null},
+          "updated_at" = NOW()
+      WHERE "stripe_id" = ${sub.stripeId}
+    `
+    return { ...sub, stripePriceId: newPriceId, stripeStatus: updated.status, endsAt: null }
+  }
+
+  /** Update the subscription quantity on Stripe and locally. */
+  static async updateQuantity(sub: SubscriptionData, quantity: number): Promise<SubscriptionData> {
+    const stripeSub = await CashierManager.stripe.subscriptions.retrieve(sub.stripeId)
+    const itemId = stripeSub.items.data[0]?.id
+    if (!itemId) throw new Error('Subscription has no items to update quantity for.')
+
+    await CashierManager.stripe.subscriptions.update(sub.stripeId, {
+      items: [{ id: itemId, quantity }],
+    })
+
+    await Subscription.sql`
+      UPDATE "subscription"
+      SET "quantity" = ${quantity}, "updated_at" = NOW()
+      WHERE "stripe_id" = ${sub.stripeId}
+    `
+    return { ...sub, quantity }
+  }
+
+  /** Delete the local subscription record. */
+  static async delete(id: number): Promise<void> {
+    await Subscription.sql`DELETE FROM "subscription" WHERE "id" = ${id}`
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): SubscriptionData {
+    const fk = Subscription.fk
+    return {
+      id: row.id as number,
+      userId: row[fk] as string | number,
+      name: row.name as string,
+      stripeId: row.stripe_id as string,
+      stripeStatus: row.stripe_status as string,
+      stripePriceId: (row.stripe_price_id as string) ?? null,
+      quantity: (row.quantity as number) ?? null,
+      trialEndsAt: (row.trial_ends_at as Date) ?? null,
+      endsAt: (row.ends_at as Date) ?? null,
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }
+  }
+}