@strav/stripe 0.1.0

package/src/subscription.ts

@@ -0,0 +1,276 @@
+import { extractUserId } from '@stravigor/database'
+import StripeManager from './stripe_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 StripeManager.db.sql
+  }
+
+  private static get fk() {
+    return StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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,
+    }
+  }
+}

package/src/subscription_builder.ts

@@ -0,0 +1,182 @@
+import type Stripe from 'stripe'
+import { extractUserId } from '@stravigor/database'
+import StripeManager from './stripe_manager.ts'
+import Customer from './customer.ts'
+import Subscription from './subscription.ts'
+import SubscriptionItem from './subscription_item.ts'
+import { SubscriptionCreationError } from './errors.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
+    let stripeSub: Stripe.Subscription
+    try {
+      stripeSub = await StripeManager.stripe.subscriptions.create(params)
+    } catch (err: any) {
+      throw new SubscriptionCreationError(
+        `Failed to create Stripe subscription "${this._name}": ${err?.message ?? err}`
+      )
+    }
+
+    // 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,170 @@
+import StripeManager from './stripe_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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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 StripeManager.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,
+    }
+  }
+}