@solvapay/server 1.0.0-preview.2 → 1.0.0-preview.20

package/dist/edge.d.ts

@@ -1,9 +1,13 @@
 interface components {
     schemas: {
+        UpdateProviderDto: Record<string, never>;
         CreateSecretKey: Record<string, never>;
         CheckName: Record<string, never>;
         CreateAdminAgent: Record<string, never>;
         UpdateAdminAgent: Record<string, never>;
+        Agent: Record<string, never>;
+        CreateAgentRequest: Record<string, never>;
+        UpdateAgentRequest: Record<string, never>;
         Signup: Record<string, never>;
         AuthResponse: Record<string, never>;
         Login: Record<string, never>;
@@ -16,291 +20,660 @@ interface components {
         UpdatePreferences: Record<string, never>;
         ChangePassword: Record<string, never>;
         RequestEmailChange: Record<string, never>;
-        CreateConnectedAccount: Record<string, never>;
-        UpdateConnectedAccount: Record<string, never>;
-        CreatePlanRequest: Record<string, never>;
+        CreateProductRequest: {
+            /**
+             * Product name
+             * @example AI Writing Assistant
+             */
+            name: string;
+            /**
+             * Product description
+             * @example AI-powered writing tool
+             */
+            description?: string;
+            /** 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;
+            /** Product-specific configuration */
+            config?: Record<string, never>;
+            /** Arbitrary key-value metadata */
+            metadata?: Record<string, never>;
+        };
+        SdkProductResponse: {
+            /**
+             * Product ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * Product reference
+             * @example prd_1A2B3C4D
+             */
+            reference: string;
+            /**
+             * Product name
+             * @example AI Writing Assistant
+             */
+            name: string;
+            /** Product description */
+            description?: string;
+            /** URL to the product image */
+            imageUrl?: string;
+            /** 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;
+            /** Product-specific configuration */
+            config?: Record<string, never>;
+            /** Arbitrary key-value metadata */
+            metadata?: Record<string, never>;
+            /** Creation timestamp */
+            createdAt: string;
+            /** Last update timestamp */
+            updatedAt: string;
+            /** Plans associated with this product */
+            plans?: string[];
+        };
+        UpdateProductRequest: {
+            /** Product name */
+            name?: string;
+            /** Product description */
+            description?: string;
+            /** URL to the product image */
+            imageUrl?: string;
+            /** Free-form product type defined by the provider */
+            productType?: string;
+            /**
+             * Product status
+             * @enum {string}
+             */
+            status?: "active" | "inactive" | "suspended";
+            /** Product-specific configuration */
+            config?: Record<string, never>;
+            /** Arbitrary key-value metadata */
+            metadata?: Record<string, never>;
+        };
+        CreatePlanRequest: {
+            /**
+             * Plan name
+             * @example Basic Plan
+             */
+            name: string;
+            /**
+             * Plan description
+             * @example Basic recurring plan with monthly billing
+             */
+            description?: string;
+            /**
+             * Plan type
+             * @example recurring
+             * @enum {string}
+             */
+            type?: "recurring" | "usage-based" | "hybrid" | "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
+             * @example 29.99
+             */
+            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";
+            /**
+             * Setup fee
+             * @example 0
+             */
+            setupFee?: number;
+            /**
+             * Trial days
+             * @example 7
+             */
+            trialDays?: number;
+            /**
+             * Number of free units included
+             * @example 100
+             */
+            freeUnits?: number;
+            /**
+             * Billing model for usage-based plans
+             * @example pre-paid
+             * @enum {string}
+             */
+            billingModel?: "pre-paid" | "post-paid";
+            /**
+             * Price per unit for usage-based plans
+             * @example 0.01
+             */
+            pricePerUnit?: number;
+            /**
+             * Unit name for usage-based plans
+             * @example request
+             */
+            unit?: string;
+            /**
+             * Usage quota for usage-based plans
+             * @example 10000
+             */
+            quota?: number;
+            /**
+             * Whether to rollover unused units
+             * @example false
+             */
+            rolloverUnusedUnits?: boolean;
+            /**
+             * Base price for hybrid plans
+             * @example 29.99
+             */
+            basePrice?: number;
+            /**
+             * Usage limits (shape varies by plan type)
+             * @example {
+             *       "maxTransactions": 1000
+             *     }
+             */
+            limits?: Record<string, never>;
+            /**
+             * Plan features (generic key/value, shape is provider-defined)
+             * @example {
+             *       "apiAccess": true,
+             *       "prioritySupport": false
+             *     }
+             */
+            features?: Record<string, never>;
+            /**
+             * Whether this is a free tier plan
+             * @example false
+             */
+            isFreeTier?: boolean;
+            /**
+             * Whether payment is required
+             * @example true
+             */
+            requiresPayment?: boolean;
+            /**
+             * 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;
+            /** Additional metadata */
+            metadata?: Record<string, never>;
+            /**
+             * Whether this is the default plan
+             * @example false
+             */
+            default?: boolean;
+        };
         UpdatePlanRequest: Record<string, never>;
-        ExecuteAnalyticsQuery: Record<string, never>;
-        ExecuteMultipleQueries: Record<string, never>;
-        CheckLimitRequest: {
+        CreateCheckoutSessionRequest: {
             /**
-             * @description Customer reference identifier
+             * Customer reference
              * @example cus_3c4d5e6f7g8h
              */
+            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;
+        };
+        CancelRenewalRequest: Record<string, never>;
+        UpdateConnectedAccount: Record<string, never>;
+        CancelPurchaseRequest: {
+            /** Reason for cancellation */
+            reason?: string;
+        };
+        CheckLimitRequest: {
+            /**
+             * Customer reference identifier
+             * @example cus_3C4D5E6F
+             */
             customerRef: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Product reference identifier
+             * @example prd_1A2B3C4D
              */
-            agentRef: string;
+            productRef: string;
         };
         LimitResponse: {
             /**
-             * @description Whether the customer is within their usage limits
+             * Whether the customer is within their usage limits
              * @example true
              */
             withinLimits: boolean;
             /**
-             * @description Remaining usage units before hitting the limit
+             * Remaining usage units before hitting the limit
              * @example 997
              */
             remaining: number;
             /**
-             * @description Optional checkout URL if payment is required
-             * @example https://checkout.solvapay.com/pay_1a2b3c4d
+             * Checkout session ID if payment is required
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            checkoutSessionId?: string;
+            /**
+             * Checkout URL if payment is required
+             * @example https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788
              */
             checkoutUrl?: string;
         };
-        UsageEvent: {
+        CreateCustomerSessionRequest: {
             /**
-             * @description Customer reference identifier
+             * Customer reference identifier
              * @example cus_3c4d5e6f7g8h
              */
             customerRef: string;
+        };
+        CustomerSessionResponse: {
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
-             */
-            agentRef: string;
-            /**
-             * @description Outcome of the action
-             * @example success
-             * @enum {string}
-             */
-            outcome: "success" | "paywall" | "fail";
-            /**
-             * @description Optional action identifier
-             * @example generate_text
+             * Customer session ID
+             * @example 507f1f77bcf86cd799439011
              */
-            action?: string;
+            id: string;
             /**
-             * @description Unique request identifier matching the limits check
-             * @example req_1a2b3c4d5e6f
+             * Public session ID used in customer URL
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            requestId: string;
+            sessionId: string;
             /**
-             * @description Duration of the action in milliseconds
-             * @example 1250
+             * Session status
+             * @example active
              */
-            actionDuration: number;
+            status: string;
             /**
-             * @description ISO 8601 timestamp of when the action occurred
-             * @example 2025-10-21T10:30:00.000Z
+             * Customer URL to open the customer page
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
              */
-            timestamp: string;
+            customerUrl: string;
         };
         CreateCustomerRequest: {
             /**
-             * @description Customer email address (required)
+             * Customer email address (required)
              * @example customer@example.com
              */
             email: string;
             /**
-             * @description Customer full name (optional)
+             * Customer full name (optional)
              * @example John Doe
              */
             name?: string;
+            /**
+             * External reference ID from your auth system to map this customer to an auth user (optional)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
         };
-        SubscriptionInfo: {
+        PurchaseInfo: {
             /**
-             * @description Subscription reference
+             * Purchase reference
              * @example sub_abc123
              */
             reference: string;
             /**
-             * @description Plan name
+             * Plan name
              * @example Pro Plan
              */
             planName: string;
             /**
-             * @description Agent name
-             * @example AI Assistant
+             * Product reference
+             * @example prd_abc123
              */
-            agentName: string;
+            productReference?: string;
             /**
-             * @description Subscription status
+             * Purchase status
              * @example active
              */
             status: string;
             /**
-             * @description Start date
+             * Start date
              * @example 2025-10-27T10:00:00Z
              */
             startDate: string;
-        };
-        CustomerResponse: {
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Amount paid in original currency (in cents)
+             * @example 9900
              */
-            reference: string;
+            amount: number;
             /**
-             * @description Customer full name
-             * @example John Doe
+             * Currency code
+             * @example USD
              */
-            name: string;
+            currency: string;
             /**
-             * @description Customer email address
-             * @example customer@example.com
+             * End date of purchase
+             * @example 2025-11-27T10:00:00Z
              */
-            email: string;
-            /** @description Active subscriptions */
-            subscriptions?: components["schemas"]["SubscriptionInfo"][];
-        };
-        Agent: Record<string, never>;
-        CreateAgentRequest: Record<string, never>;
-        UpdateAgentRequest: Record<string, never>;
-        BasePlan: Record<string, never>;
-        SubscriptionResponse: {
+            endDate?: string;
             /**
-             * @description Subscription reference identifier
-             * @example sub_1a2b3c4d5e6f
+             * When purchase was cancelled
+             * @example 2025-10-28T10:00:00Z
              */
-            reference: string;
+            cancelledAt?: string;
             /**
-             * @description Customer reference identifier
-             * @example cus_3c4d5e6f7g8h
+             * Reason for cancellation
+             * @example Customer request
              */
-            customerRef: string;
+            cancellationReason?: string;
+        };
+        CustomerResponse: {
             /**
-             * @description Customer email
-             * @example customer@example.com
+             * Customer reference identifier
+             * @example cus_3c4d5e6f7g8h
              */
-            customerEmail: string;
+            reference: string;
             /**
-             * @description Customer name
+             * Customer full name
              * @example John Doe
              */
-            customerName?: string;
+            name: string;
             /**
-             * @description Agent reference identifier
-             * @example agt_1a2b3c4d5e6f
+             * Customer email address
+             * @example customer@example.com
              */
-            agentRef: string;
+            email: string;
             /**
-             * @description Agent name
-             * @example My AI Agent
+             * External reference ID from your auth system (if set during creation or update)
+             * @example auth_user_12345
              */
-            agentName: string;
+            externalRef?: string;
+            /** Active purchases */
+            purchases?: components["schemas"]["PurchaseInfo"][];
+        };
+        CreateCustomerSessionResponse: {
             /**
-             * @description Plan reference identifier
-             * @example pln_1a2b3c4d5e6f
+             * Customer session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            planRef: string;
+            sessionId: string;
             /**
-             * @description Plan name
-             * @example Premium Plan
+             * Full customer URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
              */
-            planName: string;
+            customerUrl: string;
+        };
+        GetCustomerSessionResponse: {
             /**
-             * @description Plan type
-             * @example recurring
-             * @enum {string}
+             * Customer session ID/token
+             * @example e3f1c2d4b6a89f001122334455667788
              */
-            planType: "recurring" | "usage-based" | "one-time" | "hybrid";
+            sessionId: string;
             /**
-             * @description Subscription status
+             * Session status
              * @example active
              * @enum {string}
              */
-            status: "pending" | "active" | "expired" | "cancelled" | "suspended" | "refunded";
+            status: "active" | "expired" | "used";
             /**
-             * @description Amount paid in original currency (in cents)
-             * @example 9900
+             * Full customer URL based on backend configuration (ready to redirect customer)
+             * @example https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788
              */
-            amount: number;
+            customerUrl: string;
             /**
-             * @description Currency code
-             * @example USD
+             * Session expiration date
+             * @example 2025-01-01T12:00:00.000Z
              */
-            currency: string;
+            expiresAt: string;
+            /** Customer object from session data */
+            customer: components["schemas"]["CustomerResponse"];
             /**
-             * @description Start date of subscription
-             * @example 2025-01-01T00:00:00.000Z
+             * Session creation date
+             * @example 2025-01-01T11:45:00.000Z
              */
-            startDate: string;
+            createdAt: string;
             /**
-             * @description End date of subscription (if applicable)
-             * @example 2025-02-01T00:00:00.000Z
+             * Session last update date
+             * @example 2025-01-01T11:45:00.000Z
              */
-            endDate?: string;
+            updatedAt: string;
+        };
+        DynamicClientRegistrationDto: {
+            /** @example My AI Agent */
+            client_name: string;
             /**
-             * @description When payment was confirmed
-             * @example 2025-01-01T00:00:00.000Z
+             * @example [
+             *       "https://agent.example.com/callback"
+             *     ]
              */
-            paidAt?: string;
-            /** @description Usage quota information (for usage-based plans) */
-            usageQuota?: Record<string, never>;
+            redirect_uris: string[];
             /**
-             * @description Whether this is a recurring subscription
-             * @example true
+             * @example [
+             *       "authorization_code",
+             *       "refresh_token"
+             *     ]
              */
-            isRecurring: boolean;
+            grant_types?: string[];
             /**
-             * @description Next billing date (for recurring subscriptions)
-             * @example 2025-02-01T00:00:00.000Z
+             * @example [
+             *       "code"
+             *     ]
              */
-            nextBillingDate?: string;
+            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;
             /**
-             * @description When subscription was cancelled (if applicable)
-             * @example 2025-01-15T00:00:00.000Z
+             * @example [
+             *       "https://agent.example.com/callback"
+             *     ]
              */
-            cancelledAt?: string;
+            redirect_uris: string[];
             /**
-             * @description Reason for cancellation (if applicable)
-             * @example Customer request
+             * @example [
+             *       "authorization_code",
+             *       "refresh_token"
+             *     ]
              */
-            cancellationReason?: string;
+            grant_types: string[];
             /**
-             * @description When subscription was created
-             * @example 2025-01-01T00:00:00.000Z
+             * @example [
+             *       "code"
+             *     ]
              */
-            createdAt: string;
+            response_types: string[];
+            /** @example openid profile email */
+            scope: string;
+            /** @example client_secret_basic */
+            token_endpoint_auth_method: string;
         };
-        CancelSubscriptionRequest: {
+        GoogleLoginDto: {
+            /** The authorization code returned by Google */
+            code: string;
+            /** The redirect URI used in the initial authorization request */
+            redirect_uri: string;
+            /** The state parameter returned by Google (contains client_id) */
+            state: string;
+        };
+        GithubLoginDto: {
+            /** The authorization code returned by GitHub */
+            code: string;
+            /** The redirect URI used in the initial authorization request */
+            redirect_uri: string;
+            /** The state parameter returned by GitHub (contains client_id) */
+            state: string;
+        };
+        ExecuteAnalyticsQuery: Record<string, never>;
+        ExecuteMultipleQueries: Record<string, never>;
+        UpdateThemePreferenceDto: {
             /**
-             * @description Reason for cancellation
-             * @example Customer request
+             * Selected UI theme mode
+             * @example dark
+             * @enum {string}
              */
-            reason?: string;
+            mode: "light" | "dark";
         };
-        CreatePageSettings: {
-            /** @description Page identifier */
-            id: string;
-            /** @description Page display name */
-            name: string;
-            /** @description Logo URL */
-            logo?: string;
+        ThemeModeColorsDto: {
             /**
-             * @description Text color in hex format
-             * @example #2d3748
+             * Page background color
+             * @example #f7f7f8
              */
-            textColor: string;
+            background?: string;
             /**
-             * @description Button color in hex format
-             * @example #3182ce
+             * Card/surface background color
+             * @example #ffffff
              */
-            buttonColor: string;
+            surface?: string;
             /**
-             * @description Left background color in hex format
-             * @example #f7fafc
+             * Primary text color
+             * @example #181818
              */
-            leftBackgroundColor: string;
+            text?: string;
             /**
-             * @description Right background color in hex format
-             * @example #ffffff
+             * Secondary/muted text color
+             * @example #5c5c5c
+             */
+            secondary?: string;
+        };
+        ThemeOverridesDto: {
+            /** Light mode color overrides */
+            light?: components["schemas"]["ThemeModeColorsDto"];
+            /** Dark mode color overrides */
+            dark?: components["schemas"]["ThemeModeColorsDto"];
+        };
+        UpdateBrandThemeDto: {
+            /**
+             * Provider's brand name displayed on hosted pages
+             * @example Acme Corp
+             */
+            brandName: string;
+            /**
+             * Primary/accent color in hex format
+             * @example #3182ce
              */
-            rightBackgroundColor: string;
+            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;
+            /** Per-mode color overrides for light and dark themes */
+            themes?: components["schemas"]["ThemeOverridesDto"];
+        };
+        CreateWebhookEndpointDto: Record<string, never>;
+        UpdateWebhookEndpointDto: Record<string, never>;
+        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;
+            };
         };
     };
     responses: never;
@@ -324,13 +697,41 @@ type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
 };
 /**
  * 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;
     email?: string;
     name?: string;
+    externalRef?: string;
     plan?: string;
+    purchases?: Array<components['schemas']['PurchaseInfo'] & {
+        paidAt?: string;
+        nextBillingDate?: string;
+    }>;
 };
+/**
+ * One-time purchase information returned from payment processing
+ */
+interface OneTimePurchaseInfo {
+    reference: string;
+    productRef?: string;
+    amount: number;
+    currency: string;
+    creditsAdded?: number;
+    completedAt: string;
+}
+/**
+ * Result from processing a payment intent
+ */
+interface ProcessPaymentResult {
+    type: 'recurring' | 'one-time';
+    purchase?: components['schemas']['PurchaseInfo'];
+    oneTimePurchase?: OneTimePurchaseInfo;
+    status: 'completed';
+}
 /**
  * SolvaPay API Client Interface
  *
@@ -340,41 +741,57 @@ type CustomerResponseMapped = {
  */
 interface SolvaPayClient {
     checkLimits(params: components['schemas']['CheckLimitRequest']): Promise<LimitResponseWithPlan>;
-    trackUsage(params: components['schemas']['UsageEvent'] & {
+    trackUsage(params: {
+        customerRef: string;
+        productRef: string;
         planRef: string;
+        outcome: string;
+        action?: string;
+        requestId?: string;
+        actionDuration?: number;
+        timestamp?: string;
     }): Promise<void>;
     createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
         customerRef: string;
     }>;
-    getCustomer?(params: {
-        customerRef: 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<{
+    updateProduct?(productRef: string, params: components['schemas']['UpdateProductRequest']): Promise<components['schemas']['SdkProductResponse']>;
+    deleteProduct?(productRef: string): Promise<void>;
+    listPlans?(productRef: string): Promise<Array<{
         reference: string;
         name: string;
+        description?: string;
+        price?: number;
+        currency?: string;
+        interval?: string;
         isFreeTier?: boolean;
         freeUnits?: number;
-        description?: 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>;
+    deletePlan?(productRef: string, planRef: string): Promise<void>;
     createPaymentIntent?(params: {
-        agentRef: string;
+        productRef: string;
         planRef: string;
         customerRef: string;
         idempotencyKey?: string;
@@ -384,6 +801,18 @@ interface SolvaPayClient {
         publishableKey: string;
         accountId?: string;
     }>;
+    cancelPurchase?(params: {
+        purchaseRef: string;
+        reason?: string;
+    }): Promise<components['schemas']['PurchaseInfo']>;
+    processPaymentIntent?(params: {
+        paymentIntentId: string;
+        productRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
+    createCheckoutSession(params: components['schemas']['CreateCheckoutSessionRequest']): Promise<components['schemas']['CheckoutSessionResponse']>;
+    createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
 }
 
 /**
@@ -395,7 +824,7 @@ interface SolvaPayClient {
  * Arguments passed to protected handlers
  */
 interface PaywallArgs {
-    [key: string]: any;
+    [key: string]: unknown;
     auth?: {
         customer_ref?: string;
     };
@@ -404,7 +833,7 @@ interface PaywallArgs {
  * Metadata for configuring paywall protection
  */
 interface PaywallMetadata {
-    agent?: string;
+    product?: string;
     plan?: string;
 }
 /**
@@ -412,7 +841,7 @@ interface PaywallMetadata {
  */
 interface PaywallStructuredContent {
     kind: 'payment_required';
-    agent: string;
+    product: string;
     checkoutUrl: string;
     message: string;
 }
@@ -439,7 +868,7 @@ interface PaywallToolResult {
 /**
  * Retry configuration options
  */
-interface RetryOptions$1 {
+interface RetryOptions {
     /**
      * Maximum number of retry attempts (default: 2)
      */
@@ -474,15 +903,15 @@ interface RetryOptions$1 {
  */
 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;
     /**
@@ -560,91 +989,286 @@ 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.
+ *
+ * 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.
  *
- * @param opts - Configuration options including API key and optional base URL
+ * 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;
 
 /**
- * SolvaPay Factory
+ * Configuration for creating a SolvaPay instance.
  *
- * Main entry point for creating SolvaPay instances with the unified payable API
- */
-
-/**
- * Configuration for creating a SolvaPay instance
+ * You can provide either an `apiKey` (for production) or an `apiClient` (for testing).
+ * If neither is provided, the SDK will attempt to read `SOLVAPAY_SECRET_KEY` from
+ * environment variables. If no API key is found, the SDK runs in stub mode.
+ *
+ * @example
+ * ```typescript
+ * // Production: Use API key
+ * const config: CreateSolvaPayConfig = {
+ *   apiKey: process.env.SOLVAPAY_SECRET_KEY
+ * };
+ *
+ * // Testing: Use mock client
+ * const config: CreateSolvaPayConfig = {
+ *   apiClient: mockClient
+ * };
+ * ```
  */
 interface CreateSolvaPayConfig {
     /**
-     * API key for production use (creates client automatically)
+     * API key for production use (creates client automatically).
+     * Defaults to `SOLVAPAY_SECRET_KEY` environment variable if not provided.
      */
     apiKey?: string;
     /**
-     * API client for testing or custom implementations
+     * API client for testing or custom implementations.
+     * Use this for stub mode, testing, or custom client implementations.
      */
     apiClient?: SolvaPayClient;
     /**
-     * Optional API base URL (only used with apiKey)
+     * Optional API base URL override (only used with apiKey).
+     * Defaults to production API URL if not provided.
      */
     apiBaseUrl?: string;
 }
 /**
- * Payable function that provides explicit adapters
+ * Payable function that provides explicit adapters for different frameworks.
+ *
+ * Use the appropriate adapter method for your framework:
+ * - `http()` - Express.js, Fastify, and other HTTP frameworks
+ * - `next()` - Next.js App Router API routes
+ * - `mcp()` - Model Context Protocol servers
+ * - `function()` - Pure functions, background jobs, or testing
+ *
+ * @example
+ * ```typescript
+ * const payable = solvaPay.payable({ 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)
+     *
+     * @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): Promise<string>;
+    ensureCustomer(customerRef: string, externalRef?: string, options?: {
+        email?: string;
+        name?: string;
+    }): Promise<string>;
     /**
-     * Create a payment intent for a customer to subscribe to a plan
+     * 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;
@@ -655,11 +1279,66 @@ interface SolvaPay {
         accountId?: string;
     }>;
     /**
-     * Check if customer is within usage limits
+     * 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);
+     * }
+     * ```
+     */
+    processPaymentIntent(params: {
+        paymentIntentId: string;
+        productRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
+    /**
+     * 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'
+     * });
+     *
+     * if (!limits.withinLimits) {
+     *   // Redirect to checkout
+     *   window.location.href = limits.checkoutUrl;
+     * }
+     * ```
      */
     checkLimits(params: {
         customerRef: string;
-        agentRef: string;
+        productRef: string;
     }): Promise<{
         withinLimits: boolean;
         remaining: number;
@@ -667,11 +1346,38 @@ interface SolvaPay {
         checkoutUrl?: string;
     }>;
     /**
-     * Track usage for a customer action
+     * Track usage for a customer action.
+     *
+     * This is automatically called by the paywall system. You typically
+     * don't need to call this manually unless implementing custom tracking.
+     *
+     * @param params - Usage tracking parameters
+     * @param params.customerRef - Customer reference
+     * @param params.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: 'user_123',
+     *   productRef: 'prd_myapi',
+     *   planRef: 'pln_premium',
+     *   outcome: 'success',
+     *   action: 'api_call',
+     *   requestId: 'req_123',
+     *   actionDuration: 150,
+     *   timestamp: new Date().toISOString()
+     * });
+     * ```
      */
     trackUsage(params: {
         customerRef: string;
-        agentRef: string;
+        productRef: string;
         planRef: string;
         outcome: 'success' | 'paywall' | 'fail';
         action?: string;
@@ -680,7 +1386,23 @@ interface SolvaPay {
         timestamp: string;
     }): Promise<void>;
     /**
-     * Create a new customer
+     * Create a new customer in SolvaPay backend.
+     *
+     * Note: `ensureCustomer()` is usually preferred as it's idempotent.
+     * Use this only if you need explicit control over customer creation.
+     *
+     * @param params - Customer creation parameters
+     * @param params.email - Customer email address (required)
+     * @param params.name - Optional customer name
+     * @returns Created customer reference
+     *
+     * @example
+     * ```typescript
+     * const { customerRef } = await solvaPay.createCustomer({
+     *   email: 'user@example.com',
+     *   name: 'John Doe'
+     * });
+     * ```
      */
     createCustomer(params: {
         email: string;
@@ -689,47 +1411,153 @@ 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;
+        externalRef?: string;
+    }): Promise<CustomerResponseMapped>;
+    /**
+     * 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: {
+        productRef: string;
         customerRef: string;
+        planRef?: string;
+        returnUrl?: string;
     }): Promise<{
+        sessionId: string;
+        checkoutUrl: string;
+    }>;
+    /**
+     * 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
+     * @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;
-        email?: string;
-        name?: string;
-        plan?: string;
+    }): Promise<{
+        sessionId: string;
+        customerUrl: string;
     }>;
     /**
-     * Direct access to the API client for advanced operations
-     * (agent/plan management, etc.)
+     * Direct access to the API client for advanced operations.
+     *
+     * Use this for operations not exposed by the SolvaPay interface,
+     * such as 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 - Configuration with either apiKey or apiClient
- * @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: Pass API key
+ * // Production: Use environment variable (recommended)
+ * const solvaPay = createSolvaPay();
+ *
+ * // Production: Pass API key explicitly
  * const solvaPay = createSolvaPay({
  *   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;
+declare function createSolvaPay(config?: CreateSolvaPayConfig): SolvaPay;
 
 /**
  * SolvaPay SDK - Universal Paywall Protection
@@ -740,61 +1568,78 @@ declare function createSolvaPay(config: CreateSolvaPayConfig): SolvaPay;
  * - 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);
 }
 
 /**
  * Utility functions for the SolvaPay Server SDK
  */
+
 /**
- * Retry configuration options
- */
-interface RetryOptions {
-    /**
-     * Maximum number of retry attempts (default: 2)
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay between retries in milliseconds (default: 500)
-     */
-    initialDelay?: number;
-    /**
-     * Backoff strategy for calculating delay between retries (default: 'fixed')
-     * - 'fixed': Same delay between all retries
-     * - 'linear': Delay increases linearly (initialDelay * attempt)
-     * - 'exponential': Delay doubles each attempt (initialDelay * 2^(attempt-1))
-     */
-    backoffStrategy?: 'fixed' | 'linear' | 'exponential';
-    /**
-     * Optional function to determine if a retry should be attempted based on the error
-     * @param error The error that was thrown
-     * @param attempt The current attempt number (0-indexed)
-     * @returns true if a retry should be attempted, false otherwise
-     */
-    shouldRetry?: (error: Error, attempt: number) => boolean;
-    /**
-     * Optional callback invoked before each retry attempt
-     * @param error The error that triggered the retry
-     * @param attempt The current attempt number (0-indexed)
-     */
-    onRetry?: (error: Error, attempt: number) => void;
-}
-/**
- * Executes an async function with automatic retry logic
+ * 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(),
  *   {
@@ -806,9 +1651,326 @@ interface RetryOptions {
  *   }
  * );
  * ```
+ *
+ * @since 1.0.0
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+/**
+ * Helper Types
+ *
+ * Shared types for route helpers
+ */
+/**
+ * Error result returned by core helpers
+ */
+interface ErrorResult {
+    error: string;
+    status: number;
+    details?: string;
+}
+/**
+ * Authenticated user information
+ */
+interface AuthenticatedUser {
+    userId: string;
+    email?: string | null;
+    name?: string | null;
+}
+
+/**
+ * Error Handling Helper
+ *
+ * Generic error handling utilities for route helpers
+ */
+
+/**
+ * Check if a result is an error result
+ */
+declare function isErrorResult(result: unknown): result is ErrorResult;
+/**
+ * Handle route errors and convert to ErrorResult
+ */
+declare function handleRouteError(error: unknown, operationName: string, defaultMessage?: string): ErrorResult;
+
+/**
+ * Authentication Helper (Core)
+ *
+ * Generic helper for extracting authenticated user information from requests.
+ * Works with standard Web API Request (works everywhere).
+ */
+
+/**
+ * Extract authenticated user information from 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 - Edge Runtime Entry Point
  *
@@ -836,10 +1998,10 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
  * const event = await verifyWebhook({ body, signature, secret });
  * ```
  */
-declare function verifyWebhook({ body, signature, secret }: {
+declare function verifyWebhook({ body, signature, secret, }: {
     body: string;
     signature: string;
     secret: string;
 }): Promise<any>;
 
-export { type CreateSolvaPayConfig, type HttpAdapterOptions, type McpAdapterOptions, type NextAdapterOptions, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type RetryOptions$1 as RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, createSolvaPay, createSolvaPayClient, verifyWebhook, withRetry };
+export { type AuthenticatedUser, type CreateSolvaPayConfig, type ErrorResult, type HttpAdapterOptions, type McpAdapterOptions, type NextAdapterOptions, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, cancelPurchaseCore, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, getAuthenticatedUserCore, handleRouteError, isErrorResult, listPlansCore, processPaymentIntentCore, syncCustomerCore, verifyWebhook, withRetry };