docs: Refactor Stripe integration skill with comprehensive guide

Author: ciro-maciel

.agent/skills/riligar-dev-stripe/SKILL.md

@@ -1,86 +1,163 @@
 ---
 name: riligar-dev-stripe
 type: development
-description: Stripe payment integration patterns. Use when implementing payments, subscriptions, webhooks, checkout flows, or billing in Elysia/Bun applications.
+description: 'Complete guide for Stripe payment integration in RiLiGar applications. Use when implementing: (1) Checkout flows (hosted or embedded), (2) Subscription management, (3) Webhook handlers, (4) Customer portal, (5) One-time payments, (6) Database schema for billing.'
 ---
 
-# Stripe Integration Patterns
+# Stripe Integration Skill
 
-> Patterns for integrating Stripe payments in RiLiGar applications.
-
----
+This skill provides a complete workflow for integrating Stripe payments using Elysia (backend) and React (frontend).
 
 ## Mandatory Guidelines
 
 > [!IMPORTANT]
 > All work in this skill MUST adhere to:
 >
-> - @[.agent/skills/riligar-dev-backend] (API Standards)
+> - @[.agent/skills/riligar-dev-backend] (Elysia API Standards)
+> - @[.agent/skills/riligar-dev-frontend] (React Patterns)
 > - @[.agent/skills/riligar-dev-clean-code] (Clean Code Standards)
 
 ---
 
-## 1. Core Concepts
+## Quick Reference
 
-| Concept | Description |
-| --- | --- |
-| **Customer** | User identity in Stripe |
-| **Product** | What you're selling |
-| **Price** | How much and billing cycle |
-| **Subscription** | Recurring payment |
-| **PaymentIntent** | One-time payment |
-| **Webhook** | Event notifications |
+```
+Stripe Flow:
+┌─────────────────────────────────────────────────────────────────────┐
+│  Frontend (React)              │  Backend (Elysia)                  │
+├────────────────────────────────┼────────────────────────────────────┤
+│  1. User clicks "Subscribe"    │                                    │
+│  2. Call POST /checkout        │ → 3. Create checkout session       │
+│  4. Redirect to Stripe         │                                    │
+│                                │  5. Webhook: checkout.completed    │
+│                                │  6. Update database                │
+│  7. Redirect to success_url    │                                    │
+└────────────────────────────────┴────────────────────────────────────┘
+```
 
 ---
 
-## 2. Environment Setup
+## Core Integration Workflow
+
+### 1. Installation
 
 ```bash
-# .env
+# Backend (Elysia)
+bun add stripe
+
+# Frontend (React)
+bun add @stripe/stripe-js @stripe/react-stripe-js
+```
+
+### 2. Environment Variables
+
+```bash
+# Backend .env
 STRIPE_SECRET_KEY=sk_live_...
 STRIPE_WEBHOOK_SECRET=whsec_...
-STRIPE_PUBLISHABLE_KEY=pk_live_...
-```
 
-> [!IMPORTANT]
-> Never expose `STRIPE_SECRET_KEY` in frontend code.
+# Frontend .env.local
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+```
 
----
+> [!CAUTION]
+> **STRIPE_SECRET_KEY** is for backend only. Never expose it in frontend code.
 
-## 3. Server-Side Patterns (Elysia)
+### 3. Initialize Stripe
 
-### Initialize Stripe
+**Backend (Elysia)**
 
 ```javascript
 import Stripe from 'stripe'
 
 const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
 ```
 
-### Create Checkout Session
+**Frontend (React)**
 
 ```javascript
+import { loadStripe } from '@stripe/stripe-js'
+
+const stripePromise = loadStripe(import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY)
+```
+
+For complete setup patterns, see [stripe-server.js](assets/stripe-server.js) and [stripe-client.js](assets/stripe-client.js).
+
+---
+
+## Specialized Guides
+
+| Guide | Content |
+| --- | --- |
+| [stripe-elysia.md](references/stripe-elysia.md) | Backend routes, checkout, customer management |
+| [stripe-react.md](references/stripe-react.md) | Frontend components, Elements, forms |
+| [stripe-webhooks.md](references/stripe-webhooks.md) | Event handling, signature verification |
+| [stripe-database.md](references/stripe-database.md) | Drizzle schema for billing data |
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+| --- | --- |
+| **Customer** | User identity in Stripe (link to your user table) |
+| **Product** | What you're selling (Pro Plan, Enterprise) |
+| **Price** | Amount and billing cycle (monthly, yearly) |
+| **Subscription** | Recurring payment relationship |
+| **PaymentIntent** | One-time payment flow |
+| **Checkout Session** | Hosted payment page |
+| **Customer Portal** | Self-service billing management |
+| **Webhook** | Server-to-server event notifications |
+
+---
+
+## Common Tasks
+
+### Create Checkout Session (Subscription)
+
+```javascript
+// Backend: POST /api/checkout
 const session = await stripe.checkout.sessions.create({
     mode: 'subscription',
     customer_email: user.email,
     line_items: [{ price: priceId, quantity: 1 }],
     success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
-    cancel_url: `${baseUrl}/cancel`,
+    cancel_url: `${baseUrl}/pricing`,
+    metadata: { userId: user.id }
+})
+
+return { url: session.url }
+```
+
+### Redirect to Checkout (React)
+
+```javascript
+const handleCheckout = async (priceId) => {
+    const response = await ky.post('/api/checkout', { json: { priceId } }).json()
+    window.location.href = response.url
+}
+```
+
+### Open Customer Portal
+
+```javascript
+// Backend: POST /api/portal
+const portal = await stripe.billingPortal.sessions.create({
+    customer: user.stripeCustomerId,
+    return_url: `${baseUrl}/account`
 })
+
+return { url: portal.url }
 ```
 
-### Webhook Handler
+### Handle Webhook
 
 ```javascript
-app.post('/webhook/stripe', async ({ request, set }) => {
+app.post('/webhook/stripe', async ({ request }) => {
     const sig = request.headers.get('stripe-signature')
     const body = await request.text()
 
-    const event = stripe.webhooks.constructEvent(
-        body,
-        sig,
-        process.env.STRIPE_WEBHOOK_SECRET
-    )
+    const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET)
 
     switch (event.type) {
         case 'checkout.session.completed':
@@ -89,9 +166,6 @@ app.post('/webhook/stripe', async ({ request, set }) => {
         case 'customer.subscription.updated':
             await handleSubscriptionUpdate(event.data.object)
             break
-        case 'customer.subscription.deleted':
-            await handleSubscriptionCancel(event.data.object)
-            break
     }
 
     return { received: true }
@@ -100,53 +174,47 @@ app.post('/webhook/stripe', async ({ request, set }) => {
 
 ---
 
-## 4. Essential Webhooks
-
-| Event | When to Handle |
-| --- | --- |
-| `checkout.session.completed` | Provision access after payment |
-| `customer.subscription.updated` | Plan changes, renewals |
-| `customer.subscription.deleted` | Cancellation |
-| `invoice.payment_failed` | Payment issues |
-| `invoice.paid` | Successful recurring payment |
-
----
-
-## 5. Customer Portal
-
-```javascript
-const portalSession = await stripe.billingPortal.sessions.create({
-    customer: customerId,
-    return_url: `${baseUrl}/account`,
-})
-```
-
----
-
-## 6. Security Checklist
+## Security Checklist
 
-- [ ] Verify webhook signatures
-- [ ] Use idempotency keys for retries
-- [ ] Store customer ID in database
-- [ ] Handle edge cases (expired cards, disputes)
-- [ ] Test with Stripe CLI locally
+- [ ] Webhook signatures verified with `constructEvent`
+- [ ] Secret key only in backend environment
+- [ ] Customer ID stored in database
+- [ ] Idempotency keys for create operations
+- [ ] Prices validated server-side (never trust frontend)
+- [ ] Subscription status checked before granting access
 
 ---
 
-## 7. Testing
+## Testing
 
 ```bash
 # Install Stripe CLI
 brew install stripe/stripe-cli/stripe
 
+# Login
+stripe login
+
 # Forward webhooks to local server
 stripe listen --forward-to localhost:3000/webhook/stripe
+
+# Trigger test events
+stripe trigger checkout.session.completed
 ```
 
+**Test Cards:**
+
+| Card | Scenario |
+| --- | --- |
+| `4242 4242 4242 4242` | Successful payment |
+| `4000 0000 0000 3220` | 3D Secure required |
+| `4000 0000 0000 9995` | Declined |
+
 ---
 
 ## Related Skills
 
 - @[.agent/skills/riligar-dev-backend]
+- @[.agent/skills/riligar-dev-frontend]
 - @[.agent/skills/riligar-dev-auth-elysia]
+- @[.agent/skills/riligar-dev-auth-react]
 - @[.agent/skills/riligar-tech-stack]