@strav/stripe 0.1.0

package/src/helpers.ts

@@ -0,0 +1,110 @@
+import type Stripe from 'stripe'
+import StripeManager from './stripe_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'
+
+/**
+ * Stripe helper object — the primary convenience API.
+ *
+ * @example
+ * import { stripe } from '@stravigor/stripe'
+ *
+ * // Direct Stripe instance access
+ * stripe.stripe.customers.list()
+ *
+ * // Subscription builder
+ * await stripe.newSubscription('pro', 'price_xxx').trialDays(14).create(user)
+ *
+ * // Checkout builder
+ * const session = await stripe.newCheckout().item('price_xxx').mode('payment').create(user)
+ */
+export const stripe = {
+  /** Direct access to the configured Stripe SDK instance. */
+  get stripe(): Stripe {
+    return StripeManager.stripe
+  },
+
+  /** The Stripe publishable key (for frontend use). */
+  get key(): string {
+    return StripeManager.config.key
+  },
+
+  /** The configured default currency. */
+  get currency(): string {
+    return StripeManager.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,49 @@
+// Manager
+export { default, default as StripeManager } from './stripe_manager.ts'
+
+// Provider
+export { default as StripeProvider } from './stripe_provider.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 { stripe } from './helpers.ts'
+
+// Webhook
+export { stripeWebhook, onWebhookEvent } from './webhook.ts'
+
+// Errors
+export {
+  StripeError,
+  WebhookSignatureError,
+  CustomerNotFoundError,
+  SubscriptionNotFoundError,
+  PaymentMethodError,
+  SubscriptionCreationError,
+} from './errors.ts'
+
+// Types
+export type {
+  StripeConfig,
+  CustomerData,
+  SubscriptionData,
+  SubscriptionItemData,
+  ReceiptData,
+  SubscriptionStatusValue,
+  WebhookEventHandler,
+} from './types.ts'
+export { SubscriptionStatus } from './types.ts'

package/src/invoice.ts

@@ -0,0 +1,66 @@
+import type Stripe from 'stripe'
+import StripeManager from './stripe_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 StripeManager.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 StripeManager.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 StripeManager.stripe.invoices.retrieve(invoiceId)
+  }
+
+  /** Get the hosted invoice URL for payment. */
+  static async hostedUrl(invoiceId: string): Promise<string | null> {
+    const invoice = await StripeManager.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 StripeManager.stripe.invoices.retrieve(invoiceId)
+    return invoice.invoice_pdf ?? null
+  }
+
+  /** Void an invoice. */
+  static async void_(invoiceId: string): Promise<Stripe.Invoice> {
+    return StripeManager.stripe.invoices.voidInvoice(invoiceId)
+  }
+}

package/src/payment_method.ts

@@ -0,0 +1,59 @@
+import type Stripe from 'stripe'
+import StripeManager from './stripe_manager.ts'
+import Customer from './customer.ts'
+import { PaymentMethodError } from './errors.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 StripeManager.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 StripeManager.stripe.paymentMethods.attach(paymentMethodId, {
+        customer: customer.stripeId,
+      })
+    } catch (err: any) {
+      // Only ignore "already attached" errors — rethrow everything else
+      if (err?.code !== 'resource_already_exists') {
+        throw new PaymentMethodError(
+          `Failed to attach payment method "${paymentMethodId}": ${err?.message ?? err}`
+        )
+      }
+    }
+
+    // Set as default on Stripe
+    await StripeManager.stripe.customers.update(customer.stripeId, {
+      invoice_settings: { default_payment_method: paymentMethodId },
+    })
+
+    // Update local record
+    const pm = await StripeManager.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/database'
+import StripeManager from './stripe_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 StripeManager.db.sql
+  }
+
+  private static get fk() {
+    return StripeManager.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/stripe_manager.ts

@@ -0,0 +1,75 @@
+import Stripe from 'stripe'
+import { inject, Configuration, ConfigurationError } from '@stravigor/kernel'
+import { Database, toSnakeCase } from '@stravigor/database'
+import type { StripeConfig } from './types.ts'
+
+@inject
+export default class StripeManager {
+  private static _db: Database
+  private static _config: StripeConfig
+  private static _stripe: Stripe
+  private static _userFkColumn: string
+
+  constructor(db: Database, config: Configuration) {
+    StripeManager._db = db
+
+    const userKey = config.get('stripe.userKey', 'id') as string
+    StripeManager._userFkColumn = `user_${toSnakeCase(userKey)}`
+
+    const secret = config.get('stripe.secret', '') as string
+
+    StripeManager._config = {
+      secret,
+      key: config.get('stripe.key', '') as string,
+      webhookSecret: config.get('stripe.webhookSecret', '') as string,
+      currency: config.get('stripe.currency', 'usd') as string,
+      userKey,
+      urls: {
+        success: config.get('stripe.urls.success', '/billing/success') as string,
+        cancel: config.get('stripe.urls.cancel', '/billing/cancel') as string,
+      },
+    }
+
+    if (secret) {
+      StripeManager._stripe = new Stripe(secret)
+    }
+  }
+
+  static get db(): Database {
+    if (!StripeManager._db) {
+      throw new ConfigurationError(
+        'StripeManager not configured. Resolve it through the container first.'
+      )
+    }
+    return StripeManager._db
+  }
+
+  static get config(): StripeConfig {
+    if (!StripeManager._config) {
+      throw new ConfigurationError(
+        'StripeManager not configured. Resolve it through the container first.'
+      )
+    }
+    return StripeManager._config
+  }
+
+  static get stripe(): Stripe {
+    if (!StripeManager._stripe) {
+      throw new ConfigurationError('StripeManager not configured. Ensure STRIPE_SECRET is set.')
+    }
+    return StripeManager._stripe
+  }
+
+  /** The FK column name on stripe tables (e.g. `user_id`, `user_uid`). */
+  static get userFkColumn(): string {
+    return StripeManager._userFkColumn ?? 'user_id'
+  }
+
+  /** Reset internal state (useful for testing). */
+  static reset(): void {
+    StripeManager._db = undefined as any
+    StripeManager._config = undefined as any
+    StripeManager._stripe = undefined as any
+    StripeManager._userFkColumn = undefined as any
+  }
+}

package/src/stripe_provider.ts

@@ -0,0 +1,16 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import StripeManager from './stripe_manager.ts'
+
+export default class StripeProvider extends ServiceProvider {
+  readonly name = 'stripe'
+  override readonly dependencies = ['database']
+
+  override register(app: Application): void {
+    app.singleton(StripeManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(StripeManager)
+  }
+}