payments-stripe-full

Files (19)

• README.md
• SKILL.md
• 01-basic-checkout.ts · examples/
• 02-webhook-handler.ts · examples/
• 03-customer-portal.ts · examples/
• package-lock.json
• package.json
• checkout.ts · src/
• client.ts · src/
• customers.ts · src/
• index.ts · src/
• subscriptions.ts · src/
• types.ts · src/
• webhooks.ts · src/
• client.test.ts · tests/
• index.test.ts · tests/
• types.test.ts · tests/
• tsconfig.json
• vitest.config.ts

SKILL.md (first lines)

# Payments Stripe Full

Complete Stripe payment integration for Next.js applications with webhooks, subscriptions, checkout, and production-ready security patterns.

## When to Use

Use this skill when building Next.js SaaS applications that need:
- Stripe Checkout for one-time or subscription payments
- Webhook handling with signature verification
- Subscription management (create, update, cancel)
- Customer portal integration
- Idempotent payment operations
- Secure API key management

**Don't use this skill if:**
- You need a different payment provider (PayPal, Square, etc.)
- You only need client-side Stripe Elements (no server integration)
- Your app doesn't handle recurring subscriptions

## Stack

- Next.js 14+ (App Router)
- Stripe API (stripe npm package)
- TypeScript (strict mode)
- Webhook signature verification
- Supabase/PostgreSQL (for customer/subscription sync)

## Quick Start

### 1. Install Dependencies

```bash
npm install stripe
npm install -D @project-forge/payments-stripe-full
```

### 2. Setup Environment Variables

```bash
# .env.local
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Database
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
```

### 3. Create Configuration

```typescript
// lib/stripe/config.ts
export const stripeConfig = {
  secretKey: process.env.STRIPE_SECRET_KEY!,
  publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
}
```

### 4. Create Checkout Session

```typescript
import { createCheckoutSession } from '@project-forge/payments-stripe-full'

export async function POST(request: NextRequest) {
  const userId = await getUserId(request)

  const session = await createCheckoutSession(stripeConfig, {
    userId,
    priceId: 'price_1234...', // Stripe Price ID
    successUrl: `${process.env.NEXT_PUBLIC_URL}/success`,
    cancelUrl: `${process.env.NEXT_PUBLIC_URL}/cancel`,
  })

  return NextResponse.json({ sessionId: session.id })
}
```

### 5. Handle Webhooks

```typescript
import { handleWebhook } from '@project-forge/payments-stripe-full/webhooks'

export async function POST(request: NextRequest) {
  const payload = await request.text()
  const signature = request.headers.get('stripe-signature')!

  const result = await handleWebhook(stripeConfig, {
    payload,
    signature,
    handlers: {
      'checkout.session.completed': async (event) => {
        // Update database with successful payment
        const session = event.data.object
        await updateUserSubscription(session.customer, session.subscription)
      },
      'customer.subscription.deleted': async (event) => {
        // Handle subscription cancellation
        const subscription = event.data.object
        await cancelUserSubscription(subscription.customer)
      },
    },
  })

  return NextResponse.json(result)
}
```

## Key Features

### Secure Webhook Verification

Verifies Stripe webhook signatures to prevent fraud:

```typescript
const event = stripe.webhooks.constructEvent(
  payload,
  signature,

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge