@deiondz/better-auth-razorpay 1.0.0

package/index.ts

@@ -0,0 +1,123 @@
+import type { BetterAuthPlugin } from 'better-auth'
+import Razorpay from 'razorpay'
+import {
+  cancelSubscription,
+  getPlans,
+  getSubscription,
+  pauseSubscription,
+  resumeSubscription,
+  subscribe,
+  verifyPayment,
+  webhook,
+} from './api'
+import type { RazorpayPluginOptions } from './lib'
+
+/**
+ * Razorpay plugin for Better Auth.
+ *
+ * Provides subscription management functionality including:
+ * - Creating subscriptions
+ * - Managing subscription lifecycle (pause, resume, cancel)
+ * - Payment verification
+ * - Webhook handling for subscription events
+ * - Plan retrieval
+ *
+ * @param options - Plugin configuration options
+ * @param options.keyId - Razorpay key ID (required)
+ * @param options.keySecret - Razorpay key secret (required)
+ * @param options.webhookSecret - Webhook secret for signature verification (optional)
+ * @param options.plans - Array of plan IDs from Razorpay dashboard (required)
+ * @param options.onWebhookEvent - Optional callback for custom webhook event handling
+ * @returns Better Auth plugin configuration
+ *
+ * @throws {Error} If keyId or keySecret are not provided
+ *
+ * @example
+ * ```typescript
+ * import { razorpayPlugin } from '@better-auth/razorpay'
+ *
+ * const auth = betterAuth({
+ *   plugins: [
+ *     razorpayPlugin({
+ *       keyId: process.env.RAZORPAY_KEY_ID!,
+ *       keySecret: process.env.RAZORPAY_KEY_SECRET!,
+ *       webhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
+ *       plans: ['plan_1234567890', 'plan_0987654321'],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export const razorpayPlugin = (options: RazorpayPluginOptions) => {
+  const { keyId, keySecret, webhookSecret, plans, onWebhookEvent } = options
+
+  if (!keyId || !keySecret) {
+    throw new Error('Razorpay keyId and keySecret are required')
+  }
+
+  // Initialize Razorpay instance once in plugin closure
+  // This instance is accessible to all endpoints via closure scope
+  const razorpay = new Razorpay({
+    key_id: keyId,
+    key_secret: keySecret,
+  })
+
+  return {
+    id: 'razorpay-plugin',
+
+    schema: {
+      user: {
+        fields: {
+          subscriptionId: { type: 'string', required: false },
+          subscriptionPlanId: { type: 'string', required: false },
+          subscriptionStatus: { type: 'string', required: false },
+          subscriptionCurrentPeriodEnd: { type: 'date', required: false },
+          cancelAtPeriodEnd: { type: 'boolean', required: false },
+          lastPaymentDate: { type: 'date', required: false },
+          nextBillingDate: { type: 'date', required: false },
+        },
+      },
+      razorpayCustomer: {
+        fields: {
+          userId: { type: 'string', unique: true },
+          razorpayCustomerId: { type: 'string', unique: true },
+        },
+      },
+      razorpaySubscription: {
+        fields: {
+          userId: { type: 'string' },
+          subscriptionId: { type: 'string' },
+          planId: { type: 'string' },
+          status: { type: 'string' },
+        },
+      },
+    },
+
+    endpoints: {
+      subscribe: subscribe(razorpay, plans),
+      'get-plans': getPlans(razorpay, plans),
+      'verify-payment': verifyPayment(keySecret),
+      webhook: webhook(webhookSecret, onWebhookEvent),
+      'get-subscription': getSubscription(razorpay),
+      'pause-subscription': pauseSubscription(razorpay),
+      'cancel-subscription': cancelSubscription(razorpay),
+      'resume-subscription': resumeSubscription(razorpay),
+    },
+  } satisfies BetterAuthPlugin
+}
+
+// Re-export types for external usage
+export type {
+  OnWebhookEventCallback,
+  RazorpayApiResponse,
+  RazorpayErrorResponse,
+  RazorpayPluginOptions,
+  RazorpaySubscription,
+  RazorpaySubscriptionRecord,
+  RazorpaySuccessResponse,
+  RazorpayUserRecord,
+  RazorpayWebhookContext,
+  RazorpayWebhookEvent,
+  RazorpayWebhookPayload,
+} from './lib'
+export type { WebhookResult } from './api/webhook'

package/lib/error-handler.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+/**
+ * Helper function to handle Razorpay-related errors and reduce complexity.
+ * Handles various error types including validation, network, timeout, and Razorpay API errors.
+ */
+function handleRazorpayError(error: unknown): {
+  success: false
+  error: { code: string; description: string }
+} {
+  // Handle Zod validation errors
+  if (error instanceof z.ZodError) {
+    return {
+      success: false,
+      error: {
+        code: 'INVALID_REQUEST',
+        description: error.issues[0]?.message || 'Validation failed',
+      },
+    }
+  }
+
+  // Handle network errors (fetch/axios network failures)
+  if (error && typeof error === 'object') {
+    // Check for network error indicators
+    const errorObj = error as Record<string, unknown>
+    if (
+      'code' in errorObj &&
+      (errorObj.code === 'ECONNREFUSED' ||
+        errorObj.code === 'ENOTFOUND' ||
+        errorObj.code === 'ETIMEDOUT' ||
+        errorObj.code === 'ECONNRESET')
+    ) {
+      return {
+        success: false,
+        error: {
+          code: 'NETWORK_ERROR',
+          description: 'Network connection failed. Please check your internet connection and try again.',
+        },
+      }
+    }
+
+    // Handle timeout errors
+    if (
+      'name' in errorObj &&
+      (errorObj.name === 'TimeoutError' ||
+        errorObj.name === 'AbortError' ||
+        (typeof errorObj.message === 'string' &&
+          errorObj.message.toLowerCase().includes('timeout')))
+    ) {
+      return {
+        success: false,
+        error: {
+          code: 'TIMEOUT_ERROR',
+          description: 'Request timed out. Please try again.',
+        },
+      }
+    }
+
+    // Handle Razorpay error format: { error: { code: string, description: string } }
+    if ('error' in errorObj) {
+      const razorpayError = errorObj as {
+        error?: { code?: string; description?: string; field?: string }
+      }
+      return {
+        success: false,
+        error: {
+          code: razorpayError.error?.code || 'RAZORPAY_ERROR',
+          description:
+            razorpayError.error?.description ||
+            razorpayError.error?.field
+              ? `Razorpay error: ${razorpayError.error.field}`
+              : 'Razorpay request failed',
+        },
+      }
+    }
+
+    // Handle standard error objects with message
+    if ('message' in errorObj && typeof errorObj.message === 'string') {
+      return {
+        success: false,
+        error: {
+          code: 'UNKNOWN_ERROR',
+          description: errorObj.message,
+        },
+      }
+    }
+  }
+
+  // Fallback for unknown error types
+  return {
+    success: false,
+    error: {
+      code: 'UNKNOWN_ERROR',
+      description: 'An unexpected error occurred. Please try again or contact support.',
+    },
+  }
+}
+
+export { handleRazorpayError }

package/lib/index.ts

@@ -0,0 +1,22 @@
+export { handleRazorpayError } from './error-handler'
+export {
+  cancelSubscriptionSchema,
+  getPlansSchema,
+  pauseSubscriptionSchema,
+  resumeSubscriptionSchema,
+  subscribeSchema,
+  verifyPaymentSchema,
+} from './schemas'
+export type {
+  OnWebhookEventCallback,
+  RazorpayApiResponse,
+  RazorpayErrorResponse,
+  RazorpayPluginOptions,
+  RazorpaySubscription,
+  RazorpaySubscriptionRecord,
+  RazorpaySuccessResponse,
+  RazorpayUserRecord,
+  RazorpayWebhookContext,
+  RazorpayWebhookEvent,
+  RazorpayWebhookPayload,
+} from './types'

package/lib/schemas.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+
+// Schema for getPlans validation (GET requests don't have a body, so optional)
+const getPlansSchema = z.object({}).strict().optional()
+
+// Schema for subscribe validation
+const subscribeSchema = z.object({
+  plan_id: z.string().min(1, 'Plan ID is required'),
+  total_count: z.number().int().min(1, 'Total count must be at least 1').optional().default(12),
+  quantity: z.number().int().min(1, 'Quantity must be at least 1').optional().default(1),
+  start_at: z.number().int().optional(),
+  expire_by: z.number().int().optional(),
+  customer_notify: z.boolean().optional().default(true),
+  addons: z
+    .array(
+      z.object({
+        item: z.object({
+          name: z.string().min(1, 'Addon name is required'),
+          amount: z.number().int().positive('Addon amount must be positive'),
+          currency: z.string().min(1, 'Addon currency is required'),
+        }),
+      })
+    )
+    .optional(),
+  offer_id: z.string().optional(),
+  notes: z.record(z.string(), z.string()).optional(),
+})
+
+// Schema for verify payment validation
+const verifyPaymentSchema = z.object({
+  razorpay_payment_id: z.string().min(1, 'Payment ID is required'),
+  razorpay_subscription_id: z.string().min(1, 'Subscription ID is required'),
+  razorpay_signature: z.string().min(1, 'Signature is required'),
+})
+
+// Schema for pause subscription validation
+const pauseSubscriptionSchema = z.object({
+  subscription_id: z.string().min(1, 'Subscription ID is required'),
+})
+
+// Schema for cancel subscription validation
+const cancelSubscriptionSchema = z.object({
+  subscription_id: z.string().min(1, 'Subscription ID is required'),
+})
+
+// Schema for resume subscription validation
+const resumeSubscriptionSchema = z.object({
+  subscription_id: z.string().min(1, 'Subscription ID is required'),
+})
+
+export {
+  getPlansSchema,
+  subscribeSchema,
+  verifyPaymentSchema,
+  pauseSubscriptionSchema,
+  cancelSubscriptionSchema,
+  resumeSubscriptionSchema,
+}

package/lib/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Razorpay subscription response interface from the Razorpay API.
+ * This represents the full subscription object returned by Razorpay API calls.
+ */
+export interface RazorpaySubscription {
+  id: string
+  entity: string
+  plan_id: string
+  status: string
+  current_start: number
+  current_end: number
+  ended_at: number | null
+  quantity: number
+  notes: Record<string, string> | null
+  charge_at: number
+  start_at: number
+  end_at: number
+  auth_attempts: number
+  total_count: number
+  paid_count: number
+  customer_notify: boolean
+  created_at: number
+  expire_by: number | null
+  short_url: string
+  has_scheduled_changes: boolean
+  change_scheduled_at: number | null
+  source: string
+  offer_id: string | null
+  remaining_count: string
+}
+
+/**
+ * Subscription record stored in the auth adapter.
+ */
+export interface RazorpaySubscriptionRecord {
+  userId: string
+  subscriptionId: string
+  planId: string
+  status: string
+}
+
+/**
+ * User record shape used by the Razorpay plugin.
+ */
+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
+}
+
+type RazorpayWebhookEvent =
+  | 'subscription.authenticated'
+  | 'subscription.activated'
+  | 'subscription.charged'
+  | 'subscription.cancelled'
+  | 'subscription.paused'
+  | 'subscription.resumed'
+  | 'subscription.pending'
+  | 'subscription.halted'
+
+interface RazorpayWebhookPayload {
+  event: RazorpayWebhookEvent
+  subscription: {
+    id: string
+    plan_id: string
+    status: string
+    current_start?: number
+    current_end?: number
+    [key: string]: unknown // Allow other Razorpay subscription fields
+  }
+  payment?: {
+    id: string
+    amount: number
+    currency: string
+    [key: string]: unknown // Allow other Razorpay payment fields
+  }
+}
+
+interface RazorpayWebhookContext {
+  userId: string
+  user: {
+    id: string
+    email: string
+    name: string
+    [key: string]: unknown // Allow other user fields
+  }
+}
+
+/**
+ * Callback function invoked after webhook events are processed.
+ * Can be used for any custom logic: emails, notifications, analytics, integrations, etc.
+ */
+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.
+   */
+  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
+  }
+}
+
+/**
+ * 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

@@ -0,0 +1,58 @@
+{
+  "name": "@deiondz/better-auth-razorpay",
+  "version": "1.0.0",
+  "description": "Better Auth plugin for Razorpay subscriptions and payments",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "default": "./index.ts"
+    },
+    "./client": {
+      "types": "./client.ts",
+      "import": "./client.ts",
+      "default": "./client.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "client.ts",
+    "api",
+    "lib",
+    "README.md",
+    "RAZORPAY_PLUGIN.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "keywords": [
+    "better-auth",
+    "razorpay",
+    "plugin",
+    "subscriptions",
+    "payments",
+    "authentication"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deiondz/better-auth-razorpay.git"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.0.0"
+  },
+  "dependencies": {
+    "razorpay": "^2.9.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}