@deiondz/better-auth-razorpay 1.0.0 → 2.0.0

package/lib/types.ts

@@ -1,6 +1,5 @@
 /**
- * Razorpay subscription response interface from the Razorpay API.
- * This represents the full subscription object returned by Razorpay API calls.
+ * Razorpay subscription response from the Razorpay API.
  */
 export interface RazorpaySubscription {
   id: string
@@ -29,33 +28,103 @@ export interface RazorpaySubscription {
   remaining_count: string
 }
 
-/**
- * Subscription record stored in the auth adapter.
- */
-export interface RazorpaySubscriptionRecord {
-  userId: string
-  subscriptionId: string
-  planId: string
-  status: string
+/** Local subscription status aligned with Razorpay and plugin lifecycle. */
+export type SubscriptionStatus =
+  | 'created'
+  | 'active'
+  | 'pending'
+  | 'halted'
+  | 'cancelled'
+  | 'completed'
+  | 'expired'
+  | 'trialing'
+
+/** Local subscription record stored in the auth adapter. */
+export interface SubscriptionRecord {
+  id: string
+  plan: string
+  referenceId: string
+  razorpayCustomerId?: string | null
+  razorpaySubscriptionId?: string | null
+  status: SubscriptionStatus
+  trialStart?: Date | null
+  trialEnd?: Date | null
+  periodStart?: Date | null
+  periodEnd?: Date | null
+  cancelAtPeriodEnd: boolean
+  seats: number
+  groupId?: string | null
+  createdAt: Date
+  updatedAt: Date
 }
 
-/**
- * User record shape used by the Razorpay plugin.
- */
+/** Plan limits (customizable per plan). */
+export interface PlanLimits {
+  [key: string]: number
+}
+
+/** Free trial configuration for a plan. */
+export interface PlanFreeTrial {
+  days: number
+  onTrialStart?: (subscription: SubscriptionRecord) => Promise<void>
+  onTrialEnd?: (args: { subscription: SubscriptionRecord }) => Promise<void>
+}
+
+/** Named plan with monthly/annual Razorpay plan IDs and optional trial. */
+export interface RazorpayPlan {
+  name: string
+  monthlyPlanId: string
+  annualPlanId?: string
+  limits?: PlanLimits
+  freeTrial?: PlanFreeTrial
+}
+
+/** Subscription plugin options (plans, callbacks, authorization). */
+export interface SubscriptionOptions {
+  enabled: boolean
+  plans: RazorpayPlan[] | (() => Promise<RazorpayPlan[]>)
+  requireEmailVerification?: boolean
+  authorizeReference?: (args: {
+    user: { id: string; email?: string; name?: string; [key: string]: unknown }
+    referenceId: string
+    action: string
+  }) => Promise<boolean>
+  getSubscriptionCreateParams?: (args: {
+    user: { id: string; email?: string; name?: string; [key: string]: unknown }
+    session: unknown
+    plan: RazorpayPlan
+    subscription: SubscriptionRecord
+  }) => Promise<{ params?: Record<string, unknown> }>
+  onSubscriptionCreated?: (args: {
+    razorpaySubscription: RazorpaySubscription
+    subscription: SubscriptionRecord
+    plan: RazorpayPlan
+  }) => Promise<void>
+  onSubscriptionActivated?: (args: {
+    event: string
+    razorpaySubscription: RazorpaySubscription
+    subscription: SubscriptionRecord
+    plan: RazorpayPlan
+  }) => Promise<void>
+  onSubscriptionUpdate?: (args: { event: string; subscription: SubscriptionRecord }) => Promise<void>
+  onSubscriptionCancel?: (args: {
+    event: string
+    razorpaySubscription: RazorpaySubscription
+    subscription: SubscriptionRecord
+  }) => Promise<void>
+}
+
+/** User record shape used by the Razorpay plugin (customer ID on user). */
 export interface RazorpayUserRecord {
   id: string
   email?: string
   name?: string
-  subscriptionId?: string
-  subscriptionPlanId?: string
-  subscriptionStatus?: string
-  subscriptionCurrentPeriodEnd?: Date | null
-  cancelAtPeriodEnd?: boolean
-  lastPaymentDate?: Date | null
-  nextBillingDate?: Date | null
+  razorpayCustomerId?: string | null
+  [key: string]: unknown
 }
 
-type RazorpayWebhookEvent =
+/** Razorpay webhook event types. */
+export type RazorpayWebhookEvent =
   | 'subscription.authenticated'
   | 'subscription.activated'
   | 'subscription.charged'
@@ -64,8 +133,9 @@ type RazorpayWebhookEvent =
   | 'subscription.resumed'
   | 'subscription.pending'
   | 'subscription.halted'
+  | 'subscription.expired'
 
-interface RazorpayWebhookPayload {
+export interface RazorpayWebhookPayload {
   event: RazorpayWebhookEvent
   subscription: {
     id: string
@@ -73,79 +143,62 @@ interface RazorpayWebhookPayload {
     status: string
     current_start?: number
     current_end?: number
-    [key: string]: unknown // Allow other Razorpay subscription fields
+    [key: string]: unknown
   }
   payment?: {
     id: string
     amount: number
     currency: string
-    [key: string]: unknown // Allow other Razorpay payment fields
+    [key: string]: unknown
   }
 }
 
-interface RazorpayWebhookContext {
+export interface RazorpayWebhookContext {
   userId: string
-  user: {
-    id: string
-    email: string
-    name: string
-    [key: string]: unknown // Allow other user fields
-  }
+  user: { id: string; email?: string; name?: string; [key: string]: unknown }
 }
 
-/**
- * Callback function invoked after webhook events are processed.
- * Can be used for any custom logic: emails, notifications, analytics, integrations, etc.
- */
-type OnWebhookEventCallback = (
+export type OnWebhookEventCallback = (
   payload: RazorpayWebhookPayload,
   context: RazorpayWebhookContext
 ) => Promise<void>
 
-interface RazorpayPluginOptions {
-  keyId: string
-  keySecret: string
-  webhookSecret?: string
-  plans: string[] // Array of plan IDs from Razorpay dashboard
-  /**
-   * Optional callback function invoked after webhook events are processed.
-   * Use this for any custom logic: sending emails, updating external systems,
-   * analytics tracking, integrations, or any other business logic.
-   */
+/** Main plugin options: client, webhook secret, customer creation, subscription config, callbacks. */
+export interface RazorpayPluginOptions {
+  /** Initialized Razorpay client instance. */
+  razorpayClient: import('razorpay')
+  /** Webhook secret for signature verification. */
+  razorpayWebhookSecret?: string
+  /** Create Razorpay customer when user signs up. Default: false. */
+  createCustomerOnSignUp?: boolean
+  /** Called after a Razorpay customer is created. */
+  onCustomerCreate?: (args: {
+    user: RazorpayUserRecord
+    razorpayCustomer: { id: string; [key: string]: unknown }
+  }) => Promise<void>
+  /** Custom params (e.g. notes) when creating Razorpay customer. */
+  getCustomerCreateParams?: (args: {
+    user: RazorpayUserRecord
+    session: unknown
+  }) => Promise<{ params?: Record<string, unknown> }>
+  /** Subscription feature config (plans, callbacks). */
+  subscription?: SubscriptionOptions
+  /** Global callback for all processed webhook events. */
+  onEvent?: (event: { event: string; [key: string]: unknown }) => Promise<void>
+  /** Legacy: callback after webhook events are processed (payload + context). */
   onWebhookEvent?: OnWebhookEventCallback
 }
 
-/**
- * Standard success response structure for Razorpay API endpoints.
- */
 export interface RazorpaySuccessResponse<T = unknown> {
   success: true
   data: T
 }
 
-/**
- * Standard error response structure for Razorpay API endpoints.
- */
 export interface RazorpayErrorResponse {
   success: false
-  error: {
-    code: string
-    description: string
-    [key: string]: unknown // Allow additional error metadata
-  }
+  error: { code: string; description: string; [key: string]: unknown }
 }
 
-/**
- * Union type for all Razorpay API responses.
- */
 export type RazorpayApiResponse<T = unknown> =
   | RazorpaySuccessResponse<T>
   | RazorpayErrorResponse
-
-export type {
-  RazorpayPluginOptions,
-  RazorpayWebhookEvent,
-  RazorpayWebhookPayload,
-  RazorpayWebhookContext,
-  OnWebhookEventCallback,
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deiondz/better-auth-razorpay",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Better Auth plugin for Razorpay subscriptions and payments",
   "type": "module",
   "main": "./index.ts",
@@ -15,11 +15,17 @@
       "types": "./client.ts",
       "import": "./client.ts",
       "default": "./client.ts"
+    },
+    "./hooks": {
+      "types": "./client/hooks.ts",
+      "import": "./client/hooks.ts",
+      "default": "./client/hooks.ts"
     }
   },
   "files": [
     "index.ts",
     "client.ts",
+    "client",
     "api",
     "lib",
     "README.md",
@@ -43,13 +49,17 @@
     "url": "git+https://github.com/deiondz/better-auth-razorpay.git"
   },
   "peerDependencies": {
-    "better-auth": "^1.0.0"
+    "@tanstack/react-query": "^5.0.0",
+    "better-auth": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
     "razorpay": "^2.9.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0",
     "typescript": "^5.0.0"
   },
   "engines": {

package/api/get-subscription.ts

@@ -1,174 +0,0 @@
-import { createAuthEndpoint, sessionMiddleware } from 'better-auth/api'
-import type Razorpay from 'razorpay'
-import {
-  handleRazorpayError,
-  type RazorpaySubscription,
-  type RazorpayUserRecord,
-} from '../lib'
-
-/**
- * Retrieves the current subscription details for the authenticated user.
- *
- * @param razorpay - The Razorpay instance initialized with API credentials
- * @returns A Better Auth endpoint handler
- *
- * @remarks
- * This endpoint:
- * - Requires user authentication via session
- * - Fetches subscription details from Razorpay API
- * - Includes cancellation status and period end information
- * - Returns null if user has no active subscription
- * - Provides detailed error messages in development mode
- *
- * @example
- * Response (success):
- * ```json
- * {
- *   "success": true,
- *   "data": {
- *     "id": "sub_1234567890",
- *     "status": "active",
- *     "plan_id": "plan_1234567890",
- *     "cancel_at_period_end": false,
- *     ...
- *   }
- * }
- * ```
- */
-export const getSubscription = (razorpay: Razorpay) =>
-  createAuthEndpoint(
-    '/razorpay/get-subscription',
-    { method: 'GET', use: [sessionMiddleware] },
-    async (_ctx) => {
-      try {
-        // Get user ID from session
-        const userId = _ctx.context.session?.user?.id
-
-        if (!userId) {
-          return {
-            success: false,
-            error: {
-              code: 'UNAUTHORIZED',
-              description: 'User not authenticated',
-            },
-          }
-        }
-
-        // Get user record to check subscription status
-        const user = (await _ctx.context.adapter.findOne({
-          model: 'user',
-          where: [{ field: 'id', value: userId }],
-        })) as RazorpayUserRecord | null
-
-        if (!user) {
-          return {
-            success: false,
-            error: {
-              code: 'USER_NOT_FOUND',
-              description: 'User not found',
-            },
-          }
-        }
-
-        // Check subscription status from user table
-        const subscriptionId = user.subscriptionId
-
-        if (!subscriptionId) {
-          return {
-            success: true,
-            data: null,
-          }
-        }
-
-        // Fetch full subscription details from Razorpay API
-        try {
-          const subscription = (await razorpay.subscriptions.fetch(
-            subscriptionId
-          )) as RazorpaySubscription
-
-          // Read cancellation status from user table
-          const cancelAtPeriodEnd = user.cancelAtPeriodEnd ?? false
-          const subscriptionCurrentPeriodEnd = user.subscriptionCurrentPeriodEnd
-
-          return {
-            success: true,
-            data: {
-              id: subscription.id,
-              entity: subscription.entity,
-              plan_id: subscription.plan_id,
-              status: subscription.status,
-              current_start: subscription.current_start,
-              current_end: subscription.current_end,
-              ended_at: subscription.ended_at,
-              quantity: subscription.quantity,
-              notes: subscription.notes,
-              charge_at: subscription.charge_at,
-              start_at: subscription.start_at,
-              end_at: subscription.end_at,
-              auth_attempts: subscription.auth_attempts,
-              total_count: subscription.total_count,
-              paid_count: subscription.paid_count,
-              customer_notify: subscription.customer_notify,
-              created_at: subscription.created_at,
-              expire_by: subscription.expire_by,
-              short_url: subscription.short_url,
-              has_scheduled_changes: subscription.has_scheduled_changes,
-              change_scheduled_at: subscription.change_scheduled_at,
-              source: subscription.source,
-              offer_id: subscription.offer_id,
-              remaining_count: subscription.remaining_count,
-              cancel_at_period_end: cancelAtPeriodEnd,
-              subscription_current_period_end: subscriptionCurrentPeriodEnd
-                ? Math.floor(new Date(subscriptionCurrentPeriodEnd).getTime() / 1000)
-                : null,
-            },
-          }
-        } catch (razorpayError) {
-          // Handle Razorpay-specific errors with subscription ID context
-          const isDev = process.env.NODE_ENV === 'development'
-
-          // Extract error message from Razorpay error
-          let errorMessage = 'Failed to fetch subscription'
-          let errorCode = 'SUBSCRIPTION_FETCH_FAILED'
-
-          if (razorpayError && typeof razorpayError === 'object') {
-            // Razorpay error format: { error: { code: string, description: string } }
-            if ('error' in razorpayError) {
-              const razorpayErr = razorpayError as {
-                error?: { code?: string; description?: string }
-              }
-              errorCode = razorpayErr.error?.code || errorCode
-              errorMessage = razorpayErr.error?.description || errorMessage
-            } else if ('message' in razorpayError) {
-              errorMessage = (razorpayError as { message: string }).message
-            }
-          }
-
-          // Check if error is specifically about subscription not existing
-          const isNotFoundError =
-            errorMessage.toLowerCase().includes('does not exist') ||
-            errorMessage.toLowerCase().includes('not found') ||
-            errorCode === 'BAD_REQUEST_ERROR'
-
-          // Include subscription ID in error for debugging
-          const description = isDev
-            ? `${errorMessage} (Subscription ID: ${subscriptionId})`
-            : isNotFoundError
-              ? 'The subscription could not be found. This may indicate the subscription was deleted or the ID is invalid. Please contact support if this issue persists.'
-              : 'Unable to retrieve subscription information. Please try again or contact support if this issue persists.'
-
-          return {
-            success: false,
-            error: {
-              code: errorCode,
-              description,
-              // Include subscription ID in metadata for development
-              ...(isDev && { subscriptionId }),
-            },
-          }
-        }
-      } catch (error) {
-        return handleRazorpayError(error)
-      }
-    }
-  )

package/api/pause-subscription.ts

@@ -1,138 +0,0 @@
-import { createAuthEndpoint, sessionMiddleware } from 'better-auth/api'
-import type Razorpay from 'razorpay'
-import {
-  handleRazorpayError,
-  pauseSubscriptionSchema,
-  type RazorpaySubscription,
-  type RazorpaySubscriptionRecord,
-} from '../lib'
-
-/**
- * Pauses an active subscription.
- *
- * @param razorpay - The Razorpay instance initialized with API credentials
- * @returns A Better Auth endpoint handler
- *
- * @remarks
- * This endpoint:
- * - Requires user authentication via session
- * - Verifies subscription ownership before pausing
- * - Pauses the subscription via Razorpay API
- * - Updates subscription and user records with paused status
- * - Paused subscriptions can be resumed later
- *
- * @example
- * Request body:
- * ```json
- * {
- *   "subscription_id": "sub_1234567890"
- * }
- * ```
- */
-export const pauseSubscription = (razorpay: Razorpay) =>
-  createAuthEndpoint(
-    '/razorpay/pause-subscription',
-    { method: 'POST', use: [sessionMiddleware] },
-    async (_ctx) => {
-      try {
-        // Validate input using Zod schema
-        const validatedInput = pauseSubscriptionSchema.parse(_ctx.body)
-
-        // Get user ID from session
-        const userId = _ctx.context.session?.user?.id
-
-        if (!userId) {
-          return {
-            success: false,
-            error: {
-              code: 'UNAUTHORIZED',
-              description: 'User not authenticated',
-            },
-          }
-        }
-
-        // Get subscription record to verify it belongs to the user
-        const subscriptionRecord = (await _ctx.context.adapter.findOne({
-          model: 'razorpaySubscription',
-          where: [{ field: 'subscriptionId', value: validatedInput.subscription_id }],
-        })) as RazorpaySubscriptionRecord | null
-
-        if (!subscriptionRecord) {
-          return {
-            success: false,
-            error: {
-              code: 'SUBSCRIPTION_NOT_FOUND',
-              description: 'Subscription not found',
-            },
-          }
-        }
-
-        // Verify that the subscription belongs to the authenticated user
-        const subscriptionUserId = subscriptionRecord.userId
-        if (subscriptionUserId !== userId) {
-          return {
-            success: false,
-            error: {
-              code: 'UNAUTHORIZED',
-              description: 'Subscription does not belong to authenticated user',
-            },
-          }
-        }
-
-        // Pause subscription via Razorpay API
-        const subscription = (await razorpay.subscriptions.pause(
-          validatedInput.subscription_id
-        )) as RazorpaySubscription
-
-        // Update subscription status in database
-        await _ctx.context.adapter.update({
-          model: 'razorpaySubscription',
-          where: [{ field: 'subscriptionId', value: validatedInput.subscription_id }],
-          update: { status: subscription.status },
-        })
-
-        // Update user table with subscription status
-        await _ctx.context.adapter.update({
-          model: 'user',
-          where: [{ field: 'id', value: userId }],
-          update: {
-            data: {
-              subscriptionStatus: subscription.status,
-            },
-          },
-        })
-
-        return {
-          success: true,
-          data: {
-            id: subscription.id,
-            entity: subscription.entity,
-            plan_id: subscription.plan_id,
-            status: subscription.status,
-            current_start: subscription.current_start,
-            current_end: subscription.current_end,
-            ended_at: subscription.ended_at,
-            quantity: subscription.quantity,
-            notes: subscription.notes,
-            charge_at: subscription.charge_at,
-            start_at: subscription.start_at,
-            end_at: subscription.end_at,
-            auth_attempts: subscription.auth_attempts,
-            total_count: subscription.total_count,
-            paid_count: subscription.paid_count,
-            customer_notify: subscription.customer_notify,
-            created_at: subscription.created_at,
-            expire_by: subscription.expire_by,
-            short_url: subscription.short_url,
-            has_scheduled_changes: subscription.has_scheduled_changes,
-            change_scheduled_at: subscription.change_scheduled_at,
-            source: subscription.source,
-            offer_id: subscription.offer_id,
-            remaining_count: subscription.remaining_count,
-          },
-        }
-      } catch (error) {
-        return handleRazorpayError(error)
-      }
-    }
-  )