@solvapay/server 1.0.0-preview.1

package/dist/index.d.cts

@@ -0,0 +1,825 @@
+interface components {
+    schemas: {
+        CreateSecretKey: Record<string, never>;
+        CheckName: Record<string, never>;
+        CreateAdminAgent: Record<string, never>;
+        UpdateAdminAgent: Record<string, never>;
+        Signup: Record<string, never>;
+        AuthResponse: Record<string, never>;
+        Login: Record<string, never>;
+        ForgotPassword: Record<string, never>;
+        ResetPassword: Record<string, never>;
+        VerifyEmail: Record<string, never>;
+        CreateUser: Record<string, never>;
+        UpdateUser: Record<string, never>;
+        UpdateProfile: Record<string, never>;
+        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>;
+        ExecuteAnalyticsQuery: Record<string, never>;
+        ExecuteMultipleQueries: Record<string, never>;
+        CheckLimitRequest: {
+            /**
+             * @description Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * @description Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+        };
+        LimitResponse: {
+            /**
+             * @description Whether the customer is within their usage limits
+             * @example true
+             */
+            withinLimits: boolean;
+            /**
+             * @description Remaining usage units before hitting the limit
+             * @example 997
+             */
+            remaining: number;
+            /**
+             * @description Optional checkout URL if payment is required
+             * @example https://checkout.solvapay.com/pay_1a2b3c4d
+             */
+            checkoutUrl?: string;
+        };
+        UsageEvent: {
+            /**
+             * @description Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * @description Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+            /**
+             * @description Outcome of the action
+             * @example success
+             * @enum {string}
+             */
+            outcome: "success" | "paywall" | "fail";
+            /**
+             * @description Optional action identifier
+             * @example generate_text
+             */
+            action?: string;
+            /**
+             * @description Unique request identifier matching the limits check
+             * @example req_1a2b3c4d5e6f
+             */
+            requestId: string;
+            /**
+             * @description Duration of the action in milliseconds
+             * @example 1250
+             */
+            actionDuration: number;
+            /**
+             * @description ISO 8601 timestamp of when the action occurred
+             * @example 2025-10-21T10:30:00.000Z
+             */
+            timestamp: string;
+        };
+        CreateCustomerRequest: {
+            /**
+             * @description Customer email address (required)
+             * @example customer@example.com
+             */
+            email: string;
+            /**
+             * @description Customer full name (optional)
+             * @example John Doe
+             */
+            name?: string;
+        };
+        SubscriptionInfo: {
+            /**
+             * @description Subscription reference
+             * @example sub_abc123
+             */
+            reference: string;
+            /**
+             * @description Plan name
+             * @example Pro Plan
+             */
+            planName: string;
+            /**
+             * @description Agent name
+             * @example AI Assistant
+             */
+            agentName: string;
+            /**
+             * @description Subscription status
+             * @example active
+             */
+            status: string;
+            /**
+             * @description Start date
+             * @example 2025-10-27T10:00:00Z
+             */
+            startDate: string;
+        };
+        CustomerResponse: {
+            /**
+             * @description Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            reference: string;
+            /**
+             * @description Customer full name
+             * @example John Doe
+             */
+            name: string;
+            /**
+             * @description Customer email address
+             * @example customer@example.com
+             */
+            email: string;
+            /** @description Active subscriptions */
+            subscriptions?: components["schemas"]["SubscriptionInfo"][];
+        };
+        Agent: Record<string, never>;
+        CreateAgentRequest: Record<string, never>;
+        UpdateAgentRequest: Record<string, never>;
+        BasePlan: Record<string, never>;
+        SubscriptionResponse: {
+            /**
+             * @description Subscription reference identifier
+             * @example sub_1a2b3c4d5e6f
+             */
+            reference: string;
+            /**
+             * @description Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * @description Customer email
+             * @example customer@example.com
+             */
+            customerEmail: string;
+            /**
+             * @description Customer name
+             * @example John Doe
+             */
+            customerName?: string;
+            /**
+             * @description Agent reference identifier
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef: string;
+            /**
+             * @description Agent name
+             * @example My AI Agent
+             */
+            agentName: string;
+            /**
+             * @description Plan reference identifier
+             * @example pln_1a2b3c4d5e6f
+             */
+            planRef: string;
+            /**
+             * @description Plan name
+             * @example Premium Plan
+             */
+            planName: string;
+            /**
+             * @description Plan type
+             * @example recurring
+             * @enum {string}
+             */
+            planType: "recurring" | "usage-based" | "one-time" | "hybrid";
+            /**
+             * @description Subscription status
+             * @example active
+             * @enum {string}
+             */
+            status: "pending" | "active" | "expired" | "cancelled" | "suspended" | "refunded";
+            /**
+             * @description Amount paid in original currency (in cents)
+             * @example 9900
+             */
+            amount: number;
+            /**
+             * @description Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * @description Start date of subscription
+             * @example 2025-01-01T00:00:00.000Z
+             */
+            startDate: string;
+            /**
+             * @description End date of subscription (if applicable)
+             * @example 2025-02-01T00:00:00.000Z
+             */
+            endDate?: string;
+            /**
+             * @description 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
+             * @example true
+             */
+            isRecurring: boolean;
+            /**
+             * @description Next billing date (for recurring subscriptions)
+             * @example 2025-02-01T00:00:00.000Z
+             */
+            nextBillingDate?: string;
+            /**
+             * @description When subscription was cancelled (if applicable)
+             * @example 2025-01-15T00:00:00.000Z
+             */
+            cancelledAt?: string;
+            /**
+             * @description Reason for cancellation (if applicable)
+             * @example Customer request
+             */
+            cancellationReason?: string;
+            /**
+             * @description When subscription was created
+             * @example 2025-01-01T00:00:00.000Z
+             */
+            createdAt: string;
+        };
+        CancelSubscriptionRequest: {
+            /**
+             * @description Reason for cancellation
+             * @example Customer request
+             */
+            reason?: string;
+        };
+        CreatePageSettings: {
+            /** @description Page identifier */
+            id: string;
+            /** @description Page display name */
+            name: string;
+            /** @description Logo URL */
+            logo?: string;
+            /**
+             * @description Text color in hex format
+             * @example #2d3748
+             */
+            textColor: string;
+            /**
+             * @description Button color in hex format
+             * @example #3182ce
+             */
+            buttonColor: string;
+            /**
+             * @description Left background color in hex format
+             * @example #f7fafc
+             */
+            leftBackgroundColor: string;
+            /**
+             * @description Right background color in hex format
+             * @example #ffffff
+             */
+            rightBackgroundColor: string;
+            /**
+             * @description Font family
+             * @example Inter
+             */
+            fontFamily: string;
+            /**
+             * @description Font size
+             * @example 16px
+             */
+            fontSize: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/**
+ * SolvaPay API Client Type Definitions
+ *
+ * Types related to the SolvaPay API client and backend communication.
+ */
+
+/**
+ * Extended LimitResponse with plan field
+ */
+type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
+    plan: string;
+};
+/**
+ * Extended CustomerResponse with proper field mapping
+ */
+type CustomerResponseMapped = {
+    customerRef: string;
+    email?: string;
+    name?: string;
+    plan?: string;
+};
+/**
+ * SolvaPay API Client Interface
+ *
+ * This interface defines the contract for communicating with the SolvaPay backend.
+ * Uses auto-generated types from the OpenAPI specification.
+ * You can provide your own implementation or use the default createSolvaPayClient().
+ */
+interface SolvaPayClient {
+    checkLimits(params: components['schemas']['CheckLimitRequest']): Promise<LimitResponseWithPlan>;
+    trackUsage(params: components['schemas']['UsageEvent'] & {
+        planRef: string;
+    }): Promise<void>;
+    createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
+        customerRef: string;
+    }>;
+    getCustomer?(params: {
+        customerRef: string;
+    }): Promise<CustomerResponseMapped>;
+    listAgents?(): Promise<Array<{
+        reference: string;
+        name: string;
+        description?: string;
+    }>>;
+    createAgent?(params: components['schemas']['CreateAgentRequest']): Promise<{
+        reference: string;
+        name: string;
+    }>;
+    deleteAgent?(agentRef: string): Promise<void>;
+    listPlans?(agentRef: string): Promise<Array<{
+        reference: string;
+        name: string;
+        isFreeTier?: boolean;
+        freeUnits?: number;
+        description?: string;
+    }>>;
+    createPlan?(params: components['schemas']['CreatePlanRequest'] & {
+        agentRef: string;
+    }): Promise<{
+        reference: string;
+        name: string;
+    }>;
+    deletePlan?(agentRef: string, planRef: string): Promise<void>;
+    createPaymentIntent?(params: {
+        agentRef: string;
+        planRef: string;
+        customerRef: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        id: string;
+        clientSecret: string;
+        publishableKey: string;
+        accountId?: string;
+    }>;
+}
+
+/**
+ * Paywall Type Definitions
+ *
+ * Types related to paywall protection, limits, and gating functionality.
+ */
+/**
+ * Arguments passed to protected handlers
+ */
+interface PaywallArgs {
+    [key: string]: any;
+    auth?: {
+        customer_ref?: string;
+    };
+}
+/**
+ * Metadata for configuring paywall protection
+ */
+interface PaywallMetadata {
+    agent?: string;
+    plan?: string;
+}
+/**
+ * Structured content for paywall errors
+ */
+interface PaywallStructuredContent {
+    kind: 'payment_required';
+    agent: string;
+    checkoutUrl: string;
+    message: string;
+}
+/**
+ * MCP tool result with optional paywall information
+ */
+interface PaywallToolResult {
+    content?: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: PaywallStructuredContent;
+}
+
+/**
+ * Configuration Options Type Definitions
+ *
+ * Types for configuring various aspects of the SDK including retry behavior,
+ * payable protection, and framework adapters.
+ */
+/**
+ * Retry configuration options
+ */
+interface RetryOptions$1 {
+    /**
+     * 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;
+}
+/**
+ * Options for configuring payable protection
+ */
+interface PayableOptions {
+    /**
+     * Agent identifier (auto-detected from package.json if not provided)
+     */
+    agent?: string;
+    /**
+     * Agent reference (alias for agent, preferred for consistency with backend API)
+     */
+    agentRef?: string;
+    /**
+     * Plan identifier (defaults to agent name if not provided)
+     */
+    plan?: string;
+    /**
+     * Plan reference (alias for plan, preferred for consistency with backend API)
+     */
+    planRef?: string;
+    /**
+     * Optional function to extract customer reference from context
+     */
+    getCustomerRef?: (context: any) => string | Promise<string>;
+}
+/**
+ * HTTP adapter options for Express/Fastify
+ */
+interface HttpAdapterOptions {
+    /**
+     * Extract arguments from HTTP request
+     */
+    extractArgs?: (req: any) => any;
+    /**
+     * Extract customer reference from HTTP request
+     */
+    getCustomerRef?: (req: any) => string | Promise<string>;
+    /**
+     * Transform the response before sending
+     */
+    transformResponse?: (result: any, reply: any) => any;
+}
+/**
+ * Next.js adapter options for App Router
+ */
+interface NextAdapterOptions {
+    /**
+     * Extract arguments from Web Request
+     */
+    extractArgs?: (request: Request, context?: any) => any | Promise<any>;
+    /**
+     * Extract customer reference from Web Request
+     */
+    getCustomerRef?: (request: Request) => string | Promise<string>;
+    /**
+     * Transform the response before returning
+     */
+    transformResponse?: (result: any) => any;
+}
+/**
+ * MCP adapter options for MCP servers
+ */
+interface McpAdapterOptions {
+    /**
+     * Extract customer reference from MCP args
+     */
+    getCustomerRef?: (args: any) => string | Promise<string>;
+    /**
+     * Transform the response before wrapping in MCP format
+     */
+    transformResponse?: (result: any) => any;
+}
+
+/**
+ * SolvaPay Factory
+ *
+ * Main entry point for creating SolvaPay instances with the unified payable API
+ */
+
+/**
+ * Configuration for creating a SolvaPay instance
+ */
+interface CreateSolvaPayConfig {
+    /**
+     * API key for production use (creates client automatically)
+     */
+    apiKey?: string;
+    /**
+     * API client for testing or custom implementations
+     */
+    apiClient?: SolvaPayClient;
+    /**
+     * Optional API base URL (only used with apiKey)
+     */
+    apiBaseUrl?: string;
+}
+/**
+ * Payable function that provides explicit adapters
+ */
+interface PayableFunction {
+    /**
+     * HTTP adapter for Express/Fastify
+     */
+    http<T = any>(businessLogic: (args: any) => Promise<T>, options?: HttpAdapterOptions): (req: any, reply: any) => Promise<any>;
+    /**
+     * Next.js adapter for App Router
+     */
+    next<T = any>(businessLogic: (args: any) => Promise<T>, options?: NextAdapterOptions): (request: Request, context?: any) => Promise<Response>;
+    /**
+     * MCP adapter for Model Context Protocol servers
+     */
+    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
+     */
+    function<T = any>(businessLogic: (args: any) => Promise<T>): Promise<(args: any) => Promise<T>>;
+}
+/**
+ * SolvaPay instance with payable method and common API methods
+ */
+interface SolvaPay {
+    /**
+     * Create a payable handler with explicit adapters
+     */
+    payable(options?: PayableOptions): PayableFunction;
+    /**
+     * Ensure customer exists (for testing/setup)
+     * Only attempts creation once per customer (idempotent).
+     */
+    ensureCustomer(customerRef: string): Promise<string>;
+    /**
+     * Create a payment intent for a customer to subscribe to a plan
+     */
+    createPaymentIntent(params: {
+        agentRef: string;
+        planRef: string;
+        customerRef: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        id: string;
+        clientSecret: string;
+        publishableKey: string;
+        accountId?: string;
+    }>;
+    /**
+     * Check if customer is within usage limits
+     */
+    checkLimits(params: {
+        customerRef: string;
+        agentRef: string;
+    }): Promise<{
+        withinLimits: boolean;
+        remaining: number;
+        plan: string;
+        checkoutUrl?: string;
+    }>;
+    /**
+     * Track usage for a customer action
+     */
+    trackUsage(params: {
+        customerRef: string;
+        agentRef: string;
+        planRef: string;
+        outcome: 'success' | 'paywall' | 'fail';
+        action?: string;
+        requestId: string;
+        actionDuration: number;
+        timestamp: string;
+    }): Promise<void>;
+    /**
+     * Create a new customer
+     */
+    createCustomer(params: {
+        email: string;
+        name?: string;
+    }): Promise<{
+        customerRef: string;
+    }>;
+    /**
+     * Get customer details
+     */
+    getCustomer(params: {
+        customerRef: string;
+    }): Promise<{
+        customerRef: string;
+        email?: string;
+        name?: string;
+        plan?: string;
+    }>;
+    /**
+     * Direct access to the API client for advanced operations
+     * (agent/plan management, etc.)
+     */
+    apiClient: SolvaPayClient;
+}
+/**
+ * Create a SolvaPay instance
+ *
+ * @param config - Configuration with either apiKey or apiClient
+ * @returns SolvaPay instance with payable() method
+ *
+ * @example
+ * ```typescript
+ * // Production: Pass API key
+ * const solvaPay = createSolvaPay({
+ *   apiKey: process.env.SOLVAPAY_SECRET_KEY
+ * });
+ *
+ * // Testing: Pass 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);
+ * ```
+ */
+declare function createSolvaPay(config: CreateSolvaPayConfig): SolvaPay;
+
+/**
+ * SolvaPay Server SDK - API Client
+ *
+ * This module provides the API client implementation for communicating with
+ * the SolvaPay backend. The client handles all HTTP requests for paywall
+ * protection, usage tracking, and resource management.
+ */
+
+/**
+ * Configuration options for creating a SolvaPay API client
+ */
+type ServerClientOptions = {
+    /**
+     * Your SolvaPay API key (required)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the SolvaPay API (optional)
+     * Defaults to https://api-dev.solvapay.com
+     */
+    apiBaseUrl?: string;
+};
+/**
+ * Creates a SolvaPay API client that implements the full SolvaPayClient
+ * for server-side paywall and usage tracking operations.
+ *
+ * @param opts - Configuration options including API key and optional base URL
+ * @returns A fully configured SolvaPayClient instance
+ * @throws {SolvaPayError} If API key is missing
+ *
+ * @example
+ * ```typescript
+ * const client = createSolvaPayClient({
+ *   apiKey: process.env.SOLVAPAY_SECRET_KEY!,
+ *   apiBaseUrl: 'https://api.solvapay.com' // optional
+ * });
+ * ```
+ */
+declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient;
+
+/**
+ * SolvaPay SDK - Universal Paywall Protection
+ *
+ * One API that works everywhere:
+ * - HTTP frameworks (Fastify, Express)
+ * - MCP servers
+ * - Class-based and functional programming
+ */
+
+declare class PaywallError extends Error {
+    structuredContent: PaywallStructuredContent;
+    constructor(message: string, structuredContent: PaywallStructuredContent);
+}
+
+/**
+ * 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
+ *
+ * @template T The return type of the async function
+ * @param fn The async function to execute
+ * @param options Retry configuration options
+ * @returns A promise that resolves with the function result or rejects with the last error
+ *
+ * @example
+ * ```typescript
+ * // Simple retry with defaults
+ * const result = await withRetry(() => apiCall());
+ *
+ * // Custom retry with conditional logic
+ * const result = await withRetry(
+ *   () => apiCall(),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelay: 1000,
+ *     backoffStrategy: 'exponential',
+ *     shouldRetry: (error) => error.message.includes('timeout'),
+ *     onRetry: (error, attempt) => console.log(`Retry ${attempt + 1}`)
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * SolvaPay Server SDK
+ *
+ * Main entry point for the SolvaPay server-side SDK.
+ * Provides unified payable API with explicit adapters for all frameworks.
+ */
+
+declare function verifyWebhook({ body, signature, secret }: {
+    body: string;
+    signature: string;
+    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 };