@meith/plugin-dues 0.1.0

package/src/stripe/client.ts

@@ -0,0 +1,303 @@
+
+export interface StripeClientOptions {
+  readonly secretKey: string
+  readonly apiVersion: string
+  readonly apiBase?: string
+  readonly fetchImpl?: typeof fetch
+  readonly timeoutMs?: number
+  readonly maxAttempts?: number
+  readonly backoff?: (attempt: number) => Promise<void>
+}
+
+export class StripeError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string | null,
+    readonly type: string | null,
+  ) {
+    super(message)
+    this.name = 'StripeError'
+  }
+
+  get transient(): boolean {
+    return this.status === 429 || this.status >= 500
+  }
+}
+
+export function encodeStripeForm(body: Record<string, unknown>): string {
+  const pairs: string[] = []
+
+  const walk = (prefix: string, value: unknown): void => {
+    if (value === undefined || value === null) return
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => walk(`${prefix}[${index}]`, entry))
+      return
+    }
+    if (typeof value === 'object') {
+      for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+        walk(prefix === '' ? key : `${prefix}[${key}]`, entry)
+      }
+      return
+    }
+    pairs.push(`${encodeURIComponent(prefix)}=${encodeURIComponent(String(value))}`)
+  }
+
+  walk('', body)
+  return pairs.join('&')
+}
+
+export interface CheckoutSessionState {
+  readonly id: string
+  readonly url: string | null
+  readonly status: 'open' | 'complete' | 'expired'
+  readonly paymentStatus: 'paid' | 'unpaid' | 'no_payment_required'
+  readonly amountTotal: number | null
+  readonly currency: string | null
+  readonly subscriptionId: string | null
+  readonly paymentIntentId: string | null
+  readonly customerId: string | null
+}
+
+export interface SubscriptionState {
+  readonly id: string
+  readonly status: string
+  readonly cancelAtPeriodEnd: boolean
+  readonly currentPeriodEnd: Date | null
+}
+
+function str(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (typeof value === 'object' && value !== null && typeof (value as { id?: unknown }).id === 'string') {
+    return (value as { id: string }).id
+  }
+  return null
+}
+
+export function sessionFromApi(body: Record<string, unknown>): CheckoutSessionState {
+  return {
+    id: String(body.id),
+    url: typeof body.url === 'string' ? body.url : null,
+    status: (body.status ?? 'open') as CheckoutSessionState['status'],
+    paymentStatus: (body.payment_status ?? 'unpaid') as CheckoutSessionState['paymentStatus'],
+    amountTotal: typeof body.amount_total === 'number' ? body.amount_total : null,
+    currency: typeof body.currency === 'string' ? body.currency : null,
+    subscriptionId: str(body.subscription),
+    paymentIntentId: str(body.payment_intent),
+    customerId: str(body.customer),
+  }
+}
+
+export function subscriptionFromApi(body: Record<string, unknown>): SubscriptionState {
+  let periodEnd: number | null = typeof body.current_period_end === 'number' ? body.current_period_end : null
+
+  if (periodEnd === null) {
+    const items = (body.items as { data?: unknown } | undefined)?.data
+    if (Array.isArray(items)) {
+      for (const item of items) {
+        const end = (item as { current_period_end?: unknown }).current_period_end
+        if (typeof end === 'number' && (periodEnd === null || end > periodEnd)) periodEnd = end
+      }
+    }
+  }
+
+  return {
+    id: String(body.id),
+    status: String(body.status ?? 'unknown'),
+    cancelAtPeriodEnd: body.cancel_at_period_end === true,
+    currentPeriodEnd: periodEnd === null ? null : new Date(periodEnd * 1000),
+  }
+}
+
+export interface StripeClient {
+  createCustomer(input: {
+    readonly metadata: Readonly<Record<string, string>>
+  }): Promise<{ readonly id: string }>
+
+  createCoupon(input: {
+    readonly percentOff: number
+    readonly name: string
+    readonly reference: string
+  }): Promise<{ readonly id: string }>
+
+  createProduct(input: {
+    readonly name: string
+    readonly reference: string
+  }): Promise<{ readonly id: string }>
+
+  createPrice(input: {
+    readonly productId: string
+    readonly unitAmount: number
+    readonly currency: string
+    readonly interval: 'month' | 'year'
+    readonly reference: string
+  }): Promise<{ readonly id: string }>
+
+  createCheckoutSession(input: Record<string, unknown>): Promise<CheckoutSessionState>
+  getCheckoutSession(id: string): Promise<CheckoutSessionState>
+
+  getSubscription(id: string): Promise<SubscriptionState>
+  setCancelAtPeriodEnd(id: string, cancel: boolean): Promise<SubscriptionState>
+
+  createBillingPortalSession(input: {
+    readonly customer: string
+    readonly returnUrl: string
+  }): Promise<{ readonly url: string }>
+}
+
+const DEFAULT_BASE = 'https://api.stripe.com'
+const DEFAULT_TIMEOUT_MS = 10_000
+const DEFAULT_ATTEMPTS = 3
+
+export function createStripeClient(options: StripeClientOptions): StripeClient {
+  const base = (options.apiBase ?? DEFAULT_BASE).replace(/\/$/, '')
+  const doFetch = options.fetchImpl ?? fetch
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const maxAttempts = options.maxAttempts ?? DEFAULT_ATTEMPTS
+  const backoff =
+    options.backoff ??
+    ((attempt: number) =>
+      new Promise<void>((resolve) =>
+        setTimeout(resolve, 250 * 2 ** attempt + Math.floor(Math.random() * 100)),
+      ))
+
+  async function request(
+    method: 'GET' | 'POST',
+    path: string,
+    body?: Record<string, unknown>,
+    idempotencyKey?: string,
+  ): Promise<Record<string, unknown>> {
+    let lastError: unknown = null
+
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (attempt > 0) await backoff(attempt)
+
+      let response: Response
+      try {
+        response = await doFetch(`${base}${path}`, {
+          method,
+          headers: {
+            authorization: `Bearer ${options.secretKey}`,
+            'stripe-version': options.apiVersion,
+            ...(body === undefined
+              ? {}
+              : { 'content-type': 'application/x-www-form-urlencoded' }),
+            ...(idempotencyKey === undefined ? {} : { 'idempotency-key': idempotencyKey }),
+          },
+          ...(body === undefined ? {} : { body: encodeStripeForm(body) }),
+          signal: AbortSignal.timeout(timeoutMs),
+        })
+      } catch (error) {
+        lastError = error
+        continue
+      }
+
+      const text = await response.text()
+      let parsed: Record<string, unknown>
+      try {
+        parsed = JSON.parse(text) as Record<string, unknown>
+      } catch {
+        parsed = {}
+      }
+
+      if (response.ok) return parsed
+
+      const detail = (parsed.error ?? {}) as {
+        message?: string
+        code?: string
+        type?: string
+      }
+      const error = new StripeError(
+        detail.message ?? `Stripe answered ${response.status}`,
+        response.status,
+        detail.code ?? null,
+        detail.type ?? null,
+      )
+      if (!error.transient) throw error
+      lastError = error
+    }
+
+    throw lastError instanceof Error
+      ? lastError
+      : new StripeError('Stripe was unreachable', 0, null, null)
+  }
+
+  return {
+    async createCustomer(input) {
+      const body = await request('POST', '/v1/customers', { metadata: input.metadata })
+      return { id: String(body.id) }
+    },
+
+    async createCoupon(input) {
+      const body = await request(
+        'POST',
+        '/v1/coupons',
+        { percent_off: input.percentOff, duration: 'once', name: input.name },
+        `dues-coupon-${input.reference}`,
+      )
+      return { id: String(body.id) }
+    },
+
+    async createProduct(input) {
+      const body = await request(
+        'POST',
+        '/v1/products',
+        { name: input.name },
+        `dues-product-${input.reference}`,
+      )
+      return { id: String(body.id) }
+    },
+
+    async createPrice(input) {
+      const body = await request(
+        'POST',
+        '/v1/prices',
+        {
+          product: input.productId,
+          unit_amount: input.unitAmount,
+          currency: input.currency,
+          recurring: { interval: input.interval },
+        },
+        `dues-price-${input.reference}`,
+      )
+      return { id: String(body.id) }
+    },
+
+    async createCheckoutSession(input) {
+      const idempotencyKey =
+        typeof input.client_reference_id === 'string'
+          ? `dues-session-${input.client_reference_id}`
+          : undefined
+      return sessionFromApi(await request('POST', '/v1/checkout/sessions', input, idempotencyKey))
+    },
+
+    async getCheckoutSession(id) {
+      return sessionFromApi(await request('GET', `/v1/checkout/sessions/${encodeURIComponent(id)}`))
+    },
+
+    async getSubscription(id) {
+      return subscriptionFromApi(
+        await request('GET', `/v1/subscriptions/${encodeURIComponent(id)}`),
+      )
+    },
+
+    async setCancelAtPeriodEnd(id, cancel) {
+      return subscriptionFromApi(
+        await request(
+          'POST',
+          `/v1/subscriptions/${encodeURIComponent(id)}`,
+          { cancel_at_period_end: cancel },
+          `dues-cancel-${id}-${cancel ? 'on' : 'off'}`,
+        ),
+      )
+    },
+
+    async createBillingPortalSession(input) {
+      const body = await request('POST', '/v1/billing_portal/sessions', {
+        customer: input.customer,
+        return_url: input.returnUrl,
+      })
+      return { url: String(body.url) }
+    },
+  }
+}

package/src/stripe/events.ts

@@ -0,0 +1,189 @@
+
+export interface StripeEventEnvelope {
+  readonly id: string
+  readonly type: string
+  readonly object: Record<string, unknown>
+}
+
+export function parseEventEnvelope(payload: unknown): StripeEventEnvelope | null {
+  if (typeof payload !== 'object' || payload === null) return null
+  const event = payload as Record<string, unknown>
+  if (typeof event.id !== 'string' || typeof event.type !== 'string') return null
+  const data = event.data as { object?: unknown } | undefined
+  const object = data?.object
+  if (typeof object !== 'object' || object === null) return null
+  return { id: event.id, type: event.type, object: object as Record<string, unknown> }
+}
+
+export type InternalEvent =
+  | {
+      readonly kind: 'checkout-settled'
+      readonly sessionId: string
+      readonly paid: boolean
+      readonly amountTotal: number | null
+      readonly currency: string | null
+      readonly subscriptionId: string | null
+      readonly paymentIntentId: string | null
+      readonly customerId: string | null
+    }
+  | { readonly kind: 'checkout-failed'; readonly sessionId: string }
+  | { readonly kind: 'checkout-expired'; readonly sessionId: string }
+  | {
+      readonly kind: 'invoice-paid'
+      readonly subscriptionId: string | null
+      readonly periodEnd: Date | null
+      readonly amountPaid: number
+      readonly currency: string | null
+      readonly billingReason: string | null
+    }
+  | { readonly kind: 'invoice-failed'; readonly subscriptionId: string | null }
+  | {
+      readonly kind: 'subscription-updated'
+      readonly subscriptionId: string
+      readonly cancelAtPeriodEnd: boolean
+      readonly periodEnd: Date | null
+      readonly status: string
+    }
+  | { readonly kind: 'subscription-deleted'; readonly subscriptionId: string }
+  | {
+      readonly kind: 'payment-reversed'
+      readonly reversal: 'refund' | 'chargeback'
+      readonly paymentIntentId: string | null
+      readonly amountMinor: number
+      readonly currency: string | null
+      readonly stripeRef: string | null
+    }
+  | { readonly kind: 'unhandled'; readonly type: string }
+
+function idOf(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (typeof value === 'object' && value !== null) {
+    const id = (value as { id?: unknown }).id
+    if (typeof id === 'string') return id
+  }
+  return null
+}
+
+function invoiceSubscriptionId(invoice: Record<string, unknown>): string | null {
+  const direct = idOf(invoice.subscription)
+  if (direct !== null) return direct
+
+  const parent = invoice.parent as
+    | { subscription_details?: { subscription?: unknown } }
+    | undefined
+  return idOf(parent?.subscription_details?.subscription)
+}
+
+function invoicePeriodEnd(invoice: Record<string, unknown>): Date | null {
+  const lines = (invoice.lines as { data?: unknown } | undefined)?.data
+  let latest: number | null = null
+  if (Array.isArray(lines)) {
+    for (const line of lines) {
+      const end = ((line as { period?: { end?: unknown } }).period ?? {}).end
+      if (typeof end === 'number' && (latest === null || end > latest)) latest = end
+    }
+  }
+  if (latest === null && typeof invoice.period_end === 'number') latest = invoice.period_end
+  return latest === null ? null : new Date(latest * 1000)
+}
+
+function subscriptionPeriodEnd(subscription: Record<string, unknown>): Date | null {
+  if (typeof subscription.current_period_end === 'number') {
+    return new Date(subscription.current_period_end * 1000)
+  }
+  const items = (subscription.items as { data?: unknown } | undefined)?.data
+  let latest: number | null = null
+  if (Array.isArray(items)) {
+    for (const item of items) {
+      const end = (item as { current_period_end?: unknown }).current_period_end
+      if (typeof end === 'number' && (latest === null || end > latest)) latest = end
+    }
+  }
+  return latest === null ? null : new Date(latest * 1000)
+}
+
+export function toInternalEvent(envelope: StripeEventEnvelope): InternalEvent {
+  const object = envelope.object
+
+  switch (envelope.type) {
+    case 'checkout.session.completed':
+    case 'checkout.session.async_payment_succeeded':
+      return {
+        kind: 'checkout-settled',
+        sessionId: String(object.id),
+        paid: object.payment_status === 'paid' || object.payment_status === 'no_payment_required',
+        amountTotal: typeof object.amount_total === 'number' ? object.amount_total : null,
+        currency: typeof object.currency === 'string' ? object.currency : null,
+        subscriptionId: idOf(object.subscription),
+        paymentIntentId: idOf(object.payment_intent),
+        customerId: idOf(object.customer),
+      }
+
+    case 'checkout.session.async_payment_failed':
+      return { kind: 'checkout-failed', sessionId: String(object.id) }
+
+    case 'checkout.session.expired':
+      return { kind: 'checkout-expired', sessionId: String(object.id) }
+
+    case 'invoice.paid':
+      return {
+        kind: 'invoice-paid',
+        subscriptionId: invoiceSubscriptionId(object),
+        periodEnd: invoicePeriodEnd(object),
+        amountPaid: typeof object.amount_paid === 'number' ? object.amount_paid : 0,
+        currency: typeof object.currency === 'string' ? object.currency : null,
+        billingReason: typeof object.billing_reason === 'string' ? object.billing_reason : null,
+      }
+
+    case 'invoice.payment_failed':
+      return { kind: 'invoice-failed', subscriptionId: invoiceSubscriptionId(object) }
+
+    case 'customer.subscription.updated':
+      return {
+        kind: 'subscription-updated',
+        subscriptionId: String(object.id),
+        cancelAtPeriodEnd: object.cancel_at_period_end === true,
+        periodEnd: subscriptionPeriodEnd(object),
+        status: String(object.status ?? 'unknown'),
+      }
+
+    case 'customer.subscription.deleted':
+      return { kind: 'subscription-deleted', subscriptionId: String(object.id) }
+
+    case 'charge.refunded':
+      return {
+        kind: 'payment-reversed',
+        reversal: 'refund',
+        paymentIntentId: idOf(object.payment_intent),
+        amountMinor: typeof object.amount_refunded === 'number' ? object.amount_refunded : 0,
+        currency: typeof object.currency === 'string' ? object.currency : null,
+        stripeRef: typeof object.id === 'string' ? object.id : null,
+      }
+
+    case 'charge.dispute.created':
+      return {
+        kind: 'payment-reversed',
+        reversal: 'chargeback',
+        paymentIntentId: idOf(object.payment_intent),
+        amountMinor: typeof object.amount === 'number' ? object.amount : 0,
+        currency: typeof object.currency === 'string' ? object.currency : null,
+        stripeRef: typeof object.id === 'string' ? object.id : null,
+      }
+
+    default:
+      return { kind: 'unhandled', type: envelope.type }
+  }
+}
+
+export const SUBSCRIBED_EVENT_TYPES = [
+  'checkout.session.completed',
+  'checkout.session.async_payment_succeeded',
+  'checkout.session.async_payment_failed',
+  'checkout.session.expired',
+  'invoice.paid',
+  'invoice.payment_failed',
+  'customer.subscription.updated',
+  'customer.subscription.deleted',
+  'charge.refunded',
+  'charge.dispute.created',
+] as const

package/src/stripe/webhook.ts

@@ -0,0 +1,64 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+export const STRIPE_SIGNATURE_HEADER = 'stripe-signature'
+export const SIGNATURE_TOLERANCE_SECONDS = 300
+
+export type SignatureVerdict =
+  | { readonly ok: true; readonly timestamp: number }
+  | { readonly ok: false; readonly reason: 'missing' | 'malformed' | 'stale' | 'mismatch' }
+
+export function verifyStripeSignature(
+  rawBody: Uint8Array,
+  header: string | null | undefined,
+  secret: string,
+  now: Date = new Date(),
+  toleranceSeconds: number = SIGNATURE_TOLERANCE_SECONDS,
+): SignatureVerdict {
+  if (header === null || header === undefined || header === '') {
+    return { ok: false, reason: 'missing' }
+  }
+
+  let timestamp: number | null = null
+  const signatures: string[] = []
+
+  for (const part of header.split(',')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    const key = part.slice(0, eq).trim()
+    const value = part.slice(eq + 1).trim()
+    if (key === 't') timestamp = Number(value)
+    if (key === 'v1' && /^[0-9a-f]{64}$/.test(value)) signatures.push(value)
+  }
+
+  if (timestamp === null || !Number.isFinite(timestamp) || signatures.length === 0) {
+    return { ok: false, reason: 'malformed' }
+  }
+
+  const age = Math.abs(now.getTime() / 1000 - timestamp)
+  if (age > toleranceSeconds) return { ok: false, reason: 'stale' }
+
+  const mac = createHmac('sha256', secret)
+  mac.update(`${timestamp}.`, 'utf8')
+  mac.update(rawBody)
+  const expected = mac.digest()
+
+  for (const candidate of signatures) {
+    const presented = Buffer.from(candidate, 'hex')
+    if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
+      return { ok: true, timestamp }
+    }
+  }
+
+  return { ok: false, reason: 'mismatch' }
+}
+
+export function signStripePayload(
+  rawBody: Uint8Array | string,
+  secret: string,
+  timestamp: number,
+): string {
+  const mac = createHmac('sha256', secret)
+  mac.update(`${timestamp}.`, 'utf8')
+  mac.update(typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody)
+  return `t=${timestamp},v1=${mac.digest('hex')}`
+}