@solvapay/server 1.0.0-preview.17 → 1.0.0-preview.19

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 interface components {
     schemas: {
+        UpdateProviderProfileDto: Record<string, never>;
         CreateSecretKey: Record<string, never>;
         CheckName: Record<string, never>;
         CreateAdminAgent: Record<string, never>;
         UpdateAdminAgent: Record<string, never>;
+        SdkAgentResponse: Record<string, never>;
+        CreateAgentRequest: Record<string, never>;
+        UpdateAgentRequest: Record<string, never>;
         Signup: Record<string, never>;
         AuthResponse: Record<string, never>;
         Login: Record<string, never>;
@@ -16,261 +20,333 @@ interface components {
         UpdatePreferences: Record<string, never>;
         ChangePassword: Record<string, never>;
         RequestEmailChange: Record<string, never>;
-        CreateConnectedAccount: Record<string, never>;
-        UpdateConnectedAccount: Record<string, never>;
-        CreatePlanRequest: Record<string, never>;
-        UpdatePlanRequest: Record<string, never>;
-        CreateCustomerSessionRequest: {
-            /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
-             */
-            customerRef: string;
-        };
-        CustomerSessionResponse: {
-            /**
-             * @description Customer session ID
-             * @example 507f1f77bcf86cd799439011
-             */
-            id: string;
-            /**
-             * @description Public session ID used in customer URL
-             * @example e3f1c2d4b6a89f001122334455667788
-             */
-            sessionId: string;
-            /**
-             * @description Session status
-             * @example active
-             */
-            status: string;
-            /**
-             * @description Customer URL to open the customer page
-             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
-             */
-            customerUrl: string;
-        };
-        ExecuteAnalyticsQuery: Record<string, never>;
-        ExecuteMultipleQueries: Record<string, never>;
         CreateCheckoutSessionRequest: {
             /**
-             * @description Customer reference identifier
+             * Customer reference identifier
              * @example cus_3c4d5e6f7g8h
              */
             customerRef: string;
             /**
-             * @description Agent reference identifier
+             * Agent reference identifier
              * @example agt_1a2b3c4d5e6f
              */
             agentRef: string;
             /**
-             * @description Plan reference identifier (optional)
+             * Plan reference identifier (optional)
              * @example pln_2b3c4d5e6f7g
              */
             planRef?: string;
             /**
-             * @description URL to redirect to after successful payment (optional)
+             * URL to redirect to after successful payment (optional)
              * @example https://example.com/payment-success
              */
             returnUrl?: string;
         };
         CheckoutSessionResponse: {
             /**
-             * @description Checkout session ID
+             * Checkout session ID
              * @example 507f1f77bcf86cd799439011
              */
             id: string;
             /**
-             * @description Public session ID used in checkout URL
+             * Public session ID used in checkout URL
              * @example a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
              */
             sessionId: string;
             /**
-             * @description Amount in cents
+             * Amount in cents
              * @example 2999
              */
             amount: number;
             /**
-             * @description Currency code
+             * Currency code
              * @example USD
              */
             currency: string;
             /**
-             * @description Session status
+             * Session status
              * @example active
              */
             status: string;
             /**
-             * @description Checkout URL to open the checkout page
+             * Checkout URL to open the checkout page
              * @example https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
              */
             checkoutUrl: string;
         };
         CancelSubscriptionRequest: {
             /**
-             * @description Reason for cancellation
+             * Reason for cancellation
              * @example Customer request
              */
             reason?: string;
         };
-        CheckLimitRequest: {
+        CreateConnectedAccount: Record<string, never>;
+        UpdateConnectedAccount: Record<string, never>;
+        CreateCheckoutSessionResponse: {
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Checkout session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            customerRef: string;
+            sessionId: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Full checkout URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
              */
-            agentRef: string;
+            checkoutUrl: string;
         };
-        LimitResponse: {
+        CreatePlanRequest: {
             /**
-             * @description Whether the customer is within their usage limits
-             * @example true
+             * Plan name
+             * @example Basic Plan
              */
-            withinLimits: boolean;
+            name: string;
             /**
-             * @description Remaining usage units before hitting the limit
-             * @example 997
+             * Plan description
+             * @example Basic recurring plan with monthly billing
              */
-            remaining: number;
+            description?: string;
             /**
-             * @description Optional checkout session ID/token if payment is required
-             * @example e3f1c2d4b6a89f001122334455667788
+             * Plan type
+             * @example recurring
+             * @enum {string}
              */
-            checkoutSessionId?: string;
+            type?: "recurring" | "usage-based" | "hybrid" | "one-time";
             /**
-             * @description Optional full checkout URL if payment is required (based on backend configuration)
-             * @example https://app.solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
+             * Billing cycle
+             * @example monthly
+             * @enum {string}
              */
-            checkoutUrl?: string;
-        };
-        UsageEvent: {
+            billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Plan price
+             * @example 29.99
              */
-            customerRef: string;
+            price?: number;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Currency code (ISO 4217)
+             * @example USD
+             * @enum {string}
              */
-            agentRef: string;
+            currency?: "USD" | "EUR" | "GBP" | "SEK" | "NOK" | "DKK" | "CAD" | "AUD" | "JPY" | "CHF" | "PLN" | "CZK" | "HUF" | "RON" | "BGN" | "HRK" | "RSD" | "MKD" | "BAM" | "ALL" | "ISK" | "TRY" | "RUB" | "UAH" | "BYN" | "MDL" | "GEL" | "AMD" | "AZN" | "KZT" | "KGS" | "TJS" | "TMT" | "UZS" | "MNT" | "CNY" | "KRW" | "THB" | "VND" | "IDR" | "MYR" | "SGD" | "PHP" | "INR" | "PKR" | "BDT" | "LKR" | "NPR" | "AFN" | "IRR" | "IQD" | "JOD" | "KWD" | "LBP" | "OMR" | "QAR" | "SAR" | "SYP" | "AED" | "YER" | "ILS" | "EGP" | "MAD" | "TND" | "DZD" | "LYD" | "SDG" | "ETB" | "KES" | "TZS" | "UGX" | "RWF" | "BIF" | "DJF" | "SOS" | "ERN" | "SLL" | "GMD" | "GNF" | "CVE" | "STN" | "AOA" | "ZAR" | "BWP" | "SZL" | "LSL" | "NAD" | "ZMW" | "ZWL" | "MZN" | "MWK" | "MGA" | "MUR" | "SCR" | "KMF" | "MVR";
             /**
-             * @description Outcome of the action
-             * @example success
+             * Setup fee
+             * @example 0
+             */
+            setupFee?: number;
+            /**
+             * Trial days
+             * @example 7
+             */
+            trialDays?: number;
+            /**
+             * Number of free units included
+             * @example 100
+             */
+            freeUnits?: number;
+            /** @description Optional agent ID to associate plan with (not stored on plan, only used for initial association) */
+            agentId?: string;
+            /**
+             * Billing model for usage-based plans
+             * @example pre-paid
              * @enum {string}
              */
-            outcome: "success" | "paywall" | "fail";
+            billingModel?: "pre-paid" | "post-paid";
             /**
-             * @description Optional action identifier
-             * @example generate_text
+             * Price per unit for usage-based plans
+             * @example 0.01
              */
-            action?: string;
+            pricePerUnit?: number;
             /**
-             * @description Unique request identifier matching the limits check
-             * @example req_1a2b3c4d5e6f
+             * Unit name for usage-based plans
+             * @example request
              */
-            requestId: string;
+            unit?: string;
             /**
-             * @description Duration of the action in milliseconds
-             * @example 1250
+             * Usage quota for usage-based plans
+             * @example 10000
              */
-            actionDuration: number;
+            quota?: number;
             /**
-             * @description ISO 8601 timestamp of when the action occurred
-             * @example 2025-10-21T10:30:00.000Z
+             * Whether to rollover unused units
+             * @example false
              */
-            timestamp: string;
+            rolloverUnusedUnits?: boolean;
+            /**
+             * Base price for hybrid plans
+             * @example 29.99
+             */
+            basePrice?: number;
+            /**
+             * Usage limits
+             * @example {
+             *       "maxTransactions": 1000,
+             *       "maxCalls": 500,
+             *       "maxHours": 24
+             *     }
+             */
+            limits?: Record<string, never>;
+            /**
+             * Plan features (can be array of strings or object with boolean flags)
+             * @example {
+             *       "apiAccess": true,
+             *       "prioritySupport": false
+             *     }
+             */
+            features?: Record<string, never>;
+            /**
+             * Whether this is a free tier plan
+             * @example false
+             */
+            isFreeTier?: boolean;
+            /**
+             * Whether payment is required
+             * @example true
+             */
+            requiresPayment?: boolean;
+            /**
+             * Whether the plan is active
+             * @example true
+             */
+            isActive?: boolean;
+            /**
+             * Maximum number of active users
+             * @example 10
+             */
+            maxActiveUsers?: number;
+            /**
+             * Access expiry in days
+             * @example 30
+             */
+            accessExpiryDays?: number;
+            /** @description Additional metadata */
+            metadata?: Record<string, never>;
+            /** @description Usage tracking (internal use, not validated) */
+            customerUsage?: Record<string, never>;
+            /**
+             * Whether this is the default plan
+             * @example false
+             */
+            default?: boolean;
+        };
+        UpdatePlanRequest: Record<string, never>;
+        BasePlan: Record<string, never>;
+        CreateCustomerSessionRequest: {
+            /**
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+        };
+        CustomerSessionResponse: {
+            /**
+             * Customer session ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Public session ID used in customer URL
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            sessionId: string;
+            /**
+             * Session status
+             * @example active
+             */
+            status: string;
+            /**
+             * Customer URL to open the customer page
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
+             */
+            customerUrl: string;
         };
         CreateCustomerRequest: {
             /**
-             * @description Customer email address (required)
+             * Customer email address (required)
              * @example customer@example.com
              */
             email: string;
             /**
-             * @description Customer full name (optional)
+             * Customer full name (optional)
              * @example John Doe
              */
             name?: string;
             /**
-             * @description External reference ID from your auth system to map this customer to an auth user (optional)
+             * External reference ID from your auth system to map this customer to an auth user (optional)
              * @example auth_user_12345
              */
             externalRef?: string;
         };
         SubscriptionInfo: {
             /**
-             * @description Subscription reference
+             * Subscription reference
              * @example sub_abc123
              */
             reference: string;
             /**
-             * @description Plan name
+             * Plan name
              * @example Pro Plan
              */
             planName: string;
             /**
-             * @description Agent name
+             * Agent name
              * @example AI Assistant
              */
             agentName: string;
             /**
-             * @description Subscription status
+             * Subscription status
              * @example active
              */
             status: string;
             /**
-             * @description Start date
+             * Start date
              * @example 2025-10-27T10:00:00Z
              */
             startDate: string;
             /**
-             * @description Amount paid in original currency (in cents)
+             * Amount paid in original currency (in cents)
              * @example 9900
              */
             amount: number;
             /**
-             * @description Currency code
+             * Currency code
              * @example USD
              */
             currency: string;
             /**
-             * @description End date of subscription
+             * End date of subscription
              * @example 2025-11-27T10:00:00Z
              */
             endDate?: string;
             /**
-             * @description When subscription was cancelled
+             * When subscription was cancelled
              * @example 2025-10-28T10:00:00Z
              */
             cancelledAt?: string;
             /**
-             * @description Reason for cancellation
+             * Reason for cancellation
              * @example Customer request
              */
             cancellationReason?: string;
         };
         CustomerResponse: {
             /**
-             * @description Customer reference identifier
+             * Customer reference identifier
              * @example cus_3c4d5e6f7g8h
              */
             reference: string;
             /**
-             * @description Customer full name
+             * Customer full name
              * @example John Doe
              */
             name: string;
             /**
-             * @description Customer email address
+             * Customer email address
              * @example customer@example.com
              */
             email: string;
             /**
-             * @description External reference ID from your auth system (if set during creation or update)
+             * External reference ID from your auth system (if set during creation or update)
              * @example auth_user_12345
              */
             externalRef?: string;
@@ -279,172 +355,256 @@ interface components {
         };
         CreateCustomerSessionResponse: {
             /**
-             * @description Customer session ID/token
+             * Customer session ID/token
              * @example e3f1c2d4b6a89f001122334455667788
              */
             sessionId: string;
             /**
-             * @description Full customer URL based on backend configuration (ready to redirect customer)
+             * Full customer URL based on backend configuration (ready to redirect customer)
              * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
              */
             customerUrl: string;
         };
         GetCustomerSessionResponse: {
             /**
-             * @description Customer session ID/token
+             * Customer session ID/token
              * @example e3f1c2d4b6a89f001122334455667788
              */
             sessionId: string;
             /**
-             * @description Session status
+             * Session status
              * @example active
              * @enum {string}
              */
             status: "active" | "expired" | "used";
             /**
-             * @description Full customer URL based on backend configuration (ready to redirect customer)
+             * Full customer URL based on backend configuration (ready to redirect customer)
              * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
              */
             customerUrl: string;
             /**
-             * @description Session expiration date
+             * Session expiration date
              * @example 2025-01-01T12:00:00.000Z
              */
             expiresAt: string;
             /** @description Customer object from session data */
             customer: components["schemas"]["CustomerResponse"];
             /**
-             * @description Session creation date
+             * Session creation date
              * @example 2025-01-01T11:45:00.000Z
              */
             createdAt: string;
             /**
-             * @description Session last update date
+             * Session last update date
              * @example 2025-01-01T11:45:00.000Z
              */
             updatedAt: string;
         };
-        Agent: Record<string, never>;
-        CreateAgentRequest: Record<string, never>;
-        UpdateAgentRequest: Record<string, never>;
-        BasePlan: Record<string, never>;
+        CreateOAuthClientDto: Record<string, never>;
+        UpdateOAuthClientDto: Record<string, never>;
+        GoogleLoginDto: {
+            /** @description The authorization code returned by Google */
+            code: string;
+            /** @description The redirect URI used in the initial authorization request */
+            redirect_uri: string;
+            /** @description The state parameter returned by Google (contains client_id) */
+            state: string;
+        };
+        GithubLoginDto: {
+            /** @description The authorization code returned by GitHub */
+            code: string;
+            /** @description The redirect URI used in the initial authorization request */
+            redirect_uri: string;
+            /** @description The state parameter returned by GitHub (contains client_id) */
+            state: string;
+        };
+        ExecuteAnalyticsQuery: Record<string, never>;
+        ExecuteMultipleQueries: Record<string, never>;
         SubscriptionResponse: {
             /**
-             * @description Subscription reference identifier
+             * Subscription reference identifier
              * @example sub_1a2b3c4d5e6f
              */
             reference: string;
             /**
-             * @description Customer reference identifier
+             * Customer reference identifier
              * @example cus_3c4d5e6f7g8h
              */
             customerRef: string;
             /**
-             * @description Customer email
+             * Customer email
              * @example customer@example.com
              */
             customerEmail: string;
             /**
-             * @description Customer name
+             * Customer name
              * @example John Doe
              */
             customerName?: string;
             /**
-             * @description Agent reference identifier
+             * Agent reference identifier
              * @example agt_1a2b3c4d5e6f
              */
             agentRef: string;
             /**
-             * @description Agent name
+             * Agent name
              * @example My AI Agent
              */
             agentName: string;
             /**
-             * @description Plan reference identifier
+             * Plan reference identifier
              * @example pln_1a2b3c4d5e6f
              */
             planRef: string;
             /**
-             * @description Plan name
+             * Plan name
              * @example Premium Plan
              */
             planName: string;
             /**
-             * @description Plan type
+             * Plan type
              * @example recurring
              * @enum {string}
              */
             planType: "recurring" | "usage-based" | "one-time" | "hybrid";
             /**
-             * @description Subscription status
+             * Subscription status
              * @example active
              * @enum {string}
              */
             status: "pending" | "active" | "expired" | "cancelled" | "suspended" | "refunded";
             /**
-             * @description Amount paid in original currency (in cents)
+             * Amount paid in original currency (in cents)
              * @example 9900
              */
             amount: number;
             /**
-             * @description Currency code
+             * Currency code
              * @example USD
              */
             currency: string;
             /**
-             * @description Start date of subscription
+             * Start date of subscription
              * @example 2025-01-01T00:00:00.000Z
              */
             startDate: string;
             /**
-             * @description End date of subscription (if applicable)
+             * End date of subscription (if applicable)
              * @example 2025-02-01T00:00:00.000Z
              */
             endDate?: string;
             /**
-             * @description When payment was confirmed
+             * When payment was confirmed
              * @example 2025-01-01T00:00:00.000Z
              */
             paidAt?: string;
             /** @description Usage quota information (for usage-based plans) */
             usageQuota?: Record<string, never>;
             /**
-             * @description Whether this is a recurring subscription
+             * Whether this is a recurring subscription
              * @example true
              */
             isRecurring: boolean;
             /**
-             * @description Next billing date (for recurring subscriptions)
+             * Next billing date (for recurring subscriptions)
              * @example 2025-02-01T00:00:00.000Z
              */
             nextBillingDate?: string;
             /**
-             * @description When subscription was cancelled (if applicable)
+             * When subscription was cancelled (if applicable)
              * @example 2025-01-15T00:00:00.000Z
              */
             cancelledAt?: string;
             /**
-             * @description Reason for cancellation (if applicable)
+             * Reason for cancellation (if applicable)
              * @example Customer request
              */
             cancellationReason?: string;
             /**
-             * @description When subscription was created
+             * When subscription was created
              * @example 2025-01-01T00:00:00.000Z
              */
             createdAt: string;
         };
-        CreateCheckoutSessionResponse: {
+        CheckLimitRequest: {
+            /**
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+        };
+        LimitResponse: {
             /**
-             * @description Checkout session ID/token
+             * Whether the customer is within their usage limits
+             * @example true
+             */
+            withinLimits: boolean;
+            /**
+             * Remaining usage units before hitting the limit
+             * @example 997
+             */
+            remaining: number;
+            /**
+             * Optional checkout session ID/token if payment is required
              * @example e3f1c2d4b6a89f001122334455667788
              */
-            sessionId: string;
+            checkoutSessionId?: string;
             /**
-             * @description Full checkout URL based on backend configuration (ready to redirect customer)
-             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
+             * Optional full checkout URL if payment is required (based on backend configuration)
+             * @example https://app.solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
              */
-            checkoutUrl: string;
+            checkoutUrl?: string;
+        };
+        UsageEvent: {
+            /**
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+            /**
+             * Outcome of the action
+             * @example success
+             * @enum {string}
+             */
+            outcome: "success" | "paywall" | "fail";
+            /**
+             * Optional action identifier
+             * @example generate_text
+             */
+            action?: string;
+            /**
+             * Unique request identifier matching the limits check
+             * @example req_1a2b3c4d5e6f
+             */
+            requestId: string;
+            /**
+             * Duration of the action in milliseconds
+             * @example 1250
+             */
+            actionDuration: number;
+            /**
+             * ISO 8601 timestamp of when the action occurred
+             * @example 2025-10-21T10:30:00.000Z
+             */
+            timestamp: string;
+        };
+        UpdateThemePreferenceDto: {
+            /**
+             * Selected UI theme mode
+             * @example dark
+             * @enum {string}
+             */
+            mode: "light" | "dark";
         };
         CreatePageSettings: {
             /** @description Page identifier */
@@ -454,36 +614,38 @@ interface components {
             /** @description Logo URL */
             logo?: string;
             /**
-             * @description Text color in hex format
+             * Text color in hex format
              * @example #2d3748
              */
             textColor: string;
             /**
-             * @description Button color in hex format
+             * Button color in hex format
              * @example #3182ce
              */
             buttonColor: string;
             /**
-             * @description Left background color in hex format
+             * Left background color in hex format
              * @example #f7fafc
              */
             leftBackgroundColor: string;
             /**
-             * @description Right background color in hex format
+             * Right background color in hex format
              * @example #ffffff
              */
             rightBackgroundColor: string;
             /**
-             * @description Font family
+             * Font family
              * @example Inter
              */
             fontFamily: string;
             /**
-             * @description Font size
+             * Font size
              * @example 16px
              */
             fontSize: string;
         };
+        CreateWebhookEndpointDto: Record<string, never>;
+        UpdateWebhookEndpointDto: Record<string, never>;
     };
     responses: never;
     parameters: never;
@@ -554,11 +716,9 @@ interface SolvaPayClient {
     createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
         customerRef: string;
     }>;
-    getCustomer?(params: {
-        customerRef: string;
-    }): Promise<CustomerResponseMapped>;
-    getCustomerByExternalRef?(params: {
-        externalRef: string;
+    getCustomer(params: {
+        customerRef?: string;
+        externalRef?: string;
     }): Promise<CustomerResponseMapped>;
     listAgents?(): Promise<Array<{
         reference: string;
@@ -771,68 +931,242 @@ interface McpAdapterOptions {
 }
 
 /**
- * Configuration for creating a SolvaPay instance
+ * Configuration for creating a SolvaPay instance.
+ *
+ * You can provide either an `apiKey` (for production) or an `apiClient` (for testing).
+ * If neither is provided, the SDK will attempt to read `SOLVAPAY_SECRET_KEY` from
+ * environment variables. If no API key is found, the SDK runs in stub mode.
+ *
+ * @example
+ * ```typescript
+ * // Production: Use API key
+ * const config: CreateSolvaPayConfig = {
+ *   apiKey: process.env.SOLVAPAY_SECRET_KEY
+ * };
+ *
+ * // Testing: Use mock client
+ * const config: CreateSolvaPayConfig = {
+ *   apiClient: mockClient
+ * };
+ * ```
  */
 interface CreateSolvaPayConfig {
     /**
-     * API key for production use (creates client automatically)
+     * API key for production use (creates client automatically).
+     * Defaults to `SOLVAPAY_SECRET_KEY` environment variable if not provided.
      */
     apiKey?: string;
     /**
-     * API client for testing or custom implementations
+     * API client for testing or custom implementations.
+     * Use this for stub mode, testing, or custom client implementations.
      */
     apiClient?: SolvaPayClient;
     /**
-     * Optional API base URL (only used with apiKey)
+     * Optional API base URL override (only used with apiKey).
+     * Defaults to production API URL if not provided.
      */
     apiBaseUrl?: string;
 }
 /**
- * Payable function that provides explicit adapters
+ * Payable function that provides explicit adapters for different frameworks.
+ *
+ * Use the appropriate adapter method for your framework:
+ * - `http()` - Express.js, Fastify, and other HTTP frameworks
+ * - `next()` - Next.js App Router API routes
+ * - `mcp()` - Model Context Protocol servers
+ * - `function()` - Pure functions, background jobs, or testing
+ *
+ * @example
+ * ```typescript
+ * const payable = solvaPay.payable({ agent: 'agt_myapi', plan: 'pln_premium' });
+ *
+ * // Express.js
+ * app.post('/tasks', payable.http(createTask));
+ *
+ * // Next.js
+ * export const POST = payable.next(createTask);
+ *
+ * // MCP Server
+ * const handler = payable.mcp(createTask);
+ *
+ * // Pure function
+ * const protectedFn = await payable.function(createTask);
+ * ```
  */
 interface PayableFunction {
     /**
-     * HTTP adapter for Express/Fastify
+     * HTTP adapter for Express.js, Fastify, and other HTTP frameworks.
+     *
+     * @param businessLogic - Your business logic function
+     * @param options - Optional adapter configuration
+     * @returns HTTP route handler function
+     *
+     * @example
+     * ```typescript
+     * app.post('/tasks', payable.http(async (req) => {
+     *   const { title } = req.body;
+     *   return { success: true, task: { title } };
+     * }));
+     * ```
      */
     http<T = any>(businessLogic: (args: any) => Promise<T>, options?: HttpAdapterOptions): (req: any, reply: any) => Promise<any>;
     /**
-     * Next.js adapter for App Router
+     * Next.js adapter for App Router API routes.
+     *
+     * @param businessLogic - Your business logic function
+     * @param options - Optional adapter configuration
+     * @returns Next.js route handler function
+     *
+     * @example
+     * ```typescript
+     * // app/api/tasks/route.ts
+     * export const POST = payable.next(async (request) => {
+     *   const body = await request.json();
+     *   return Response.json({ success: true });
+     * });
+     * ```
      */
     next<T = any>(businessLogic: (args: any) => Promise<T>, options?: NextAdapterOptions): (request: Request, context?: any) => Promise<Response>;
     /**
-     * MCP adapter for Model Context Protocol servers
+     * MCP adapter for Model Context Protocol servers.
+     *
+     * @param businessLogic - Your tool implementation function
+     * @param options - Optional adapter configuration
+     * @returns MCP tool handler function
+     *
+     * @example
+     * ```typescript
+     * const handler = payable.mcp(async (args) => {
+     *   return { success: true, result: 'tool output' };
+     * });
+     * ```
      */
     mcp<T = any>(businessLogic: (args: any) => Promise<T>, options?: McpAdapterOptions): (args: any) => Promise<any>;
     /**
-     * Pure function adapter for direct function protection
-     * Use this for testing, background jobs, or non-framework contexts
+     * Pure function adapter for direct function protection.
+     *
+     * Use this for testing, background jobs, or non-framework contexts.
+     *
+     * @param businessLogic - Your business logic function
+     * @returns Protected function that requires customer reference in args
+     *
+     * @example
+     * ```typescript
+     * const protectedFn = await payable.function(async (args) => {
+     *   return { result: 'processed' };
+     * });
+     *
+     * // Call with customer reference
+     * const result = await protectedFn({
+     *   auth: { customer_ref: 'user_123' },
+     *   // ... other args
+     * });
+     * ```
      */
     function<T = any>(businessLogic: (args: any) => Promise<T>): Promise<(args: any) => Promise<T>>;
 }
 /**
- * SolvaPay instance with payable method and common API methods
+ * SolvaPay instance with payable method and common API methods.
+ *
+ * This interface provides the main API for interacting with SolvaPay.
+ * Use `createSolvaPay()` to create an instance.
+ *
+ * @example
+ * ```typescript
+ * const solvaPay = createSolvaPay();
+ *
+ * // Create payable handlers
+ * const payable = solvaPay.payable({ agent: 'agt_myapi', plan: 'pln_premium' });
+ *
+ * // Manage customers
+ * const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
+ *   email: 'user@example.com'
+ * });
+ *
+ * // Create payment intents
+ * const intent = await solvaPay.createPaymentIntent({
+ *   agentRef: 'agt_myapi',
+ *   planRef: 'pln_premium',
+ *   customerRef: 'user_123'
+ * });
+ * ```
  */
 interface SolvaPay {
     /**
-     * Create a payable handler with explicit adapters
+     * Create a payable handler with explicit adapters for different frameworks.
+     *
+     * @param options - Payable options including agent and plan references
+     * @returns PayableFunction with framework-specific adapters
+     *
+     * @example
+     * ```typescript
+     * const payable = solvaPay.payable({
+     *   agent: 'agt_myapi',
+     *   plan: 'pln_premium'
+     * });
+     *
+     * app.post('/tasks', payable.http(createTask));
+     * ```
      */
     payable(options?: PayableOptions): PayableFunction;
     /**
-     * Ensure customer exists (for testing/setup)
-     * Only attempts creation once per customer (idempotent).
+     * Ensure customer exists in SolvaPay backend (idempotent).
+     *
+     * Creates a customer if they don't exist, or returns existing customer reference.
+     * This is automatically called by the paywall system, but you can call it
+     * explicitly for setup or testing.
      *
      * @param customerRef - The customer reference used as a cache key (e.g., Supabase user ID)
-     * @param externalRef - Optional external reference for backend lookup (e.g., Supabase user ID)
+     * @param externalRef - Optional external reference for backend lookup (e.g., Supabase user ID).
      *   If provided, will lookup existing customer by externalRef before creating new one.
      *   The externalRef is stored on the SolvaPay backend for customer lookup.
-     * @param options - Optional customer details (email, name) for customer creation
+     * @param options - Optional customer details for customer creation
+     * @param options.email - Customer email address
+     * @param options.name - Customer name
+     * @returns Customer reference (backend customer ID)
+     *
+     * @example
+     * ```typescript
+     * // Ensure customer exists before processing payment
+     * const customerRef = await solvaPay.ensureCustomer(
+     *   'user_123',           // customerRef (your user ID)
+     *   'user_123',           // externalRef (same or different)
+     *   {
+     *     email: 'user@example.com',
+     *     name: 'John Doe'
+     *   }
+     * );
+     * ```
      */
     ensureCustomer(customerRef: string, externalRef?: string, options?: {
         email?: string;
         name?: string;
     }): Promise<string>;
     /**
-     * Create a payment intent for a customer to subscribe to a plan
+     * Create a Stripe payment intent for a customer to subscribe to a plan.
+     *
+     * This creates a payment intent that can be confirmed on the client side
+     * using Stripe.js. After confirmation, call `processPayment()` to complete
+     * the subscription.
+     *
+     * @param params - Payment intent parameters
+     * @param params.agentRef - Agent reference
+     * @param params.planRef - Plan reference to subscribe to
+     * @param params.customerRef - Customer reference
+     * @param params.idempotencyKey - Optional idempotency key for retry safety
+     * @returns Payment intent with client secret and publishable key
+     *
+     * @example
+     * ```typescript
+     * const intent = await solvaPay.createPaymentIntent({
+     *   agentRef: 'agt_myapi',
+     *   planRef: 'pln_premium',
+     *   customerRef: 'user_123',
+     *   idempotencyKey: 'unique-key-123'
+     * });
+     *
+     * // Use intent.clientSecret with Stripe.js on client
+     * ```
      */
     createPaymentIntent(params: {
         agentRef: string;
@@ -846,8 +1180,32 @@ interface SolvaPay {
         accountId?: string;
     }>;
     /**
-     * Process a payment intent after client-side confirmation
-     * Creates subscription or purchase immediately, eliminating webhook delay
+     * Process a payment intent after client-side Stripe confirmation.
+     *
+     * Creates subscription or purchase immediately, eliminating webhook delay.
+     * Call this after the client has confirmed the payment intent with Stripe.js.
+     *
+     * @param params - Payment processing parameters
+     * @param params.paymentIntentId - Stripe payment intent ID from client confirmation
+     * @param params.agentRef - Agent reference
+     * @param params.customerRef - Customer reference
+     * @param params.planRef - Optional plan reference (if not in payment intent)
+     * @returns Payment processing result with subscription details
+     *
+     * @example
+     * ```typescript
+     * // After client confirms payment with Stripe.js
+     * const result = await solvaPay.processPayment({
+     *   paymentIntentId: 'pi_1234567890',
+     *   agentRef: 'agt_myapi',
+     *   customerRef: 'user_123',
+     *   planRef: 'pln_premium'
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Subscription created:', result.subscriptionRef);
+     * }
+     * ```
      */
     processPayment(params: {
         paymentIntentId: string;
@@ -856,7 +1214,28 @@ interface SolvaPay {
         planRef?: string;
     }): Promise<ProcessPaymentResult>;
     /**
-     * Check if customer is within usage limits
+     * Check if customer is within usage limits for an agent.
+     *
+     * This method checks subscription status and usage limits without
+     * executing business logic. Use `payable()` for automatic protection.
+     *
+     * @param params - Limit check parameters
+     * @param params.customerRef - Customer reference
+     * @param params.agentRef - Agent reference
+     * @returns Limit check result with remaining usage and checkout URL if needed
+     *
+     * @example
+     * ```typescript
+     * const limits = await solvaPay.checkLimits({
+     *   customerRef: 'user_123',
+     *   agentRef: 'agt_myapi'
+     * });
+     *
+     * if (!limits.withinLimits) {
+     *   // Redirect to checkout
+     *   window.location.href = limits.checkoutUrl;
+     * }
+     * ```
      */
     checkLimits(params: {
         customerRef: string;
@@ -868,7 +1247,34 @@ interface SolvaPay {
         checkoutUrl?: string;
     }>;
     /**
-     * Track usage for a customer action
+     * Track usage for a customer action.
+     *
+     * This is automatically called by the paywall system. You typically
+     * don't need to call this manually unless implementing custom tracking.
+     *
+     * @param params - Usage tracking parameters
+     * @param params.customerRef - Customer reference
+     * @param params.agentRef - Agent reference
+     * @param params.planRef - Plan reference
+     * @param params.outcome - Action outcome ('success', 'paywall', or 'fail')
+     * @param params.action - Optional action name for analytics
+     * @param params.requestId - Unique request ID
+     * @param params.actionDuration - Action duration in milliseconds
+     * @param params.timestamp - ISO timestamp of the action
+     *
+     * @example
+     * ```typescript
+     * await solvaPay.trackUsage({
+     *   customerRef: 'user_123',
+     *   agentRef: 'agt_myapi',
+     *   planRef: 'pln_premium',
+     *   outcome: 'success',
+     *   action: 'api_call',
+     *   requestId: 'req_123',
+     *   actionDuration: 150,
+     *   timestamp: new Date().toISOString()
+     * });
+     * ```
      */
     trackUsage(params: {
         customerRef: string;
@@ -881,7 +1287,23 @@ interface SolvaPay {
         timestamp: string;
     }): Promise<void>;
     /**
-     * Create a new customer
+     * Create a new customer in SolvaPay backend.
+     *
+     * Note: `ensureCustomer()` is usually preferred as it's idempotent.
+     * Use this only if you need explicit control over customer creation.
+     *
+     * @param params - Customer creation parameters
+     * @param params.email - Customer email address (required)
+     * @param params.name - Optional customer name
+     * @returns Created customer reference
+     *
+     * @example
+     * ```typescript
+     * const { customerRef } = await solvaPay.createCustomer({
+     *   email: 'user@example.com',
+     *   name: 'John Doe'
+     * });
+     * ```
      */
     createCustomer(params: {
         email: string;
@@ -890,25 +1312,87 @@ interface SolvaPay {
         customerRef: string;
     }>;
     /**
-     * Get customer details
-     * Uses the generated CustomerResponseMapped type which includes all subscription fields from the API
+     * Get customer details including subscriptions and usage.
+     *
+     * Returns full customer information from the SolvaPay backend, including
+     * all active subscriptions, usage history, and customer metadata.
+     *
+     * @param params - Customer lookup parameters
+     * @param params.customerRef - Optional customer reference (SolvaPay ID)
+     * @param params.externalRef - Optional external reference (e.g., Supabase ID)
+     * @returns Customer details with subscriptions and metadata
+     *
+     * @example
+     * ```typescript
+     * // Lookup by SolvaPay customer ID
+     * const customer = await solvaPay.getCustomer({
+     *   customerRef: 'cust_123'
+     * });
+     *
+     * // Lookup by external ID (e.g. Supabase user ID)
+     * const customer = await solvaPay.getCustomer({
+     *   externalRef: 'user_123'
+     * });
+     * ```
      */
     getCustomer(params: {
-        customerRef: string;
+        customerRef?: string;
+        externalRef?: string;
     }): Promise<CustomerResponseMapped>;
     /**
-     * Create a checkout session for a customer
+     * Create a hosted checkout session for a customer.
+     *
+     * This creates a Stripe Checkout session that redirects the customer
+     * to a hosted payment page. After payment, customer is redirected back.
+     *
+     * @param params - Checkout session parameters
+     * @param params.agentRef - Agent reference
+     * @param params.customerRef - Customer reference
+     * @param params.planRef - Optional plan reference (if not specified, shows plan selector)
+     * @param params.returnUrl - URL to redirect to after successful payment
+     * @returns Checkout session with redirect URL
+     *
+     * @example
+     * ```typescript
+     * const session = await solvaPay.createCheckoutSession({
+     *   agentRef: 'agt_myapi',
+     *   customerRef: 'user_123',
+     *   planRef: 'pln_premium',
+     *   returnUrl: 'https://myapp.com/success'
+     * });
+     *
+     * // Redirect customer to checkout
+     * window.location.href = session.checkoutUrl;
+     * ```
      */
     createCheckoutSession(params: {
         agentRef: string;
         customerRef: string;
         planRef?: string;
+        returnUrl?: string;
     }): Promise<{
         sessionId: string;
         checkoutUrl: string;
     }>;
     /**
-     * Create a customer session for accessing customer-specific functionality
+     * Create a customer portal session for managing subscriptions.
+     *
+     * This creates a Stripe Customer Portal session that allows customers
+     * to manage their subscriptions, update payment methods, and view invoices.
+     *
+     * @param params - Customer session parameters
+     * @param params.customerRef - Customer reference
+     * @returns Customer portal session with redirect URL
+     *
+     * @example
+     * ```typescript
+     * const session = await solvaPay.createCustomerSession({
+     *   customerRef: 'user_123'
+     * });
+     *
+     * // Redirect customer to portal
+     * window.location.href = session.customerUrl;
+     * ```
      */
     createCustomerSession(params: {
         customerRef: string;
@@ -917,20 +1401,35 @@ interface SolvaPay {
         customerUrl: string;
     }>;
     /**
-     * Direct access to the API client for advanced operations
-     * (agent/plan management, etc.)
+     * Direct access to the API client for advanced operations.
+     *
+     * Use this for operations not exposed by the SolvaPay interface,
+     * such as agent/plan management or custom API calls.
+     *
+     * @example
+     * ```typescript
+     * // Access API client directly for custom operations
+     * const agents = await solvaPay.apiClient.listAgents();
+     * ```
      */
     apiClient: SolvaPayClient;
 }
 /**
- * Create a SolvaPay instance
+ * Create a SolvaPay instance with paywall protection capabilities.
+ *
+ * This factory function creates a SolvaPay instance that can be used to
+ * protect API endpoints, functions, and MCP tools with usage limits and
+ * subscription checks.
  *
- * @param config - Optional configuration with either apiKey or apiClient. If not provided, reads from environment variables.
- * @returns SolvaPay instance with payable() method
+ * @param config - Optional configuration object
+ * @param config.apiKey - API key for production use (defaults to `SOLVAPAY_SECRET_KEY` env var)
+ * @param config.apiClient - Custom API client for testing or advanced use cases
+ * @param config.apiBaseUrl - Optional API base URL override
+ * @returns SolvaPay instance with payable() method and API client access
  *
  * @example
  * ```typescript
- * // Production: Read from environment variables (recommended)
+ * // Production: Use environment variable (recommended)
  * const solvaPay = createSolvaPay();
  *
  * // Production: Pass API key explicitly
@@ -938,16 +1437,26 @@ interface SolvaPay {
  *   apiKey: process.env.SOLVAPAY_SECRET_KEY
  * });
  *
- * // Testing: Pass mock client
+ * // Testing: Use mock client
  * const solvaPay = createSolvaPay({
  *   apiClient: mockClient
  * });
  *
- * // Create payable handlers
- * const payable = solvaPay.payable({ agent: 'my-api' });
- * app.post('/tasks', payable.http(createTask));
- * export const POST = payable.next(createTask);
+ * // Create payable handlers for your agent
+ * const payable = solvaPay.payable({
+ *   agent: 'agt_myapi',
+ *   plan: 'pln_premium'
+ * });
+ *
+ * // Protect endpoints with framework-specific adapters
+ * app.post('/tasks', payable.http(createTask));      // Express/Fastify
+ * export const POST = payable.next(createTask);      // Next.js App Router
+ * const handler = payable.mcp(createTask);           // MCP servers
  * ```
+ *
+ * @see {@link SolvaPay} for the returned instance interface
+ * @see {@link CreateSolvaPayConfig} for configuration options
+ * @since 1.0.0
  */
 declare function createSolvaPay(config?: CreateSolvaPayConfig): SolvaPay;
 
@@ -969,25 +1478,43 @@ type ServerClientOptions = {
     apiKey: string;
     /**
      * Base URL for the SolvaPay API (optional)
-     * Defaults to https://api-dev.solvapay.com
+     * Defaults to https://api.solvapay.com
      */
     apiBaseUrl?: string;
 };
 /**
- * Creates a SolvaPay API client that implements the full SolvaPayClient
- * for server-side paywall and usage tracking operations.
+ * Creates a SolvaPay API client that implements the full SolvaPayClient interface.
  *
- * @param opts - Configuration options including API key and optional base URL
+ * This function creates a low-level API client for direct communication with the
+ * SolvaPay backend. For most use cases, use `createSolvaPay()` instead, which
+ * provides a higher-level API with paywall protection.
+ *
+ * Use this function when you need:
+ * - Direct API access for custom operations
+ * - Testing with custom client implementations
+ * - Advanced use cases not covered by the main API
+ *
+ * @param opts - Configuration options
+ * @param opts.apiKey - Your SolvaPay API key (required)
+ * @param opts.apiBaseUrl - Optional API base URL override
  * @returns A fully configured SolvaPayClient instance
  * @throws {SolvaPayError} If API key is missing
  *
  * @example
  * ```typescript
+ * // Create API client directly
  * const client = createSolvaPayClient({
  *   apiKey: process.env.SOLVAPAY_SECRET_KEY!,
  *   apiBaseUrl: 'https://api.solvapay.com' // optional
  * });
+ *
+ * // Use client for custom operations
+ * const agents = await client.listAgents();
  * ```
+ *
+ * @see {@link createSolvaPay} for the recommended high-level API
+ * @see {@link ServerClientOptions} for configuration options
+ * @since 1.0.0
  */
 declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient;
 
@@ -1000,8 +1527,48 @@ declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient
  * - Class-based and functional programming
  */
 
+/**
+ * Error thrown when a paywall is triggered (subscription required or usage limit exceeded).
+ *
+ * This error is automatically thrown by the paywall protection system when:
+ * - Customer doesn't have required subscription
+ * - Customer has exceeded usage limits
+ * - Customer needs to upgrade their plan
+ *
+ * The error includes structured content with checkout URLs and metadata for
+ * building custom paywall UIs.
+ *
+ * @example
+ * ```typescript
+ * import { PaywallError } from '@solvapay/server';
+ *
+ * try {
+ *   const result = await payable.http(createTask)(req, res);
+ *   return result;
+ * } catch (error) {
+ *   if (error instanceof PaywallError) {
+ *     // Custom paywall handling
+ *     return res.status(402).json({
+ *       error: error.message,
+ *       checkoutUrl: error.structuredContent.checkoutUrl,
+ *       // Additional metadata available in error.structuredContent
+ *     });
+ *   }
+ *   throw error;
+ * }
+ * ```
+ *
+ * @see {@link PaywallStructuredContent} for the structured content format
+ * @since 1.0.0
+ */
 declare class PaywallError extends Error {
     structuredContent: PaywallStructuredContent;
+    /**
+     * Creates a new PaywallError instance.
+     *
+     * @param message - Error message
+     * @param structuredContent - Structured content with checkout URLs and metadata
+     */
     constructor(message: string, structuredContent: PaywallStructuredContent);
 }
 
@@ -1010,19 +1577,28 @@ declare class PaywallError extends Error {
  */
 
 /**
- * Executes an async function with automatic retry logic
+ * Execute an async function with automatic retry logic.
+ *
+ * This utility function provides configurable retry logic with exponential backoff,
+ * conditional retry logic, and retry callbacks. Useful for handling transient
+ * network errors or rate limiting.
  *
  * @template T The return type of the async function
  * @param fn The async function to execute
  * @param options Retry configuration options
+ * @param options.maxRetries - Maximum number of retry attempts (default: 2)
+ * @param options.initialDelay - Initial delay in milliseconds before first retry (default: 500)
+ * @param options.backoffStrategy - Backoff strategy: 'fixed', 'linear', or 'exponential' (default: 'fixed')
+ * @param options.shouldRetry - Optional function to determine if error should be retried
+ * @param options.onRetry - Optional callback called before each retry attempt
  * @returns A promise that resolves with the function result or rejects with the last error
  *
  * @example
  * ```typescript
- * // Simple retry with defaults
+ * // Simple retry with defaults (2 retries, 500ms delay)
  * const result = await withRetry(() => apiCall());
  *
- * // Custom retry with conditional logic
+ * // Custom retry with exponential backoff
  * const result = await withRetry(
  *   () => apiCall(),
  *   {
@@ -1034,6 +1610,8 @@ declare class PaywallError extends Error {
  *   }
  * );
  * ```
+ *
+ * @since 1.0.0
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
@@ -1082,14 +1660,39 @@ declare function handleRouteError(error: unknown, operationName: string, default
  */
 
 /**
- * Extract authenticated user information from request
+ * Extract authenticated user information from a standard Web API Request.
  *
- * This is a generic implementation that uses dynamic imports to avoid
- * requiring @solvapay/auth package at build time.
+ * This is a generic, framework-agnostic helper that extracts user ID, email,
+ * and name from authenticated requests. Works with any framework that uses
+ * the standard Web API Request (Express, Fastify, Next.js, Edge Functions, etc.).
  *
- * @param request - Standard Web API Request
+ * Uses dynamic imports to avoid requiring @solvapay/auth at build time,
+ * making it suitable for edge runtime environments.
+ *
+ * @param request - Standard Web API Request object
  * @param options - Configuration options
+ * @param options.includeEmail - Whether to extract email from JWT token (default: true)
+ * @param options.includeName - Whether to extract name from JWT token (default: true)
  * @returns Authenticated user info or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function GET(request: Request) {
+ *   const userResult = await getAuthenticatedUserCore(request);
+ *
+ *   if (isErrorResult(userResult)) {
+ *     return Response.json(userResult, { status: userResult.status });
+ *   }
+ *
+ *   const { userId, email, name } = userResult;
+ *   // Use user info...
+ * }
+ * ```
+ *
+ * @see {@link AuthenticatedUser} for the return type
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
  */
 declare function getAuthenticatedUserCore(request: Request, options?: {
     includeEmail?: boolean;
@@ -1104,13 +1707,41 @@ declare function getAuthenticatedUserCore(request: Request, options?: {
  */
 
 /**
- * Sync customer - ensure customer exists in SolvaPay backend
+ * Sync customer with SolvaPay backend (ensure customer exists).
  *
- * Uses externalRef for consistent lookup and prevents duplicate customers.
+ * This helper ensures a customer exists in the SolvaPay backend by:
+ * 1. Extracting authenticated user information from the request
+ * 2. Creating or retrieving the customer using the user ID as external reference
+ * 3. Syncing customer data (email, name) if provided
  *
- * @param request - Standard Web API Request
+ * Uses `externalRef` for consistent lookup and prevents duplicate customers.
+ * The returned customer reference is the SolvaPay backend customer ID.
+ *
+ * @param request - Standard Web API Request object
  * @param options - Configuration options
- * @returns Customer reference or error result
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @param options.includeEmail - Whether to include email in customer data (default: true)
+ * @param options.includeName - Whether to include name in customer data (default: true)
+ * @returns Customer reference (backend customer ID) or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function POST(request: Request) {
+ *   const customerResult = await syncCustomerCore(request);
+ *
+ *   if (isErrorResult(customerResult)) {
+ *     return Response.json(customerResult, { status: customerResult.status });
+ *   }
+ *
+ *   const customerRef = customerResult;
+ *   // Use customer reference...
+ * }
+ * ```
+ *
+ * @see {@link getAuthenticatedUserCore} for user extraction
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
  */
 declare function syncCustomerCore(request: Request, options?: {
     solvaPay?: SolvaPay;
@@ -1119,12 +1750,44 @@ declare function syncCustomerCore(request: Request, options?: {
 }): Promise<string | ErrorResult>;
 
 /**
- * Create payment intent - core implementation
+ * Create a Stripe payment intent for a customer to subscribe to a plan.
  *
- * @param request - Standard Web API Request
+ * This is a framework-agnostic helper that:
+ * 1. Extracts authenticated user from the request
+ * 2. Syncs customer with SolvaPay backend
+ * 3. Creates a payment intent for the specified plan
+ *
+ * The payment intent can then be confirmed on the client side using Stripe.js.
+ * After confirmation, use `processPaymentCore()` to complete the subscription.
+ *
+ * @param request - Standard Web API Request object
  * @param body - Payment intent parameters
+ * @param body.planRef - Plan reference to subscribe to (required)
+ * @param body.agentRef - Agent reference (required)
  * @param options - Configuration options
- * @returns Payment intent response or error result
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @param options.includeEmail - Whether to include email in customer data (default: true)
+ * @param options.includeName - Whether to include name in customer data (default: true)
+ * @returns Payment intent response with client secret and customer reference, or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function POST(request: Request) {
+ *   const body = await request.json();
+ *   const result = await createPaymentIntentCore(request, body);
+ *
+ *   if (isErrorResult(result)) {
+ *     return Response.json(result, { status: result.status });
+ *   }
+ *
+ *   return Response.json(result);
+ * }
+ * ```
+ *
+ * @see {@link processPaymentCore} for processing confirmed payments
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
  */
 declare function createPaymentIntentCore(request: Request, body: {
     planRef: string;
@@ -1141,12 +1804,45 @@ declare function createPaymentIntentCore(request: Request, body: {
     customerRef: string;
 } | ErrorResult>;
 /**
- * Process payment - core implementation
+ * Process a payment intent after client-side Stripe confirmation.
  *
- * @param request - Standard Web API Request
+ * This helper processes a payment intent that has been confirmed on the client
+ * side using Stripe.js. It creates the subscription or purchase immediately,
+ * eliminating webhook delay.
+ *
+ * Call this after the client has confirmed the payment intent with Stripe.js.
+ *
+ * @param request - Standard Web API Request object
  * @param body - Payment processing parameters
+ * @param body.paymentIntentId - Stripe payment intent ID from client confirmation (required)
+ * @param body.agentRef - Agent reference (required)
+ * @param body.planRef - Optional plan reference (if not in payment intent)
  * @param options - Configuration options
- * @returns Process payment result or error result
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @returns Process payment result with subscription details, or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function POST(request: Request) {
+ *   const body = await request.json();
+ *   const result = await processPaymentCore(request, body);
+ *
+ *   if (isErrorResult(result)) {
+ *     return Response.json(result, { status: result.status });
+ *   }
+ *
+ *   if (result.success) {
+ *     console.log('Subscription created:', result.subscriptionRef);
+ *   }
+ *
+ *   return Response.json(result);
+ * }
+ * ```
+ *
+ * @see {@link createPaymentIntentCore} for creating payment intents
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
  */
 declare function processPaymentCore(request: Request, body: {
     paymentIntentId: string;
@@ -1174,10 +1870,12 @@ declare function processPaymentCore(request: Request, body: {
 declare function createCheckoutSessionCore(request: Request, body: {
     agentRef: string;
     planRef?: string;
+    returnUrl?: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
+    returnUrl?: string;
 }): Promise<{
     sessionId: string;
     checkoutUrl: string;
@@ -1246,7 +1944,50 @@ declare function listPlansCore(request: Request): Promise<{
  * Provides unified payable API with explicit adapters for all frameworks.
  */
 
-declare function verifyWebhook({ body, signature, secret }: {
+/**
+ * Verify webhook signature from SolvaPay backend.
+ *
+ * This function verifies that a webhook request is authentic by comparing
+ * the provided signature with a computed HMAC-SHA256 signature of the request body.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param params - Webhook verification parameters
+ * @param params.body - Raw request body as string (must be exactly as received)
+ * @param params.signature - Signature from `x-solvapay-signature` header
+ * @param params.secret - Webhook secret from SolvaPay dashboard
+ * @returns Parsed webhook payload as object
+ * @throws {SolvaPayError} If signature is invalid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@solvapay/server';
+ *
+ * // In Express.js
+ * app.post('/webhooks/solvapay', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const signature = req.headers['x-solvapay-signature'] as string;
+ *     const payload = verifyWebhook({
+ *       body: req.body.toString(),
+ *       signature,
+ *       secret: process.env.SOLVAPAY_WEBHOOK_SECRET!
+ *     });
+ *
+ *     // Handle webhook event
+ *     if (payload.type === 'subscription.created') {
+ *       // Process subscription creation
+ *     }
+ *
+ *     res.json({ received: true });
+ *   } catch (error) {
+ *     res.status(401).json({ error: 'Invalid signature' });
+ *   }
+ * });
+ * ```
+ *
+ * @see [Webhook Guide](../../../docs/guides/webhooks.md) for complete webhook handling examples
+ * @since 1.0.0
+ */
+declare function verifyWebhook({ body, signature, secret, }: {
     body: string;
     signature: string;
     secret: string;