recur-skills 0.0.11 → 0.0.13

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.11",
+  "version": "0.0.13",
   "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.11"
+    "version": "0.0.13"
   },
   "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.11",
+      "version": "0.0.13",
       "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.11",
+  "version": "0.0.13",
   "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.11",
+  "version": "0.0.13",
   "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.11",
+  "version": "0.0.13",
   "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,7 +4,7 @@ description: Implement Recur checkout flows including embedded, modal, and redir
 license: MIT
 metadata:
   author: recur
-  version: "0.0.11"
+  version: "0.0.13"
 ---
 
 # Recur Checkout Integration
@@ -261,7 +261,7 @@ 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
+`metadata`, `productFamily`, `displayOrder`. There is no `priceFormatted` on the SDK type — format with
 `` `NT$${product.price.toLocaleString()}` ``.
 
 ## Payment Failed Handling

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.11"
+  version: "0.0.13"
 ---
 
 # Recur Entitlements & Access Control
@@ -15,13 +15,18 @@ You are helping implement access control using Recur's entitlements system. Enti
 
 ```tsx
 import { RecurProvider, useCustomer } from 'recur-tw'
+// Your own hook, defined in "Knowing when the answer is real" below.
+import { useEntitlementsReady } from './hooks/use-entitlements-ready'
+
+// The identifier you hand the provider. Pass the same value to the readiness hook.
+const customerEmail = 'user@example.com'
 
 // 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' }}
+      customer={{ email: customerEmail }}
     >
       <MyApp />
     </RecurProvider>
@@ -30,9 +35,10 @@ function App() {
 
 // 2. Check access anywhere in your app
 function PremiumFeature() {
-  const { check, isLoading } = useCustomer()
+  const { check } = useCustomer()
+  const ready = useEntitlementsReady(customerEmail)
 
-  if (isLoading) return <div>Loading...</div>
+  if (!ready) return <div>Loading...</div>
 
   const { allowed } = check('pro-plan')
 
@@ -44,6 +50,101 @@ function PremiumFeature() {
 }
 ```
 
+### Knowing when the answer is real
+
+`useCustomer()` has no "initialized" flag. `isLoading` starts `false` because the request
+only begins in an effect, and `customer` is `null` both before the request and when the
+customer genuinely does not exist — so neither one can tell "not fetched yet" from "no such
+customer". Gating on `isLoading` alone flashes an upgrade prompt on the first paint; gating
+on `!customer` leaves a brand-new customer on the spinner forever.
+
+Track the first completed load yourself:
+
+```tsx
+// hooks/use-entitlements-ready.ts
+import { useEffect, useRef, useState } from 'react'
+import { useCustomer } from 'recur-tw'
+
+// `customerKey` is the identifier you pass to RecurProvider (email, externalId or id).
+export function useEntitlementsReady(customerKey: string | null | undefined) {
+  const { isLoading, error, customer } = useCustomer()
+  const [ready, setReady] = useState(false)
+  const [seenKey, setSeenKey] = useState(customerKey)
+  const pending = useRef(false)
+  const switched = useRef(false)
+
+  // Adjusted during render, not in an effect: RecurProvider kicks off the new request
+  // from an effect and leaves the old cache with `isLoading === false` until it does,
+  // so an effect-only guard would still pass for one render after a switch.
+  if (customerKey !== seenKey) {
+    setSeenKey(customerKey)
+    setReady(false)
+    switched.current = true
+  }
+
+  useEffect(() => {
+    if (isLoading) {
+      pending.current = true
+      setReady(false)          // a new fetch: the cache still holds the previous customer
+    } else if (pending.current) {
+      pending.current = false
+      setReady(!error)         // ready only when that request actually succeeded
+    }
+  }, [isLoading, error])
+
+  // A customer already in the cache proves a request finished. Without this, a gate that
+  // first mounts AFTER the provider settled never sees isLoading go true, so it would wait
+  // forever. Only before a switch: afterwards the cache still holds the previous customer.
+  return ready || (!switched.current && !isLoading && customer !== null)
+}
+```
+
+The `!error` reset matters because the SDK restores its last successful cache on a failed
+request and still clears `isLoading`; without it a failed fetch would open the guard over
+whatever was cached before. Read `error` from `useCustomer()` to tell "still loading" from
+"the fetch failed".
+
+It stays `false` if you did not pass a `customer` to `RecurProvider`, because no request
+ever runs — that is the case to catch in development.
+
+### Mount the gate with the provider
+
+Put the guard in one component directly under `RecurProvider`, not in every leaf:
+
+```tsx
+function EntitlementsGate({ children }: { children: React.ReactNode }) {
+  const ready = useEntitlementsReady(customerEmail)
+  if (!ready) return <Spinner />
+  return <>{children}</>
+}
+
+<RecurProvider config={{ publishableKey }} customer={{ email: customerEmail }}>
+  <EntitlementsGate>
+    <App />          {/* everything below can call check() freely */}
+  </EntitlementsGate>
+</RecurProvider>
+```
+
+A gate that mounts with the provider watches the whole request, which is the only way the
+hook sees the load at all. A gate that first mounts much later relies on the cache fallback
+in the last line of the hook, and that cannot help when the customer does not exist in
+Recur: the entitlements endpoint answers `200` with `customer: null` both for "no such
+customer" and for "not fetched yet", so a late-mounted gate for an unknown customer waits.
+
+### What this hook cannot do
+
+It does not make a customer switch safe. `RecurProvider` has no request sequencing: when
+the identifier changes it starts a second request while the first is still in flight, and
+whichever lands last wins. The previous customer's response can overwrite the new one's
+cache and clear the shared `isLoading` flag, at which point this hook reports ready over the
+wrong data. The render-time reset narrows the window but cannot close it from outside the
+SDK.
+
+So if one session can switch between customers in place, do not treat the client cache as an
+authorization decision. Confirm on the server, where you hold the secret key and read the
+customer you actually mean. Remounting the app on a switch also avoids the overlap.
+
+
 ## Customer Identification
 
 Identify customers using one of these methods:
@@ -82,20 +183,28 @@ if (allowed) {
 
 ### Async Check (Live)
 
-Fetches fresh data from API. Use for critical operations.
+Refetches before answering. Useful, but **not authoritative** — see the warning below.
 
 ```tsx
 const { check } = useCustomer()
 
-// Real-time check
+// Refetches, then answers
 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
+// - Refreshing the UI after checkout
+// - When cached data is probably stale
 ```
 
+> **`{ live: true }` can answer from the previous snapshot.** In the current SDK it awaits
+> the refetch and then calls the synchronous check captured by the render it was called
+> from, so the fresh data is in the cache but the answer is not computed from it. Right
+> after a purchase it can still say `false`.
+>
+> Never use it as the gate on something that matters — granting access, releasing a
+> download, starting paid work. Check on the server with the secret key instead. On the
+> client, `{ live: true }` is a way to refresh what the user sees, not a decision.
+
 ### Manual Refetch
 
 ```tsx
@@ -168,7 +277,7 @@ async function checkAccess(userEmail: string) {
 ### Using REST API Directly
 
 ```typescript
-// GET /api/v1/customers/entitlements
+// GET /v1/customers/entitlements
 const response = await fetch(
   `https://api.recur.tw/v1/customers/entitlements?email=${encodeURIComponent(email)}`,
   {
@@ -192,15 +301,19 @@ const { customer, subscription, entitlements } = await response.json()
 function Paywall({
   children,
   product,
+  customerKey,
   fallback
 }: {
   children: React.ReactNode
   product: string
+  /** The identifier passed to RecurProvider, so the guard closes on a customer switch. */
+  customerKey: string | null | undefined
   fallback?: React.ReactNode
 }) {
-  const { check, isLoading } = useCustomer()
+  const { check } = useCustomer()
+  const ready = useEntitlementsReady(customerKey)
 
-  if (isLoading) {
+  if (!ready) {
     return <div>Loading...</div>
   }
 
@@ -214,7 +327,7 @@ function Paywall({
 }
 
 // Usage
-<Paywall product="pro-plan">
+<Paywall product="pro-plan" customerKey={customerEmail}>
   <PremiumDashboard />
 </Paywall>
 ```
@@ -222,11 +335,14 @@ function Paywall({
 ### Feature Flag Style
 
 ```tsx
-function useFeature(featureProduct: string) {
-  const { check, isLoading } = useCustomer()
-
-  if (isLoading) {
-    return { enabled: false, loading: true }
+function useFeature(featureProduct: string, customerKey: string | null | undefined) {
+  const { check, error } = useCustomer()
+  const ready = useEntitlementsReady(customerKey)
+
+  // `isLoading` alone is not enough here either: it starts false, so the first paint
+  // would read an empty cache and report the feature as off.
+  if (!ready) {
+    return { enabled: false, loading: !error, error, entitlement: undefined }
   }
 
   const { allowed, entitlement } = check(featureProduct)
@@ -234,6 +350,7 @@ function useFeature(featureProduct: string) {
   return {
     enabled: allowed,
     loading: false,
+    error: null,
     entitlement,
     isTrial: entitlement?.status === 'trialing',
     isPastDue: entitlement?.status === 'past_due',
@@ -242,7 +359,7 @@ function useFeature(featureProduct: string) {
 
 // Usage
 function MyComponent() {
-  const { enabled, isTrial } = useFeature('pro-plan')
+  const { enabled, isTrial } = useFeature('pro-plan', customerEmail)
 
   if (!enabled) return <UpgradeButton />
 
@@ -337,7 +454,7 @@ 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))
+  const daysLeft = Math.ceil((trialEnds.getTime() - Date.now()) / (1000 * 60 * 60 * 24))
 
   return <TrialBanner daysLeft={daysLeft} />
 }
@@ -393,7 +510,9 @@ if (!allowed) {
 ## Best Practices
 
 1. **Use cached checks for UI** - Fast rendering, good UX
-2. **Use live checks for actions** - Ensure fresh data for important operations
+2. **Decide on the server** - Anything that grants access, releases a file or starts paid
+   work is checked with the secret key. `{ live: true }` refreshes the UI; it can still
+   answer from the previous snapshot, so it is not an authorization decision
 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

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.11"
+  version: "0.0.13"
 ---
 
 # 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.11"
+  version: "0.0.13"
 ---
 
 # Recur Customer Portal Integration

package/skills/recur-quickstart/SKILL.md

@@ -4,7 +4,7 @@ description: Quick setup guide for Recur payment integration, from account signu
 license: MIT
 metadata:
   author: recur
-  version: "0.0.11"
+  version: "0.0.13"
 ---
 
 # Recur Quickstart

package/skills/recur-webhooks/SKILL.md

@@ -4,7 +4,7 @@ description: Set up and handle Recur webhook events for payment notifications. U
 license: MIT
 metadata:
   author: recur
-  version: "0.0.11"
+  version: "0.0.13"
 ---
 
 # Recur Webhook Integration
@@ -22,8 +22,8 @@ You are helping implement Recur webhooks to receive real-time payment and subscr
 | `subscription.cancelled` | Subscription cancelled — check `data.status` / `data.current_period_end`: period-end cancellation keeps access until that date, while dashboard or refund cancellation revokes it immediately |
 | `subscription.renewed` | Recurring payment successful |
 | `subscription.past_due` | Payment failed, subscription at risk |
-| `invoice.paid` / `invoice.payment_failed` | Invoice outcome — check `billing_reason` (`subscription_cycle` = renewal, `subscription_update` = plan switch, `subscription_create`, `purchase`). A paid renewal also sends `subscription.renewed`; a failed charge also sends `subscription.past_due` only with a grace period. A renewal with no usable card sends NO invoice event — see `subscription.payment_method_required` / `subscription.revoked` |
-| `order.paid` | One-time purchase completed |
+| `invoice.paid` / `invoice.payment_failed` | Invoice outcome. Invoices exist only for renewals and plan switches, so `billing_reason` is `subscription_cycle` or `subscription_update` and **never** `subscription_create` — a first payment produces no invoice. A paid renewal also sends `subscription.renewed`; a failed charge also sends `subscription.past_due` only with a grace period. A renewal with no usable card sends NO invoice event — see `subscription.payment_method_required` / `subscription.revoked` |
+| `order.paid` / `order.payment_failed` | An order was paid or failed — **not one-time purchases only**. A subscription's first payment is an order, not an invoice, so both events also carry `billing_reason: 'subscription_create'`, and these are the ONLY events that report that first charge. Handle both branches: `purchase` is the one-time buy, `subscription_create` the signup. An empty `subscription_create` branch silently loses every new subscriber |
 | `refund.created` | Refund initiated |
 
 ### All Supported Events (`WEBHOOK_EVENT_TYPES` in `recur-tw/server`)
@@ -97,13 +97,32 @@ export async function POST(request: Request) {
     // subscription.payment_method_required (grace) or subscription.revoked (no grace).
     // Handle those below, or you will miss those failures entirely.
     case 'invoice.paid':
-      // invoice.paid is not renewal-only: a plan switch pays an invoice too. Branch on
-      // billing_reason — 'subscription_cycle' is the renewal, 'subscription_update' the
-      // switch, 'subscription_create' the first payment, 'purchase' a one-off.
+      // Invoices exist only for renewals and plan switches, so billing_reason here is
+      // 'subscription_cycle' or 'subscription_update' — never 'subscription_create'.
+      // A subscription's FIRST payment produces no invoice at all; it arrives as
+      // order.paid. One-time purchases produce no invoice either.
       if (event.data.billing_reason === 'subscription_cycle') {
         await handleRenewal(event.data)        // extend access, record recurring revenue
       } else {
-        await handleInvoicePaid(event.data)    // switches, first payments, one-offs
+        await handleSwitchInvoice(event.data)  // 'subscription_update': the plan switch
+      }
+      break
+    case 'order.paid':
+      // Orders cover BOTH one-time buys and a subscription's first payment. Nothing else
+      // reports that first payment, so both branches have to do real work.
+      if (event.data.billing_reason === 'purchase') {
+        await handleOneTimePurchase(event.data)
+      } else {
+        await handleFirstSubscriptionPayment(event.data)   // 'subscription_create'
+      }
+      break
+    case 'order.payment_failed':
+      // Same split. A failed signup emits ONLY this event — no invoice.payment_failed
+      // follows it — so an empty branch here loses the failure entirely.
+      if (event.data.billing_reason === 'purchase') {
+        await handlePurchaseFailed(event.data)
+      } else {
+        await handleSignupFailed(event.data)               // 'subscription_create'
       }
       break
     case 'subscription.renewed':
@@ -143,8 +162,12 @@ async function handleSubscriptionCancelled(data: Payload) {
   // Period-end cancellation: keep access until current_period_end.
   // Immediate cancellation (dashboard, refund): status is already "canceled" — revoke now.
 }
-async function handleRenewal(data: Payload) {}        // billing_reason 'subscription_cycle'
-async function handleInvoicePaid(data: Payload) {}    // every other billing_reason
+async function handleRenewal(data: Payload) {}          // invoice, 'subscription_cycle'
+async function handleSwitchInvoice(data: Payload) {}    // invoice, 'subscription_update'
+async function handleOneTimePurchase(data: Payload) {}  // order, 'purchase'
+async function handleFirstSubscriptionPayment(data: Payload) {}  // order, 'subscription_create'
+async function handlePurchaseFailed(data: Payload) {}   // order failure, 'purchase'
+async function handleSignupFailed(data: Payload) {}     // order failure, 'subscription_create'
 async function handlePaymentFailure(data: Payload) {}
 async function handleRefundCreated(data: Payload) {}
 ```
@@ -154,12 +177,14 @@ async function handleRefundCreated(data: Payload) {}
 ```typescript
 import express from 'express'
 import { Recur } from 'recur-tw/server'
+// Your own dispatch — the claim-first version is in "Idempotency" below.
+import { handleEvent } from './handle-event'
 
 const app = express()
 const recur = new Recur(process.env.RECUR_SECRET_KEY!)
 
 // Use the raw body for signature verification
-app.post('/api/webhooks/recur', express.raw({ type: 'application/json' }), (req, res) => {
+app.post('/api/webhooks/recur', express.raw({ type: 'application/json' }), async (req, res) => {
   const payload = req.body.toString()
   const signature = req.header('x-recur-signature') ?? null
 
@@ -170,7 +195,14 @@ app.post('/api/webhooks/recur', express.raw({ type: 'application/json' }), (req,
     return res.status(401).json({ error: 'Invalid signature' })
   }
 
-  console.log('Received event:', event.type, event.id)   // envelope id: present on every event
+  // Dispatch before answering: a 2xx tells Recur the event is handled.
+  try {
+    await handleEvent(event)
+  } catch (err) {
+    console.error('webhook handler failed', event.id, err)
+    return res.status(500).json({ error: 'handler failed' })   // Recur retries
+  }
+
   res.json({ received: true })
 })
 ```
@@ -233,6 +265,8 @@ interface WebhookEvent {
 
 // Enum-derived fields (status, type, billing_reason, switch_type, reason) are lowercased
 // before delivery: "active", "canceled", "complete" — compare against lowercase values.
+// The REST API does NOT do this: the same field reads "SUBSCRIPTION_UPDATE" / "ACTIVE"
+// there (see openapi.json). Only webhook payloads are lowercased.
 
 // Example: checkout.completed
 {
@@ -290,7 +324,8 @@ MCP: `test_webhook` sends a test event to your endpoint; `get_webhook_events` sh
 
 ### 1. Always Verify Signatures
 
-Never trust webhook payloads without `recur.webhooks.verify()`.
+Never trust a webhook payload you have not verified — with `recur.webhooks.verify()`, or
+with one of the constant-time verifiers above if you are not using the SDK.
 
 ### 2. Handle Idempotency