Stripe

Stripe-only. Uses the official Stripe SDK under the hood.

Installation

bun add @strav/stripe
bun strav install stripe

• config/stripe.ts — Stripe keys, currency, webhook secret, checkout URLs.
• database/schemas/customer.ts — the customer table schema.
• database/schemas/subscription.ts — the subscription table schema.
• database/schemas/subscription_item.ts — the subscription_item table schema.
• database/schemas/receipt.ts — the receipt table schema.

Setup

1. Register StripeManager

Using a service provider (recommended)

import { StripeProvider } from '@strav/stripe'

app.use(new StripeProvider())

Manual setup

import StripeManager from '@strav/stripe'

app.singleton(StripeManager)
app.resolve(StripeManager)

2. Configure Stripe credentials

import { env } from '@strav/kernel'

export default {
  secret: env('STRIPE_SECRET', ''),
  key: env('STRIPE_KEY', ''),
  webhookSecret: env('STRIPE_WEBHOOK_SECRET', ''),
  currency: 'usd',
  userKey: 'id',
  urls: {
    success: env('APP_URL', 'http://localhost:3000') + '/billing/success',
    cancel: env('APP_URL', 'http://localhost:3000') + '/billing/cancel',
  },
}

3. Run the migration

bun strav generate:migration -m "add billing tables"
bun strav migrate

4. Add environment variables

STRIPE_SECRET=sk_test_...
STRIPE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Billable mixin

import { BaseModel } from '@strav/database'
import { billable } from '@strav/stripe'

class User extends billable(BaseModel) {
  declare id: number
  declare email: string
}

import { compose } from '@strav/kernel'
import { billable } from '@strav/stripe'

class User extends compose(BaseModel, softDeletes, billable) {
  declare id: number
  declare email: string
}

Once applied, the user instance gains all the methods documented below.

Customers

// Get or create the Stripe customer
const customer = await user.createOrGetStripeCustomer()

// Check if the user has a Stripe customer record
await user.hasStripeId()  // true

// Get the Stripe customer ID
await user.stripeId()  // 'cus_xxx'

// Get the local customer record
const customer = await user.customer()
// customer.stripeId, customer.pmType, customer.pmLastFour, customer.trialEndsAt

Subscriptions

Creating subscriptions

// Simple subscription
await user.subscribe('default', 'price_xxx')

// With a trial period
await user.newSubscription('pro', 'price_xxx')
  .trialDays(14)
  .create()

// With a coupon
await user.newSubscription('pro', 'price_xxx')
  .coupon('LAUNCH20')
  .create()

// Multi-plan subscription
await user.newSubscription('enterprise', 'price_base')
  .plan('price_addon', 3)
  .create()

// Full builder API
await user.newSubscription('pro', 'price_xxx')
  .quantity(5)
  .trialDays(14)
  .coupon('LAUNCH20')
  .promotionCode('promo_abc')
  .metadata({ team: 'alpha' })
  .paymentBehavior('allow_incomplete')
  .anchorBillingCycleOn(timestamp)
  .create()

Checking subscription status

// Is the user subscribed? (active, trialing, or on grace period)
await user.subscribed('pro')        // true
await user.subscribed()             // checks 'default'

// Is the user on a trial?
await user.onTrial('pro')           // true if trial_ends_at is in the future

// Is the subscription on a grace period? (canceled but not yet expired)
await user.onGracePeriod('pro')     // true

// Is the user subscribed to a specific price?
await user.subscribedToPrice('price_xxx')  // true

// Get subscription details
const sub = await user.subscription('pro')
sub.name            // 'pro'
sub.stripeId        // 'sub_xxx'
sub.stripeStatus    // 'active'
sub.stripePriceId   // 'price_xxx'
sub.quantity        // 1
sub.trialEndsAt     // Date | null
sub.endsAt          // Date | null

// Get all subscriptions
const subs = await user.subscriptions()

Status checks on SubscriptionData

import Subscription from '@strav/stripe/subscription'

const sub = await user.subscription('pro')
Subscription.active(sub)        // active, trialing, or past_due
Subscription.onTrial(sub)       // trial_ends_at in the future
Subscription.onGracePeriod(sub) // ends_at in the future
Subscription.canceled(sub)      // ends_at is set
Subscription.ended(sub)         // canceled and past grace period
Subscription.pastDue(sub)       // stripe_status === 'past_due'
Subscription.recurring(sub)     // not on trial, not canceled
Subscription.valid(sub)         // active OR onTrial OR onGracePeriod

Canceling subscriptions

import Subscription from '@strav/stripe/subscription'

const sub = await user.subscription('pro')

// Cancel at period end (grace period)
await Subscription.cancel(sub)

// Cancel immediately (no grace period)
await Subscription.cancelNow(sub)

Resuming subscriptions

Resume a subscription that was canceled but is still within its grace period:

await Subscription.resume(sub)

Throws if the subscription is not on a grace period.

Swapping plans

Switch a subscription to a different price (prorates by default):

await Subscription.swap(sub, 'price_new')

Updating quantity

await Subscription.updateQuantity(sub, 10)

One-time charges

// Charge a payment method
const paymentIntent = await user.charge(2500, 'pm_xxx')
// amount is in the smallest currency unit (e.g. cents)

// With options
const paymentIntent = await user.charge(2500, 'pm_xxx', {
  currency: 'eur',
  description: 'Add-on purchase',
  metadata: { product: 'widget' },
})

// Refund a charge (full)
const refund = await user.refund('pi_xxx')

// Partial refund
const refund = await user.refund('pi_xxx', 1000)

Payment methods

// List all payment methods
const methods = await user.paymentMethods()

// Set a payment method as default
await user.setDefaultPaymentMethod('pm_xxx')

// Create a SetupIntent (for collecting card details without charging)
const intent = await user.createSetupIntent()
// Pass intent.client_secret to Stripe.js on the frontend

Checkout sessions

Create Stripe Checkout sessions for one-time payments or subscriptions.

Quick checkout

// One-time payment
const session = await user.checkout([
  { price: 'price_xxx', quantity: 1 },
  { price: 'price_yyy', quantity: 2 },
])
// Redirect to session.url

Checkout builder

const session = await user.newCheckout()
  .item('price_xxx', 2)
  .item('price_yyy')
  .mode('subscription')
  .subscriptionName('pro')
  .trialDays(14)
  .successUrl('/billing/success')
  .cancelUrl('/billing/cancel')
  .allowPromotionCodes()
  .metadata({ campaign: 'launch' })
  .create()

Guest checkout

For users without a Stripe customer (not logged in):

const session = await new CheckoutBuilder()
  .item('price_xxx')
  .email('guest@example.com')
  .create()

Invoices

// List recent invoices
const invoices = await user.invoices()

// Preview the next invoice (prorations, upcoming charges)
const upcoming = await user.upcomingInvoice()

For direct access to invoice operations:

import Invoice from '@strav/stripe/invoice'

const invoice = await Invoice.find('in_xxx')
const pdfUrl = await Invoice.pdfUrl('in_xxx')
const hostedUrl = await Invoice.hostedUrl('in_xxx')
await Invoice.void_('in_xxx')

Billing portal

Create a Stripe Customer Portal session URL so users can manage their subscriptions, payment methods, and invoices:

const url = await user.billingPortalUrl()
// Redirect to url

// With a custom return URL
const url = await user.billingPortalUrl('/account')

Webhooks

Register a route handler to receive Stripe webhook events. The handler verifies signatures, keeps local database records in sync, and dispatches custom event handlers.

Route setup

import { router } from '@strav/http'
import { stripeWebhook } from '@strav/stripe/webhook'

router.post('/stripe/webhook', stripeWebhook())

Built-in event handling

The webhook handler automatically processes these events to keep local records in sync:

Custom event handlers

Register handlers for any Stripe event type:

import { onWebhookEvent } from '@strav/stripe/webhook'

onWebhookEvent('invoice.payment_failed', async (event) => {
  const invoice = event.data.object as Stripe.Invoice
  // Send a notification to the user...
})

onWebhookEvent('checkout.session.completed', async (event) => {
  const session = event.data.object as Stripe.Checkout.Session
  // Fulfill the order...
})

Custom handlers run after the built-in handlers.

Stripe CLI for local testing

Forward webhook events to your local server during development:

stripe listen --forward-to localhost:3000/stripe/webhook

STRIPE_WEBHOOK_SECRET=whsec_...

stripe helper

import { stripe } from '@strav/stripe'

// Customer
const customer = await stripe.createOrGetCustomer(user)
const customer = await stripe.findCustomer(user)

// Subscriptions
const sub = await stripe.newSubscription('pro', 'price_xxx')
  .trialDays(14)
  .create(user)

const sub = await stripe.subscription(user, 'pro')
const isSubscribed = await stripe.subscribed(user, 'pro')

// Checkout
const session = await stripe.newCheckout()
  .item('price_xxx')
  .mode('subscription')
  .subscriptionName('pro')
  .create(user)

// Invoices & payment methods
const invoices = await stripe.invoices(user)
const upcoming = await stripe.upcomingInvoice(user)
const methods = await stripe.paymentMethods(user)
await stripe.setDefaultPaymentMethod(user, 'pm_xxx')

// Receipts
const receipts = await stripe.receipts(user)

// Direct Stripe SDK access
stripe.stripe.customers.list({ limit: 10 })
stripe.key       // publishable key for frontend
stripe.currency  // configured default currency

Error handling

The module throws these error types:

• StripeError — general billing errors (extends StravError)
• CustomerNotFoundError — no local customer record found for a user
• SubscriptionNotFoundError — no subscription found with the given name
• PaymentMethodError — a payment method operation failed on Stripe (attach, detach, etc.)
• SubscriptionCreationError — subscription creation failed on Stripe
• WebhookSignatureError — Stripe webhook signature verification failed

import { StripeError, PaymentMethodError, SubscriptionCreationError } from '@strav/stripe'

try {
  await user.subscribe('pro', 'price_xxx')
} catch (error) {
  if (error instanceof SubscriptionCreationError) {
    // Stripe rejected the subscription creation
  } else if (error instanceof StripeError) {
    // Other billing error
  }
}

Database tables

The module uses four tables, defined by the schema stubs:

customer

subscription

subscription_item

receipt

SubscriptionData

CustomerData