recur-skills 0.0.1

package/skills/recur-quickstart/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: recur-quickstart
+description: Quick setup guide for Recur payment integration. Use when starting a new Recur integration, setting up API keys, installing the SDK, or when user mentions "integrate Recur", "setup Recur", "Recur 串接", "金流設定".
+---
+
+# Recur Quickstart
+
+You are helping a developer integrate Recur, Taiwan's subscription payment platform (similar to Stripe Billing).
+
+## Step 1: Install SDK
+
+```bash
+pnpm add recur-tw
+# or
+npm install recur-tw
+```
+
+## Step 2: Get API Keys
+
+API keys are available in the Recur dashboard at `app.recur.tw` → Settings → Developers.
+
+**Key formats:**
+- `pk_test_xxx` - Publishable key (frontend, safe to expose)
+- `sk_test_xxx` - Secret key (backend only, never expose)
+- `pk_live_xxx` / `sk_live_xxx` - Production keys
+
+**Environment variables to set:**
+```bash
+RECUR_PUBLISHABLE_KEY=pk_test_xxx
+RECUR_SECRET_KEY=sk_test_xxx
+```
+
+## Step 3: Add Provider (React)
+
+Wrap your app with `RecurProvider`:
+
+```tsx
+import { RecurProvider } from 'recur-tw'
+
+export default function App({ children }) {
+  return (
+    <RecurProvider
+      config={{
+        publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY,
+      }}
+    >
+      {children}
+    </RecurProvider>
+  )
+}
+```
+
+## Step 4: Create Your First Checkout
+
+```tsx
+import { useRecur } from 'recur-tw'
+
+function PricingButton({ productId }: { productId: string }) {
+  const { checkout } = useRecur()
+
+  const handleCheckout = async () => {
+    await checkout({
+      productId,
+      onPaymentComplete: (subscription) => {
+        console.log('Payment successful!', subscription)
+      },
+      onPaymentFailed: (error) => {
+        console.error('Payment failed:', error)
+      },
+    })
+  }
+
+  return <button onClick={handleCheckout}>Subscribe</button>
+}
+```
+
+## Step 5: Set Up Webhooks
+
+Create a webhook endpoint to receive payment notifications. See the `recur-webhooks` skill for detailed instructions.
+
+## Quick Verification Checklist
+
+- [ ] SDK installed (`pnpm list recur-tw`)
+- [ ] Environment variables set
+- [ ] RecurProvider wrapping app
+- [ ] Test checkout works in sandbox
+- [ ] Webhook endpoint configured
+
+## Common Issues
+
+### "Invalid API key"
+- Check key format: must start with `pk_test_`, `sk_test_`, `pk_live_`, or `sk_live_`
+- Ensure using publishable key for frontend, secret key for backend
+
+### "Product not found"
+- Verify product exists in Recur dashboard
+- Check you're using correct environment (sandbox vs production)
+
+### Checkout not appearing
+- Ensure `RecurProvider` wraps your app
+- Check browser console for errors
+- Verify publishable key is correct
+
+## Next Steps
+
+- `/recur-checkout` - Learn checkout flow options
+- `/recur-webhooks` - Set up payment notifications
+- `/recur-entitlements` - Implement access control
+
+## Resources
+
+- [Recur Documentation](https://recur.tw/docs)
+- [SDK on npm](https://www.npmjs.com/package/recur-tw)
+- [API Reference](https://recur.tw/docs/api)

package/skills/recur-quickstart/scripts/check-env.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Check Recur environment setup
+
+echo "🔍 Checking Recur environment..."
+echo ""
+
+# Check for recur-tw package
+if [ -f "package.json" ]; then
+  if grep -q '"recur-tw"' package.json; then
+    VERSION=$(grep '"recur-tw"' package.json | head -1 | sed 's/.*: "\(.*\)".*/\1/')
+    echo "✅ recur-tw installed: $VERSION"
+  else
+    echo "❌ recur-tw not found in package.json"
+    echo "   Run: pnpm add recur-tw"
+  fi
+else
+  echo "⚠️  No package.json found in current directory"
+fi
+
+echo ""
+
+# Check environment variables
+check_env() {
+  local var_name=$1
+  local var_value=$(printenv "$var_name")
+
+  if [ -n "$var_value" ]; then
+    # Mask the value, show first 12 chars
+    local masked="${var_value:0:12}..."
+    echo "✅ $var_name: $masked"
+  else
+    echo "❌ $var_name: not set"
+  fi
+}
+
+echo "Environment Variables:"
+check_env "RECUR_PUBLISHABLE_KEY"
+check_env "NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY"
+check_env "RECUR_SECRET_KEY"
+check_env "RECUR_WEBHOOK_SECRET"
+
+echo ""
+
+# Check .env files
+echo "Configuration Files:"
+for file in .env .env.local .env.development .env.production; do
+  if [ -f "$file" ]; then
+    if grep -q "RECUR" "$file"; then
+      echo "✅ $file contains RECUR variables"
+    else
+      echo "⚠️  $file exists but no RECUR variables"
+    fi
+  fi
+done
+
+echo ""
+echo "Done! 🎉"

package/skills/recur-webhooks/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: recur-webhooks
+description: Set up and handle Recur webhook events for payment notifications. Use when implementing webhook handlers, verifying signatures, handling subscription events, or when user mentions "webhook", "付款通知", "訂閱事件", "payment notification".
+---
+
+# Recur Webhook Integration
+
+You are helping implement Recur webhooks to receive real-time payment and subscription events.
+
+## Webhook Events
+
+### Core Events (Most Common)
+
+| Event | When Fired |
+|-------|------------|
+| `checkout.completed` | Payment successful, subscription/order created |
+| `subscription.activated` | Subscription is now active |
+| `subscription.cancelled` | Subscription was cancelled |
+| `subscription.renewed` | Recurring payment successful |
+| `subscription.past_due` | Payment failed, subscription at risk |
+| `order.paid` | One-time purchase completed |
+| `refund.created` | Refund initiated |
+
+### All Supported Events
+
+```typescript
+type WebhookEventType =
+  // Checkout
+  | 'checkout.created'
+  | 'checkout.completed'
+  // Orders
+  | 'order.paid'
+  | 'order.payment_failed'
+  // Subscription Lifecycle
+  | 'subscription.created'
+  | 'subscription.activated'
+  | 'subscription.cancelled'
+  | 'subscription.expired'
+  | 'subscription.trial_ending'
+  // Subscription Changes
+  | 'subscription.upgraded'
+  | 'subscription.downgraded'
+  | 'subscription.renewed'
+  | 'subscription.past_due'
+  // Scheduled Changes
+  | 'subscription.schedule_created'
+  | 'subscription.schedule_executed'
+  | 'subscription.schedule_cancelled'
+  // Invoices
+  | 'invoice.created'
+  | 'invoice.paid'
+  | 'invoice.payment_failed'
+  // Customer
+  | 'customer.created'
+  | 'customer.updated'
+  // Product
+  | 'product.created'
+  | 'product.updated'
+  // Refunds
+  | 'refund.created'
+  | 'refund.succeeded'
+  | 'refund.failed'
+```
+
+## Webhook Handler Implementation
+
+### Next.js App Router
+
+```typescript
+// app/api/webhooks/recur/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import crypto from 'crypto'
+
+const WEBHOOK_SECRET = process.env.RECUR_WEBHOOK_SECRET!
+
+function verifySignature(payload: string, signature: string): boolean {
+  const expected = crypto
+    .createHmac('sha256', WEBHOOK_SECRET)
+    .update(payload)
+    .digest('hex')
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  )
+}
+
+export async function POST(request: NextRequest) {
+  const payload = await request.text()
+  const signature = request.headers.get('x-recur-signature')
+
+  // Verify signature
+  if (!signature || !verifySignature(payload, signature)) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
+  }
+
+  const event = JSON.parse(payload)
+
+  // Handle events
+  switch (event.type) {
+    case 'checkout.completed':
+      await handleCheckoutCompleted(event.data)
+      break
+
+    case 'subscription.activated':
+      await handleSubscriptionActivated(event.data)
+      break
+
+    case 'subscription.cancelled':
+      await handleSubscriptionCancelled(event.data)
+      break
+
+    case 'subscription.renewed':
+      await handleSubscriptionRenewed(event.data)
+      break
+
+    case 'subscription.past_due':
+      await handleSubscriptionPastDue(event.data)
+      break
+
+    case 'refund.created':
+      await handleRefundCreated(event.data)
+      break
+
+    default:
+      console.log(`Unhandled event type: ${event.type}`)
+  }
+
+  return NextResponse.json({ received: true })
+}
+
+// Event handlers
+async function handleCheckoutCompleted(data: any) {
+  const { customerId, subscriptionId, orderId, productId, amount } = data
+
+  // Update your database
+  // Grant access to the user
+  // Send confirmation email
+}
+
+async function handleSubscriptionActivated(data: any) {
+  const { subscriptionId, customerId, productId, status } = data
+
+  // Update user's subscription status in your database
+  // Enable premium features
+}
+
+async function handleSubscriptionCancelled(data: any) {
+  const { subscriptionId, customerId, cancelledAt, accessUntil } = data
+
+  // Mark subscription as cancelled
+  // User still has access until accessUntil date
+  // Send cancellation confirmation email
+}
+
+async function handleSubscriptionRenewed(data: any) {
+  const { subscriptionId, customerId, amount, nextBillingDate } = data
+
+  // Update billing records
+  // Extend access period
+}
+
+async function handleSubscriptionPastDue(data: any) {
+  const { subscriptionId, customerId, failureReason } = data
+
+  // Notify user of payment failure
+  // Consider sending dunning emails
+  // May want to restrict access after grace period
+}
+
+async function handleRefundCreated(data: any) {
+  const { refundId, orderId, amount, reason } = data
+
+  // Update order status
+  // Adjust user credits/access
+  // Send refund notification
+}
+```
+
+### Express.js
+
+```typescript
+import express from 'express'
+import crypto from 'crypto'
+
+const app = express()
+
+// Important: Use raw body for signature verification
+app.post(
+  '/api/webhooks/recur',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const payload = req.body.toString()
+    const signature = req.headers['x-recur-signature'] as string
+
+    // Verify signature
+    const expected = crypto
+      .createHmac('sha256', process.env.RECUR_WEBHOOK_SECRET!)
+      .update(payload)
+      .digest('hex')
+
+    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+      return res.status(401).json({ error: 'Invalid signature' })
+    }
+
+    const event = JSON.parse(payload)
+
+    // Handle event...
+    console.log('Received event:', event.type)
+
+    res.json({ received: true })
+  }
+)
+```
+
+## Event Payload Structure
+
+```typescript
+interface WebhookEvent {
+  id: string           // Event ID (for idempotency)
+  type: string         // Event type
+  timestamp: string    // ISO 8601 timestamp
+  data: {
+    // Varies by event type
+    customerId?: string
+    customerEmail?: string
+    subscriptionId?: string
+    orderId?: string
+    productId?: string
+    amount?: number
+    currency?: string
+    // ... more fields depending on event
+  }
+}
+```
+
+## Webhook Configuration
+
+1. Go to **Recur Dashboard** → **Settings** → **Webhooks**
+2. Click **Add Endpoint**
+3. Enter your endpoint URL (e.g., `https://yourapp.com/api/webhooks/recur`)
+4. Select events to receive
+5. Copy the **Webhook Secret** to your environment variables
+
+## Testing Webhooks Locally
+
+### Using ngrok
+
+```bash
+# Start ngrok tunnel
+ngrok http 3000
+
+# Use the ngrok URL in Recur dashboard
+# https://xxxx.ngrok.io/api/webhooks/recur
+```
+
+### Using Recur CLI (if available)
+
+```bash
+# Forward webhooks to local server
+recur webhooks forward --to localhost:3000/api/webhooks/recur
+```
+
+## Best Practices
+
+### 1. Always Verify Signatures
+
+Never trust webhook payloads without verifying the signature.
+
+### 2. Handle Idempotency
+
+Webhooks may be delivered multiple times. Use the event `id` to deduplicate:
+
+```typescript
+async function handleEvent(event: WebhookEvent) {
+  // Check if already processed
+  const existing = await db.webhookEvent.findUnique({
+    where: { eventId: event.id }
+  })
+
+  if (existing) {
+    console.log('Event already processed:', event.id)
+    return
+  }
+
+  // Process event...
+
+  // Mark as processed
+  await db.webhookEvent.create({
+    data: { eventId: event.id, processedAt: new Date() }
+  })
+}
+```
+
+### 3. Return 200 Quickly
+
+Process events asynchronously to avoid timeouts:
+
+```typescript
+export async function POST(request: NextRequest) {
+  // Verify and parse...
+
+  // Queue for async processing
+  await queue.add('process-webhook', event)
+
+  // Return immediately
+  return NextResponse.json({ received: true })
+}
+```
+
+### 4. Handle Retries Gracefully
+
+Recur retries failed webhook deliveries. Ensure your handler is idempotent.
+
+### 5. Log Everything
+
+```typescript
+console.log('Webhook received:', {
+  type: event.type,
+  id: event.id,
+  timestamp: event.timestamp,
+})
+```
+
+## Debugging Webhooks
+
+### Check Webhook Logs
+
+In Recur Dashboard → Webhooks → Click endpoint → View delivery logs
+
+### Common Issues
+
+**401 Unauthorized**
+- Check webhook secret is correct
+- Ensure using raw body for signature verification
+- Verify signature algorithm (HMAC SHA-256)
+
+**Timeout (no response)**
+- Return 200 before processing
+- Use async processing for heavy operations
+
+**Missing events**
+- Check event types are selected in dashboard
+- Verify endpoint URL is correct and accessible
+
+## Related Skills
+
+- `/recur-quickstart` - Initial SDK setup
+- `/recur-checkout` - Implement payment flows
+- `/recur-entitlements` - Check subscription access after webhook

package/skills/recur-webhooks/scripts/test-webhook.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# Send a test webhook to your local endpoint
+#
+# Usage:
+#   ./test-webhook.sh [endpoint] [event_type]
+#
+# Example:
+#   ./test-webhook.sh http://localhost:3000/api/webhooks/recur checkout.completed
+
+ENDPOINT="${1:-http://localhost:3000/api/webhooks/recur}"
+EVENT_TYPE="${2:-checkout.completed}"
+SECRET="${RECUR_WEBHOOK_SECRET:-test_secret}"
+
+# Generate timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Create payload based on event type
+case $EVENT_TYPE in
+  "checkout.completed")
+    PAYLOAD=$(cat <<EOF
+{
+  "id": "evt_test_$(date +%s)",
+  "type": "checkout.completed",
+  "timestamp": "$TIMESTAMP",
+  "data": {
+    "checkoutId": "chk_test_123",
+    "customerId": "cus_test_456",
+    "customerEmail": "test@example.com",
+    "subscriptionId": "sub_test_789",
+    "productId": "prod_test_abc",
+    "amount": 29900,
+    "currency": "TWD"
+  }
+}
+EOF
+)
+    ;;
+  "subscription.activated")
+    PAYLOAD=$(cat <<EOF
+{
+  "id": "evt_test_$(date +%s)",
+  "type": "subscription.activated",
+  "timestamp": "$TIMESTAMP",
+  "data": {
+    "subscriptionId": "sub_test_789",
+    "customerId": "cus_test_456",
+    "productId": "prod_test_abc",
+    "status": "ACTIVE",
+    "currentPeriodStart": "$TIMESTAMP",
+    "currentPeriodEnd": "$(date -u -v+1m +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d '+1 month' +"%Y-%m-%dT%H:%M:%SZ")"
+  }
+}
+EOF
+)
+    ;;
+  "subscription.cancelled")
+    PAYLOAD=$(cat <<EOF
+{
+  "id": "evt_test_$(date +%s)",
+  "type": "subscription.cancelled",
+  "timestamp": "$TIMESTAMP",
+  "data": {
+    "subscriptionId": "sub_test_789",
+    "customerId": "cus_test_456",
+    "cancelledAt": "$TIMESTAMP",
+    "accessUntil": "$(date -u -v+1m +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d '+1 month' +"%Y-%m-%dT%H:%M:%SZ")"
+  }
+}
+EOF
+)
+    ;;
+  *)
+    PAYLOAD=$(cat <<EOF
+{
+  "id": "evt_test_$(date +%s)",
+  "type": "$EVENT_TYPE",
+  "timestamp": "$TIMESTAMP",
+  "data": {}
+}
+EOF
+)
+    ;;
+esac
+
+# Calculate signature
+SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
+
+echo "📤 Sending test webhook..."
+echo "Endpoint: $ENDPOINT"
+echo "Event: $EVENT_TYPE"
+echo "Signature: ${SIGNATURE:0:20}..."
+echo ""
+
+# Send request
+RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$ENDPOINT" \
+  -H "Content-Type: application/json" \
+  -H "x-recur-signature: $SIGNATURE" \
+  -d "$PAYLOAD")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+echo "Response: $HTTP_CODE"
+echo "$BODY"
+echo ""
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "✅ Webhook delivered successfully!"
+else
+  echo "❌ Webhook delivery failed"
+fi

package/skills/recur-webhooks/scripts/verify-signature.ts

@@ -0,0 +1,59 @@
+/**
+ * Verify Recur webhook signature
+ *
+ * Usage:
+ *   npx tsx verify-signature.ts <payload> <signature> <secret>
+ *
+ * Example:
+ *   npx tsx verify-signature.ts '{"type":"checkout.completed"}' 'abc123...' 'whsec_xxx'
+ */
+
+import crypto from 'crypto'
+
+function verifySignature(payload: string, signature: string, secret: string): boolean {
+  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')
+
+  try {
+    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
+  } catch {
+    return false
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2)
+
+  if (args.length < 3) {
+    console.log('Usage: npx tsx verify-signature.ts <payload> <signature> <secret>')
+    console.log('')
+    console.log('Example:')
+    console.log(
+      "  npx tsx verify-signature.ts '{\"type\":\"test\"}' 'abc123' 'whsec_xxx'"
+    )
+    process.exit(1)
+  }
+
+  const [payload, signature, secret] = args
+
+  console.log('Payload:', payload.substring(0, 50) + '...')
+  console.log('Signature:', signature.substring(0, 20) + '...')
+  console.log('')
+
+  const isValid = verifySignature(payload, signature, secret)
+
+  if (isValid) {
+    console.log('✅ Signature is VALID')
+  } else {
+    console.log('❌ Signature is INVALID')
+
+    // Show expected signature for debugging
+    const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')
+    console.log('')
+    console.log('Expected:', expected)
+    console.log('Received:', signature)
+  }
+
+  process.exit(isValid ? 0 : 1)
+}
+
+main()