@riligar/agents-kit 1.12.0 → 1.13.0

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

@@ -1,152 +1,257 @@
 ---
 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: 'Interactive Stripe setup wizard. Use when implementing payments. The agent will ask for keys, products, and configure everything automatically.'
 ---
 
-# Stripe Integration Patterns
+# Stripe Setup Wizard
 
-> Patterns for integrating Stripe payments in RiLiGar applications.
+Esta skill configura a integração completa do Stripe no seu projeto. O agente vai guiar você através de um setup interativo.
 
 ---
 
-## Mandatory Guidelines
+## Setup Workflow
 
-> [!IMPORTANT]
-> All work in this skill MUST adhere to:
+Quando o usuário solicitar configurar o Stripe, siga este fluxo **OBRIGATÓRIO**:
+
+### Step 1: Coletar Chaves
+
+Pergunte ao usuário:
+
+> Para configurar o Stripe, preciso das suas chaves da API.
+> Você pode encontrá-las em: https://dashboard.stripe.com/apikeys
 >
-> - @[.agent/skills/riligar-dev-backend] (API Standards)
-> - @[.agent/skills/riligar-dev-clean-code] (Clean Code Standards)
+> Por favor, me forneça:
+> 1. **Publishable Key** (pk_live_... ou pk_test_...)
+> 2. **Secret Key** (sk_live_... ou sk_test_...)
 
----
+Aguarde as chaves antes de prosseguir.
 
-## 1. Core Concepts
+### Step 2: Identificar Produtos
 
-| 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 |
+Após receber as chaves, pergunte:
 
----
+> Agora preciso entender seus produtos. Me diga:
+>
+> 1. **Tipo de cobrança**: Assinatura (recorrente) ou pagamento único?
+> 2. **Quais planos/produtos** você quer oferecer?
+>
+> Exemplo de resposta:
+> - Assinatura mensal
+> - Plano Starter: R$ 29/mês (5 projetos, suporte email)
+> - Plano Pro: R$ 99/mês (ilimitado, suporte prioritário)
+> - Plano Enterprise: R$ 299/mês (tudo + SLA)
 
-## 2. Environment Setup
+### Step 3: Criar Produtos no Stripe
 
-```bash
-# .env
-STRIPE_SECRET_KEY=sk_live_...
-STRIPE_WEBHOOK_SECRET=whsec_...
-STRIPE_PUBLISHABLE_KEY=pk_live_...
+Com as informações coletadas, gere o script para criar os produtos:
+
+```javascript
+// scripts/setup-stripe-products.js
+import Stripe from 'stripe'
+
+const stripe = new Stripe('SK_KEY_AQUI')
+
+async function setupProducts() {
+    const products = [
+        // Substituir com os produtos do usuário
+        {
+            name: 'Plano Starter',
+            description: '5 projetos, suporte email',
+            price: 2900,  // R$ 29,00 em centavos
+            interval: 'month',
+            features: ['5 projetos', 'Suporte email', '1GB storage']
+        },
+        {
+            name: 'Plano Pro',
+            description: 'Ilimitado, suporte prioritário',
+            price: 9900,  // R$ 99,00 em centavos
+            interval: 'month',
+            features: ['Projetos ilimitados', 'Suporte prioritário', '10GB storage']
+        }
+    ]
+
+    console.log('Criando produtos no Stripe...\n')
+
+    for (const product of products) {
+        const stripeProduct = await stripe.products.create({
+            name: product.name,
+            description: product.description,
+            metadata: { features: JSON.stringify(product.features) }
+        })
+
+        const stripePrice = await stripe.prices.create({
+            product: stripeProduct.id,
+            unit_amount: product.price,
+            currency: 'brl',
+            recurring: product.interval ? { interval: product.interval } : undefined
+        })
+
+        console.log(`✓ ${product.name}`)
+        console.log(`  Product ID: ${stripeProduct.id}`)
+        console.log(`  Price ID: ${stripePrice.id}\n`)
+    }
+
+    console.log('Produtos criados com sucesso!')
+}
+
+setupProducts().catch(console.error)
 ```
 
-> [!IMPORTANT]
-> Never expose `STRIPE_SECRET_KEY` in frontend code.
+Instrua o usuário a executar: `bun run scripts/setup-stripe-products.js`
 
----
+### Step 4: Coletar Price IDs
 
-## 3. Server-Side Patterns (Elysia)
+Após executar o script, peça:
 
-### Initialize Stripe
+> O script gerou os Price IDs. Por favor, me envie os IDs gerados.
+> Exemplo: price_1ABC123...
 
-```javascript
-import Stripe from 'stripe'
+### Step 5: Configurar Ambiente
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
+Com as chaves e Price IDs, configure os arquivos de ambiente:
+
+**Backend: `.env.development` e `.env.production`**
+```bash
+# .env.development (chaves de teste)
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# .env.production (chaves de produção)
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
 ```
 
-### Create Checkout Session
+**Frontend: `.env.development` e `.env.production`**
+```bash
+# .env.development
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
 
-```javascript
-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`,
-})
+# .env.production
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
 ```
 
-### Webhook Handler
+### Step 6: Configurar Database
 
-```javascript
-app.post('/webhook/stripe', async ({ request, set }) => {
-    const sig = request.headers.get('stripe-signature')
-    const body = await request.text()
-
-    const event = stripe.webhooks.constructEvent(
-        body,
-        sig,
-        process.env.STRIPE_WEBHOOK_SECRET
-    )
-
-    switch (event.type) {
-        case 'checkout.session.completed':
-            await handleCheckoutComplete(event.data.object)
-            break
-        case 'customer.subscription.updated':
-            await handleSubscriptionUpdate(event.data.object)
-            break
-        case 'customer.subscription.deleted':
-            await handleSubscriptionCancel(event.data.object)
-            break
-    }
+Gere a migration para adicionar campos do Stripe:
 
-    return { received: true }
-})
+```javascript
+// database/schema.js - adicionar aos users
+stripeCustomerId: text('stripe_customer_id').unique(),
+stripeSubscriptionId: text('stripe_subscription_id').unique(),
+plan: text('plan').default('free'),
+subscriptionStatus: text('subscription_status'),
+currentPeriodEnd: integer('current_period_end', { mode: 'timestamp' }),
 ```
 
----
+### Step 7: Configurar Webhook
 
-## 4. Essential Webhooks
+Instrua o usuário:
 
-| Event | When to Handle |
+> Configure o webhook no Stripe Dashboard:
+>
+> 1. Acesse https://dashboard.stripe.com/webhooks
+> 2. Clique em "Add endpoint"
+> 3. URL: `https://seu-dominio.com/webhook/stripe`
+> 4. Selecione os eventos:
+>    - `checkout.session.completed`
+>    - `customer.subscription.updated`
+>    - `customer.subscription.deleted`
+>    - `invoice.paid`
+>    - `invoice.payment_failed`
+> 5. Copie o "Signing secret" (whsec_...)
+> 6. Adicione ao `.env.development` e `.env.production`
+
+### Step 8: Gerar Código
+
+Gere todos os arquivos necessários usando os templates de [assets/](assets/):
+
+| Arquivo | Baseado em |
 | --- | --- |
-| `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 |
+| `plugins/stripe.js` | stripe-server.js (seção 1) |
+| `routes/billing.js` | stripe-server.js (seção 2) |
+| `routes/webhook.js` | stripe-server.js (seção 3) |
+| `services/billing.js` | stripe-server.js (seção 4) |
+| `config/stripe-prices.js` | Price IDs coletados |
+| `pages/Pricing.jsx` | stripe-client.js (seção 3) |
+| `components/BillingSettings.jsx` | stripe-client.js (seção 4) |
+| `hooks/useSubscription.js` | stripe-client.js (seção 2) |
 
----
+### Step 9: Criar Config de Preços
 
-## 5. Customer Portal
+Gere o arquivo de configuração com os Price IDs:
 
 ```javascript
-const portalSession = await stripe.billingPortal.sessions.create({
-    customer: customerId,
-    return_url: `${baseUrl}/account`,
-})
+// config/stripe-prices.js
+export const STRIPE_PRICES = {
+    starter: {
+        priceId: 'price_COLETADO_STARTER',
+        name: 'Starter',
+        price: 29,
+        features: ['5 projetos', 'Suporte email', '1GB storage']
+    },
+    pro: {
+        priceId: 'price_COLETADO_PRO',
+        name: 'Pro',
+        price: 99,
+        features: ['Projetos ilimitados', 'Suporte prioritário', '10GB storage']
+    }
+}
+
+export const getPrice = (plan) => STRIPE_PRICES[plan]
+export const getPriceId = (plan) => STRIPE_PRICES[plan]?.priceId
 ```
 
 ---
 
-## 6. Security Checklist
+## Checklist Final
 
-- [ ] Verify webhook signatures
-- [ ] Use idempotency keys for retries
-- [ ] Store customer ID in database
-- [ ] Handle edge cases (expired cards, disputes)
-- [ ] Test with Stripe CLI locally
+Ao completar o setup, confirme:
+
+- [ ] Dependências instaladas (`bun add stripe @stripe/stripe-js @stripe/react-stripe-js`)
+- [ ] Chaves no `.env.development` e `.env.production` (backend e frontend)
+- [ ] Produtos criados no Stripe
+- [ ] Price IDs configurados em `config/stripe-prices.js`
+- [ ] Schema do database atualizado
+- [ ] Webhook endpoint configurado no Stripe Dashboard
+- [ ] Webhook secret nos arquivos de ambiente
+- [ ] Rotas de billing funcionando
+- [ ] Página de pricing criada
+- [ ] Testado com cartão 4242 4242 4242 4242
 
 ---
 
-## 7. Testing
+## Testing Local
 
 ```bash
-# Install Stripe CLI
+# Instalar Stripe CLI
 brew install stripe/stripe-cli/stripe
 
-# Forward webhooks to local server
+# Login
+stripe login
+
+# Forward webhooks
 stripe listen --forward-to localhost:3000/webhook/stripe
+
+# Testar checkout
+stripe trigger checkout.session.completed
 ```
 
 ---
 
+## Specialized Guides
+
+| Guide | Content |
+| --- | --- |
+| [stripe-elysia.md](references/stripe-elysia.md) | Backend routes completas |
+| [stripe-react.md](references/stripe-react.md) | Componentes React/Mantine |
+| [stripe-webhooks.md](references/stripe-webhooks.md) | Handlers de eventos |
+| [stripe-database.md](references/stripe-database.md) | Schema Drizzle |
+
+---
+
 ## Related Skills
 
 - @[.agent/skills/riligar-dev-backend]
+- @[.agent/skills/riligar-dev-frontend]
 - @[.agent/skills/riligar-dev-auth-elysia]
 - @[.agent/skills/riligar-tech-stack]