@deiondz/better-auth-razorpay 2.0.3 → 2.0.5

package/README.md

@@ -725,7 +725,7 @@ type User = typeof authClient.$Infer.Session.user
 
 ## TanStack Query Hooks
 
-The plugin works with **TanStack Query**. We provide optional pre-built hooks that accept your auth client; when you use `razorpayClientPlugin()`, the hooks call `authClient.razorpay.*` so requests hit the correct paths. If you prefer a different setup, use `authClient.razorpay.getPlans()`, `authClient.razorpay.createOrUpdateSubscription(...)`, etc., or build your own hooks around those methods.
+The plugin works with **TanStack Query**. We provide optional pre-built hooks that get the auth client from React context; wrap your app once with **`<RazorpayAuthProvider client={authClient}>`** and use **`usePlans()`**, **`useSubscriptions()`**, etc. with **no client argument**. When you use `razorpayClientPlugin()`, the hooks call `authClient.razorpay.*` so requests hit the correct paths. If you prefer a different setup, use `authClient.razorpay.getPlans()`, `authClient.razorpay.createOrUpdateSubscription(...)`, etc., or build your own hooks around those methods.
 
 To use our pre-built hooks, install peer dependencies:
 
@@ -734,13 +734,14 @@ npm install @tanstack/react-query react
 # or yarn / pnpm / bun
 ```
 
-Import from `@deiondz/better-auth-razorpay/hooks` and pass your Better Auth client as the first argument:
+Import from `@deiondz/better-auth-razorpay/hooks` and wrap your app with **`RazorpayAuthProvider`** so hooks can read the client from context:
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { createAuthClient } from 'better-auth/react'
 import { razorpayClientPlugin } from '@deiondz/better-auth-razorpay/client'
 import {
+  RazorpayAuthProvider,
   usePlans,
   useSubscriptions,
   useCreateOrUpdateSubscription,
@@ -759,21 +760,23 @@ const authClient = createAuthClient<typeof auth>({
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <SubscriptionUI />
+      <RazorpayAuthProvider client={authClient}>
+        <SubscriptionUI />
+      </RazorpayAuthProvider>
     </QueryClientProvider>
   )
 }
 
 function SubscriptionUI() {
   // Plans (no auth required)
-  const { data: plans, isLoading: plansLoading } = usePlans(authClient)
+  const { data: plans, isLoading: plansLoading } = usePlans()
 
   // Current user's subscriptions (requires session)
-  const { data: subscriptions, isLoading: subsLoading } = useSubscriptions(authClient)
+  const { data: subscriptions, isLoading: subsLoading } = useSubscriptions()
 
-  const createOrUpdate = useCreateOrUpdateSubscription(authClient)
-  const cancel = useCancelSubscription(authClient)
-  const restore = useRestoreSubscription(authClient)
+  const createOrUpdate = useCreateOrUpdateSubscription()
+  const cancel = useCancelSubscription()
+  const restore = useRestoreSubscription()
 
   const handleSubscribe = () => {
     createOrUpdate.mutate(
@@ -821,11 +824,11 @@ function SubscriptionUI() {
 
 | Hook | Type | Description |
 |------|------|-------------|
-| `usePlans(client, options?)` | `useQuery` | Fetches configured plans (GET `/razorpay/get-plans`). |
-| `useSubscriptions(client, input?, options?)` | `useQuery` | Lists active/trialing subscriptions (GET `/razorpay/subscription/list`). Optional `referenceId` in input or options. |
-| `useCreateOrUpdateSubscription(client, options?)` | `useMutation` | Creates or updates subscription; returns `checkoutUrl`. Invalidates subscriptions list on success. |
-| `useCancelSubscription(client, options?)` | `useMutation` | Cancels by local subscription ID; optional `immediately`. Invalidates subscriptions list on success. |
-| `useRestoreSubscription(client, options?)` | `useMutation` | Restores a subscription scheduled to cancel. Invalidates subscriptions list on success. |
+| `usePlans(options?)` | `useQuery` | Fetches configured plans (GET `/razorpay/get-plans`). Requires `RazorpayAuthProvider` above in the tree. |
+| `useSubscriptions(input?, options?)` | `useQuery` | Lists active/trialing subscriptions (GET `/razorpay/subscription/list`). Optional `referenceId` in input or options. Requires `RazorpayAuthProvider`. |
+| `useCreateOrUpdateSubscription(options?)` | `useMutation` | Creates or updates subscription; returns `checkoutUrl`. Invalidates subscriptions list on success. Requires `RazorpayAuthProvider`. |
+| `useCancelSubscription(options?)` | `useMutation` | Cancels by local subscription ID; optional `immediately`. Invalidates subscriptions list on success. Requires `RazorpayAuthProvider`. |
+| `useRestoreSubscription(options?)` | `useMutation` | Restores a subscription scheduled to cancel. Invalidates subscriptions list on success. Requires `RazorpayAuthProvider`. |
 
 **Query keys** (for manual invalidation or prefetching):
 
@@ -1381,7 +1384,10 @@ async function initializeRazorpayCheckout(subscriptionId: string) {
 **1. "POST /api/auth/api/get 404" or Razorpay requests returning 404**
 - Add the **client plugin** to your auth client: `createAuthClient({ plugins: [razorpayClientPlugin(), ...] })`
 - Use **method-based API** instead of `authClient.api.get/post`: call `authClient.razorpay.getPlans()`, `authClient.razorpay.createOrUpdateSubscription(...)`, etc., so requests use the plugin’s route map and hit the correct paths
-- The TanStack hooks (`usePlans`, `useSubscriptions`, etc.) use `authClient.razorpay` when present, so they work correctly once the client plugin is added
+- Wrap your app with **`<RazorpayAuthProvider client={authClient}>`** so hooks get the client from context; use **`usePlans()`**, **`useSubscriptions()`**, etc. with no client argument
+- The TanStack hooks use `authClient.razorpay` when present, so they work correctly once the client plugin is added
+
+**For maintainers:** See [Razorpay plugin × Better Auth client (problem and solution)](docs/BETTER_AUTH_CLIENT_CONTEXT.md) for the 404/TypeScript root cause and plugin-side fixes.
 
 **2. "Plan not found in configured plans"**
 - Ensure the plan ID exists in Razorpay dashboard

package/client/hooks.ts

@@ -1,8 +1,9 @@
 /**
  * React hooks for Razorpay subscription features using TanStack Query.
- * Use with your Better Auth client: usePlans(authClient), useSubscriptions(authClient), etc.
+ * Wrap your app with <RazorpayAuthProvider client={authClient}> and use usePlans(), useSubscriptions(), etc. with no client argument.
  */
 
+import { createContext, useContext, createElement, type ReactNode } from 'react'
 import {
   useQuery,
   useMutation,
@@ -29,6 +30,37 @@ import type {
 
 const BASE = '/razorpay'
 
+const RAZORPAY_NO_CLIENT_MESSAGE =
+  'Razorpay hooks require wrapping your app with <RazorpayAuthProvider client={authClient}>.'
+
+const RAZORPAY_NO_RAZORPAY_OR_API_MESSAGE =
+  'Razorpay hooks require a client created with razorpayClientPlugin() in createAuthClient({ plugins: [...] }).'
+
+/** Context holding the Razorpay-capable auth client. Default is null. */
+export const RazorpayAuthContext = createContext<RazorpayAuthClient | null>(null)
+
+/** Provider that supplies the auth client to Razorpay hooks. Wrap your app once with client={authClient}. */
+export function RazorpayAuthProvider({
+  client,
+  children,
+}: {
+  client: RazorpayAuthClient | null
+  children: ReactNode
+}) {
+  return createElement(RazorpayAuthContext.Provider, { value: client }, children)
+}
+
+/** Returns the Razorpay-capable auth client from context, or null if not wrapped with RazorpayAuthProvider. */
+export function useRazorpayAuthClient(): RazorpayAuthClient | null {
+  return useContext(RazorpayAuthContext)
+}
+
+function requireRazorpayOrApi(client: RazorpayAuthClient): void {
+  if (!client.razorpay && !client.api) {
+    throw new Error(RAZORPAY_NO_RAZORPAY_OR_API_MESSAGE)
+  }
+}
+
 /** Query keys for cache invalidation. */
 export const razorpayQueryKeys = {
   all: ['razorpay'] as const,
@@ -48,9 +80,10 @@ function assertSuccess<T>(res: unknown): asserts res is { success: true; data: T
 
 /** Fetch plans (GET /razorpay/get-plans). Prefers client.razorpay when available to avoid 404s. */
 async function fetchPlans(client: RazorpayAuthClient): Promise<PlanSummary[]> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.getPlans()
-    : await client.api.get(`${BASE}/get-plans`)
+    : await client.api!.get(`${BASE}/get-plans`)
   assertSuccess<PlanSummary[]>(res)
   return res.data
 }
@@ -60,16 +93,17 @@ async function fetchSubscriptions(
   client: RazorpayAuthClient,
   input?: ListSubscriptionsInput
 ): Promise<ListSubscriptionsResponse['data']> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.listSubscriptions(input)
     : (() => {
-        const query: Record<string, string> = {}
-        if (input?.referenceId) query.referenceId = input.referenceId
-        const path = `${BASE}/subscription/list`
-        return Object.keys(query).length > 0
-          ? client.api.get(path, { query })
-          : client.api.get(path)
-      })()
+      const query: Record<string, string> = {}
+      if (input?.referenceId) query.referenceId = input.referenceId
+      const path = `${BASE}/subscription/list`
+      return Object.keys(query).length > 0
+        ? client.api!.get(path, { query })
+        : client.api!.get(path)
+    })()
   assertSuccess<ListSubscriptionsResponse['data']>(res)
   return res.data
 }
@@ -79,11 +113,12 @@ async function createOrUpdateSubscription(
   client: RazorpayAuthClient,
   input: CreateOrUpdateSubscriptionInput
 ): Promise<CreateOrUpdateSubscriptionResponse['data']> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.createOrUpdateSubscription(input)
-    : await client.api.post(`${BASE}/subscription/create-or-update`, {
-        body: input as unknown as Record<string, unknown>,
-      })
+    : await client.api!.post(`${BASE}/subscription/create-or-update`, {
+      body: input as unknown as Record<string, unknown>,
+    })
   assertSuccess<CreateOrUpdateSubscriptionResponse['data']>(res)
   return res.data
 }
@@ -93,11 +128,12 @@ async function cancelSubscription(
   client: RazorpayAuthClient,
   input: CancelSubscriptionInput
 ): Promise<CancelSubscriptionResponse['data']> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.cancelSubscription(input)
-    : await client.api.post(`${BASE}/subscription/cancel`, {
-        body: input as unknown as Record<string, unknown>,
-      })
+    : await client.api!.post(`${BASE}/subscription/cancel`, {
+      body: input as unknown as Record<string, unknown>,
+    })
   assertSuccess<CancelSubscriptionResponse['data']>(res)
   return res.data
 }
@@ -107,11 +143,12 @@ async function restoreSubscription(
   client: RazorpayAuthClient,
   input: RestoreSubscriptionInput
 ): Promise<RestoreSubscriptionResponse['data']> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.restoreSubscription(input)
-    : await client.api.post(`${BASE}/subscription/restore`, {
-        body: input as unknown as Record<string, unknown>,
-      })
+    : await client.api!.post(`${BASE}/subscription/restore`, {
+      body: input as unknown as Record<string, unknown>,
+    })
   assertSuccess<RestoreSubscriptionResponse['data']>(res)
   return res.data
 }
@@ -121,11 +158,12 @@ async function verifyPayment(
   client: RazorpayAuthClient,
   input: VerifyPaymentInput
 ): Promise<VerifyPaymentResponse['data']> {
+  requireRazorpayOrApi(client)
   const res = client.razorpay
     ? await client.razorpay.verifyPayment(input)
-    : await client.api.post(`${BASE}/verify-payment`, {
-        body: input as unknown as Record<string, unknown>,
-      })
+    : await client.api!.post(`${BASE}/verify-payment`, {
+      body: input as unknown as Record<string, unknown>,
+    })
   assertSuccess<VerifyPaymentResponse['data']>(res)
   return res.data
 }
@@ -137,11 +175,10 @@ export type UsePlansOptions = Omit<
 
 /**
  * Fetch configured subscription plans (no auth required).
+ * Requires RazorpayAuthProvider above in the tree.
  */
-export function usePlans(
-  client: RazorpayAuthClient | null | undefined,
-  options?: UsePlansOptions
-) {
+export function usePlans(options?: UsePlansOptions) {
+  const client = useRazorpayAuthClient()
   return useQuery({
     queryKey: razorpayQueryKeys.plans(),
     queryFn: () => fetchPlans(client!),
@@ -162,12 +199,13 @@ export type UseSubscriptionsOptions = Omit<
 
 /**
  * List active/trialing subscriptions for the current user (or referenceId).
+ * Requires RazorpayAuthProvider above in the tree.
  */
 export function useSubscriptions(
-  client: RazorpayAuthClient | null | undefined,
   input?: ListSubscriptionsInput,
   options?: UseSubscriptionsOptions
 ) {
+  const client = useRazorpayAuthClient()
   const { referenceId, ...queryOptions } = options ?? {}
   const refId = input?.referenceId ?? referenceId
   return useQuery({
@@ -188,15 +226,18 @@ export type UseCreateOrUpdateSubscriptionOptions = UseMutationOptions<
 /**
  * Create or update a subscription. Returns checkoutUrl for Razorpay payment page.
  * Invalidates subscriptions list on success.
+ * Requires RazorpayAuthProvider above in the tree.
  */
 export function useCreateOrUpdateSubscription(
-  client: RazorpayAuthClient | null | undefined,
   options?: UseCreateOrUpdateSubscriptionOptions
 ) {
+  const client = useRazorpayAuthClient()
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: (input: CreateOrUpdateSubscriptionInput) =>
-      createOrUpdateSubscription(client!, input),
+    mutationFn: (input: CreateOrUpdateSubscriptionInput) => {
+      if (!client) throw new Error(RAZORPAY_NO_CLIENT_MESSAGE)
+      return createOrUpdateSubscription(client, input)
+    },
     ...options,
     onSuccess: (data, variables, onMutateResult, context) => {
       queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.subscriptions() })
@@ -215,14 +256,16 @@ export type UseCancelSubscriptionOptions = UseMutationOptions<
 /**
  * Cancel a subscription by local subscription ID (at period end or immediately).
  * Invalidates subscriptions list on success.
+ * Requires RazorpayAuthProvider above in the tree.
  */
-export function useCancelSubscription(
-  client: RazorpayAuthClient | null | undefined,
-  options?: UseCancelSubscriptionOptions
-) {
+export function useCancelSubscription(options?: UseCancelSubscriptionOptions) {
+  const client = useRazorpayAuthClient()
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: (input: CancelSubscriptionInput) => cancelSubscription(client!, input),
+    mutationFn: (input: CancelSubscriptionInput) => {
+      if (!client) throw new Error(RAZORPAY_NO_CLIENT_MESSAGE)
+      return cancelSubscription(client, input)
+    },
     ...options,
     onSuccess: (data, variables, onMutateResult, context) => {
       queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.subscriptions() })
@@ -261,14 +304,16 @@ export type {
 /**
  * Restore a subscription that was scheduled to cancel at period end.
  * Invalidates subscriptions list on success.
+ * Requires RazorpayAuthProvider above in the tree.
  */
-export function useRestoreSubscription(
-  client: RazorpayAuthClient | null | undefined,
-  options?: UseRestoreSubscriptionOptions
-) {
+export function useRestoreSubscription(options?: UseRestoreSubscriptionOptions) {
+  const client = useRazorpayAuthClient()
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: (input: RestoreSubscriptionInput) => restoreSubscription(client!, input),
+    mutationFn: (input: RestoreSubscriptionInput) => {
+      if (!client) throw new Error(RAZORPAY_NO_CLIENT_MESSAGE)
+      return restoreSubscription(client, input)
+    },
     ...options,
     onSuccess: (data, variables, onMutateResult, context) => {
       queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.subscriptions() })
@@ -288,14 +333,16 @@ export type UseVerifyPaymentOptions = UseMutationOptions<
  * Verify payment signature after Razorpay checkout success.
  * Call with the payload from the Razorpay success handler (razorpay_payment_id, razorpay_subscription_id, razorpay_signature).
  * Invalidates subscriptions list on success.
+ * Requires RazorpayAuthProvider above in the tree.
  */
-export function useVerifyPayment(
-  client: RazorpayAuthClient | null | undefined,
-  options?: UseVerifyPaymentOptions
-) {
+export function useVerifyPayment(options?: UseVerifyPaymentOptions) {
+  const client = useRazorpayAuthClient()
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: (input: VerifyPaymentInput) => verifyPayment(client!, input),
+    mutationFn: (input: VerifyPaymentInput) => {
+      if (!client) throw new Error(RAZORPAY_NO_CLIENT_MESSAGE)
+      return verifyPayment(client, input)
+    },
     ...options,
     onSuccess: (data, variables, onMutateResult, context) => {
       queryClient.invalidateQueries({ queryKey: razorpayQueryKeys.subscriptions() })

package/client/types.ts

@@ -91,10 +91,14 @@ export interface RazorpayClientActions {
 
 /**
  * Minimal auth client interface for Razorpay hooks.
- * When using the client plugin (razorpayClientPlugin()), authClient.razorpay is set and hooks use it so requests hit the correct paths (avoids 404s from api.get/post).
+ * Primary: razorpay is set when razorpayClientPlugin() is used in createAuthClient({ plugins: [...] }); prefer it so requests hit the correct paths.
+ * Fallback: api is optional for custom clients that implement path-based api.get/api.post.
  */
 export interface RazorpayAuthClient {
-  api: {
+  /** Set when razorpayClientPlugin() is used in createAuthClient({ plugins: [razorpayClientPlugin()] }). Prefer these methods over api.get/post. */
+  razorpay?: RazorpayClientActions
+  /** Optional; for custom clients that implement path-based api.get/post. */
+  api?: {
     get: (
       path: string,
       options?: { query?: Record<string, string> }
@@ -104,8 +108,6 @@ export interface RazorpayAuthClient {
       options?: { body?: Record<string, unknown> }
     ) => Promise<RazorpayApiResult<unknown>>
   }
-  /** Set when razorpayClientPlugin() is used in createAuthClient({ plugins: [razorpayClientPlugin()] }). Prefer these methods over api.get/post. */
-  razorpay?: RazorpayClientActions
 }
 
 /** Input for create-or-update subscription. */

package/lib/types.ts

@@ -75,6 +75,7 @@ export interface RazorpayPlan {
   name: string
   monthlyPlanId: string
   annualPlanId?: string
+  description?: string
   limits?: PlanLimits
   freeTrial?: PlanFreeTrial
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deiondz/better-auth-razorpay",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Better Auth plugin for Razorpay subscriptions and payments",
   "type": "module",
   "main": "./index.ts",