# stripe-launch

Automatically adds complete Stripe payment infrastructure to any web project. Detects your framework, installs the right SDK, wires up checkout, webhooks, and customer portal, then commits production-ready code.

**Invoke:** `/stripe-launch`

**Optional args:** `/stripe-launch subscriptions` or `/stripe-launch one-time`

---

## What this skill produces

- Stripe Checkout session endpoint (one-time or subscription)
- Webhook handler with signature verification
- Customer portal endpoint (for subscriptions)
- `.env.example` updated with required Stripe keys
- Unit/integration tests for payment flows
- `STRIPE_SETUP.md` guide for going live

---

## Instructions

### Phase 1 — Recon

1. Read `package.json`, `requirements.txt`, `Gemfile`, `composer.json`, or `go.mod` to identify the framework and language.
2. Check for existing Stripe imports or environment variables. If Stripe is already partially set up, note what exists and build on it rather than overwriting.
3. Identify the entry point: `app.js`, `server.js`, `main.py`, `app.py`, `app.rb`, `routes/web.php`, etc.
4. Identify the frontend framework if one exists (React, Vue, Next.js, plain HTML).
5. Check for an existing `.env` or `.env.example`. Note the format.
6. Check for an existing test setup (Jest, pytest, RSpec, PHPUnit, Go test).

### Phase 2 — Install Stripe SDK

Based on the detected language/framework, run the appropriate install command:

- **Node.js / Next.js:** `npm install stripe @stripe/stripe-js`
- **Python / Django / FastAPI / Flask:** `pip install stripe` and update `requirements.txt`
- **Ruby on Rails:** `bundle add stripe`
- **PHP / Laravel:** `composer require stripe/stripe-php`
- **Go:** `go get github.com/stripe/stripe-go/v76`

Do NOT run the install command if Stripe is already in the dependency file.

### Phase 3 — Determine payment mode

If the user passed `subscriptions` as an argument, use subscription mode.
If the user passed `one-time` as an argument, use one-time payment mode.
If neither was passed:
- Look for clues in the codebase (words like "plan", "subscribe", "monthly", "tier" suggest subscriptions)
- Default to **one-time** if unclear, and note your choice in the summary

### Phase 4 — Create server-side payment files

Create all files under a `payments/` directory (or framework-appropriate location).

#### 4a. Checkout endpoint

Create a function/route that:
1. Accepts a POST request with `{ price_id, success_url, cancel_url }` (or reads these from env)
2. Creates a Stripe Checkout Session using `stripe.checkout.sessions.create`
3. Returns the session URL or session ID
4. Handles errors gracefully and returns appropriate HTTP status codes
5. Uses `STRIPE_SECRET_KEY` from environment variables — never hardcoded

For **subscriptions**, set `mode: 'subscription'` and include `allow_promotion_codes: true`.
For **one-time**, set `mode: 'payment'`.

#### 4b. Webhook handler

Create a route that handles `POST /webhook` (or `/api/webhook` for Next.js):
1. Reads the raw request body (critical for signature verification)
2. Verifies the signature using `stripe.webhooks.constructEvent` with `STRIPE_WEBHOOK_SECRET`
3. Handles these events with a switch/match:
   - `checkout.session.completed` — mark payment as successful, fulfill order
   - `invoice.payment_succeeded` (subscriptions only) — renew access
   - `invoice.payment_failed` (subscriptions only) — notify user, restrict access
   - `customer.subscription.deleted` (subscriptions only) — revoke access
4. Returns 200 immediately to acknowledge receipt
5. Includes a clear TODO comment for where to add database/fulfillment logic

**Raw body parsing is required.** Add the correct middleware:
- Express: `express.raw({ type: 'application/json' })` on the webhook route only
- Next.js: `export const config = { api: { bodyParser: false } }`
- Django: no body parsing needed (access `request.body` directly)
- Flask: use `request.data`

#### 4c. Customer portal (subscriptions only)

Create a `POST /portal` endpoint that:
1. Looks up the Stripe customer ID for the authenticated user
2. Creates a billing portal session via `stripe.billingPortal.sessions.create`
3. Redirects to the portal URL
4. Includes a TODO for where to fetch the customer ID from your database

### Phase 5 — Frontend integration

If a frontend framework is detected:

**React / Next.js:**
- Create `components/CheckoutButton.jsx` (or `.tsx` if TypeScript is used)
- The button calls your checkout endpoint, then redirects to `session.url`
- Show a loading spinner while the request is in flight
- Handle errors by displaying a user-friendly message

**Plain HTML:**
- Add a `<script>` block to the existing HTML that fetches the checkout endpoint on button click

**No frontend detected (API-only):**
- Skip frontend files and note in the summary that the buyer should call the checkout endpoint directly

### Phase 6 — Environment variables

Add these to `.env.example` (create it if it doesn't exist):

```
# Stripe — get these from https://dashboard.stripe.com/apikeys
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Optional: your default Price ID from Stripe Dashboard
STRIPE_PRICE_ID=price_...
```

Never add actual key values. Only add to `.env.example`, never `.env`.

### Phase 7 — Write tests

Create tests appropriate for the detected test framework.

Test cases to cover:
1. Checkout endpoint returns a session URL when called with valid params
2. Checkout endpoint returns 400 when required params are missing
3. Webhook handler returns 200 for a valid signed event
4. Webhook handler returns 400 for an invalid signature
5. (Subscriptions) Webhook correctly handles `invoice.payment_failed`

Mock Stripe calls — do not make real API calls in tests.

### Phase 8 — Create STRIPE_SETUP.md

Create a `STRIPE_SETUP.md` file at the project root with these sections:

1. **Prerequisites** — Stripe account, keys, and where to find them
2. **Local testing** — How to install and use the Stripe CLI to forward webhooks
3. **Going live checklist** — Switch to live keys, set up webhook endpoint in dashboard, test with a real card
4. **Price ID setup** — How to create a product and price in the Stripe Dashboard and copy the `price_` ID
5. **Troubleshooting** — Common errors (wrong webhook secret, body parser conflicts, CORS issues)

### Phase 9 — Commit

Stage all created/modified files and create a commit:
```
git add .
git commit -m "feat: add Stripe payment infrastructure via stripe-launch"
```

### Phase 10 — Summary

Output a clean summary with:
- Framework detected
- Payment mode (one-time / subscription)
- Files created (list each with a one-line description)
- Next steps (numbered, actionable):
  1. Copy `.env.example` to `.env` and fill in your Stripe keys
  2. Run the Stripe CLI to test webhooks locally: `stripe listen --forward-to localhost:3000/webhook`
  3. Create a product in the Stripe Dashboard and paste the `price_` ID into your env
  4. Test with Stripe test card: `4242 4242 4242 4242`
  5. See `STRIPE_SETUP.md` for going-live checklist

---

## Quality rules

- All Stripe keys must come from environment variables. If you see a hardcoded key anywhere, remove it.
- Never commit `.env` files. If one exists without a `.gitignore` entry, add it.
- Webhook signature verification is not optional. If the framework makes it difficult, add a comment explaining the risk.
- Add a `// FULFILL ORDER HERE` or `# FULFILL ORDER HERE` comment in the webhook handler so the buyer knows exactly where to hook in their business logic.
- Keep files focused. One responsibility per file.
- Match the existing code style (spacing, quotes, semicolons, type annotations).