@riligar/agents-kit 1.12.0 → 1.14.0

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

@@ -0,0 +1,376 @@
+# Stripe Webhooks
+
+Complete patterns for handling Stripe webhook events in Elysia.
+
+## Webhook Endpoint
+
+```javascript
+// routes/webhook.js
+import { Elysia } from 'elysia'
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
+
+export const webhookRoutes = new Elysia()
+    .post('/webhook/stripe', async ({ request, set }) => {
+        const sig = request.headers.get('stripe-signature')
+        const body = await request.text()
+
+        let event
+
+        try {
+            event = stripe.webhooks.constructEvent(
+                body,
+                sig,
+                process.env.STRIPE_WEBHOOK_SECRET
+            )
+        } catch (err) {
+            console.error('Webhook signature verification failed:', err.message)
+            set.status = 400
+            return { error: 'Invalid signature' }
+        }
+
+        // Handle the event
+        try {
+            await handleWebhookEvent(event)
+        } catch (err) {
+            console.error('Webhook handler error:', err)
+            set.status = 500
+            return { error: 'Webhook handler failed' }
+        }
+
+        return { received: true }
+    })
+```
+
+## Essential Events
+
+| Event | When | Action |
+| --- | --- | --- |
+| `checkout.session.completed` | User completes checkout | Provision access, create records |
+| `customer.subscription.created` | New subscription | Store subscription ID |
+| `customer.subscription.updated` | Plan change, renewal | Update plan/status |
+| `customer.subscription.deleted` | Subscription ends | Revoke access |
+| `invoice.paid` | Successful payment | Update billing history |
+| `invoice.payment_failed` | Payment failed | Notify user, retry logic |
+| `customer.created` | New customer | Store customer ID |
+
+## Event Handler
+
+```javascript
+// services/webhook-handlers.js
+import { db } from '../database'
+import { users, subscriptions } from '../database/schema'
+import { eq } from 'drizzle-orm'
+
+export async function handleWebhookEvent(event) {
+    switch (event.type) {
+        case 'checkout.session.completed':
+            await handleCheckoutComplete(event.data.object)
+            break
+
+        case 'customer.subscription.created':
+        case 'customer.subscription.updated':
+            await handleSubscriptionChange(event.data.object)
+            break
+
+        case 'customer.subscription.deleted':
+            await handleSubscriptionDeleted(event.data.object)
+            break
+
+        case 'invoice.paid':
+            await handleInvoicePaid(event.data.object)
+            break
+
+        case 'invoice.payment_failed':
+            await handlePaymentFailed(event.data.object)
+            break
+
+        default:
+            console.log(`Unhandled event type: ${event.type}`)
+    }
+}
+```
+
+## Handler Functions
+
+### Checkout Complete
+
+```javascript
+async function handleCheckoutComplete(session) {
+    const { customer, subscription, metadata } = session
+    const userId = metadata.userId
+
+    // Update user with Stripe IDs
+    await db.update(users)
+        .set({
+            stripeCustomerId: customer,
+            stripeSubscriptionId: subscription,
+            plan: 'pro',  // or extract from session
+            updatedAt: new Date()
+        })
+        .where(eq(users.id, userId))
+
+    // Optional: send welcome email
+    // await sendWelcomeEmail(userId)
+
+    console.log(`Checkout completed for user ${userId}`)
+}
+```
+
+### Subscription Change
+
+```javascript
+async function handleSubscriptionChange(subscription) {
+    const { id, status, items, current_period_end, cancel_at_period_end } = subscription
+    const priceId = items.data[0].price.id
+
+    // Find user by subscription ID
+    const [user] = await db.select()
+        .from(users)
+        .where(eq(users.stripeSubscriptionId, id))
+        .limit(1)
+
+    if (!user) {
+        console.error(`No user found for subscription ${id}`)
+        return
+    }
+
+    // Map price ID to plan name
+    const planMap = {
+        'price_starter_monthly': 'starter',
+        'price_pro_monthly': 'pro',
+        'price_enterprise_monthly': 'enterprise'
+    }
+
+    await db.update(users)
+        .set({
+            plan: planMap[priceId] || 'free',
+            subscriptionStatus: status,
+            currentPeriodEnd: new Date(current_period_end * 1000),
+            cancelAtPeriodEnd: cancel_at_period_end,
+            updatedAt: new Date()
+        })
+        .where(eq(users.id, user.id))
+
+    console.log(`Subscription ${id} updated to ${status}`)
+}
+```
+
+### Subscription Deleted
+
+```javascript
+async function handleSubscriptionDeleted(subscription) {
+    const { id } = subscription
+
+    await db.update(users)
+        .set({
+            plan: 'free',
+            subscriptionStatus: 'canceled',
+            stripeSubscriptionId: null,
+            updatedAt: new Date()
+        })
+        .where(eq(users.stripeSubscriptionId, id))
+
+    console.log(`Subscription ${id} deleted`)
+}
+```
+
+### Invoice Paid
+
+```javascript
+async function handleInvoicePaid(invoice) {
+    const { customer, amount_paid, id, hosted_invoice_url } = invoice
+
+    // Find user by customer ID
+    const [user] = await db.select()
+        .from(users)
+        .where(eq(users.stripeCustomerId, customer))
+        .limit(1)
+
+    if (!user) return
+
+    // Store invoice record (optional)
+    await db.insert(invoices).values({
+        userId: user.id,
+        stripeInvoiceId: id,
+        amount: amount_paid,
+        status: 'paid',
+        url: hosted_invoice_url,
+        createdAt: new Date()
+    })
+
+    console.log(`Invoice ${id} paid: ${amount_paid}`)
+}
+```
+
+### Payment Failed
+
+```javascript
+async function handlePaymentFailed(invoice) {
+    const { customer, attempt_count, next_payment_attempt } = invoice
+
+    const [user] = await db.select()
+        .from(users)
+        .where(eq(users.stripeCustomerId, customer))
+        .limit(1)
+
+    if (!user) return
+
+    // Update subscription status
+    await db.update(users)
+        .set({
+            subscriptionStatus: 'past_due',
+            updatedAt: new Date()
+        })
+        .where(eq(users.id, user.id))
+
+    // Send notification
+    // await sendPaymentFailedEmail(user.email, {
+    //     attemptCount: attempt_count,
+    //     nextAttempt: next_payment_attempt
+    // })
+
+    console.log(`Payment failed for customer ${customer}, attempt ${attempt_count}`)
+}
+```
+
+## Idempotency
+
+Webhooks may be sent multiple times. Handle idempotency:
+
+```javascript
+async function handleCheckoutComplete(session) {
+    const { id, metadata } = session
+    const userId = metadata.userId
+
+    // Check if already processed
+    const [existing] = await db.select()
+        .from(webhookEvents)
+        .where(eq(webhookEvents.stripeEventId, id))
+        .limit(1)
+
+    if (existing) {
+        console.log(`Event ${id} already processed`)
+        return
+    }
+
+    // Record event
+    await db.insert(webhookEvents).values({
+        stripeEventId: id,
+        type: 'checkout.session.completed',
+        processedAt: new Date()
+    })
+
+    // Process the event
+    await db.update(users)
+        .set({
+            stripeCustomerId: session.customer,
+            stripeSubscriptionId: session.subscription,
+            plan: 'pro'
+        })
+        .where(eq(users.id, userId))
+}
+```
+
+## Testing Locally
+
+```bash
+# Install Stripe CLI
+brew install stripe/stripe-cli/stripe
+
+# Login to Stripe
+stripe login
+
+# Forward webhooks to local server
+stripe listen --forward-to localhost:3000/webhook/stripe
+
+# Copy the webhook signing secret (whsec_...) to .env.development
+
+# Trigger specific events
+stripe trigger checkout.session.completed
+stripe trigger customer.subscription.updated
+stripe trigger invoice.payment_failed
+```
+
+## Webhook Event Types Reference
+
+### Checkout Events
+
+| Event | Data Object |
+| --- | --- |
+| `checkout.session.completed` | Session with customer, subscription, metadata |
+| `checkout.session.expired` | Session that expired |
+
+### Subscription Events
+
+| Event | Data Object |
+| --- | --- |
+| `customer.subscription.created` | Full subscription object |
+| `customer.subscription.updated` | Full subscription with changes |
+| `customer.subscription.deleted` | Subscription being canceled |
+| `customer.subscription.trial_will_end` | 3 days before trial ends |
+
+### Invoice Events
+
+| Event | Data Object |
+| --- | --- |
+| `invoice.paid` | Invoice with payment details |
+| `invoice.payment_failed` | Invoice with failure reason |
+| `invoice.upcoming` | Preview of next invoice |
+| `invoice.finalized` | Invoice ready for payment |
+
+### Payment Events
+
+| Event | Data Object |
+| --- | --- |
+| `payment_intent.succeeded` | PaymentIntent completed |
+| `payment_intent.payment_failed` | PaymentIntent failed |
+
+## Error Handling
+
+```javascript
+export const webhookRoutes = new Elysia()
+    .post('/webhook/stripe', async ({ request, set }) => {
+        const sig = request.headers.get('stripe-signature')
+        const body = await request.text()
+
+        let event
+
+        // Verify signature
+        try {
+            event = stripe.webhooks.constructEvent(
+                body,
+                sig,
+                process.env.STRIPE_WEBHOOK_SECRET
+            )
+        } catch (err) {
+            console.error('Invalid signature:', err.message)
+            set.status = 400
+            return { error: 'Invalid signature' }
+        }
+
+        // Handle event with error catching
+        try {
+            await handleWebhookEvent(event)
+            return { received: true }
+        } catch (err) {
+            console.error('Handler error:', err)
+
+            // Return 200 to prevent Stripe retries for permanent failures
+            // Return 500 to trigger Stripe retry for temporary failures
+            if (isPermanentFailure(err)) {
+                console.error('Permanent failure, not retrying')
+                return { received: true, error: err.message }
+            }
+
+            set.status = 500
+            return { error: 'Internal error' }
+        }
+    })
+
+function isPermanentFailure(err) {
+    // User not found, invalid data, etc.
+    return err.code === 'USER_NOT_FOUND' || err.code === 'INVALID_DATA'
+}
+```

package/.agent/skills/riligar-infrastructure/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-infrastructure
-type: infrastructure
 description: Especialista em Infraestrutura da RiLiGar. Use para configurar deployments no Fly.io, DNS e proxying no Cloudflare, e garantir padrões de infraestrutura e deployment.
 ---
 

package/.agent/skills/riligar-marketing-copy/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-marketing-copy
-type: marketing
 description: Generate compelling marketing copy using the Elevated Direct Response framework. Use when creating landing pages, headlines, email campaigns, ad copy, CTAs, value propositions, or any persuasive marketing content.
 ---
 

package/.agent/skills/riligar-marketing-email/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-marketing-email
-type: marketing
 description: Email sequence design and optimization. Use when creating drip campaigns, automated flows, nurture sequences, onboarding emails, welcome sequences, re-engagement emails, or lifecycle email programs.
 ---
 

package/.agent/skills/riligar-marketing-seo/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-marketing-seo
-type: marketing
 description: Design and evaluate programmatic SEO strategies for creating SEO-driven pages at scale. Use when working with programmatic SEO, template pages, directory pages, location pages, or keyword-pattern page generation.
 ---
 

package/.agent/skills/riligar-plan-writing/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-plan-writing
-type: development
 description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
 ---
 

package/.agent/skills/riligar-tech-stack/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: riligar-tech-stack
-type: development
 description: Especialista na Tech Stack da RiLiGar. Use para criar projetos React/Vite, componentes com Mantine, APIs Bun/Elysia, e garantir padrões de código e estrutura de projetos.
 ---
 

package/.agent/skills/skill-creator/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: skill-creator
-type: meta
 description: Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 ---
 
@@ -337,7 +336,6 @@ Write the YAML frontmatter with `name`, `type`, and `description`:
 ```yaml
 ---
 name: riligar-dev-example
-type: development
 description: Brief description of what the skill does. Use when [specific triggers].
 ---
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@riligar/agents-kit",
-    "version": "1.12.0",
+    "version": "1.14.0",
     "publishConfig": {
         "access": "public"
     },