npm install @latimer-woods-tech/stripe

wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET

function createStripeClient(secretKey: string): Stripe;

function validateWebhook(
  request: Request,
  webhookSecret: string,
  stripeClient: Stripe,
): Promise<Stripe.Event>;

function getSubscription(
  customerId: string,
  stripeClient: Stripe,
): Promise<SubscriptionStatus>;

interface CreateCheckoutSessionOptions {
  priceId: string;
  customerId: string;
  successUrl: string;
  cancelUrl: string;
  stripeClient: Stripe;
  /** Defaults to 'subscription'. Use 'payment' for one-time purchases. */
  mode?: 'subscription' | 'payment';
  /** Idempotency key to prevent duplicate session creation on retry. */
  idempotencyKey?: string;
  /** Explicitly set accepted payment method types (e.g. ['card']). */
  paymentMethodTypes?: string[];
  /** Metadata to attach to the session. */
  metadata?: Record<string, string>;
}

function createCheckoutSession(opts: CreateCheckoutSessionOptions): Promise<string>;

interface CreatePortalSessionOptions {
  customerId: string;
  returnUrl: string;
  stripeClient: Stripe;
}

function createPortalSession(opts: CreatePortalSessionOptions): Promise<string>;

function stripeWebhookHandler(options: StripeWebhookHandlerOptions): Handler;

function priceToTier(priceId: string, tierMap: Record<string, string>): string;

import {
  createStripeClient,
  createCheckoutSession,
  createPortalSession,
  stripeWebhookHandler,
} from '@latimer-woods-tech/stripe';

const stripe = createStripeClient(env.STRIPE_SECRET_KEY);

// Subscription checkout (monthly, annual, or one-time)
app.post('/api/checkout', authMiddleware, async (c) => {
  const { priceId } = await c.req.json<{ priceId: string }>();
  const user = c.get('user');

  const url = await createCheckoutSession({
    priceId,
    customerId: user.stripeCustomerId,
    successUrl: `${env.APP_URL}/checkout/success`,
    cancelUrl: `${env.APP_URL}/pricing`,
    stripeClient: stripe,
    idempotencyKey: `checkout_${user.id}_${priceId}`,
    paymentMethodTypes: ['card'],
    metadata: { userId: user.id },
  });

  return c.redirect(url);
});

// Customer Portal — self-service cancel / upgrade / payment details
app.post('/api/billing/portal', authMiddleware, async (c) => {
  const user = c.get('user');

  const url = await createPortalSession({
    customerId: user.stripeCustomerId,
    returnUrl: `${env.APP_URL}/account`,
    stripeClient: stripe,
  });

  return c.redirect(url);
});

// Webhook handler
app.post('/webhooks/stripe', stripeWebhookHandler({
  webhookSecret: env.STRIPE_WEBHOOK_SECRET,
  stripeClient: stripe,
  handlers: {
    created: async (status) => {
      await db.insert(subscriptions).values({
        customerId: status.customerId,
        status: status.status,
        tier: status.tier,
        currentPeriodEnd: status.currentPeriodEnd,
      });
    },
    canceled: async (status) => {
      await db.delete(subscriptions)
        .where(eq(subscriptions.customerId, status.customerId));
    },
    past_due: async (status) => {
      logger.warn('Subscription payment failed', { customerId: status.customerId });
    },
  },
}));