@riligar/agents-kit 1.12.0 → 1.14.0

package/.agent/skills/riligar-dev-stripe/references/stripe-react.md

@@ -0,0 +1,478 @@
+# Stripe Frontend Patterns (React)
+
+Complete patterns for Stripe integration in React applications with Mantine UI.
+
+## Setup
+
+### Stripe Provider
+
+```javascript
+// main.jsx
+import { loadStripe } from '@stripe/stripe-js'
+import { Elements } from '@stripe/react-stripe-js'
+
+const stripePromise = loadStripe(import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY)
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+    <Elements stripe={stripePromise}>
+        <App />
+    </Elements>
+)
+```
+
+### Stripe Configuration
+
+```javascript
+// services/stripe.js
+import { loadStripe } from '@stripe/stripe-js'
+
+export const stripePromise = loadStripe(import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY)
+
+// Elements appearance (matches Mantine theme)
+export const elementsAppearance = {
+    theme: 'stripe',
+    variables: {
+        colorPrimary: '#228be6',
+        colorBackground: '#ffffff',
+        colorText: '#1a1b1e',
+        colorDanger: '#fa5252',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        borderRadius: '4px',
+    },
+}
+```
+
+## Hosted Checkout (Recommended)
+
+### Pricing Page
+
+```javascript
+// pages/Pricing.jsx
+import { Button, Card, Group, Stack, Text, Title } from '@mantine/core'
+import { IconCheck } from '@tabler/icons-react'
+import { useState } from 'react'
+import ky from 'ky'
+
+const plans = [
+    {
+        name: 'Starter',
+        priceId: 'price_starter_monthly',
+        price: 'R$ 29',
+        features: ['5 projetos', 'Suporte email', '1GB storage']
+    },
+    {
+        name: 'Pro',
+        priceId: 'price_pro_monthly',
+        price: 'R$ 99',
+        features: ['Projetos ilimitados', 'Suporte prioritário', '10GB storage', 'API access']
+    }
+]
+
+export default function Pricing() {
+    const [loading, setLoading] = useState(null)
+
+    const handleCheckout = async (priceId) => {
+        setLoading(priceId)
+        try {
+            const { url } = await ky.post('/api/billing/checkout', {
+                json: { priceId, mode: 'subscription' }
+            }).json()
+
+            window.location.href = url
+        } catch (error) {
+            console.error('Checkout error:', error)
+        } finally {
+            setLoading(null)
+        }
+    }
+
+    return (
+        <Group gap="lg" justify="center">
+            {plans.map(plan => (
+                <Card key={plan.priceId} shadow="sm" padding="lg" radius="md" withBorder w={300}>
+                    <Stack>
+                        <Title order={3}>{plan.name}</Title>
+                        <Text size="xl" fw={700}>{plan.price}<Text span size="sm" c="dimmed">/mês</Text></Text>
+
+                        <Stack gap="xs">
+                            {plan.features.map(feature => (
+                                <Group key={feature} gap="xs">
+                                    <IconCheck size={16} color="green" />
+                                    <Text size="sm">{feature}</Text>
+                                </Group>
+                            ))}
+                        </Stack>
+
+                        <Button
+                            fullWidth
+                            loading={loading === plan.priceId}
+                            onClick={() => handleCheckout(plan.priceId)}
+                        >
+                            Assinar {plan.name}
+                        </Button>
+                    </Stack>
+                </Card>
+            ))}
+        </Group>
+    )
+}
+```
+
+### Success Page
+
+```javascript
+// pages/Success.jsx
+import { Button, Container, Stack, Text, Title } from '@mantine/core'
+import { IconCircleCheck } from '@tabler/icons-react'
+import { useEffect, useState } from 'react'
+import { useSearchParams, useNavigate } from 'react-router-dom'
+import ky from 'ky'
+
+export default function Success() {
+    const [searchParams] = useSearchParams()
+    const navigate = useNavigate()
+    const [session, setSession] = useState(null)
+
+    useEffect(() => {
+        const sessionId = searchParams.get('session_id')
+        if (sessionId) {
+            ky.get(`/api/billing/session/${sessionId}`).json()
+                .then(setSession)
+                .catch(console.error)
+        }
+    }, [searchParams])
+
+    return (
+        <Container size="sm" py="xl">
+            <Stack align="center" gap="md">
+                <IconCircleCheck size={64} color="green" />
+                <Title order={2}>Pagamento confirmado!</Title>
+                <Text c="dimmed">
+                    Obrigado por assinar. Seu acesso já está ativo.
+                </Text>
+                <Button onClick={() => navigate('/dashboard')}>
+                    Ir para o Dashboard
+                </Button>
+            </Stack>
+        </Container>
+    )
+}
+```
+
+## Customer Portal
+
+```javascript
+// components/BillingSettings.jsx
+import { Button, Card, Group, Stack, Text, Title, Badge } from '@mantine/core'
+import { useState, useEffect } from 'react'
+import ky from 'ky'
+
+export default function BillingSettings() {
+    const [subscription, setSubscription] = useState(null)
+    const [loading, setLoading] = useState(false)
+
+    useEffect(() => {
+        ky.get('/api/billing/subscription').json()
+            .then(setSubscription)
+            .catch(console.error)
+    }, [])
+
+    const openPortal = async () => {
+        setLoading(true)
+        try {
+            const { url } = await ky.post('/api/billing/portal').json()
+            window.location.href = url
+        } catch (error) {
+            console.error('Portal error:', error)
+        } finally {
+            setLoading(false)
+        }
+    }
+
+    const getStatusBadge = (status) => {
+        const colors = {
+            active: 'green',
+            trialing: 'blue',
+            past_due: 'yellow',
+            canceled: 'red',
+            none: 'gray'
+        }
+        return <Badge color={colors[status] || 'gray'}>{status}</Badge>
+    }
+
+    return (
+        <Card shadow="sm" padding="lg" radius="md" withBorder>
+            <Stack>
+                <Title order={4}>Assinatura</Title>
+
+                {subscription ? (
+                    <>
+                        <Group justify="space-between">
+                            <Text>Status</Text>
+                            {getStatusBadge(subscription.status)}
+                        </Group>
+
+                        {subscription.status !== 'none' && (
+                            <>
+                                <Group justify="space-between">
+                                    <Text>Plano</Text>
+                                    <Text fw={500}>{subscription.plan}</Text>
+                                </Group>
+
+                                {subscription.cancelAtPeriodEnd && (
+                                    <Text size="sm" c="orange">
+                                        Cancela em {new Date(subscription.currentPeriodEnd * 1000).toLocaleDateString()}
+                                    </Text>
+                                )}
+                            </>
+                        )}
+
+                        <Button variant="outline" onClick={openPortal} loading={loading}>
+                            Gerenciar Assinatura
+                        </Button>
+                    </>
+                ) : (
+                    <Text c="dimmed">Carregando...</Text>
+                )}
+            </Stack>
+        </Card>
+    )
+}
+```
+
+## Embedded Payment Form
+
+For custom payment forms (one-time payments):
+
+### Payment Form Component
+
+```javascript
+// components/PaymentForm.jsx
+import { Button, Stack, Text } from '@mantine/core'
+import { PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js'
+import { useState } from 'react'
+
+export default function PaymentForm({ onSuccess }) {
+    const stripe = useStripe()
+    const elements = useElements()
+    const [loading, setLoading] = useState(false)
+    const [error, setError] = useState(null)
+
+    const handleSubmit = async (e) => {
+        e.preventDefault()
+        if (!stripe || !elements) return
+
+        setLoading(true)
+        setError(null)
+
+        const { error: submitError, paymentIntent } = await stripe.confirmPayment({
+            elements,
+            confirmParams: {
+                return_url: `${window.location.origin}/payment/success`,
+            },
+            redirect: 'if_required'
+        })
+
+        if (submitError) {
+            setError(submitError.message)
+            setLoading(false)
+            return
+        }
+
+        if (paymentIntent?.status === 'succeeded') {
+            onSuccess?.(paymentIntent)
+        }
+
+        setLoading(false)
+    }
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <Stack>
+                <PaymentElement />
+
+                {error && <Text c="red" size="sm">{error}</Text>}
+
+                <Button type="submit" loading={loading} disabled={!stripe}>
+                    Pagar
+                </Button>
+            </Stack>
+        </form>
+    )
+}
+```
+
+### Using Payment Form
+
+```javascript
+// pages/Checkout.jsx
+import { Container, Card, Title, Text, Stack } from '@mantine/core'
+import { Elements } from '@stripe/react-stripe-js'
+import { useState, useEffect } from 'react'
+import { stripePromise, elementsAppearance } from '../services/stripe'
+import PaymentForm from '../components/PaymentForm'
+import ky from 'ky'
+
+export default function Checkout({ productId, amount }) {
+    const [clientSecret, setClientSecret] = useState(null)
+
+    useEffect(() => {
+        ky.post('/api/billing/payment/create', {
+            json: { productId, amount }
+        }).json()
+            .then(({ clientSecret }) => setClientSecret(clientSecret))
+            .catch(console.error)
+    }, [productId, amount])
+
+    if (!clientSecret) {
+        return <Text>Carregando...</Text>
+    }
+
+    return (
+        <Container size="sm">
+            <Card shadow="sm" padding="lg" radius="md" withBorder>
+                <Stack>
+                    <Title order={3}>Finalizar Compra</Title>
+                    <Text c="dimmed">Total: R$ {(amount / 100).toFixed(2)}</Text>
+
+                    <Elements
+                        stripe={stripePromise}
+                        options={{
+                            clientSecret,
+                            appearance: elementsAppearance
+                        }}
+                    >
+                        <PaymentForm onSuccess={() => console.log('Paid!')} />
+                    </Elements>
+                </Stack>
+            </Card>
+        </Container>
+    )
+}
+```
+
+## Subscription Hook
+
+```javascript
+// hooks/useSubscription.js
+import { useState, useEffect } from 'react'
+import ky from 'ky'
+
+export function useSubscription() {
+    const [subscription, setSubscription] = useState(null)
+    const [loading, setLoading] = useState(true)
+    const [error, setError] = useState(null)
+
+    const fetchSubscription = async () => {
+        setLoading(true)
+        try {
+            const data = await ky.get('/api/billing/subscription').json()
+            setSubscription(data)
+            setError(null)
+        } catch (err) {
+            setError(err)
+        } finally {
+            setLoading(false)
+        }
+    }
+
+    useEffect(() => {
+        fetchSubscription()
+    }, [])
+
+    const isActive = subscription?.status === 'active' || subscription?.status === 'trialing'
+    const isPro = isActive && subscription?.plan?.includes('pro')
+
+    return {
+        subscription,
+        loading,
+        error,
+        isActive,
+        isPro,
+        refresh: fetchSubscription
+    }
+}
+```
+
+### Using the Hook
+
+```javascript
+// components/PremiumFeature.jsx
+import { Alert } from '@mantine/core'
+import { useSubscription } from '../hooks/useSubscription'
+
+export default function PremiumFeature({ children }) {
+    const { isActive, loading } = useSubscription()
+
+    if (loading) return null
+
+    if (!isActive) {
+        return (
+            <Alert color="yellow" title="Recurso Premium">
+                Faça upgrade para acessar este recurso.
+            </Alert>
+        )
+    }
+
+    return children
+}
+```
+
+## Invoices List
+
+```javascript
+// components/InvoiceList.jsx
+import { Table, Badge, ActionIcon, Text } from '@mantine/core'
+import { IconDownload } from '@tabler/icons-react'
+import { useState, useEffect } from 'react'
+import ky from 'ky'
+
+export default function InvoiceList() {
+    const [invoices, setInvoices] = useState([])
+
+    useEffect(() => {
+        ky.get('/api/billing/invoices').json()
+            .then(({ data }) => setInvoices(data))
+            .catch(console.error)
+    }, [])
+
+    const getStatusBadge = (status) => {
+        const colors = { paid: 'green', open: 'blue', void: 'gray' }
+        return <Badge color={colors[status]}>{status}</Badge>
+    }
+
+    return (
+        <Table>
+            <Table.Thead>
+                <Table.Tr>
+                    <Table.Th>Data</Table.Th>
+                    <Table.Th>Valor</Table.Th>
+                    <Table.Th>Status</Table.Th>
+                    <Table.Th></Table.Th>
+                </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>
+                {invoices.map(invoice => (
+                    <Table.Tr key={invoice.id}>
+                        <Table.Td>{new Date(invoice.date * 1000).toLocaleDateString()}</Table.Td>
+                        <Table.Td>R$ {(invoice.amount / 100).toFixed(2)}</Table.Td>
+                        <Table.Td>{getStatusBadge(invoice.status)}</Table.Td>
+                        <Table.Td>
+                            {invoice.pdfUrl && (
+                                <ActionIcon
+                                    component="a"
+                                    href={invoice.pdfUrl}
+                                    target="_blank"
+                                    variant="subtle"
+                                >
+                                    <IconDownload size={16} />
+                                </ActionIcon>
+                            )}
+                        </Table.Td>
+                    </Table.Tr>
+                ))}
+            </Table.Tbody>
+        </Table>
+    )
+}
+```