@solvapay/server 1.0.0-preview.5 → 1.0.0-preview.7

package/README.md

@@ -93,6 +93,36 @@ const result = await protectedHandler({
 });
 ```
 
+### Authentication Integration
+
+You can integrate authentication adapters from `@solvapay/auth` with the `getCustomerRef` option:
+
+```ts
+import { createSolvaPay } from '@solvapay/server';
+import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+
+const auth = new SupabaseAuthAdapter({
+  jwtSecret: process.env.SUPABASE_JWT_SECRET!
+});
+
+const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! });
+
+// Use with Next.js adapter
+export const POST = solvaPay.payable({ agent: 'my-api' }).next(
+  async (args) => {
+    return { result: 'success' };
+  },
+  {
+    getCustomerRef: async (req) => {
+      const userId = await auth.getUserIdFromRequest(req);
+      return userId ?? 'anonymous';
+    }
+  }
+);
+```
+
+This automatically extracts the user ID from authentication tokens and uses it as the customer reference for paywall checks.
+
 ### When to Use Each Adapter
 
 Choose the adapter based on your context:

package/dist/edge.d.ts

@@ -22,6 +22,62 @@ interface components {
         UpdatePlanRequest: Record<string, never>;
         ExecuteAnalyticsQuery: Record<string, never>;
         ExecuteMultipleQueries: Record<string, never>;
+        CreateCheckoutSessionRequest: {
+            /**
+             * @description Customer reference
+             * @example cus_3c4d5e6f7g8h
+             */
+            customerReference: string;
+            /**
+             * @description Plan reference (optional)
+             * @example pln_2b3c4d5e6f7g
+             */
+            planRef?: string;
+            /**
+             * @description Agent reference (optional)
+             * @example agt_1a2b3c4d5e6f
+             */
+            agentRef?: string;
+        };
+        CheckoutSessionResponse: {
+            /**
+             * @description Checkout session ID
+             * @example 507f1f77bcf86cd799439011
+             */
+            id: string;
+            /**
+             * @description Public session ID used in checkout URL
+             * @example a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            sessionId: string;
+            /**
+             * @description Amount in cents
+             * @example 2999
+             */
+            amount: number;
+            /**
+             * @description Currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * @description Session status
+             * @example active
+             */
+            status: string;
+            /**
+             * @description Checkout URL to open the checkout page
+             * @example http://localhost:3000/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+             */
+            checkoutUrl: string;
+        };
+        CancelSubscriptionRequest: {
+            /**
+             * @description Reason for cancellation
+             * @example Customer request
+             */
+            reason?: string;
+        };
         CheckLimitRequest: {
             /**
              * @description Customer reference identifier
@@ -50,6 +106,11 @@ interface components {
              * @example https://checkout.solvapay.com/pay_1a2b3c4d
              */
             checkoutUrl?: string;
+            /**
+             * @description Optional checkout session ID if payment is required
+             * @example e3f1c2d4b6a89f001122334455667788
+             */
+            checkoutSessionId?: string;
         };
         UsageEvent: {
             /**
@@ -100,6 +161,11 @@ interface components {
              * @example John Doe
              */
             name?: string;
+            /**
+             * @description External reference ID from your auth system to map this customer to an auth user (optional)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
         };
         SubscriptionInfo: {
             /**
@@ -144,6 +210,11 @@ interface components {
              * @example customer@example.com
              */
             email: string;
+            /**
+             * @description External reference ID from your auth system (if set during creation or update)
+             * @example auth_user_12345
+             */
+            externalRef?: string;
             /** @description Active subscriptions */
             subscriptions?: components["schemas"]["SubscriptionInfo"][];
         };
@@ -257,13 +328,6 @@ interface components {
              */
             createdAt: string;
         };
-        CancelSubscriptionRequest: {
-            /**
-             * @description Reason for cancellation
-             * @example Customer request
-             */
-            reason?: string;
-        };
         CreatePageSettings: {
             /** @description Page identifier */
             id: string;
@@ -329,9 +393,30 @@ type CustomerResponseMapped = {
     customerRef: string;
     email?: string;
     name?: string;
+    externalRef?: string;
     plan?: string;
     subscriptions?: components['schemas']['SubscriptionInfo'][];
 };
+/**
+ * Purchase information returned from payment processing
+ */
+interface PurchaseInfo {
+    reference: string;
+    productRef?: string;
+    amount: number;
+    currency: string;
+    creditsAdded?: number;
+    completedAt: string;
+}
+/**
+ * Result from processing a payment intent
+ */
+interface ProcessPaymentResult {
+    type: 'subscription' | 'purchase';
+    subscription?: components['schemas']['SubscriptionInfo'];
+    purchase?: PurchaseInfo;
+    status: 'completed';
+}
 /**
  * SolvaPay API Client Interface
  *
@@ -350,6 +435,9 @@ interface SolvaPayClient {
     getCustomer?(params: {
         customerRef: string;
     }): Promise<CustomerResponseMapped>;
+    getCustomerByExternalRef?(params: {
+        externalRef: string;
+    }): Promise<CustomerResponseMapped>;
     listAgents?(): Promise<Array<{
         reference: string;
         name: string;
@@ -363,9 +451,14 @@ interface SolvaPayClient {
     listPlans?(agentRef: string): Promise<Array<{
         reference: string;
         name: string;
+        description?: string;
+        price?: number;
+        currency?: string;
+        interval?: string;
         isFreeTier?: boolean;
         freeUnits?: number;
-        description?: string;
+        metadata?: Record<string, any>;
+        [key: string]: any;
     }>>;
     createPlan?(params: components['schemas']['CreatePlanRequest'] & {
         agentRef: string;
@@ -385,6 +478,16 @@ interface SolvaPayClient {
         publishableKey: string;
         accountId?: string;
     }>;
+    cancelSubscription?(params: {
+        subscriptionRef: string;
+        reason?: string;
+    }): Promise<components['schemas']['SubscriptionResponse']>;
+    processPayment?(params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
 }
 
 /**
@@ -440,7 +543,7 @@ interface PaywallToolResult {
 /**
  * Retry configuration options
  */
-interface RetryOptions$1 {
+interface RetryOptions {
     /**
      * Maximum number of retry attempts (default: 2)
      */
@@ -583,12 +686,6 @@ type ServerClientOptions = {
  */
 declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient;
 
-/**
- * SolvaPay Factory
- *
- * Main entry point for creating SolvaPay instances with the unified payable API
- */
-
 /**
  * Configuration for creating a SolvaPay instance
  */
@@ -639,8 +736,16 @@ interface SolvaPay {
     /**
      * Ensure customer exists (for testing/setup)
      * Only attempts creation once per customer (idempotent).
+     *
+     * @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
      */
-    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
      */
@@ -655,6 +760,16 @@ interface SolvaPay {
         publishableKey: string;
         accountId?: string;
     }>;
+    /**
+     * Process a payment intent after client-side confirmation
+     * Creates subscription or purchase immediately, eliminating webhook delay
+     */
+    processPayment(params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }): Promise<ProcessPaymentResult>;
     /**
      * Check if customer is within usage limits
      */
@@ -716,12 +831,15 @@ interface SolvaPay {
 /**
  * Create a SolvaPay instance
  *
- * @param config - Configuration with either apiKey or apiClient
+ * @param config - Optional configuration with either apiKey or apiClient. If not provided, reads from environment variables.
  * @returns SolvaPay instance with payable() method
  *
  * @example
  * ```typescript
- * // Production: Pass API key
+ * // Production: Read from environment variables (recommended)
+ * const solvaPay = createSolvaPay();
+ *
+ * // Production: Pass API key explicitly
  * const solvaPay = createSolvaPay({
  *   apiKey: process.env.SOLVAPAY_SECRET_KEY
  * });
@@ -737,7 +855,7 @@ interface SolvaPay {
  * export const POST = payable.next(createTask);
  * ```
  */
-declare function createSolvaPay(config: CreateSolvaPayConfig): SolvaPay;
+declare function createSolvaPay(config?: CreateSolvaPayConfig): SolvaPay;
 
 /**
  * SolvaPay SDK - Universal Paywall Protection
@@ -756,39 +874,7 @@ declare class PaywallError extends Error {
 /**
  * Utility functions for the SolvaPay Server SDK
  */
-/**
- * Retry configuration options
- */
-interface RetryOptions {
-    /**
-     * Maximum number of retry attempts (default: 2)
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay between retries in milliseconds (default: 500)
-     */
-    initialDelay?: number;
-    /**
-     * Backoff strategy for calculating delay between retries (default: 'fixed')
-     * - 'fixed': Same delay between all retries
-     * - 'linear': Delay increases linearly (initialDelay * attempt)
-     * - 'exponential': Delay doubles each attempt (initialDelay * 2^(attempt-1))
-     */
-    backoffStrategy?: 'fixed' | 'linear' | 'exponential';
-    /**
-     * Optional function to determine if a retry should be attempted based on the error
-     * @param error The error that was thrown
-     * @param attempt The current attempt number (0-indexed)
-     * @returns true if a retry should be attempted, false otherwise
-     */
-    shouldRetry?: (error: Error, attempt: number) => boolean;
-    /**
-     * Optional callback invoked before each retry attempt
-     * @param error The error that triggered the retry
-     * @param attempt The current attempt number (0-indexed)
-     */
-    onRetry?: (error: Error, attempt: number) => void;
-}
+
 /**
  * Executes an async function with automatic retry logic
  *
@@ -850,4 +936,4 @@ declare function verifyWebhook({ body, signature, secret }: {
     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 CreateSolvaPayConfig, 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, createSolvaPay, createSolvaPayClient, verifyWebhook, withRetry };