@solvapay/server 1.0.0-preview.1 → 1.0.0-preview.11

package/dist/index.d.cts

@@ -20,8 +20,98 @@ interface components {
         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
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * @description Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+            /**
+             * @description Plan reference identifier (optional)
+             * @example pln_2b3c4d5e6f7g
+             */
+            planRef?: string;
+            /**
+             * @description URL to redirect to after successful payment (optional)
+             * @example https://example.com/payment-success
+             */
+            returnUrl?: string;
+        };
+        CheckoutSessionResponse: {
+            /**
+             * @description Checkout session ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * @description Public session ID used in checkout URL
+             * @example a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            sessionId: string;
+            /**
+             * @description Amount in cents
+             * @example 2999
+             */
+            amount: number;
+            /**
+             * @description Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * @description Session status
+             * @example active
+             */
+            status: string;
+            /**
+             * @description Checkout URL to open the checkout page
+             * @example https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            checkoutUrl: string;
+        };
+        CancelSubscriptionRequest: {
+            /**
+             * @description Reason for cancellation
+             * @example Customer request
+             */
+            reason?: string;
+        };
         CheckLimitRequest: {
             /**
              * @description Customer reference identifier
@@ -46,8 +136,13 @@ interface components {
              */
             remaining: number;
             /**
-             * @description Optional checkout URL if payment is required
-             * @example https://checkout.solvapay.com/pay_1a2b3c4d
+             * @description Optional checkout session ID/token if payment is required
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            checkoutSessionId?: string;
+            /**
+             * @description Optional full checkout URL if payment is required (based on backend configuration)
+             * @example https://app.solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
              */
             checkoutUrl?: string;
         };
@@ -100,6 +195,11 @@ interface components {
              * @example John Doe
              */
             name?: string;
+            /**
+             * @description External reference ID from your auth system to map this customer to an auth user (optional)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
         };
         SubscriptionInfo: {
             /**
@@ -127,6 +227,31 @@ interface components {
              * @example 2025-10-27T10:00:00Z
              */
             startDate: string;
+            /**
+             * @description Amount paid in original currency (in cents)
+             * @example 9900
+             */
+            amount: number;
+            /**
+             * @description Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * @description End date of subscription
+             * @example 2025-11-27T10:00:00Z
+             */
+            endDate?: string;
+            /**
+             * @description When subscription was cancelled
+             * @example 2025-10-28T10:00:00Z
+             */
+            cancelledAt?: string;
+            /**
+             * @description Reason for cancellation
+             * @example Customer request
+             */
+            cancellationReason?: string;
         };
         CustomerResponse: {
             /**
@@ -144,9 +269,61 @@ interface components {
              * @example customer@example.com
              */
             email: string;
+            /**
+             * @description External reference ID from your auth system (if set during creation or update)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
             /** @description Active subscriptions */
             subscriptions?: components["schemas"]["SubscriptionInfo"][];
         };
+        CreateCustomerSessionResponse: {
+            /**
+             * @description Customer session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            sessionId: string;
+            /**
+             * @description 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
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            sessionId: string;
+            /**
+             * @description Session status
+             * @example active
+             * @enum {string}
+             */
+            status: "active" | "expired" | "used";
+            /**
+             * @description 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
+             * @example 2025-01-01T12:00:00.000Z
+             */
+            expiresAt: string;
+            /** @description Customer object from session data */
+            customer: components["schemas"]["CustomerResponse"];
+            /**
+             * @description Session creation date
+             * @example 2025-01-01T11:45:00.000Z
+             */
+            createdAt: string;
+            /**
+             * @description 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>;
@@ -257,12 +434,17 @@ interface components {
              */
             createdAt: string;
         };
-        CancelSubscriptionRequest: {
+        CreateCheckoutSessionResponse: {
             /**
-             * @description Reason for cancellation
-             * @example Customer request
+             * @description Checkout session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            reason?: string;
+            sessionId: string;
+            /**
+             * @description Full checkout URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
+             */
+            checkoutUrl: string;
         };
         CreatePageSettings: {
             /** @description Page identifier */
@@ -324,13 +506,39 @@ type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
 };
 /**
  * Extended CustomerResponse with proper field mapping
+ *
+ * Note: The backend API may return subscriptions with additional fields beyond SubscriptionInfo
+ * (e.g., amount, endDate, cancelledAt, cancellationReason) as defined in SubscriptionResponse.
+ * These additional fields are preserved in the subscriptions array.
  */
 type CustomerResponseMapped = {
     customerRef: string;
     email?: string;
     name?: string;
+    externalRef?: string;
     plan?: string;
+    subscriptions?: Array<components['schemas']['SubscriptionInfo'] & Partial<Pick<components['schemas']['SubscriptionResponse'], 'amount' | 'currency' | 'endDate' | 'cancelledAt' | 'cancellationReason' | 'paidAt' | 'nextBillingDate'>>>;
 };
+/**
+ * Purchase information returned from payment processing
+ */
+interface PurchaseInfo {
+    reference: string;
+    productRef?: string;
+    amount: number;
+    currency: string;
+    creditsAdded?: number;
+    completedAt: string;
+}
+/**
+ * Result from processing a payment intent
+ */
+interface ProcessPaymentResult {
+    type: 'subscription' | 'purchase';
+    subscription?: components['schemas']['SubscriptionInfo'];
+    purchase?: PurchaseInfo;
+    status: 'completed';
+}
 /**
  * SolvaPay API Client Interface
  *
@@ -349,6 +557,9 @@ interface SolvaPayClient {
     getCustomer?(params: {
         customerRef: string;
     }): Promise<CustomerResponseMapped>;
+    getCustomerByExternalRef?(params: {
+        externalRef: string;
+    }): Promise<CustomerResponseMapped>;
     listAgents?(): Promise<Array<{
         reference: string;
         name: string;
@@ -362,9 +573,14 @@ interface SolvaPayClient {
     listPlans?(agentRef: string): Promise<Array<{
         reference: string;
         name: string;
+        description?: string;
+        price?: number;
+        currency?: string;
+        interval?: string;
         isFreeTier?: boolean;
         freeUnits?: number;
-        description?: string;
+        metadata?: Record<string, any>;
+        [key: string]: any;
     }>>;
     createPlan?(params: components['schemas']['CreatePlanRequest'] & {
         agentRef: string;
@@ -384,6 +600,18 @@ interface SolvaPayClient {
         publishableKey: string;
         accountId?: string;
     }>;
+    cancelSubscription?(params: {
+        subscriptionRef: string;
+        reason?: string;
+    }): Promise<components['schemas']['SubscriptionResponse']>;
+    processPayment?(params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
+    createCheckoutSession(params: components['schemas']['CreateCheckoutSessionRequest']): Promise<components['schemas']['CreateCheckoutSessionResponse']>;
+    createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
 }
 
 /**
@@ -439,7 +667,7 @@ interface PaywallToolResult {
 /**
  * Retry configuration options
  */
-interface RetryOptions$1 {
+interface RetryOptions {
     /**
      * Maximum number of retry attempts (default: 2)
      */
@@ -542,12 +770,6 @@ interface McpAdapterOptions {
     transformResponse?: (result: any) => any;
 }
 
-/**
- * SolvaPay Factory
- *
- * Main entry point for creating SolvaPay instances with the unified payable API
- */
-
 /**
  * Configuration for creating a SolvaPay instance
  */
@@ -598,8 +820,17 @@ interface SolvaPay {
     /**
      * Ensure customer exists (for testing/setup)
      * Only attempts creation once per customer (idempotent).
+     *
+     * @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)
+     *   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
      */
-    ensureCustomer(customerRef: string): Promise<string>;
+    ensureCustomer(customerRef: string, externalRef?: string, options?: {
+        email?: string;
+        name?: string;
+    }): Promise<string>;
     /**
      * Create a payment intent for a customer to subscribe to a plan
      */
@@ -614,6 +845,16 @@ interface SolvaPay {
         publishableKey: string;
         accountId?: string;
     }>;
+    /**
+     * Process a payment intent after client-side confirmation
+     * Creates subscription or purchase immediately, eliminating webhook delay
+     */
+    processPayment(params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
     /**
      * Check if customer is within usage limits
      */
@@ -650,14 +891,30 @@ interface SolvaPay {
     }>;
     /**
      * Get customer details
+     * Uses the generated CustomerResponseMapped type which includes all subscription fields from the API
      */
     getCustomer(params: {
         customerRef: string;
+    }): Promise<CustomerResponseMapped>;
+    /**
+     * Create a checkout session for a customer
+     */
+    createCheckoutSession(params: {
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
     }): Promise<{
+        sessionId: string;
+        checkoutUrl: string;
+    }>;
+    /**
+     * Create a customer session for accessing customer-specific functionality
+     */
+    createCustomerSession(params: {
         customerRef: string;
-        email?: string;
-        name?: string;
-        plan?: string;
+    }): Promise<{
+        sessionId: string;
+        customerUrl: string;
     }>;
     /**
      * Direct access to the API client for advanced operations
@@ -668,12 +925,15 @@ interface SolvaPay {
 /**
  * Create a SolvaPay instance
  *
- * @param config - Configuration with either apiKey or apiClient
+ * @param config - Optional configuration with either apiKey or apiClient. If not provided, reads from environment variables.
  * @returns SolvaPay instance with payable() method
  *
  * @example
  * ```typescript
- * // Production: Pass API key
+ * // Production: Read from environment variables (recommended)
+ * const solvaPay = createSolvaPay();
+ *
+ * // Production: Pass API key explicitly
  * const solvaPay = createSolvaPay({
  *   apiKey: process.env.SOLVAPAY_SECRET_KEY
  * });
@@ -689,7 +949,7 @@ interface SolvaPay {
  * export const POST = payable.next(createTask);
  * ```
  */
-declare function createSolvaPay(config: CreateSolvaPayConfig): SolvaPay;
+declare function createSolvaPay(config?: CreateSolvaPayConfig): SolvaPay;
 
 /**
  * SolvaPay Server SDK - API Client
@@ -748,39 +1008,7 @@ declare class PaywallError extends Error {
 /**
  * Utility functions for the SolvaPay Server SDK
  */
-/**
- * Retry configuration options
- */
-interface RetryOptions {
-    /**
-     * Maximum number of retry attempts (default: 2)
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay between retries in milliseconds (default: 500)
-     */
-    initialDelay?: number;
-    /**
-     * Backoff strategy for calculating delay between retries (default: 'fixed')
-     * - 'fixed': Same delay between all retries
-     * - 'linear': Delay increases linearly (initialDelay * attempt)
-     * - 'exponential': Delay doubles each attempt (initialDelay * 2^(attempt-1))
-     */
-    backoffStrategy?: 'fixed' | 'linear' | 'exponential';
-    /**
-     * Optional function to determine if a retry should be attempted based on the error
-     * @param error The error that was thrown
-     * @param attempt The current attempt number (0-indexed)
-     * @returns true if a retry should be attempted, false otherwise
-     */
-    shouldRetry?: (error: Error, attempt: number) => boolean;
-    /**
-     * Optional callback invoked before each retry attempt
-     * @param error The error that triggered the retry
-     * @param attempt The current attempt number (0-indexed)
-     */
-    onRetry?: (error: Error, attempt: number) => void;
-}
+
 /**
  * Executes an async function with automatic retry logic
  *
@@ -809,6 +1037,208 @@ interface RetryOptions {
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+/**
+ * Helper Types
+ *
+ * Shared types for route helpers
+ */
+/**
+ * Error result returned by core helpers
+ */
+interface ErrorResult {
+    error: string;
+    status: number;
+    details?: string;
+}
+/**
+ * Authenticated user information
+ */
+interface AuthenticatedUser {
+    userId: string;
+    email?: string | null;
+    name?: string | null;
+}
+
+/**
+ * Error Handling Helper
+ *
+ * Generic error handling utilities for route helpers
+ */
+
+/**
+ * Check if a result is an error result
+ */
+declare function isErrorResult(result: unknown): result is ErrorResult;
+/**
+ * Handle route errors and convert to ErrorResult
+ */
+declare function handleRouteError(error: unknown, operationName: string, defaultMessage?: string): ErrorResult;
+
+/**
+ * Authentication Helper (Core)
+ *
+ * Generic helper for extracting authenticated user information from requests.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Extract authenticated user information from request
+ *
+ * This is a generic implementation that uses dynamic imports to avoid
+ * requiring @solvapay/auth package at build time.
+ *
+ * @param request - Standard Web API Request
+ * @param options - Configuration options
+ * @returns Authenticated user info or error result
+ */
+declare function getAuthenticatedUserCore(request: Request, options?: {
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<AuthenticatedUser | ErrorResult>;
+
+/**
+ * Customer Helper (Core)
+ *
+ * Generic helper for syncing customers with SolvaPay backend.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Sync customer - ensure customer exists in SolvaPay backend
+ *
+ * Uses externalRef for consistent lookup and prevents duplicate customers.
+ *
+ * @param request - Standard Web API Request
+ * @param options - Configuration options
+ * @returns Customer reference or error result
+ */
+declare function syncCustomerCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<string | ErrorResult>;
+
+/**
+ * Create payment intent - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Payment intent parameters
+ * @param options - Configuration options
+ * @returns Payment intent response or error result
+ */
+declare function createPaymentIntentCore(request: Request, body: {
+    planRef: string;
+    agentRef: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    id: string;
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef: string;
+} | ErrorResult>;
+/**
+ * Process payment - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Payment processing parameters
+ * @param options - Configuration options
+ * @returns Process payment result or error result
+ */
+declare function processPaymentCore(request: Request, body: {
+    paymentIntentId: string;
+    agentRef: string;
+    planRef?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<ProcessPaymentResult | ErrorResult>;
+
+/**
+ * Checkout Helpers (Core)
+ *
+ * Generic helpers for checkout session operations.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Create checkout session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Checkout session parameters
+ * @param options - Configuration options
+ * @returns Checkout session response or error result
+ */
+declare function createCheckoutSessionCore(request: Request, body: {
+    agentRef: string;
+    planRef?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    checkoutUrl: string;
+} | ErrorResult>;
+/**
+ * Create customer session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param options - Configuration options
+ * @returns Customer session response or error result
+ */
+declare function createCustomerSessionCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    customerUrl: string;
+} | ErrorResult>;
+
+/**
+ * Subscription Helpers (Core)
+ *
+ * Generic helpers for subscription operations.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Cancel subscription - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Cancellation parameters
+ * @param options - Configuration options
+ * @returns Cancelled subscription response or error result
+ */
+declare function cancelSubscriptionCore(request: Request, body: {
+    subscriptionRef: string;
+    reason?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<any | ErrorResult>;
+
+/**
+ * Plans Helper (Core)
+ *
+ * Generic helper for listing plans.
+ * Works with standard Web API Request (works everywhere).
+ * This is a public route - no authentication required.
+ */
+
+/**
+ * List plans - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @returns Plans response or error result
+ */
+declare function listPlansCore(request: Request): Promise<{
+    plans: any[];
+    agentRef: string;
+} | ErrorResult>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -822,4 +1252,4 @@ declare function verifyWebhook({ body, signature, secret }: {
     secret: string;
 }): any;
 
-export { type CreateSolvaPayConfig, type HttpAdapterOptions, type McpAdapterOptions, type NextAdapterOptions, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type RetryOptions$1 as RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, createSolvaPay, createSolvaPayClient, verifyWebhook, withRetry };
+export { type AuthenticatedUser, type CreateSolvaPayConfig, type CustomerResponseMapped, type ErrorResult, type HttpAdapterOptions, type McpAdapterOptions, type NextAdapterOptions, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type PurchaseInfo, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, cancelSubscriptionCore, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, getAuthenticatedUserCore, handleRouteError, isErrorResult, listPlansCore, processPaymentCore, syncCustomerCore, verifyWebhook, withRetry };