@solvapay/server 1.0.0-preview.9 → 1.0.1-preview.2

package/dist/index.d.cts

@@ -1,441 +1,1820 @@
+type WebhookEventType = 'payment.succeeded' | 'payment.failed' | 'payment.refunded' | 'payment.refund_failed' | 'purchase.created' | 'purchase.updated' | 'purchase.cancelled' | 'purchase.expired' | 'purchase.suspended' | 'customer.created' | 'customer.updated' | 'customer.deleted';
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    created: number;
+    api_version: string;
+    data: {
+        object: Record<string, any>;
+        previous_attributes: Record<string, any> | null;
+    };
+    livemode: boolean;
+    request: {
+        id: string | null;
+        idempotency_key: string | null;
+    };
+}
+
 interface components {
     schemas: {
+        UpdateProviderDto: {
+            /** @description Legal entity information */
+            legalEntity?: Record<string, never>;
+            /**
+             * Provider description
+             * @example My business
+             */
+            description?: string;
+            /**
+             * Business website URL
+             * @example https://example.com
+             */
+            website?: string;
+            /**
+             * Business type
+             * @example individual
+             * @enum {string}
+             */
+            businessType?: "individual" | "company";
+            /**
+             * Business email address
+             * @example business@example.com
+             */
+            businessEmail?: string;
+            /**
+             * Support email address
+             * @example support@example.com
+             */
+            supportEmail?: string;
+            /**
+             * Business telephone number
+             * @example +1234567890
+             */
+            telephone?: string;
+            /**
+             * Support telephone number
+             * @example +1234567890
+             */
+            supportTelephone?: string;
+            /**
+             * Default currency code
+             * @example usd
+             */
+            defaultCurrency?: string;
+            /** @description Arbitrary metadata */
+            metadata?: Record<string, never>;
+            /** @description Terms of Service acceptance */
+            tosAcceptance?: Record<string, never>;
+        };
         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>;
+        RequestEmailChange: {
+            newEmail: string;
+        };
+        VerifyEmailChange: {
+            code: string;
+        };
         CreateCheckoutSessionRequest: {
             /**
-             * @description Customer reference identifier
+             * Customer reference
              * @example cus_3c4d5e6f7g8h
              */
-            customerRef: string;
+            customerReference: string;
+            /**
+             * Plan reference (optional)
+             * @example pln_2b3c4d5e6f7g
+             */
+            planRef?: string;
+            /**
+             * Product reference (required)
+             * @example prd_1a2b3c4d5e6f
+             */
+            productRef: string;
+        };
+        CheckoutSessionResponse: {
+            /**
+             * Checkout session ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Public session ID used in checkout URL
+             * @example a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            sessionId: string;
+            /**
+             * Amount in cents
+             * @example 2999
+             */
+            amount: number;
+            /**
+             * Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * Session status
+             * @example active
+             */
+            status: string;
+            /**
+             * Checkout URL to open the checkout page
+             * @example https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            checkoutUrl: string;
+        };
+        SelectCustomerSessionProductRequest: {
+            /**
+             * Product reference or ID to scope the customer manage session
+             * @example prd_1a2b3c4d5e6f
+             */
+            productRef: string;
+        };
+        CancelRenewalRequest: {
+            /** @description Reason for cancelling renewal */
+            reason?: string;
+        };
+        ExternalAccount: {
+            /**
+             * Country code
+             * @example US
+             */
+            country: string;
+            /**
+             * Currency code
+             * @example usd
+             */
+            currency: string;
+            /**
+             * Account holder name
+             * @example John Doe
+             */
+            accountHolderName: string;
+            /**
+             * Account holder type
+             * @example individual
+             * @enum {string}
+             */
+            accountHolderType: "individual" | "company";
+            /**
+             * Routing number
+             * @example 110000000
+             */
+            routingNumber: string;
+            /**
+             * Account number
+             * @example 000123456789
+             */
+            accountNumber: string;
+        };
+        TosAcceptance: {
+            /**
+             * IP address of user accepting ToS
+             * @example 192.168.1.1
+             */
+            ip: string;
+        };
+        UpdateConnectedAccount: {
+            /**
+             * Business website URL
+             * @example https://example.com
+             */
+            website?: string;
+            /** @description External bank account */
+            externalAccount?: components["schemas"]["ExternalAccount"];
+            /** @description Terms of Service acceptance */
+            tosAcceptance?: components["schemas"]["TosAcceptance"];
+        };
+        Signup: {
+            name: string;
+            email: string;
+            /** @enum {string} */
+            type?: "provider" | "admin" | "super_admin";
+        };
+        AuthUserDto: {
+            id: string;
+            name: string;
+            email: string;
+            /** @enum {string} */
+            type: "provider" | "admin" | "super_admin";
+            emailVerified: boolean;
+            /** @enum {string} */
+            authProvider: "local" | "google" | "github" | "facebook";
+            providerId?: string;
+            providerRole?: string;
+            preferences?: Record<string, never>;
+        };
+        AuthResponse: {
+            user: components["schemas"]["AuthUserDto"];
+            accessToken?: string;
+            refreshToken?: string;
+            expiresIn?: number;
+            message?: string;
+            requiresMfa?: boolean;
+            requiresMfaSetup?: boolean;
+        };
+        Login: {
+            /** @description Email to send a 6-digit login code to */
+            email: string;
+        };
+        VerifyLoginCode: {
+            email: string;
+            /** @description 6-digit login code sent to email */
+            code: string;
+        };
+        VerifyEmail: {
+            emailVerificationCode: string;
+        };
+        DynamicClientRegistrationDto: {
+            /** @example My AI Agent */
+            client_name: string;
+            /**
+             * @example [
+             *       "https://agent.example.com/callback"
+             *     ]
+             */
+            redirect_uris: string[];
+            /**
+             * @example [
+             *       "authorization_code",
+             *       "refresh_token"
+             *     ]
+             */
+            grant_types?: string[];
+            /**
+             * @example [
+             *       "code"
+             *     ]
+             */
+            response_types?: string[];
+            /** @example agent-123 */
+            software_id?: string;
+            /** @example 1.0.0 */
+            software_version?: string;
+            /** @example https://example.com/logo.png */
+            logo_uri?: string;
+            /** @example https://example.com/tos */
+            tos_uri?: string;
+            /** @example https://example.com/policy */
+            policy_uri?: string;
+            /** @example https://example.com */
+            client_uri?: string;
+        };
+        DynamicClientRegistrationResponseDto: {
+            /** @example client-id-123 */
+            client_id: string;
+            /** @example client-secret-456 */
+            client_secret: string;
+            /** @example 1734567890 */
+            client_id_issued_at: number;
+            /** @example 0 */
+            client_secret_expires_at: number;
+            /** @example My AI Agent */
+            client_name: string;
+            /**
+             * @example [
+             *       "https://agent.example.com/callback"
+             *     ]
+             */
+            redirect_uris: string[];
+            /**
+             * @example [
+             *       "authorization_code",
+             *       "refresh_token"
+             *     ]
+             */
+            grant_types: string[];
+            /**
+             * @example [
+             *       "code"
+             *     ]
+             */
+            response_types: string[];
+            /** @example openid profile email */
+            scope: string;
+            /** @example client_secret_basic */
+            token_endpoint_auth_method: string;
+        };
+        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;
+        };
+        CreateOAuthClientDto: Record<string, never>;
+        UpdateOAuthClientDto: Record<string, never>;
+        Plan: {
+            /**
+             * Plan type exposed in SDK
+             * @example recurring
+             * @enum {string}
+             */
+            type: "recurring" | "one-time";
+            /**
+             * Plan ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Plan reference
+             * @example pln_1A2B3C4D
+             */
+            reference: string;
+            /**
+             * Plan price in cents
+             * @example 2999
+             */
+            price: number;
+            /**
+             * Currency code (ISO 4217)
+             * @example USD
+             */
+            currency: string;
+            /**
+             * Currency symbol (derived from currency)
+             * @example $
+             */
+            currencySymbol?: string;
+            /**
+             * Number of free units included
+             * @example 100
+             */
+            freeUnits?: number;
+            /**
+             * One-time setup fee
+             * @example 500
+             */
+            setupFee?: number;
+            /**
+             * Free trial period in days
+             * @example 14
+             */
+            trialDays?: number;
+            /**
+             * Billing cycle
+             * @example monthly
+             */
+            billingCycle?: string;
+            /**
+             * Billing model
+             * @example pre-paid
+             * @enum {string}
+             */
+            billingModel?: "pre-paid" | "post-paid";
+            /**
+             * Price per usage unit
+             * @example 0.01
+             */
+            pricePerUnit?: number;
+            /**
+             * What the plan measures for usage tracking
+             * @example requests
+             */
+            measures?: string;
+            /**
+             * Usage limit for the meter
+             * @example 10000
+             */
+            limit?: number;
+            /**
+             * Whether unused units roll over to next period
+             * @example false
+             */
+            rolloverUnusedUnits?: boolean;
+            /** @description Usage limits */
+            limits?: {
+                [key: string]: unknown;
+            };
+            /** @description Plan features */
+            features?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Whether this is a free tier plan
+             * @example false
+             */
+            isFreeTier: boolean;
+            /**
+             * Whether payment is required
+             * @example true
+             */
+            requiresPayment: boolean;
+            /**
+             * Whether the plan is active (derived from status)
+             * @example true
+             */
+            isActive: boolean;
+            /** @description Maximum number of active users */
+            maxActiveUsers?: number;
+            /** @description Access expiry in days */
+            accessExpiryDays?: number;
+            /**
+             * Plan status
+             * @example active
+             */
+            status: string;
+            /** @description Creation timestamp */
+            createdAt: string;
+            /** @description Last update timestamp */
+            updatedAt: string;
+        };
+        CreatePlanRequest: {
+            /**
+             * Plan type exposed in SDK
+             * @example recurring
+             * @enum {string}
+             */
+            type?: "recurring" | "one-time";
+            /**
+             * Billing cycle (required for recurring/hybrid, optional for post-paid usage-based)
+             * @example monthly
+             * @enum {string}
+             */
+            billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
+            /**
+             * Plan price in cents
+             * @example 2999
+             */
+            price?: number;
+            /**
+             * Currency code (ISO 4217)
+             * @example USD
+             * @enum {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";
+            /**
+             * Number of free units included
+             * @example 100
+             */
+            freeUnits?: number;
+            /**
+             * Usage limit for the meter
+             * @example 10000
+             */
+            limit?: number;
+            /**
+             * Usage limits (shape varies by plan type)
+             * @example {
+             *       "maxTransactions": 1000
+             *     }
+             */
+            limits?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Plan features (generic key/value, shape is provider-defined)
+             * @example {
+             *       "apiAccess": true,
+             *       "prioritySupport": false
+             *     }
+             */
+            features?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Whether this is a free tier plan
+             * @example false
+             */
+            isFreeTier?: boolean;
+            /**
+             * Whether payment is required
+             * @example true
+             */
+            requiresPayment?: boolean;
+            /**
+             * Plan status
+             * @example active
+             * @enum {string}
+             */
+            status?: "active" | "inactive" | "archived";
+            /**
+             * Maximum number of active users
+             * @example 10
+             */
+            maxActiveUsers?: number;
+            /**
+             * Access expiry in days
+             * @example 30
+             */
+            accessExpiryDays?: number;
+            /** @description Additional metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Whether this is the default plan
+             * @example false
+             */
+            default?: boolean;
+        };
+        UpdatePlanRequest: {
+            /**
+             * Billing cycle
+             * @example monthly
+             * @enum {string}
+             */
+            billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
+            /**
+             * Plan price in cents
+             * @example 2999
+             */
+            price?: number;
+            /**
+             * Currency code (ISO 4217)
+             * @example USD
+             */
+            currency?: string;
+            /**
+             * Number of free units included
+             * @example 100
+             */
+            freeUnits?: number;
+            /**
+             * Usage limit for the meter
+             * @example 10000
+             */
+            limit?: number;
+            /**
+             * Usage limits (shape varies by plan type)
+             * @example {
+             *       "maxTransactions": 1000
+             *     }
+             */
+            limits?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Plan features (generic key/value, shape is provider-defined)
+             * @example {
+             *       "apiAccess": true,
+             *       "prioritySupport": false
+             *     }
+             */
+            features?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Whether this is a free tier plan
+             * @example false
+             */
+            isFreeTier?: boolean;
+            /**
+             * Whether payment is required
+             * @example true
+             */
+            requiresPayment?: boolean;
+            /**
+             * Plan status
+             * @example active
+             * @enum {string}
+             */
+            status?: "active" | "inactive" | "archived";
+            /**
+             * Maximum number of active users
+             * @example 10
+             */
+            maxActiveUsers?: number;
+            /**
+             * Access expiry in days
+             * @example 30
+             */
+            accessExpiryDays?: number;
+            /** @description Additional metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Whether this is the default plan
+             * @example false
+             */
+            default?: boolean;
+        };
+        ProductConfigDto: {
+            /**
+             * Fulfillment type
+             * @example digital
+             */
+            fulfillmentType?: string;
+            /**
+             * Validity period in days
+             * @example 30
+             */
+            validityPeriod?: number;
+            /**
+             * Delivery method
+             * @example api
+             */
+            deliveryMethod?: string;
+        };
+        CreateProductRequest: {
+            /**
+             * Product name
+             * @example AI Writing Assistant
+             */
+            name: string;
+            /**
+             * Product description
+             * @example AI-powered writing tool
+             */
+            description?: string;
+            /** @description URL to the product image */
+            imageUrl?: string;
+            /**
+             * Free-form product type defined by the provider
+             * @example Coding Assistant
+             */
+            productType?: string;
+            /**
+             * Whether this product uses MCP Pay proxy
+             * @default false
+             */
+            isMcpPay: boolean;
+            /** @description Product-specific configuration */
+            config?: components["schemas"]["ProductConfigDto"];
+            /** @description Arbitrary key-value metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
+        SdkPlanResponse: {
+            /**
+             * Plan ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Plan reference
+             * @example pln_1A2B3C4D
+             */
+            reference: string;
+            /**
+             * Plan price in cents
+             * @example 2999
+             */
+            price: number;
+            /**
+             * Currency code (ISO 4217)
+             * @example USD
+             */
+            currency: string;
+            /**
+             * Currency symbol
+             * @example $
+             */
+            currencySymbol?: string;
+            /**
+             * One-time setup fee
+             * @example 500
+             */
+            setupFee?: number;
+            /**
+             * Free trial period in days
+             * @example 14
+             */
+            trialDays?: number;
+            /**
+             * Billing cycle
+             * @example monthly
+             */
+            billingCycle?: string;
+            /**
+             * Billing model
+             * @example pre-paid
+             */
+            billingModel?: string;
+            /**
+             * Price per unit in cents
+             * @example 10
+             */
+            pricePerUnit?: number;
+            /**
+             * What the plan measures for usage tracking
+             * @example requests
+             */
+            measures?: string;
+            /**
+             * Usage limit for the meter
+             * @example 10000
+             */
+            limit?: number;
+            /**
+             * Whether unused units roll over to next period
+             * @example false
+             */
+            rolloverUnusedUnits?: boolean;
+            /**
+             * Included free units
+             * @example 1000
+             */
+            freeUnits?: number;
+            /** @description Usage limits */
+            limits?: {
+                [key: string]: unknown;
+            };
+            /** @description Plan features */
+            features?: {
+                [key: string]: unknown;
+            };
+            /**
+             * 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;
+            /**
+             * Plan status
+             * @example active
+             */
+            status: string;
+            /** @description Creation timestamp */
+            createdAt: string;
+            /** @description Last update timestamp */
+            updatedAt: string;
+        };
+        SdkProductResponse: {
+            /**
+             * Product ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Product reference
+             * @example prd_1A2B3C4D
+             */
+            reference: string;
+            /**
+             * Product name
+             * @example AI Writing Assistant
+             */
+            name: string;
+            /** @description Product description */
+            description?: string;
+            /** @description URL to the product image */
+            imageUrl?: string;
+            /** @description Free-form product type */
+            productType?: string;
+            /**
+             * Product status
+             * @example active
+             */
+            status: string;
+            /**
+             * Product balance in cents
+             * @example 0
+             */
+            balance: number;
+            /**
+             * Total number of transactions
+             * @example 0
+             */
+            totalTransactions: number;
+            /**
+             * Whether this product uses MCP Pay proxy
+             * @example false
+             */
+            isMcpPay: boolean;
+            /** @description Product-specific configuration */
+            config?: components["schemas"]["ProductConfigDto"];
+            /** @description Arbitrary key-value metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+            /** @description Creation timestamp */
+            createdAt: string;
+            /** @description Last update timestamp */
+            updatedAt: string;
+            /** @description Plans associated with this product */
+            plans?: components["schemas"]["SdkPlanResponse"][];
+            /**
+             * MCP linkage details for MCP-enabled products
+             * @example {
+             *       "mcpServerId": "67f90f1f1b1c9c0b8df0f111",
+             *       "mcpServerReference": "mcp_ABC123",
+             *       "mcpSubdomain": "acme-docs",
+             *       "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp",
+             *       "originUrl": "https://origin.example.com/mcp",
+             *       "defaultPlanId": "67f90f1f1b1c9c0b8df0f001"
+             *     }
+             */
+            mcp?: {
+                [key: string]: unknown;
+            };
+        };
+        UpdateProductRequest: {
+            /** @description Product name */
+            name?: string;
+            /** @description Product description */
+            description?: string;
+            /** @description URL to the product image */
+            imageUrl?: string;
+            /** @description Free-form product type defined by the provider */
+            productType?: string;
+            /**
+             * Product status
+             * @enum {string}
+             */
+            status?: "active" | "inactive" | "suspended";
+            /** @description Product-specific configuration */
+            config?: components["schemas"]["ProductConfigDto"];
+            /** @description Arbitrary key-value metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
+        McpBootstrapFreePlanConfig: {
+            /**
+             * Free plan display name override
+             * @example Starter
+             */
+            name?: string;
+            /**
+             * Included free units (default 1000)
+             * @example 500
+             */
+            freeUnits?: number;
+        };
+        McpBootstrapPaidPlanInput: {
+            /**
+             * Logical plan key (must not be "free")
+             * @example pro
+             */
+            key: string;
+            /**
+             * Plan display name
+             * @example Pro
+             */
+            name: string;
+            /**
+             * Plan price in cents (must be > 0)
+             * @example 2000
+             */
+            price: number;
+            /**
+             * Currency code (ISO 4217)
+             * @example USD
+             */
+            currency: string;
+            /**
+             * Billing cycle for recurring plans
+             * @example monthly
+             * @enum {string}
+             */
+            billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
+            /**
+             * Plan type
+             * @example recurring
+             * @enum {string}
+             */
+            type?: "recurring" | "one-time";
+            /**
+             * Included free units
+             * @example 1000
+             */
+            freeUnits?: number;
+            /**
+             * Meter id for usage tracking
+             * @example 67f90f1f1b1c9c0b8df0f001
+             */
+            meterId?: string;
+            /**
+             * Plan usage limit
+             * @example 10000
+             */
+            limit?: number;
+            /** @description Plan features */
+            features?: {
+                [key: string]: unknown;
+            };
+        };
+        McpBootstrapToolInput: {
+            /**
+             * Tool name
+             * @example search_docs
+             */
+            name: string;
+            /**
+             * Tool description
+             * @example Search indexed documents
+             */
+            description?: string;
+            /**
+             * If true, tool is publicly available without a plan
+             * @example false
+             */
+            noPlan?: boolean;
+            /**
+             * Direct plan IDs allowed for this tool
+             * @example [
+             *       "67f90f1f1b1c9c0b8df0f001"
+             *     ]
+             */
+            planIds?: string[];
+            /**
+             * Plan references allowed for this tool
+             * @example [
+             *       "pln_ABC123"
+             *     ]
+             */
+            planRefs?: string[];
+            /**
+             * Bootstrap plan keys allowed for this tool (for example free or starter_paid)
+             * @example [
+             *       "free"
+             *     ]
+             */
+            planKeys?: string[];
+        };
+        McpBootstrapRequest: {
+            /**
+             * Product name (optional when derivable from origin MCP metadata)
+             * @example Acme MCP Toolkit
+             */
+            name?: string;
+            /**
+             * Product description
+             * @example MCP toolkit with tiered access
+             */
+            description?: string;
+            /** @description Product image URL */
+            imageUrl?: string;
+            /**
+             * Free-form product type
+             * @example MCP Server
+             */
+            productType?: string;
+            /**
+             * Origin MCP server URL (must be https)
+             * @example https://origin.example.com/mcp
+             */
+            originUrl: string;
+            /**
+             * Optional final MCP subdomain override (for example, value returned by bootstrap-subdomain-checks)
+             * @example acme-docs
+             */
+            mcpDomain?: string;
+            /**
+             * Optional auth header name forwarded to origin server
+             * @example X-API-Key
+             */
+            authHeaderName?: string;
+            /**
+             * Optional auth API key forwarded to origin server
+             * @example sk-origin-123
+             */
+            authApiKey?: string;
+            /** @description Free plan config overrides. A free plan is always created; this just customizes name/freeUnits. */
+            freePlan?: components["schemas"]["McpBootstrapFreePlanConfig"];
+            /** @description Paid plan definitions requiring price + currency */
+            paidPlans?: components["schemas"]["McpBootstrapPaidPlanInput"][];
+            /** @description Tool to plan mapping configuration */
+            tools?: components["schemas"]["McpBootstrapToolInput"][];
+            /** @description Arbitrary product metadata */
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
+        McpBootstrapResult: {
+            /** @description Created product */
+            product: components["schemas"]["SdkProductResponse"];
+            /**
+             * Created or updated MCP server identity
+             * @example {
+             *       "id": "67f90f1f1b1c9c0b8df0f111",
+             *       "reference": "mcp_ABC123",
+             *       "subdomain": "acme-docs",
+             *       "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp",
+             *       "url": "https://origin.example.com/mcp",
+             *       "defaultPlanId": "67f90f1f1b1c9c0b8df0f001"
+             *     }
+             */
+            mcpServer: {
+                [key: string]: unknown;
+            };
+            /**
+             * Resolved plan mapping by bootstrap key
+             * @example {
+             *       "free": {
+             *         "id": "67f90f1f1b1c9c0b8df0f001",
+             *         "reference": "pln_FREE123",
+             *         "name": "Free"
+             *       }
+             *     }
+             */
+            planMap: {
+                [key: string]: unknown;
+            };
+            /**
+             * True when tools were auto-discovered from origin because the request omitted tools
+             * @example true
+             */
+            toolsAutoMapped?: boolean;
+            /** @description Auto-discovered tools used during bootstrap */
+            autoMappedTools?: {
+                name?: string;
+                description?: string;
+            }[];
+        };
+        McpBootstrapPreviewResult: {
+            /** @description Discovered tools from the origin MCP server */
+            discoveredTools: {
+                name?: string;
+                description?: string;
+            }[];
+            /** @description Validation status for the provided bootstrap payload */
+            validation: {
+                valid?: boolean;
+                errors?: components["schemas"]["McpBootstrapPreviewValidationError"][];
+            };
+            /**
+             * Product name derived from origin MCP metadata or hostname fallback
+             * @example acme-origin-mcp
+             */
+            derivedName?: string;
+            /**
+             * Product description derived from origin server instructions
+             * @example MCP toolkit for document retrieval and summarization.
+             */
+            derivedDescription?: string;
+            /** @description Source of derived metadata */
+            metadataSource: {
+                /** @enum {string} */
+                name?: "request" | "origin" | "hostname";
+                /** @enum {string} */
+                description?: "request" | "instructions" | "none";
+            };
+            /** @description Suggested default tool-to-plan mapping for UI review */
+            suggestedMapping: {
+                name?: string;
+                description?: string;
+                planKey?: string;
+            }[];
+        };
+        RecordMeterEventDto: {
+            /**
+             * Meter name to record against
+             * @example requests
+             */
+            meterName: string;
+            /**
+             * Customer reference
+             * @example cus_ABC123
+             */
+            customerId: string;
+            /**
+             * Numeric value (default 1)
+             * @default 1
+             * @example 1
+             */
+            value: number;
+            /**
+             * Arbitrary key-value tags
+             * @example {
+             *       "endpoint": "/api/v1/search",
+             *       "region": "us-east-1"
+             *     }
+             */
+            properties?: {
+                [key: string]: unknown;
+            };
+            /** @description Product ID to scope the usage event to */
+            productId?: string;
+            /** @description Product reference to scope the usage event to */
+            productReference?: string;
+            /** @description ISO 8601 timestamp (defaults to now) */
+            timestamp?: string;
+        };
+        RecordBulkMeterEventsDto: {
+            /** @description Array of events to record */
+            events: components["schemas"]["RecordMeterEventDto"][];
+        };
+        CreateCustomerSessionRequest: {
+            /**
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerRef: string;
+            /**
+             * Optional product reference or ID to scope the customer manage page to a single product.
+             * @example prd_1a2b3c4d5e6f
+             */
+            productRef?: 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: {
+            /**
+             * Customer email address (required)
+             * @example customer@example.com
+             */
+            email: string;
+            /**
+             * Customer full name (optional)
+             * @example John Doe
+             */
+            name?: string;
+            /**
+             * External reference ID from your auth system to map this customer to an auth user (optional)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
+        };
+        PurchaseInfo: {
+            /**
+             * Purchase reference
+             * @example pur_1A2B3C4D
+             */
+            reference: string;
+            /**
+             * Product name
+             * @example API Gateway Manager
+             */
+            productName: string;
+            /**
+             * Product reference
+             * @example prd_abc123
+             */
+            productReference?: string;
+            /**
+             * Purchase status
+             * @example active
+             */
+            status: string;
+            /**
+             * Start date
+             * @example 2025-10-27T10:00:00Z
+             */
+            startDate: string;
+            /**
+             * Amount paid in original currency (in cents)
+             * @example 9900
+             */
+            amount: number;
+            /**
+             * Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * End date of purchase
+             * @example 2025-11-27T10:00:00Z
+             */
+            endDate?: string;
+            /**
+             * When purchase was cancelled
+             * @example 2025-10-28T10:00:00Z
+             */
+            cancelledAt?: string;
+            /**
+             * Reason for cancellation
+             * @example Customer request
+             */
+            cancellationReason?: string;
+            /** @description Snapshot of the plan at time of purchase */
+            planSnapshot?: Record<string, never>;
+        };
+        CustomerResponse: {
+            /**
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
+             */
+            reference: string;
+            /**
+             * Customer full name
+             * @example John Doe
+             */
+            name: string;
+            /**
+             * Customer email address
+             * @example customer@example.com
+             */
+            email: string;
+            /**
+             * External reference ID from your auth system (if set during creation or update)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
+            /** @description Active purchases */
+            purchases?: components["schemas"]["PurchaseInfo"][];
+        };
+        CreateCustomerSessionResponse: {
+            /**
+             * Customer session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            sessionId: string;
+            /**
+             * Full customer URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
+             */
+            customerUrl: string;
+        };
+        GetCustomerSessionResponse: {
+            /**
+             * Customer session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            sessionId: string;
+            /**
+             * Session status
+             * @example active
+             * @enum {string}
+             */
+            status: "active" | "expired" | "used";
+            /**
+             * Full customer URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
+             */
+            customerUrl: string;
+            /**
+             * Session expiration date
+             * @example 2025-01-01T12:00:00.000Z
+             */
+            expiresAt: string;
+            /** @description Customer object from session data */
+            customer: components["schemas"]["CustomerResponse"];
+            /**
+             * Session creation date
+             * @example 2025-01-01T11:45:00.000Z
+             */
+            createdAt: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Session last update date
+             * @example 2025-01-01T11:45:00.000Z
              */
-            agentRef: string;
+            updatedAt: string;
+        };
+        UserInfoRequest: {
             /**
-             * @description Plan reference identifier (optional)
-             * @example pln_2b3c4d5e6f7g
+             * Customer reference
+             * @example cus_3C4D5E6F
              */
-            planRef?: string;
+            customerRef: string;
             /**
-             * @description URL to redirect to after successful payment (optional)
-             * @example https://example.com/payment-success
+             * Product reference
+             * @example prd_1A2B3C4D
              */
-            returnUrl?: string;
+            productRef: string;
         };
-        CheckoutSessionResponse: {
+        UserInfoUserDto: {
+            /** @example cus_3C4D5E6F */
+            reference: string;
+            /** @example John Doe */
+            name?: string | null;
+            /** @example john@example.com */
+            email: string;
+            /** @example auth_user_12345 */
+            externalRef?: string | null;
+        };
+        UserInfoUsageDto: {
+            /** @example 1000 */
+            total: number;
+            /** @example 250 */
+            used: number;
+            /** @example 750 */
+            remaining: number;
             /**
-             * @description Checkout session ID
+             * Meter ObjectId reference
              * @example 507f1f77bcf86cd799439011
              */
-            id: string;
-            /**
-             * @description Public session ID used in checkout URL
-             * @example a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
-             */
-            sessionId: string;
+            meterId?: string;
+            /** @example 25 */
+            percentUsed?: number | null;
+        };
+        UserInfoPlanDto: {
+            /** @example pln_2B3C4D5E */
+            reference: string;
             /**
-             * @description Amount in cents
+             * Price in minor currency units (e.g. cents)
              * @example 2999
              */
-            amount: number;
-            /**
-             * @description Currency code
-             * @example USD
-             */
+            price: number;
+            /** @example USD */
             currency: string;
+            /** @example recurring */
+            type: string;
+            /** @example monthly */
+            billingCycle?: string | null;
+            features?: string[] | null;
+            limits?: {
+                [key: string]: unknown;
+            } | null;
+        };
+        UserInfoPurchaseDto: {
+            /** @example pur_1A2B3C4D */
+            reference: string;
+            /** @example active */
+            status: string;
+            /** @example My API Product */
+            productName: string;
+            /** @example recurring */
+            planType: string;
+            /** @example 2025-10-27T10:00:00Z */
+            startDate?: string | null;
+            /** @example 2025-11-27T10:00:00Z */
+            endDate?: string | null;
+            usage?: components["schemas"]["UserInfoUsageDto"];
+            plan?: components["schemas"]["UserInfoPlanDto"];
+        };
+        UserInfoResponse: {
             /**
-             * @description Session status
-             * @example active
+             * Human-readable status summary
+             * @example Active subscription: My API Product (25% usage consumed)
              */
             status: string;
             /**
-             * @description Checkout URL to open the checkout page
-             * @example https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             * Customer portal session URL
+             * @example https://solvapay.com/customer/manage?id=abc123
              */
-            checkoutUrl: string;
+            verifyUrl?: string | null;
+            user?: components["schemas"]["UserInfoUserDto"];
+            purchase?: components["schemas"]["UserInfoPurchaseDto"];
         };
-        CancelSubscriptionRequest: {
+        McpToolDto: {
             /**
-             * @description Reason for cancellation
-             * @example Customer request
+             * Tool name
+             * @example search_documents
              */
-            reason?: string;
-        };
-        CheckLimitRequest: {
+            name: string;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Plan IDs that grant access to this tool
+             * @example [
+             *       "pln_abc123"
+             *     ]
              */
-            customerRef: string;
+            planIds?: string[];
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * If true, the tool is unprotected (no purchase check or usage tracking)
+             * @example false
              */
-            agentRef: string;
-        };
-        LimitResponse: {
+            noPlan?: boolean;
             /**
-             * @description Whether the customer is within their usage limits
-             * @example true
+             * Human-readable tool description
+             * @example Search indexed documents
              */
-            withinLimits: boolean;
+            description?: string;
             /**
-             * @description Remaining usage units before hitting the limit
-             * @example 997
+             * Whether this is a virtual platform tool handled by SolvaPay
+             * @example false
              */
-            remaining: number;
+            isVirtual?: boolean;
+        };
+        McpServerDto: {
             /**
-             * @description Optional checkout session ID/token if payment is required
-             * @example e3f1c2d4b6a89f001122334455667788
+             * Server ID
+             * @example 507f1f77bcf86cd799439011
              */
-            checkoutSessionId?: string;
+            id?: string;
             /**
-             * @description Optional full checkout URL if payment is required (based on backend configuration)
-             * @example https://app.solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
+             * Unique server reference
+             * @example mcp_abc123
              */
-            checkoutUrl?: string;
-        };
-        UsageEvent: {
+            reference?: string;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Domain slug used to derive the MCP endpoint subdomain
+             * @example my-mcp-server
              */
-            customerRef: string;
+            name: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * URL-safe subdomain derived from name
+             * @example my-mcp-server
              */
-            agentRef: string;
+            subdomain: string;
             /**
-             * @description Outcome of the action
-             * @example success
-             * @enum {string}
+             * SolvaPay proxy URL that MCP clients connect to
+             * @example https://mytelescope.mcp.solvapay.com/mcp
              */
-            outcome: "success" | "paywall" | "fail";
+            mcpProxyUrl?: string;
             /**
-             * @description Optional action identifier
-             * @example generate_text
+             * Origin URL of the actual MCP server
+             * @example https://origin.example.com/mcp
              */
-            action?: string;
+            url: string;
             /**
-             * @description Unique request identifier matching the limits check
-             * @example req_1a2b3c4d5e6f
+             * Avatar image URL
+             * @example https://example.com/avatar.png
              */
-            requestId: string;
+            avatarUrl?: string;
+            /** @description Registered tools for this server */
+            tools?: components["schemas"]["McpToolDto"][];
             /**
-             * @description Duration of the action in milliseconds
-             * @example 1250
+             * Default plan ID for tool access gating. Must belong to the linked product and be a free-tier plan (isFreeTier=true or price=0).
+             * @example pln_default
              */
-            actionDuration: number;
+            defaultPlanId?: string;
             /**
-             * @description ISO 8601 timestamp of when the action occurred
-             * @example 2025-10-21T10:30:00.000Z
+             * Associated product ID
+             * @example 507f1f77bcf86cd799439011
              */
-            timestamp: string;
-        };
-        CreateCustomerRequest: {
+            productId?: string;
             /**
-             * @description Customer email address (required)
-             * @example customer@example.com
+             * Server status
+             * @example active
+             * @enum {string}
              */
-            email: string;
+            status?: "active" | "inactive" | "suspended";
             /**
-             * @description Customer full name (optional)
-             * @example John Doe
+             * Provider ID that owns this server
+             * @example 507f1f77bcf86cd799439011
              */
-            name?: string;
+            providerId: string;
             /**
-             * @description External reference ID from your auth system to map this customer to an auth user (optional)
-             * @example auth_user_12345
+             * Custom auth header name for origin requests
+             * @example X-API-Key
              */
-            externalRef?: string;
-        };
-        SubscriptionInfo: {
+            authHeaderName?: string;
             /**
-             * @description Subscription reference
-             * @example sub_abc123
+             * Whether an auth API key is configured
+             * @example true
              */
-            reference: string;
+            hasAuthApiKey?: boolean;
             /**
-             * @description Plan name
-             * @example Pro Plan
+             * Total number of tool-call transactions
+             * @example 42
              */
-            planName: string;
+            totalTransactions?: number;
             /**
-             * @description Agent name
-             * @example AI Assistant
+             * Current balance in cents
+             * @example 1500
              */
-            agentName: string;
+            balance?: number;
+        };
+        PlanSnapshotDto: {
             /**
-             * @description Subscription status
-             * @example active
+             * Plan reference
+             * @example pln_1A2B3C4D
              */
-            status: string;
+            reference?: string;
             /**
-             * @description Start date
-             * @example 2025-10-27T10:00:00Z
+             * Plan price in cents
+             * @example 2999
              */
-            startDate: string;
-        };
-        CustomerResponse: {
+            price: number;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Currency code
+             * @example USD
              */
-            reference: string;
+            currency: string;
             /**
-             * @description Customer full name
-             * @example John Doe
+             * Plan type
+             * @example recurring
              */
-            name: string;
+            planType: string;
             /**
-             * @description Customer email address
-             * @example customer@example.com
+             * Billing cycle
+             * @example monthly
              */
-            email: string;
+            billingCycle?: string | null;
+            /** @description Plan features */
+            features?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description Usage limits */
+            limits?: {
+                [key: string]: unknown;
+            } | null;
             /**
-             * @description External reference ID from your auth system (if set during creation or update)
-             * @example auth_user_12345
+             * Meter ObjectId reference
+             * @example 507f1f77bcf86cd799439011
              */
-            externalRef?: string;
-            /** @description Active subscriptions */
-            subscriptions?: components["schemas"]["SubscriptionInfo"][];
-        };
-        CreateCustomerSessionRequest: {
+            meterId?: string;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Usage limit for the meter
+             * @example 5000
              */
-            customerRef: string;
-        };
-        CreateCustomerSessionResponse: {
+            limit?: number;
             /**
-             * @description Customer session ID/token
-             * @example e3f1c2d4b6a89f001122334455667788
+             * Number of free units included
+             * @example 100
              */
-            sessionId: string;
+            freeUnits?: number;
             /**
-             * @description Full customer URL based on backend configuration (ready to redirect customer)
-             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
+             * Price per usage unit in cents
+             * @example 10
              */
-            customerUrl: string;
+            pricePerUnit?: number;
         };
-        GetCustomerSessionResponse: {
+        UsageBillingDto: {
             /**
-             * @description Customer session ID/token
-             * @example e3f1c2d4b6a89f001122334455667788
+             * Units consumed in current period
+             * @example 150
              */
-            sessionId: string;
+            used: number;
             /**
-             * @description Session status
-             * @example active
-             * @enum {string}
+             * Units exceeding the plan limit
+             * @example 0
              */
-            status: "active" | "expired" | "used";
+            overageUnits: number;
             /**
-             * @description Full customer URL based on backend configuration (ready to redirect customer)
-             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
+             * Overage cost in cents
+             * @example 0
              */
-            customerUrl: string;
+            overageCost: number;
             /**
-             * @description Session expiration date
-             * @example 2025-01-01T12:00:00.000Z
+             * Period start date
+             * @example 2025-10-01T00:00:00Z
              */
-            expiresAt: string;
-            /** @description Customer object from session data */
-            customer: components["schemas"]["CustomerResponse"];
+            periodStart?: string;
             /**
-             * @description Session creation date
-             * @example 2025-01-01T11:45:00.000Z
+             * Period end date
+             * @example 2025-11-01T00:00:00Z
              */
-            createdAt: string;
+            periodEnd?: string;
+        };
+        PurchaseResponse: {
             /**
-             * @description Session last update date
-             * @example 2025-01-01T11:45:00.000Z
+             * Purchase ID
+             * @example 507f1f77bcf86cd799439011
              */
-            updatedAt: string;
-        };
-        Agent: Record<string, never>;
-        CreateAgentRequest: Record<string, never>;
-        UpdateAgentRequest: Record<string, never>;
-        BasePlan: Record<string, never>;
-        SubscriptionResponse: {
+            id: string;
             /**
-             * @description Subscription reference identifier
-             * @example sub_1a2b3c4d5e6f
+             * Purchase reference
+             * @example pur_1A2B3C4D
              */
             reference: string;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Customer reference
+             * @example cus_3C4D5E6F
              */
             customerRef: string;
             /**
-             * @description Customer email
+             * Customer email
              * @example customer@example.com
              */
             customerEmail: string;
             /**
-             * @description Customer name
-             * @example John Doe
+             * Product reference
+             * @example prd_1A2B3C4D
              */
-            customerName?: string;
+            productRef: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Product ID
+             * @example 507f1f77bcf86cd799439012
              */
-            agentRef: string;
+            productId?: string;
             /**
-             * @description Agent name
-             * @example My AI Agent
+             * Product name
+             * @example API Gateway Manager
              */
-            agentName: string;
+            productName?: string;
+            /** @description Plan snapshot at time of purchase */
+            planSnapshot: components["schemas"]["PlanSnapshotDto"];
             /**
-             * @description Plan reference identifier
-             * @example pln_1a2b3c4d5e6f
+             * Purchase status
+             * @example active
              */
-            planRef: string;
+            status: string;
             /**
-             * @description Plan name
-             * @example Premium Plan
+             * Amount in cents
+             * @example 9900
              */
-            planName: string;
+            amount: number;
             /**
-             * @description Plan type
-             * @example recurring
-             * @enum {string}
+             * Currency code
+             * @example USD
              */
-            planType: "recurring" | "usage-based" | "one-time" | "hybrid";
+            currency: string;
+            /** @description Start date */
+            startDate: string;
+            /** @description End date */
+            endDate?: string;
+            /** @description Paid at timestamp */
+            paidAt?: string;
+            /** @description Usage billing state for usage-based plans */
+            usage?: components["schemas"]["UsageBillingDto"];
             /**
-             * @description Subscription status
-             * @example active
+             * Is recurring
+             * @example true
+             */
+            isRecurring: boolean;
+            /**
+             * Billing cycle
              * @enum {string}
              */
-            status: "pending" | "active" | "expired" | "cancelled" | "suspended" | "refunded";
+            billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly";
+            /** @description Next billing date */
+            nextBillingDate?: string;
+            /** @description Auto-renew enabled */
+            autoRenew?: boolean;
+            /** @description Whether this is a free tier purchase */
+            isFreeTier?: boolean;
+            /** @description Cancelled at */
+            cancelledAt?: string;
+            /** @description Cancellation reason */
+            cancellationReason?: string;
+            /** @description Created at */
+            createdAt: string;
+        };
+        CancelPurchaseRequest: {
+            /** @description Reason for cancellation */
+            reason?: string;
+        };
+        CheckLimitRequest: {
             /**
-             * @description Amount paid in original currency (in cents)
-             * @example 9900
+             * Customer reference identifier
+             * @example cus_3C4D5E6F
              */
-            amount: number;
+            customerRef: string;
             /**
-             * @description Currency code
-             * @example USD
+             * Product reference identifier
+             * @example prd_1A2B3C4D
              */
-            currency: string;
+            productRef: string;
             /**
-             * @description Start date of subscription
-             * @example 2025-01-01T00:00:00.000Z
+             * Plan reference to pre-select when creating a checkout session. If provided and the customer needs to purchase, the checkout page skips plan selection and shows the payment form directly.
+             * @example pln_2B3C4D5E
              */
-            startDate: string;
+            planRef?: string;
             /**
-             * @description End date of subscription (if applicable)
-             * @example 2025-02-01T00:00:00.000Z
+             * Canonical usage meter name used for limit checks (for example: requests, tokens).
+             * @example requests
              */
-            endDate?: string;
+            meterName?: string;
             /**
-             * @description When payment was confirmed
-             * @example 2025-01-01T00:00:00.000Z
+             * Usage type alias for meterName. If both are provided, meterName takes precedence.
+             * @example requests
              */
-            paidAt?: string;
-            /** @description Usage quota information (for usage-based plans) */
-            usageQuota?: Record<string, never>;
+            usageType?: string;
+        };
+        LimitResponse: {
             /**
-             * @description Whether this is a recurring subscription
+             * Whether the customer is within their usage limits
              * @example true
              */
-            isRecurring: boolean;
+            withinLimits: boolean;
             /**
-             * @description Next billing date (for recurring subscriptions)
-             * @example 2025-02-01T00:00:00.000Z
+             * Remaining usage units before hitting the limit
+             * @example 997
              */
-            nextBillingDate?: string;
+            remaining: number;
             /**
-             * @description When subscription was cancelled (if applicable)
-             * @example 2025-01-15T00:00:00.000Z
+             * Checkout session ID if payment is required
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            cancelledAt?: string;
+            checkoutSessionId?: string;
             /**
-             * @description Reason for cancellation (if applicable)
-             * @example Customer request
+             * Checkout URL if payment is required
+             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
              */
-            cancellationReason?: string;
+            checkoutUrl?: string;
             /**
-             * @description When subscription was created
-             * @example 2025-01-01T00:00:00.000Z
+             * The meter name to use when tracking usage events
+             * @example requests
              */
-            createdAt: string;
+            meterName?: string;
         };
-        CreateCheckoutSessionResponse: {
+        ExecuteAnalyticsQuery: Record<string, never>;
+        ExecuteMultipleQueries: Record<string, never>;
+        CreateWebhookEndpointDto: {
             /**
-             * @description Checkout session ID/token
-             * @example e3f1c2d4b6a89f001122334455667788
+             * Webhook endpoint URL
+             * @example https://example.com/webhook
              */
-            sessionId: string;
+            url: string;
             /**
-             * @description Full checkout URL based on backend configuration (ready to redirect customer)
-             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
+             * Webhook endpoint description
+             * @example Production webhook
              */
-            checkoutUrl: string;
+            description?: string;
         };
-        CreatePageSettings: {
-            /** @description Page identifier */
-            id: string;
-            /** @description Page display name */
-            name: string;
-            /** @description Logo URL */
-            logo?: string;
+        UpdateWebhookEndpointDto: {
             /**
-             * @description Text color in hex format
-             * @example #2d3748
+             * Webhook endpoint URL
+             * @example https://example.com/webhook
              */
-            textColor: string;
+            url?: string;
             /**
-             * @description Button color in hex format
-             * @example #3182ce
+             * Webhook endpoint description
+             * @example Updated webhook
+             */
+            description?: string;
+        };
+        UpdateThemePreferenceDto: {
+            /**
+             * Selected UI theme mode
+             * @example dark
+             * @enum {string}
              */
-            buttonColor: string;
+            mode: "light" | "dark";
+        };
+        ThemeModeColorsDto: {
             /**
-             * @description Left background color in hex format
-             * @example #f7fafc
+             * Page background color
+             * @example #f7f7f8
              */
-            leftBackgroundColor: string;
+            background?: string;
             /**
-             * @description Right background color in hex format
+             * Card/surface background color
              * @example #ffffff
              */
-            rightBackgroundColor: string;
+            surface?: string;
+            /**
+             * Primary text color
+             * @example #181818
+             */
+            text?: string;
+            /**
+             * Secondary/muted text color
+             * @example #5c5c5c
+             */
+            secondary?: string;
+        };
+        ThemeOverridesDto: {
+            /** @description Light mode color overrides */
+            light?: components["schemas"]["ThemeModeColorsDto"];
+            /** @description Dark mode color overrides */
+            dark?: components["schemas"]["ThemeModeColorsDto"];
+        };
+        UpdateBrandThemeDto: {
+            /**
+             * Logo image URL displayed in hosted page headers
+             * @example /ui/files/download/provider-assets/provider-123/logos/logo.png
+             */
+            logo?: string;
+            /**
+             * Provider's brand name displayed on hosted pages
+             * @example Acme Corp
+             */
+            brandName: string;
+            /**
+             * Primary/accent color in hex format
+             * @example #3182ce
+             */
+            primaryColor: string;
             /**
-             * @description Font family
+             * Font family for hosted pages
+             * @default Inter
              * @example Inter
              */
             fontFamily: string;
             /**
-             * @description Font size
+             * Base font size
+             * @default 16px
              * @example 16px
              */
             fontSize: string;
+            /** @description Per-mode color overrides for light and dark themes */
+            themes?: components["schemas"]["ThemeOverridesDto"];
+        };
+        CreatePreregistrationDto: {
+            /** @example jane@company.com */
+            email: string;
+            /** @example Jane Smith */
+            fullName: string;
+            /** @example Acme Corp */
+            companyName: string;
+            /** @example SaaS */
+            businessType?: string;
+            /** @example Purchase billing for our platform */
+            useCase?: string;
+            customFields?: {
+                [key: string]: string;
+            };
+        };
+        /** @description Auto-generated fallback schema for unresolved reference: McpBootstrapPreviewValidationError */
+        McpBootstrapPreviewValidationError: {
+            [key: string]: unknown;
         };
     };
     responses: never;
@@ -451,14 +1830,23 @@ interface components {
  * Types related to the SolvaPay API client and backend communication.
  */
 
+type UsageMeterType = 'requests' | 'tokens';
+type CheckLimitsRequest = components['schemas']['CheckLimitRequest'] & {
+    meterName?: string;
+    usageType?: UsageMeterType;
+};
 /**
  * Extended LimitResponse with plan field
  */
 type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
     plan: string;
+    meterName?: string;
 };
 /**
  * Extended CustomerResponse with proper field mapping
+ *
+ * Note: The backend API returns purchases as PurchaseInfo objects.
+ * Additional fields (paidAt, nextBillingDate) may be present in the response.
  */
 type CustomerResponseMapped = {
     customerRef: string;
@@ -466,12 +1854,15 @@ type CustomerResponseMapped = {
     name?: string;
     externalRef?: string;
     plan?: string;
-    subscriptions?: components['schemas']['SubscriptionInfo'][];
+    purchases?: Array<components['schemas']['PurchaseInfo'] & {
+        paidAt?: string;
+        nextBillingDate?: string;
+    }>;
 };
 /**
- * Purchase information returned from payment processing
+ * One-time purchase information returned from payment processing
  */
-interface PurchaseInfo {
+interface OneTimePurchaseInfo {
     reference: string;
     productRef?: string;
     amount: number;
@@ -483,11 +1874,72 @@ interface PurchaseInfo {
  * Result from processing a payment intent
  */
 interface ProcessPaymentResult {
-    type: 'subscription' | 'purchase';
-    subscription?: components['schemas']['SubscriptionInfo'];
-    purchase?: PurchaseInfo;
+    type: 'recurring' | 'one-time';
+    purchase?: components['schemas']['PurchaseInfo'];
+    oneTimePurchase?: OneTimePurchaseInfo;
     status: 'completed';
 }
+interface McpBootstrapFreePlanConfig {
+    name?: string;
+    freeUnits?: number;
+}
+interface McpBootstrapPaidPlanInput {
+    key: string;
+    name: string;
+    /** Price in cents (e.g. 2000 = $20.00) */
+    price: number;
+    currency: string;
+    billingCycle?: 'weekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
+    type?: 'recurring' | 'one-time';
+    freeUnits?: number;
+    meterId?: string;
+    limit?: number;
+    features?: Record<string, unknown>;
+}
+interface ToolPlanMappingInput {
+    name: string;
+    description?: string;
+    noPlan?: boolean;
+    planIds?: string[];
+    planRefs?: string[];
+    planKeys?: string[];
+}
+interface McpBootstrapRequest {
+    name?: string;
+    description?: string;
+    imageUrl?: string;
+    productType?: string;
+    originUrl: string;
+    /** Optional token combined with provider name to derive the final MCP subdomain. */
+    mcpDomain?: string;
+    authHeaderName?: string;
+    authApiKey?: string;
+    freePlan?: McpBootstrapFreePlanConfig;
+    paidPlans?: McpBootstrapPaidPlanInput[];
+    tools?: ToolPlanMappingInput[];
+    metadata?: Record<string, unknown>;
+}
+interface McpBootstrapResponse {
+    product: components['schemas']['SdkProductResponse'];
+    mcpServer: {
+        id?: string;
+        reference?: string;
+        subdomain?: string;
+        mcpProxyUrl?: string;
+        url: string;
+        defaultPlanId?: string;
+    };
+    planMap: Record<string, {
+        id: string;
+        reference: string;
+        name?: string;
+    }>;
+    toolsAutoMapped?: boolean;
+    autoMappedTools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
 /**
  * SolvaPay API Client Interface
  *
@@ -496,50 +1948,73 @@ interface ProcessPaymentResult {
  * 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;
+    checkLimits(params: CheckLimitsRequest): Promise<LimitResponseWithPlan>;
+    trackUsage(params: {
+        customerRef: string;
+        actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
+        units?: number;
+        outcome?: 'success' | 'paywall' | 'fail';
+        productReference?: string;
+        purchaseReference?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+        duration?: number;
+        timestamp?: string;
+        idempotencyKey?: string;
     }): Promise<void>;
     createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
         customerRef: string;
     }>;
-    getCustomer?(params: {
-        customerRef: string;
-    }): Promise<CustomerResponseMapped>;
-    getCustomerByExternalRef?(params: {
-        externalRef: string;
+    getCustomer(params: {
+        customerRef?: string;
+        externalRef?: string;
+        email?: string;
     }): Promise<CustomerResponseMapped>;
-    listAgents?(): Promise<Array<{
+    listProducts?(): Promise<Array<{
         reference: string;
         name: string;
         description?: string;
+        status?: string;
     }>>;
-    createAgent?(params: components['schemas']['CreateAgentRequest']): Promise<{
+    createProduct?(params: components['schemas']['CreateProductRequest']): Promise<{
         reference: string;
         name: string;
     }>;
-    deleteAgent?(agentRef: string): Promise<void>;
-    listPlans?(agentRef: string): Promise<Array<{
+    bootstrapMcpProduct?(params: McpBootstrapRequest): Promise<McpBootstrapResponse>;
+    updateProduct?(productRef: string, params: components['schemas']['UpdateProductRequest']): Promise<components['schemas']['SdkProductResponse']>;
+    deleteProduct?(productRef: string): Promise<void>;
+    cloneProduct?(productRef: string, overrides?: {
+        name?: string;
+    }): Promise<{
         reference: string;
         name: string;
-        description?: string;
+    }>;
+    listPlans?(productRef: string): Promise<Array<{
+        reference: string;
         price?: number;
         currency?: string;
         interval?: string;
         isFreeTier?: boolean;
         freeUnits?: number;
-        metadata?: Record<string, any>;
-        [key: string]: any;
+        measures?: string;
+        limit?: number;
+        pricePerUnit?: number;
+        billingModel?: string;
+        metadata?: Record<string, unknown>;
+        [key: string]: unknown;
     }>>;
     createPlan?(params: components['schemas']['CreatePlanRequest'] & {
-        agentRef: string;
+        productRef: string;
     }): Promise<{
         reference: string;
-        name: string;
     }>;
-    deletePlan?(agentRef: string, planRef: string): Promise<void>;
+    updatePlan?(productRef: string, planRef: string, params: Partial<components['schemas']['CreatePlanRequest']>): Promise<{
+        reference: string;
+        [key: string]: unknown;
+    }>;
+    deletePlan?(productRef: string, planRef: string): Promise<void>;
     createPaymentIntent?(params: {
-        agentRef: string;
+        productRef: string;
         planRef: string;
         customerRef: string;
         idempotencyKey?: string;
@@ -549,17 +2024,21 @@ interface SolvaPayClient {
         publishableKey: string;
         accountId?: string;
     }>;
-    cancelSubscription?(params: {
-        subscriptionRef: string;
+    cancelPurchase?(params: {
+        purchaseRef: string;
         reason?: string;
-    }): Promise<components['schemas']['SubscriptionResponse']>;
-    processPayment?(params: {
+    }): Promise<components['schemas']['PurchaseInfo']>;
+    processPaymentIntent?(params: {
         paymentIntentId: string;
-        agentRef: string;
+        productRef: string;
         customerRef: string;
         planRef?: string;
     }): Promise<ProcessPaymentResult>;
-    createCheckoutSession(params: components['schemas']['CreateCheckoutSessionRequest']): Promise<components['schemas']['CreateCheckoutSessionResponse']>;
+    getUserInfo?(params: {
+        customerRef: string;
+        productRef: string;
+    }): Promise<components['schemas']['UserInfoResponse']>;
+    createCheckoutSession(params: components['schemas']['CreateCheckoutSessionRequest']): Promise<components['schemas']['CheckoutSessionResponse']>;
     createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
 }
 
@@ -572,7 +2051,7 @@ interface SolvaPayClient {
  * Arguments passed to protected handlers
  */
 interface PaywallArgs {
-    [key: string]: any;
+    [key: string]: unknown;
     auth?: {
         customer_ref?: string;
     };
@@ -581,15 +2060,16 @@ interface PaywallArgs {
  * Metadata for configuring paywall protection
  */
 interface PaywallMetadata {
-    agent?: string;
+    product?: string;
     plan?: string;
+    usageType?: 'requests' | 'tokens';
 }
 /**
  * Structured content for paywall errors
  */
 interface PaywallStructuredContent {
     kind: 'payment_required';
-    agent: string;
+    product: string;
     checkoutUrl: string;
     message: string;
 }
@@ -651,21 +2131,25 @@ interface RetryOptions {
  */
 interface PayableOptions {
     /**
-     * Agent identifier (auto-detected from package.json if not provided)
+     * Product identifier
      */
-    agent?: string;
+    product?: string;
     /**
-     * Agent reference (alias for agent, preferred for consistency with backend API)
+     * Product reference (alias for product, preferred for consistency with backend API)
      */
-    agentRef?: string;
+    productRef?: string;
     /**
-     * Plan identifier (defaults to agent name if not provided)
+     * Plan identifier (defaults to product name if not provided)
      */
     plan?: string;
     /**
      * Plan reference (alias for plan, preferred for consistency with backend API)
      */
     planRef?: string;
+    /**
+     * Usage meter type to charge against (defaults to 'requests')
+     */
+    usageType?: 'requests' | 'tokens';
     /**
      * Optional function to extract customer reference from context
      */
@@ -720,70 +2204,294 @@ interface McpAdapterOptions {
 }
 
 /**
- * Configuration for creating a SolvaPay instance
+ * Virtual Tools for MCP Server Monetization
+ *
+ * Provides the same self-service tools (get_user_info, upgrade, manage_account)
+ * that hosted MCP Pay servers get automatically, but for SDK-integrated servers.
+ * These tools are NOT usage-tracked and bypass the paywall.
+ */
+
+interface VirtualToolsOptions {
+    /** Product reference (required) */
+    product: string;
+    /** Extract customer reference from MCP tool args */
+    getCustomerRef: (args: Record<string, unknown>) => string;
+    /** Tool names to exclude from registration (optional) */
+    exclude?: string[];
+}
+interface VirtualToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, object>;
+        required: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+declare const VIRTUAL_TOOL_DEFINITIONS: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, object>;
+        required: string[];
+    };
+}[];
+declare function createVirtualTools(apiClient: SolvaPayClient, options: VirtualToolsOptions): VirtualToolDefinition[];
+
+/**
+ * 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;
+    /**
+     * TTL in ms for the checkLimits cache (default 10 000).
+     * Positive results are cached and optimistically decremented to avoid
+     * redundant API calls during tool-call bursts.
+     */
+    limitsCacheTTL?: number;
 }
 /**
- * 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({ product: 'prd_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>;
+    http<T = any>(businessLogic: (args: any) => Promise<T>, options?: HttpAdapterOptions): (req: any, reply: any) => Promise<unknown>;
     /**
-     * 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>;
+    mcp<T = any>(businessLogic: (args: any) => Promise<T>, options?: McpAdapterOptions): (args: Record<string, unknown>) => Promise<unknown>;
     /**
-     * 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({ product: 'prd_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({
+   *   productRef: 'prd_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 product and plan references
+     * @returns PayableFunction with framework-specific adapters
+     *
+     * @example
+     * ```typescript
+     * const payable = solvaPay.payable({
+     *   product: 'prd_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).
+     *   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 for customer creation
+     * @param options.email - Customer email address
+     * @param options.name - Customer name
+     * @returns Customer reference (backend customer ID)
      *
-     * @param customerRef - The customer reference (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
-     * @param options - Optional customer details (email, name) for customer creation
+     * @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 purchase a plan.
+     *
+     * This creates a payment intent that can be confirmed on the client side
+     * using Stripe.js. After confirmation, call `processPaymentIntent()` to complete
+     * the purchase.
+     *
+     * @param params - Payment intent parameters
+     * @param params.productRef - Product reference
+     * @param params.planRef - Plan reference to purchase
+     * @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({
+     *   productRef: 'prd_myapi',
+     *   planRef: 'pln_premium',
+     *   customerRef: 'user_123',
+     *   idempotencyKey: 'unique-key-123'
+     * });
+     *
+     * // Use intent.clientSecret with Stripe.js on client
+     * ```
      */
     createPaymentIntent(params: {
-        agentRef: string;
+        productRef: string;
         planRef: string;
         customerRef: string;
         idempotencyKey?: string;
@@ -794,42 +2502,135 @@ 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 the 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.productRef - Product reference
+     * @param params.customerRef - Customer reference
+     * @param params.planRef - Optional plan reference (if not in payment intent)
+     * @returns Payment processing result with purchase details
+     *
+     * @example
+     * ```typescript
+     * // After client confirms payment with Stripe.js
+     * const result = await solvaPay.processPaymentIntent({
+     *   paymentIntentId: 'pi_1234567890',
+     *   productRef: 'prd_myapi',
+     *   customerRef: 'user_123',
+     *   planRef: 'pln_premium'
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Purchase created:', result.purchase);
+     * }
+     * ```
      */
-    processPayment(params: {
+    processPaymentIntent(params: {
         paymentIntentId: string;
-        agentRef: string;
+        productRef: string;
         customerRef: string;
         planRef?: string;
     }): Promise<ProcessPaymentResult>;
     /**
-     * Check if customer is within usage limits
+     * Check if customer is within usage limits for a product.
+     *
+     * This method checks purchase 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.productRef - Product reference
+     * @returns Limit check result with remaining usage and checkout URL if needed
+     *
+     * @example
+     * ```typescript
+     * const limits = await solvaPay.checkLimits({
+     *   customerRef: 'user_123',
+     *   productRef: 'prd_myapi',
+     *   planRef: 'pln_premium'
+     * });
+     *
+     * if (!limits.withinLimits) {
+     *   // Redirect to checkout
+     *   window.location.href = limits.checkoutUrl;
+     * }
+     * ```
      */
     checkLimits(params: {
         customerRef: string;
-        agentRef: string;
+        productRef: string;
+        planRef?: string;
+        meterName?: 'requests' | 'tokens';
+        usageType?: 'requests' | 'tokens';
     }): Promise<{
         withinLimits: boolean;
         remaining: number;
         plan: string;
         checkoutUrl?: string;
+        meterName?: 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.productRef - Product 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: 'cus_3C4D5E6F',
+     *   actionType: 'api_call',
+     *   units: 1,
+     *   outcome: 'success',
+     *   metadata: { toolName: 'search', endpoint: '/search' },
+     * });
+     * ```
      */
     trackUsage(params: {
         customerRef: string;
-        agentRef: string;
-        planRef: string;
-        outcome: 'success' | 'paywall' | 'fail';
-        action?: string;
-        requestId: string;
-        actionDuration: number;
-        timestamp: string;
+        actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
+        units?: number;
+        outcome?: 'success' | 'paywall' | 'fail';
+        productReference?: string;
+        purchaseReference?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+        duration?: number;
+        timestamp?: string;
+        idempotencyKey?: 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;
@@ -838,58 +2639,162 @@ interface SolvaPay {
         customerRef: string;
     }>;
     /**
-     * Get customer details
+     * Get customer details including purchases and usage.
+     *
+     * Returns full customer information from the SolvaPay backend, including
+     * all active purchases, 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 purchases 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;
-    }): Promise<{
-        customerRef: string;
-        email?: string;
-        name?: string;
-        plan?: string;
-        subscriptions?: Array<{
-            reference: string;
-            planName: string;
-            agentName: string;
-            status: string;
-            startDate: 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.productRef - Product 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({
+     *   productRef: 'prd_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;
+        productRef: 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 purchases.
+     *
+     * This creates a Stripe Customer Portal session that allows customers
+     * to manage their purchases, update payment methods, and view invoices.
+     *
+     * @param params - Customer session parameters
+     * @param params.customerRef - Customer reference
+     * @param params.productRef - Optional product reference for scoping portal view
+     * @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;
+        productRef?: string;
     }): Promise<{
         sessionId: string;
         customerUrl: string;
     }>;
     /**
-     * Direct access to the API client for advanced operations
-     * (agent/plan management, etc.)
+     * Bootstrap an MCP-enabled product with plans and tool mappings.
+     *
+     * This helper wraps the backend orchestration endpoint and is intended for
+     * fast setup flows where you want one call for product + plans + MCP config.
+     */
+    bootstrapMcpProduct(params: McpBootstrapRequest): Promise<McpBootstrapResponse>;
+    /**
+     * Get virtual tool definitions with bound handlers for MCP server integration.
+     *
+     * Returns an array of tool objects (name, description, inputSchema, handler)
+     * that provide self-service capabilities: user info, upgrade, and account management.
+     * These tools bypass the paywall and are not usage-tracked.
+     *
+     * Register the returned tools on your MCP server alongside your own tools.
+     *
+     * @param options - Virtual tools configuration
+     * @param options.product - Product reference (required)
+     * @param options.getCustomerRef - Function to extract customer ref from tool args
+     * @param options.exclude - Optional list of tool names to exclude
+     * @returns Array of virtual tool definitions with handlers
+     *
+     * @example
+     * ```typescript
+     * const virtualTools = solvaPay.getVirtualTools({
+     *   product: 'prd_myapi',
+     *   getCustomerRef: args => args._auth?.customer_ref || 'anonymous',
+     * });
+     *
+     * // Register on your MCP server
+     * for (const tool of virtualTools) {
+     *   // Add to tools/list and tools/call handlers
+     * }
+     * ```
+     */
+    getVirtualTools(options: VirtualToolsOptions): VirtualToolDefinition[];
+    /**
+     * Direct access to the API client for advanced operations.
+     *
+     * Use this for operations not exposed by the SolvaPay interface,
+     * such as product/plan management or custom API calls.
+     *
+     * @example
+     * ```typescript
+     * // Access API client directly for custom operations
+     * const products = await solvaPay.apiClient.listProducts();
+     * ```
      */
     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
+   * purchase 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
@@ -897,16 +2802,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 product
+ * const payable = solvaPay.payable({
+ *   product: 'prd_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;
 
@@ -928,25 +2843,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 products = await client.listProducts();
  * ```
+ *
+ * @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;
 
@@ -959,8 +2892,48 @@ declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient
  * - Class-based and functional programming
  */
 
+/**
+ * Error thrown when a paywall is triggered (purchase required or usage limit exceeded).
+ *
+ * This error is automatically thrown by the paywall protection system when:
+ * - Customer doesn't have required purchase
+ * - 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);
 }
 
@@ -969,19 +2942,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(),
  *   {
@@ -993,9 +2975,343 @@ declare class PaywallError extends Error {
  *   }
  * );
  * ```
+ *
+ * @since 1.0.0
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+/**
+ * MCP OAuth helper utilities.
+ *
+ * These helpers are intentionally lightweight and do not verify JWT signatures.
+ * Use them after token validation (for example via /v1/customer/auth/userinfo).
+ */
+declare class McpBearerAuthError extends Error {
+    constructor(message: string);
+}
+type McpBearerCustomerRefOptions = {
+    claimPriority?: string[];
+};
+declare function extractBearerToken(authorization?: string | null): string | null;
+declare function decodeJwtPayload(token: string): Record<string, unknown>;
+declare function getCustomerRefFromJwtPayload(payload: Record<string, unknown>, options?: McpBearerCustomerRefOptions): string;
+declare function getCustomerRefFromBearerAuthHeader(authorization?: string | null, options?: McpBearerCustomerRefOptions): string;
+
+/**
+ * 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 a standard Web API Request.
+ *
+ * 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.).
+ *
+ * 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;
+    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 with SolvaPay backend (ensure customer exists).
+ *
+ * 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
+ *
+ * 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
+ * @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;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<string | ErrorResult>;
+
+/**
+ * Create a Stripe payment intent for a customer to purchase a plan.
+ *
+ * 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 `processPaymentIntentCore()` to complete the purchase.
+ *
+ * @param request - Standard Web API Request object
+ * @param body - Payment intent parameters
+ * @param body.planRef - Plan reference to purchase (required)
+ * @param body.productRef - Product reference (required)
+ * @param options - Configuration options
+ * @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 processPaymentIntentCore} for processing confirmed payments
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+declare function createPaymentIntentCore(request: Request, body: {
+    planRef: string;
+    productRef: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    id: string;
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef: string;
+} | ErrorResult>;
+/**
+ * Process a payment intent after client-side Stripe confirmation.
+ *
+ * This helper processes a payment intent that has been confirmed on the client
+ * side using Stripe.js. It creates the 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.productRef - Product reference (required)
+ * @param body.planRef - Optional plan reference (if not in payment intent)
+ * @param options - Configuration options
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @returns Process payment result with purchase 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 processPaymentIntentCore(request, body);
+ *
+ *   if (isErrorResult(result)) {
+ *     return Response.json(result, { status: result.status });
+ *   }
+ *
+ *   return Response.json(result);
+ * }
+ * ```
+ *
+ * @see {@link createPaymentIntentCore} for creating payment intents
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+declare function processPaymentIntentCore(request: Request, body: {
+    paymentIntentId: string;
+    productRef: 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: {
+    productRef: string;
+    planRef?: string;
+    returnUrl?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+    returnUrl?: string;
+}): 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>;
+
+/**
+ * Purchase Cancellation Helpers (Core)
+ *
+ * Generic helpers for purchase cancellation operations.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Cancel purchase - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Cancellation parameters
+ * @param options - Configuration options
+ * @returns Cancelled purchase response or error result
+ */
+declare function cancelPurchaseCore(request: Request, body: {
+    purchaseRef: string;
+    reason?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<Record<string, unknown> | 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
+ */
+declare function listPlansCore(request: Request): Promise<{
+    plans: Record<string, unknown>[];
+    productRef: string;
+} | ErrorResult>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -1003,10 +3319,52 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
  * Provides unified payable API with explicit adapters for all frameworks.
  */
 
-declare function verifyWebhook({ body, signature, secret }: {
+/**
+ * Verify webhook signature from SolvaPay backend.
+ *
+ * The backend sends an `SV-Signature` header in the format `t={timestamp},v1={hmac}`.
+ * The HMAC is SHA-256 over `"{timestamp}.{rawBody}"` keyed by the full webhook secret
+ * (including the `whsec_` prefix). Signatures older than 5 minutes are rejected to
+ * prevent replay attacks.
+ *
+ * @param params - Webhook verification parameters
+ * @param params.body - Raw request body as string (must be exactly as received)
+ * @param params.signature - Value of the `SV-Signature` header
+ * @param params.secret - Webhook signing secret from SolvaPay dashboard (`whsec_…`)
+ * @returns Parsed and typed {@link WebhookEvent} object
+ * @throws {SolvaPayError} If signature is missing, malformed, expired, or invalid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@solvapay/server';
+ *
+ * // Express.js — use express.raw() so the body is not parsed
+ * app.post('/webhooks/solvapay', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const event = verifyWebhook({
+ *       body: req.body.toString(),
+ *       signature: req.headers['sv-signature'] as string,
+ *       secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
+ *     });
+ *
+ *     if (event.type === 'purchase.created') {
+ *       // …
+ *     }
+ *
+ *     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;
-}): any;
+}): WebhookEvent;
 
-export { type CreateSolvaPayConfig, type CustomerResponseMapped, 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, createSolvaPay, createSolvaPayClient, verifyWebhook, withRetry };
+export { type AuthenticatedUser, type CreateSolvaPayConfig, type CustomerResponseMapped, type ErrorResult, type HttpAdapterOptions, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapFreePlanConfig, type McpBootstrapPaidPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventType, cancelPurchaseCore, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createVirtualTools, decodeJwtPayload, extractBearerToken, getAuthenticatedUserCore, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, handleRouteError, isErrorResult, listPlansCore, processPaymentIntentCore, syncCustomerCore, verifyWebhook, withRetry };