recur-skills 0.0.9 → 0.0.11

package/.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "recur-skills",
   "description": "Claude Code skills for integrating Recur — Taiwan's subscription payment platform",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "owner": {
     "name": "Recur",
     "email": "hi@recur.tw",
@@ -10,14 +10,14 @@
   },
   "metadata": {
     "description": "Claude Code skills for integrating Recur - Taiwan's subscription payment platform",
-    "version": "0.0.9"
+    "version": "0.0.11"
   },
   "plugins": [
     {
       "name": "recur-skills",
       "displayName": "Recur Skills",
       "description": "Skills for Recur SDK integration (quickstart, checkout, webhooks, entitlements, portal) and the Recur MCP server for signup, API keys, and products",
-      "version": "0.0.9",
+      "version": "0.0.11",
       "source": "./",
       "category": "development",
       "homepage": "https://docs.recur.tw/guides/skills",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "recur-skills",
   "displayName": "Recur Skills",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Skills for Recur SDK integration (quickstart, checkout, webhooks, entitlements, customer portal) plus the Recur MCP server (https://mcp.recur.tw/) for account signup, API keys, and products.",
   "author": {
     "name": "Recur",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recur-skills",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Claude Code skills and MCP plugin for Recur - Taiwan's subscription payment platform",
   "keywords": [
     "recur",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "recur-skills",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Skills for Recur SDK integration: quickstart, checkout, webhooks, entitlements, and customer portal. Taiwan subscription billing via PAYUNi.",
   "author": {
     "name": "Recur",

package/skills/recur-checkout/SKILL.md

@@ -4,109 +4,161 @@ description: Implement Recur checkout flows including embedded, modal, and redir
 license: MIT
 metadata:
   author: recur
-  version: "0.0.9"
+  version: "0.0.11"
 ---
 
 # Recur Checkout Integration
 
-You are helping implement Recur checkout flows. Recur supports multiple checkout modes for different use cases.
+You are helping implement Recur checkout flows. Everything below is checked against the
+`recur-tw` typings (`RecurContextValue`, `UseSubscribeResult`, `CheckoutOptions`,
+`RedirectToCheckoutOptions`, `SubscriptionResult`). Product IDs are CUIDs from
+`list_products` / the dashboard (e.g. `cmfxq8n2a0001l8yz3k5p9t7d`); `prod_xxx` in the
+examples is a placeholder. You can also pass `productSlug`.
 
 ## 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 |
+| Mode | How | Best For |
+|------|-----|----------|
+| **Hosted** (recommended) | `useRecur().redirectToCheckout()` → checkout.recur.tw | Any app, works on localhost |
+| **Modal** | `useSubscribe()` / `useRecur().checkout()` with provider `checkoutMode: 'modal'` | Quick purchases without leaving the page |
+| **Embedded** | same hooks with provider `checkoutMode: 'embedded'` + `containerElementId` | Custom checkout pages |
 
-## Basic Implementation
+`checkoutMode` lives on `<RecurProvider config>`, not on the call. The provider default is
+`'embedded'`, which throws without `containerElementId` — set `checkoutMode: 'modal'` when
+you want the popup. There is no `mode: 'hosted' | 'modal'` option on any call.
 
-### Using useRecur Hook
+## Hosted Checkout (recommended)
+
+`isCheckingOut` is only set by `checkout()`; `redirectToCheckout()` creates the session and
+navigates away, so track your own pending flag.
 
 ```tsx
+'use client'
+
+import { useState } from 'react'
 import { useRecur } from 'recur-tw'
 
 function CheckoutButton({ productId }: { productId: string }) {
-  const { checkout, isLoading } = useRecur()
+  const { redirectToCheckout } = useRecur()
+  const [redirecting, setRedirecting] = useState(false)
 
   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')
-      },
-    })
+    setRedirecting(true)
+    try {
+      await redirectToCheckout({
+        productId,                            // or productSlug: 'pro-plan'
+        successUrl: `${window.location.origin}/success?session_id={CHECKOUT_SESSION_ID}`,
+        cancelUrl: `${window.location.origin}/pricing`,
+        customerEmail: 'user@example.com',    // optional, pre-fills the checkout page
+        customerName: 'John Doe',             // optional
+        externalCustomerId: 'user_123',       // optional, links to your user system
+      })
+    } catch (err) {
+      setRedirecting(false)
+      console.error('Failed to start checkout:', err)
+    }
   }
 
   return (
-    <button onClick={handleClick} disabled={isLoading}>
-      {isLoading ? 'Processing...' : 'Subscribe'}
+    <button onClick={handleClick} disabled={redirecting}>
+      {redirecting ? 'Redirecting...' : 'Subscribe'}
     </button>
   )
 }
 ```
 
-### Using useSubscribe Hook (with state management)
+The browser navigates away; no callbacks fire. Confirm the payment on your success page
+(via the session id) or with webhooks.
+
+## Modal / Embedded Checkout
+
+### Using useSubscribe (recommended for modal)
+
+Callbacks are options of the hook; `subscribe()` takes the checkout options only.
 
 ```tsx
+'use client'
+
 import { useSubscribe } from 'recur-tw'
+import { useRouter } from 'next/navigation'
 
 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>
-  }
+  const router = useRouter()
+  const { subscribe, isLoading, error, reset } = useSubscribe({
+    onPaymentComplete: (subscription) => {
+      // subscription: SubscriptionResult — id, status, productId, amount, currentPeriodEnd
+      router.push('/dashboard')
+    },
+    onPaymentFailed: (error) => {
+      console.error('Failed:', error.code, error.message)
+      return { action: 'retry' } // or 'close' or 'custom'
+    },
+    onPaymentCancel: () => console.log('User cancelled'),
+  })
 
   return (
     <>
-      <button onClick={handleClick} disabled={isLoading}>
-        Subscribe
+      <button
+        onClick={() => subscribe({ productId, customerEmail: 'user@example.com' })}
+        disabled={isLoading}
+      >
+        {isLoading ? 'Processing...' : 'Subscribe'}
       </button>
-      {error && <p className="error">{error.message}</p>}
+      {error && <p className="error" onClick={reset}>{error.message}</p>}
     </>
   )
 }
 ```
 
-## Embedded Mode Setup
+`useSubscribe()` returns `{ subscribe, mutate, isLoading, error, reset }` — there is no
+`subscription` field; use `onPaymentComplete` for the result.
+
+### Using useRecur().checkout (callbacks inline)
+
+```tsx
+'use client'
+
+import { useRecur } from 'recur-tw'
+
+function CheckoutButton({ productId }: { productId: string }) {
+  const { checkout, isCheckingOut } = useRecur()
+
+  const handleClick = () =>
+    checkout({
+      productId,
+      customerEmail: 'user@example.com',    // optional; collected in the form if omitted
+      customerName: 'John Doe',
+      externalCustomerId: 'user_123',
+      onPaymentComplete: (subscription) => console.log('Success!', subscription.id, subscription.status),
+      onPaymentFailed: (error) => ({ action: 'retry' }),
+      onPaymentCancel: () => console.log('User cancelled'),
+    })
+
+  return (
+    <button onClick={handleClick} disabled={isCheckingOut}>
+      {isCheckingOut ? 'Processing...' : 'Subscribe'}
+    </button>
+  )
+}
+```
 
-For embedded mode, you need a container element:
+### Provider setup for modal / embedded
 
 ```tsx
-// In RecurProvider config
+// Modal (popup)
+<RecurProvider
+  config={{
+    publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY!,
+    checkoutMode: 'modal',
+  }}
+>
+  {children}
+</RecurProvider>
+
+// Embedded (inline form) — the container must exist in the DOM
 <RecurProvider
   config={{
-    publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY,
+    publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY!,
     checkoutMode: 'embedded',
     containerElementId: 'recur-checkout-container',
   }}
@@ -114,47 +166,76 @@ For embedded mode, you need a container element:
   {children}
 </RecurProvider>
 
-// In your checkout page
 function CheckoutPage() {
   return (
     <div>
       <h1>Complete Your Purchase</h1>
-      {/* Recur will render the payment form here */}
+      {/* Recur renders the payment form here */}
       <div id="recur-checkout-container" />
     </div>
   )
 }
 ```
 
-## Handling 3D Verification
+Modal/embedded checkout needs a registered domain; on `localhost` use Hosted Checkout.
 
-Recur handles 3D Secure automatically. For mobile apps or specific flows:
+## Option Types
 
-```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',
-})
-```
+```typescript
+// redirectToCheckout()
+interface RedirectToCheckoutOptions {
+  productId?: string          // or productSlug — one is required
+  productSlug?: string
+  mode?: 'PAYMENT' | 'SUBSCRIPTION' | 'SETUP'  // usually inferred from the product
+  successUrl: string
+  cancelUrl: string
+  customerEmail?: string
+  customerName?: string
+  externalCustomerId?: string
+}
 
-## Product Types
+// checkout() / subscribe()
+interface CheckoutOptions {
+  productId?: string
+  productSlug?: string
+  customerEmail?: string
+  customerName?: string
+  externalCustomerId?: string
+  successUrl?: string         // used if 3-D Secure needs a redirect
+  cancelUrl?: string
+  // checkout() only — for subscribe() pass these to useSubscribe():
+  onPaymentComplete?: (subscription: SubscriptionResult) => void
+  onPaymentFailed?: (error: CheckoutError) => PaymentFailedAction | void
+  onPaymentCancel?: () => void
+  onSuccess?: (result: CheckoutResult) => void   // session created (before payment)
+  onError?: (error: CheckoutError) => void
+}
 
-Recur supports different product types:
+interface SubscriptionResult {          // onPaymentComplete argument
+  id: string
+  status: string                        // 'ACTIVE', 'TRIALING', ...
+  productId: string
+  amount: number                        // whole TWD (499 = NT$499). NEVER divide by 100
+  billingPeriod: string
+  currentPeriodStart: string
+  currentPeriodEnd: string
+  trialEndsAt?: string
+  nextBillingDate?: string
+}
+```
 
-```tsx
-// Subscription (recurring)
-checkout({ productId: 'prod_subscription_xxx' })
+No `trialDays`, `quantity`, or `metadata` on these options — trials and pricing come from
+the product (the server SDK's `checkoutSessions.create()` does accept `metadata`).
 
-// One-time purchase
-checkout({ productId: 'prod_onetime_xxx' })
+## Product Types
 
-// Credits (prepaid wallet)
-checkout({ productId: 'prod_credits_xxx' })
+All four types go through the same calls; the product decides the behaviour:
 
-// Donation (variable amount)
-checkout({ productId: 'prod_donation_xxx' })
+```tsx
+redirectToCheckout({ productSlug: 'pro-monthly', successUrl, cancelUrl })  // SUBSCRIPTION (recurring)
+redirectToCheckout({ productSlug: 'ebook', successUrl, cancelUrl })        // ONE_TIME
+redirectToCheckout({ productSlug: 'credits-100', successUrl, cancelUrl })  // CREDITS (prepaid wallet)
+redirectToCheckout({ productSlug: 'support-us', successUrl, cancelUrl })   // DONATION (variable amount)
 ```
 
 ## Listing Products
@@ -163,15 +244,14 @@ checkout({ productId: 'prod_donation_xxx' })
 import { useProducts } from 'recur-tw'
 
 function PricingPage() {
-  const { products, isLoading } = useProducts({
-    type: 'SUBSCRIPTION', // Filter by type
-  })
+  const { data: products, isLoading, error } = useProducts({ type: 'SUBSCRIPTION' })
 
   if (isLoading) return <div>Loading...</div>
+  if (error) return <div>{error.message}</div>
 
   return (
     <div className="pricing-grid">
-      {products.map(product => (
+      {products?.map((product) => (
         <PricingCard key={product.id} product={product} />
       ))}
     </div>
@@ -179,36 +259,56 @@ function PricingPage() {
 }
 ```
 
+`Product` fields: `id`, `name`, `slug`, `description`, `type`, `billingPeriod`
+(`'MONTHLY' | 'YEARLY' | ... | null`), `price` (whole TWD), `currency`, `trialDays`,
+`metadata`. There is no `priceFormatted` on the SDK type — format with
+`` `NT$${product.price.toLocaleString()}` ``.
+
 ## Payment Failed Handling
 
+`CheckoutError.code` is `'PAYMENT_FAILED'` for a declined payment; the gateway's own code
+is in `error.details.failure_code` (with `failure_message` and `can_retry`).
+`CheckoutErrorDetails` is a union — an array for conflict errors, an object for payment
+failures — so narrow it before reading the fields.
+
 ```tsx
 onPaymentFailed: (error) => {
-  // error.code tells you what went wrong
-  switch (error.code) {
+  const details = Array.isArray(error.details) ? undefined : error.details
+
+  switch (details?.failure_code) {
     case 'CARD_DECLINED':
       return { action: 'retry' }
     case 'INSUFFICIENT_FUNDS':
-      return {
-        action: 'custom',
-        customTitle: '餘額不足',
-        customMessage: '請使用其他付款方式',
-      }
+      return { action: 'custom', customTitle: '餘額不足', customMessage: '請使用其他付款方式' }
     default:
-      return { action: 'close' }
+      return details?.can_retry ? { action: 'retry' } : { action: 'close' }
   }
 }
 ```
 
-## Server-Side Checkout (API)
+## Server-Side Checkout (Hosted, no React)
+
+```typescript
+import { Recur } from 'recur-tw/server'
+
+const recur = new Recur(process.env.RECUR_SECRET_KEY!)
+const session = await recur.checkoutSessions.create({
+  productId: 'prod_xxx',                 // a CUID from list_products
+  successUrl: 'https://yourapp.com/success',
+  cancelUrl: 'https://yourapp.com/cancel',
+  customerEmail: 'user@example.com',
+  metadata: { plan: 'pro' },             // optional, server-side only
+})
+// redirect the customer to session.url
+```
 
-For server-rendered apps or custom flows:
+Or with plain REST:
 
 ```typescript
-// Create checkout session
-const response = await fetch('https://api.recur.tw/v1/checkouts', {
+const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
   method: 'POST',
   headers: {
-    'X-Recur-Secret-Key': process.env.RECUR_SECRET_KEY,
+    Authorization: `Bearer ${process.env.RECUR_SECRET_KEY}`,   // X-Recur-Secret-Key also works
     'Content-Type': 'application/json',
   },
   body: JSON.stringify({
@@ -219,31 +319,19 @@ const response = await fetch('https://api.recur.tw/v1/checkouts', {
   }),
 })
 
-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
-}
+// The session object is the response body itself (no outer `data` wrapper, snake_case keys)
+const { url } = await response.json()
+// Redirect the customer to `url`. (/v1/checkouts is the embedded-form endpoint, different shape.)
 ```
 
 ## 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
+1. **Default to Hosted Checkout** — works everywhere, including localhost
+2. **Handle every callback** on modal/embedded — onPaymentComplete, onPaymentFailed, onPaymentCancel
+3. **Show loading states** — `isCheckingOut` (useRecur, modal/embedded only) / `isLoading` (useSubscribe); for `redirectToCheckout()` track your own flag
+4. **Pre-fill customer info** when you already have it; it is optional
+5. **Use externalCustomerId** to link Recur customers to your user system
+6. **Test in sandbox first** — `pk_test_` / `sk_test_` keys
 
 ## Related Skills
 

package/skills/recur-entitlements/SKILL.md

@@ -4,7 +4,7 @@ description: Implement access control and permission checking with Recur entitle
 license: MIT
 metadata:
   author: recur
-  version: "0.0.9"
+  version: "0.0.11"
 ---
 
 # Recur Entitlements & Access Control
@@ -71,7 +71,7 @@ const { check } = useCustomer()
 // Check by product slug
 const { allowed, entitlement } = check('pro-plan')
 
-// Check by product ID
+// Check by product ID (a CUID from list_products, e.g. 'cmfxq8n2a0001l8yz3k5p9t7d'; 'prod_xxx' is a placeholder)
 const { allowed } = check('prod_xxx')
 
 if (allowed) {
@@ -111,14 +111,24 @@ onPaymentComplete: async () => {
 ## Entitlement Response Structure
 
 ```typescript
+interface CheckResult {          // what check() returns
+  allowed: boolean
+  reason?: 'no_customer' | 'no_entitlement' | 'not_found' | 'expired' | 'insufficient_balance'
+  entitlement?: Entitlement
+  balance?: number               // CREDITS products
+  unlimited?: boolean
+  subscription?: { id: string; status: string; product: { id: string; slug: string; name: string }; currentPeriodEnd: string }
+}
+
 interface Entitlement {
   product: string        // Product slug
-  productId: string      // Product ID
+  productId: string      // Product ID (CUID)
   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)
+  subscriptionId?: string
 }
 
 type EntitlementStatus =
@@ -140,7 +150,9 @@ 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({
+  // Server EntitlementCheckResult is { allowed, subscription? } — there is no
+  // `entitlement` field here (that one belongs to the React check()).
+  const { allowed, subscription } = await recur.entitlements.check({
     product: 'pro-plan',
     customer: { email: userEmail },
   })
@@ -149,7 +161,7 @@ async function checkAccess(userEmail: string) {
     throw new Error('Upgrade required')
   }
 
-  return entitlement
+  return subscription
 }
 ```
 
@@ -166,6 +178,9 @@ const response = await fetch(
   }
 )
 
+// REST responses are snake_case (the API wrapper converts them), unlike the SDK's
+// camelCase types: customer { id, email, name, external_id }, subscription | null,
+// entitlements[] with product_id / granted_at / expires_at / source_id.
 const { customer, subscription, entitlements } = await response.json()
 ```
 
@@ -254,16 +269,13 @@ export async function requireSubscription(
 ) {
   const userEmail = await getUserEmail(req) // Your auth logic
 
-  const { allowed, denial } = await recur.entitlements.check({
+  const { allowed } = 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.
-    }), {
+    throw new Response(JSON.stringify({ error: 'Subscription required' }), {
       status: 403,
       headers: { 'Content-Type': 'application/json' },
     })
@@ -349,13 +361,13 @@ if (entitlement?.status === 'canceled') {
 
 ## Denial Reasons
 
-When `allowed` is `false`, check the denial reason:
+When `allowed` is `false`, `CheckResult.reason` says why (`'no_customer' | 'no_entitlement' | 'not_found' | 'expired' | 'insufficient_balance'`):
 
 ```typescript
-const { allowed, denial } = check('pro-plan')
+const { allowed, reason } = check('pro-plan')
 
 if (!allowed) {
-  switch (denial?.reason) {
+  switch (reason) {
     case 'no_customer':
       // Customer not found
       return <CreateAccountPrompt />

package/skills/recur-help/SKILL.md

@@ -4,7 +4,7 @@ description: List all available Recur skills and how to use them. Use when user
 license: MIT
 metadata:
   author: recur
-  version: "0.0.9"
+  version: "0.0.11"
 ---
 
 # Recur Skills 使用指南

package/skills/recur-portal/SKILL.md

@@ -4,7 +4,7 @@ description: Implement Customer Portal for subscription self-service. Use when b
 license: MIT
 metadata:
   author: recur
-  version: "0.0.9"
+  version: "0.0.11"
 ---
 
 # Recur Customer Portal Integration