recur-skills 0.0.1

package/skills/recur-checkout/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: recur-checkout
+description: Implement Recur checkout flows including embedded, modal, and redirect modes. Use when adding payment buttons, checkout forms, subscription purchase flows, or when user mentions "checkout", "結帳", "付款按鈕", "embedded checkout".
+---
+
+# Recur Checkout Integration
+
+You are helping implement Recur checkout flows. Recur supports multiple checkout modes for different use cases.
+
+## Checkout Modes
+
+| Mode | Best For | User Experience |
+|------|----------|-----------------|
+| `embedded` | SPA apps | Form renders inline in your page |
+| `modal` | Quick purchases | Form appears in a dialog overlay |
+| `redirect` | Simple integration | Full page redirect to Recur |
+
+## Basic Implementation
+
+### Using useRecur Hook
+
+```tsx
+import { useRecur } from 'recur-tw'
+
+function CheckoutButton({ productId }: { productId: string }) {
+  const { checkout, isLoading } = useRecur()
+
+  const handleClick = async () => {
+    await checkout({
+      productId,
+      // Or use productSlug: 'pro-plan'
+
+      // Optional: Pre-fill customer info
+      customerEmail: 'user@example.com',
+      customerName: 'John Doe',
+
+      // Optional: Link to your user system
+      externalCustomerId: 'user_123',
+
+      // Callbacks
+      onPaymentComplete: (result) => {
+        console.log('Success!', result)
+        // result.id - Subscription/Order ID
+        // result.status - 'ACTIVE', 'TRIALING', etc.
+      },
+      onPaymentFailed: (error) => {
+        console.error('Failed:', error)
+        return { action: 'retry' } // or 'close' or 'custom'
+      },
+      onPaymentCancel: () => {
+        console.log('User cancelled')
+      },
+    })
+  }
+
+  return (
+    <button onClick={handleClick} disabled={isLoading}>
+      {isLoading ? 'Processing...' : 'Subscribe'}
+    </button>
+  )
+}
+```
+
+### Using useSubscribe Hook (with state management)
+
+```tsx
+import { useSubscribe } from 'recur-tw'
+
+function SubscribeButton({ productId }: { productId: string }) {
+  const { subscribe, isLoading, error, subscription } = useSubscribe()
+
+  const handleClick = () => {
+    subscribe({
+      productId,
+      onPaymentComplete: (sub) => {
+        // Subscription created successfully
+        router.push('/dashboard')
+      },
+    })
+  }
+
+  if (subscription) {
+    return <p>Subscribed! ID: {subscription.id}</p>
+  }
+
+  return (
+    <>
+      <button onClick={handleClick} disabled={isLoading}>
+        Subscribe
+      </button>
+      {error && <p className="error">{error.message}</p>}
+    </>
+  )
+}
+```
+
+## Embedded Mode Setup
+
+For embedded mode, you need a container element:
+
+```tsx
+// In RecurProvider config
+<RecurProvider
+  config={{
+    publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY,
+    checkoutMode: 'embedded',
+    containerElementId: 'recur-checkout-container',
+  }}
+>
+  {children}
+</RecurProvider>
+
+// In your checkout page
+function CheckoutPage() {
+  return (
+    <div>
+      <h1>Complete Your Purchase</h1>
+      {/* Recur will render the payment form here */}
+      <div id="recur-checkout-container" />
+    </div>
+  )
+}
+```
+
+## Handling 3D Verification
+
+Recur handles 3D Secure automatically. For mobile apps or specific flows:
+
+```tsx
+await checkout({
+  productId,
+  // These URLs are used when 3D verification requires redirect
+  successUrl: 'https://yourapp.com/checkout/success',
+  cancelUrl: 'https://yourapp.com/checkout/cancel',
+})
+```
+
+## Product Types
+
+Recur supports different product types:
+
+```tsx
+// Subscription (recurring)
+checkout({ productId: 'prod_subscription_xxx' })
+
+// One-time purchase
+checkout({ productId: 'prod_onetime_xxx' })
+
+// Credits (prepaid wallet)
+checkout({ productId: 'prod_credits_xxx' })
+
+// Donation (variable amount)
+checkout({ productId: 'prod_donation_xxx' })
+```
+
+## Listing Products
+
+```tsx
+import { useProducts } from 'recur-tw'
+
+function PricingPage() {
+  const { products, isLoading } = useProducts({
+    type: 'SUBSCRIPTION', // Filter by type
+  })
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <div className="pricing-grid">
+      {products.map(product => (
+        <PricingCard key={product.id} product={product} />
+      ))}
+    </div>
+  )
+}
+```
+
+## Payment Failed Handling
+
+```tsx
+onPaymentFailed: (error) => {
+  // error.code tells you what went wrong
+  switch (error.code) {
+    case 'CARD_DECLINED':
+      return { action: 'retry' }
+    case 'INSUFFICIENT_FUNDS':
+      return {
+        action: 'custom',
+        customTitle: '餘額不足',
+        customMessage: '請使用其他付款方式',
+      }
+    default:
+      return { action: 'close' }
+  }
+}
+```
+
+## Server-Side Checkout (API)
+
+For server-rendered apps or custom flows:
+
+```typescript
+// Create checkout session
+const response = await fetch('https://api.recur.tw/v1/checkouts', {
+  method: 'POST',
+  headers: {
+    'X-Recur-Secret-Key': process.env.RECUR_SECRET_KEY,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    productId: 'prod_xxx',
+    customerEmail: 'user@example.com',
+    successUrl: 'https://yourapp.com/success',
+    cancelUrl: 'https://yourapp.com/cancel',
+  }),
+})
+
+const { checkoutUrl } = await response.json()
+// Redirect user to checkoutUrl
+```
+
+## Checkout Result Structure
+
+```typescript
+interface CheckoutResult {
+  id: string              // Subscription or Order ID
+  status: string          // 'ACTIVE', 'TRIALING', 'PENDING'
+  productId: string
+  amount: number          // In cents (e.g., 29900 = NT$299)
+  billingPeriod?: string  // 'MONTHLY', 'YEARLY' for subscriptions
+  currentPeriodEnd?: string  // ISO date
+  trialEndsAt?: string    // ISO date if trial
+}
+```
+
+## Best Practices
+
+1. **Always handle all callbacks** - onPaymentComplete, onPaymentFailed, onPaymentCancel
+2. **Show loading states** - Use isLoading to disable buttons during checkout
+3. **Pre-fill customer info** - Reduces friction if you already have user data
+4. **Use externalCustomerId** - Links Recur customers to your user system
+5. **Test in sandbox first** - Use `pk_test_` keys during development
+
+## Related Skills
+
+- `/recur-quickstart` - Initial SDK setup
+- `/recur-webhooks` - Receive payment notifications
+- `/recur-entitlements` - Check subscription access

package/skills/recur-entitlements/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: recur-entitlements
+description: Implement access control and permission checking with Recur entitlements API. Use when building paywalls, checking subscription status, gating premium features, or when user mentions "paywall", "權限檢查", "entitlements", "access control", "premium features".
+---
+
+# Recur Entitlements & Access Control
+
+You are helping implement access control using Recur's entitlements system. Entitlements let you check if a customer has access to your products (subscriptions or one-time purchases).
+
+## Quick Start: Client-Side Check
+
+```tsx
+import { RecurProvider, useCustomer } from 'recur-tw'
+
+// 1. Wrap app with provider and identify customer
+function App() {
+  return (
+    <RecurProvider
+      config={{ publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY }}
+      customer={{ email: 'user@example.com' }}
+    >
+      <MyApp />
+    </RecurProvider>
+  )
+}
+
+// 2. Check access anywhere in your app
+function PremiumFeature() {
+  const { check, isLoading } = useCustomer()
+
+  if (isLoading) return <div>Loading...</div>
+
+  const { allowed } = check('pro-plan')
+
+  if (!allowed) {
+    return <UpgradePrompt />
+  }
+
+  return <PremiumContent />
+}
+```
+
+## Customer Identification
+
+Identify customers using one of these methods:
+
+```tsx
+// By email (most common)
+<RecurProvider customer={{ email: 'user@example.com' }}>
+
+// By your system's user ID
+<RecurProvider customer={{ externalId: 'user_123' }}>
+
+// By Recur customer ID
+<RecurProvider customer={{ id: 'cus_xxx' }}>
+```
+
+## Checking Access
+
+### Synchronous Check (Cached)
+
+Fast, uses cached data. Good for UI rendering.
+
+```tsx
+const { check } = useCustomer()
+
+// Check by product slug
+const { allowed, entitlement } = check('pro-plan')
+
+// Check by product ID
+const { allowed } = check('prod_xxx')
+
+if (allowed) {
+  // User has access
+  // entitlement contains details like status, expiresAt
+}
+```
+
+### Async Check (Live)
+
+Fetches fresh data from API. Use for critical operations.
+
+```tsx
+const { check } = useCustomer()
+
+// Real-time check
+const { allowed, entitlement } = await check('pro-plan', { live: true })
+
+// Good for:
+// - Before processing important actions
+// - After checkout to confirm access
+// - When cached data might be stale
+```
+
+### Manual Refetch
+
+```tsx
+const { refetch } = useCustomer()
+
+// After checkout completion
+onPaymentComplete: async () => {
+  await refetch() // Refresh entitlements
+  router.push('/dashboard')
+}
+```
+
+## Entitlement Response Structure
+
+```typescript
+interface Entitlement {
+  product: string        // Product slug
+  productId: string      // Product ID
+  status: EntitlementStatus
+  source: 'subscription' | 'order'  // How they got access
+  sourceId: string       // Subscription/Order ID
+  grantedAt: string      // When access was granted
+  expiresAt: string | null  // When access expires (null = permanent)
+}
+
+type EntitlementStatus =
+  | 'active'      // Subscription active
+  | 'trialing'    // In trial period
+  | 'past_due'    // Payment failed, in grace period
+  | 'canceled'    // Cancelled but access until period end
+  | 'purchased'   // One-time purchase (permanent)
+```
+
+## Server-Side Checking
+
+### Using Server SDK
+
+```typescript
+import { Recur } from 'recur-tw/server'
+
+const recur = new Recur(process.env.RECUR_SECRET_KEY!)
+
+// In API route or server action
+async function checkAccess(userEmail: string) {
+  const { allowed, entitlement } = await recur.entitlements.check({
+    product: 'pro-plan',
+    customer: { email: userEmail },
+  })
+
+  if (!allowed) {
+    throw new Error('Upgrade required')
+  }
+
+  return entitlement
+}
+```
+
+### Using REST API Directly
+
+```typescript
+// GET /api/v1/customers/entitlements
+const response = await fetch(
+  `https://api.recur.tw/v1/customers/entitlements?email=${encodeURIComponent(email)}`,
+  {
+    headers: {
+      'X-Recur-Secret-Key': process.env.RECUR_SECRET_KEY!,
+    },
+  }
+)
+
+const { customer, subscription, entitlements } = await response.json()
+```
+
+## Common Patterns
+
+### Paywall Component
+
+```tsx
+function Paywall({
+  children,
+  product,
+  fallback
+}: {
+  children: React.ReactNode
+  product: string
+  fallback?: React.ReactNode
+}) {
+  const { check, isLoading } = useCustomer()
+
+  if (isLoading) {
+    return <div>Loading...</div>
+  }
+
+  const { allowed } = check(product)
+
+  if (!allowed) {
+    return fallback || <UpgradePrompt product={product} />
+  }
+
+  return <>{children}</>
+}
+
+// Usage
+<Paywall product="pro-plan">
+  <PremiumDashboard />
+</Paywall>
+```
+
+### Feature Flag Style
+
+```tsx
+function useFeature(featureProduct: string) {
+  const { check, isLoading } = useCustomer()
+
+  if (isLoading) {
+    return { enabled: false, loading: true }
+  }
+
+  const { allowed, entitlement } = check(featureProduct)
+
+  return {
+    enabled: allowed,
+    loading: false,
+    entitlement,
+    isTrial: entitlement?.status === 'trialing',
+    isPastDue: entitlement?.status === 'past_due',
+  }
+}
+
+// Usage
+function MyComponent() {
+  const { enabled, isTrial } = useFeature('pro-plan')
+
+  if (!enabled) return <UpgradeButton />
+
+  return (
+    <>
+      {isTrial && <TrialBanner />}
+      <ProFeature />
+    </>
+  )
+}
+```
+
+### API Middleware
+
+```typescript
+// middleware/requireSubscription.ts
+import { Recur } from 'recur-tw/server'
+
+const recur = new Recur(process.env.RECUR_SECRET_KEY!)
+
+export async function requireSubscription(
+  req: Request,
+  product: string
+) {
+  const userEmail = await getUserEmail(req) // Your auth logic
+
+  const { allowed, denial } = await recur.entitlements.check({
+    product,
+    customer: { email: userEmail },
+  })
+
+  if (!allowed) {
+    throw new Response(JSON.stringify({
+      error: 'Subscription required',
+      reason: denial?.reason, // 'no_customer', 'no_entitlement', etc.
+    }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+}
+
+// Usage in API route
+export async function GET(req: Request) {
+  await requireSubscription(req, 'pro-plan')
+
+  // User has access, continue...
+  return Response.json({ data: 'premium content' })
+}
+```
+
+### Multiple Product Tiers
+
+```tsx
+function PricingGate() {
+  const { check } = useCustomer()
+
+  const hasPro = check('pro-plan').allowed
+  const hasEnterprise = check('enterprise-plan').allowed
+
+  if (hasEnterprise) {
+    return <EnterpriseDashboard />
+  }
+
+  if (hasPro) {
+    return <ProDashboard />
+  }
+
+  return <FreeDashboard />
+}
+```
+
+## Handling Edge Cases
+
+### Past Due Subscriptions
+
+```tsx
+const { allowed, entitlement } = check('pro-plan')
+
+if (allowed && entitlement?.status === 'past_due') {
+  // Show warning but allow access during grace period
+  return (
+    <>
+      <PaymentFailedBanner />
+      <PremiumContent />
+    </>
+  )
+}
+```
+
+### Trial Subscriptions
+
+```tsx
+const { entitlement } = check('pro-plan')
+
+if (entitlement?.status === 'trialing') {
+  const trialEnds = new Date(entitlement.expiresAt!)
+  const daysLeft = Math.ceil((trialEnds - Date.now()) / (1000 * 60 * 60 * 24))
+
+  return <TrialBanner daysLeft={daysLeft} />
+}
+```
+
+### Cancelled but Active
+
+```tsx
+const { entitlement } = check('pro-plan')
+
+if (entitlement?.status === 'canceled') {
+  // User cancelled but still has access until period end
+  return (
+    <>
+      <ResubscribeBanner expiresAt={entitlement.expiresAt} />
+      <PremiumContent />
+    </>
+  )
+}
+```
+
+## Denial Reasons
+
+When `allowed` is `false`, check the denial reason:
+
+```typescript
+const { allowed, denial } = check('pro-plan')
+
+if (!allowed) {
+  switch (denial?.reason) {
+    case 'no_customer':
+      // Customer not found
+      return <CreateAccountPrompt />
+
+    case 'no_entitlement':
+      // No subscription to this product
+      return <SubscribePrompt />
+
+    case 'expired':
+      // Subscription/access expired
+      return <RenewPrompt />
+
+    case 'insufficient_balance':
+      // For credit-based products
+      return <BuyCreditsPrompt />
+
+    default:
+      return <GenericUpgradePrompt />
+  }
+}
+```
+
+## Best Practices
+
+1. **Use cached checks for UI** - Fast rendering, good UX
+2. **Use live checks for actions** - Ensure fresh data for important operations
+3. **Handle all statuses** - active, trialing, past_due, canceled
+4. **Refetch after checkout** - Ensure UI updates after purchase
+5. **Implement graceful degradation** - Show upgrade prompts, not errors
+
+## Related Skills
+
+- `/recur-quickstart` - Initial SDK setup
+- `/recur-checkout` - Implement purchase flows
+- `/recur-webhooks` - Sync entitlements with webhooks