@solvapay/next 1.0.0-preview.17 → 1.0.0-preview.19

package/dist/index.cjs

@@ -50,6 +50,136 @@ var import_server16 = require("next/server");
 var import_server17 = require("@solvapay/server");
 var import_core = require("@solvapay/core");
 
+// src/cache.ts
+function createRequestDeduplicator(options = {}) {
+  const { cacheTTL = 2e3, maxCacheSize = 1e3, cacheErrors = true } = options;
+  const inFlightRequests = /* @__PURE__ */ new Map();
+  const resultCache = /* @__PURE__ */ new Map();
+  const cacheInvalidatedAt = /* @__PURE__ */ new Map();
+  if (cacheTTL > 0) {
+    setInterval(
+      () => {
+        const now = Date.now();
+        const entriesToDelete = [];
+        for (const [key, cached] of resultCache.entries()) {
+          if (now - cached.timestamp >= cacheTTL) {
+            entriesToDelete.push(key);
+          }
+        }
+        for (const key of entriesToDelete) {
+          resultCache.delete(key);
+          cacheInvalidatedAt.delete(key);
+        }
+        if (resultCache.size > maxCacheSize) {
+          const sortedEntries = Array.from(resultCache.entries()).sort(
+            (a, b) => a[1].timestamp - b[1].timestamp
+          );
+          const toRemove = sortedEntries.slice(0, resultCache.size - maxCacheSize);
+          for (const [key] of toRemove) {
+            resultCache.delete(key);
+            cacheInvalidatedAt.delete(key);
+          }
+        }
+      },
+      Math.min(cacheTTL, 1e3)
+    );
+  }
+  const deduplicate = async (key, fn) => {
+    if (cacheTTL > 0) {
+      const cached = resultCache.get(key);
+      if (cached && Date.now() - cached.timestamp < cacheTTL) {
+        return cached.data;
+      } else if (cached) {
+        resultCache.delete(key);
+      }
+    }
+    let requestPromise = inFlightRequests.get(key);
+    if (!requestPromise) {
+      const requestStartTime = Date.now();
+      requestPromise = (async () => {
+        try {
+          const result = await fn();
+          const invalidatedAt = cacheInvalidatedAt.get(key);
+          const shouldCache = !invalidatedAt || invalidatedAt < requestStartTime;
+          if (cacheTTL > 0 && shouldCache) {
+            resultCache.set(key, {
+              data: result,
+              timestamp: Date.now()
+            });
+          }
+          return result;
+        } catch (error) {
+          const invalidatedAt = cacheInvalidatedAt.get(key);
+          const shouldCache = !invalidatedAt || invalidatedAt < requestStartTime;
+          if (cacheTTL > 0 && cacheErrors && shouldCache) {
+            resultCache.set(key, {
+              data: error,
+              timestamp: Date.now()
+            });
+          }
+          throw error;
+        } finally {
+          inFlightRequests.delete(key);
+        }
+      })();
+      const existingPromise = inFlightRequests.get(key);
+      if (existingPromise) {
+        requestPromise = existingPromise;
+      } else {
+        inFlightRequests.set(key, requestPromise);
+      }
+    }
+    return requestPromise;
+  };
+  const clearCache = (key) => {
+    resultCache.delete(key);
+    cacheInvalidatedAt.set(key, Date.now());
+    inFlightRequests.delete(key);
+  };
+  const clearAllCache = () => {
+    resultCache.clear();
+    cacheInvalidatedAt.clear();
+    inFlightRequests.clear();
+  };
+  const getStats = () => ({
+    inFlight: inFlightRequests.size,
+    cached: resultCache.size
+  });
+  return {
+    deduplicate,
+    clearCache,
+    clearAllCache,
+    getStats
+  };
+}
+var sharedSubscriptionDeduplicator = null;
+function getSharedDeduplicator(options) {
+  if (!sharedSubscriptionDeduplicator) {
+    sharedSubscriptionDeduplicator = createRequestDeduplicator({
+      cacheTTL: 2e3,
+      // Cache results for 2 seconds
+      maxCacheSize: 1e3,
+      // Maximum cache entries
+      cacheErrors: true,
+      // Cache error results too
+      ...options
+    });
+  }
+  return sharedSubscriptionDeduplicator;
+}
+function clearSubscriptionCache(userId) {
+  const deduplicator = getSharedDeduplicator();
+  deduplicator.clearCache(userId);
+}
+function clearAllSubscriptionCache() {
+  const deduplicator = getSharedDeduplicator();
+  deduplicator.clearAllCache();
+}
+function getSubscriptionCacheStats() {
+  const deduplicator = getSharedDeduplicator();
+  return deduplicator.getStats();
+}
+
 // src/helpers/auth.ts
 var import_server = require("next/server");
 var import_server2 = require("@solvapay/server");
@@ -180,20 +310,17 @@ async function listPlans(request) {
 // src/helpers/middleware.ts
 var import_server15 = require("next/server");
 function createAuthMiddleware(options) {
-  const {
-    adapter,
-    publicRoutes = [],
-    userIdHeader = "x-user-id"
-  } = options;
+  const { adapter, publicRoutes = [], userIdHeader = "x-user-id" } = options;
   return async function middleware(request) {
-    const { pathname } = request.nextUrl;
+    const req = request;
+    const { pathname } = req.nextUrl;
     if (!pathname.startsWith("/api")) {
       return import_server15.NextResponse.next();
     }
     const isPublicRoute = publicRoutes.some((route) => pathname.startsWith(route));
-    const userId = await adapter.getUserIdFromRequest(request);
+    const userId = await adapter.getUserIdFromRequest(req);
     if (isPublicRoute) {
-      const requestHeaders2 = new Headers(request.headers);
+      const requestHeaders2 = new Headers(req.headers);
       if (userId) {
         requestHeaders2.set(userIdHeader, userId);
       }
@@ -209,7 +336,7 @@ function createAuthMiddleware(options) {
         { status: 401 }
       );
     }
-    const requestHeaders = new Headers(request.headers);
+    const requestHeaders = new Headers(req.headers);
     requestHeaders.set(userIdHeader, userId);
     return import_server15.NextResponse.next({
       request: {
@@ -219,11 +346,7 @@ function createAuthMiddleware(options) {
   };
 }
 function createSupabaseAuthMiddleware(options = {}) {
-  const {
-    jwtSecret,
-    publicRoutes = [],
-    userIdHeader = "x-user-id"
-  } = options;
+  const { jwtSecret, publicRoutes = [], userIdHeader = "x-user-id" } = options;
   let authAdapter = null;
   let adapterPromise = null;
   const lazyAdapter = {
@@ -255,122 +378,6 @@ function createSupabaseAuthMiddleware(options = {}) {
 }
 
 // src/index.ts
-function createRequestDeduplicator(options = {}) {
-  const {
-    cacheTTL = 2e3,
-    maxCacheSize = 1e3,
-    cacheErrors = true
-  } = options;
-  const inFlightRequests = /* @__PURE__ */ new Map();
-  const resultCache = /* @__PURE__ */ new Map();
-  const cacheInvalidatedAt = /* @__PURE__ */ new Map();
-  let cleanupInterval = null;
-  if (cacheTTL > 0) {
-    cleanupInterval = setInterval(() => {
-      const now = Date.now();
-      const entriesToDelete = [];
-      for (const [key, cached] of resultCache.entries()) {
-        if (now - cached.timestamp >= cacheTTL) {
-          entriesToDelete.push(key);
-        }
-      }
-      for (const key of entriesToDelete) {
-        resultCache.delete(key);
-        cacheInvalidatedAt.delete(key);
-      }
-      if (resultCache.size > maxCacheSize) {
-        const sortedEntries = Array.from(resultCache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp);
-        const toRemove = sortedEntries.slice(0, resultCache.size - maxCacheSize);
-        for (const [key] of toRemove) {
-          resultCache.delete(key);
-          cacheInvalidatedAt.delete(key);
-        }
-      }
-    }, Math.min(cacheTTL, 1e3));
-  }
-  const deduplicate = async (key, fn) => {
-    if (cacheTTL > 0) {
-      const cached = resultCache.get(key);
-      if (cached && Date.now() - cached.timestamp < cacheTTL) {
-        return cached.data;
-      } else if (cached) {
-        resultCache.delete(key);
-      }
-    }
-    let requestPromise = inFlightRequests.get(key);
-    if (!requestPromise) {
-      const requestStartTime = Date.now();
-      requestPromise = (async () => {
-        try {
-          const result = await fn();
-          const invalidatedAt = cacheInvalidatedAt.get(key);
-          const shouldCache = !invalidatedAt || invalidatedAt < requestStartTime;
-          if (cacheTTL > 0 && shouldCache) {
-            resultCache.set(key, {
-              data: result,
-              timestamp: Date.now()
-            });
-          }
-          return result;
-        } catch (error) {
-          const invalidatedAt = cacheInvalidatedAt.get(key);
-          const shouldCache = !invalidatedAt || invalidatedAt < requestStartTime;
-          if (cacheTTL > 0 && cacheErrors && shouldCache) {
-            resultCache.set(key, {
-              data: error,
-              timestamp: Date.now()
-            });
-          }
-          throw error;
-        } finally {
-          inFlightRequests.delete(key);
-        }
-      })();
-      const existingPromise = inFlightRequests.get(key);
-      if (existingPromise) {
-        requestPromise = existingPromise;
-      } else {
-        inFlightRequests.set(key, requestPromise);
-      }
-    }
-    return requestPromise;
-  };
-  const clearCache = (key) => {
-    resultCache.delete(key);
-    cacheInvalidatedAt.set(key, Date.now());
-    inFlightRequests.delete(key);
-  };
-  const clearAllCache = () => {
-    resultCache.clear();
-    cacheInvalidatedAt.clear();
-    inFlightRequests.clear();
-  };
-  const getStats = () => ({
-    inFlight: inFlightRequests.size,
-    cached: resultCache.size
-  });
-  return {
-    deduplicate,
-    clearCache,
-    clearAllCache,
-    getStats
-  };
-}
-var sharedSubscriptionDeduplicator = null;
-function getSharedDeduplicator(options) {
-  if (!sharedSubscriptionDeduplicator) {
-    sharedSubscriptionDeduplicator = createRequestDeduplicator({
-      cacheTTL: 2e3,
-      // Cache results for 2 seconds
-      maxCacheSize: 1e3,
-      // Maximum cache entries
-      cacheErrors: true,
-      // Cache error results too
-      ...options
-    });
-  }
-  return sharedSubscriptionDeduplicator;
-}
 async function checkSubscription(request, options = {}) {
   try {
     const { requireUserId, getUserEmailFromRequest, getUserNameFromRequest } = await import("@solvapay/auth");
@@ -401,7 +408,7 @@ async function checkSubscription(request, options = {}) {
             };
           }
         }
-      } catch (error) {
+      } catch {
       }
     }
     const deduplicator = getSharedDeduplicator(options.deduplication);
@@ -434,10 +441,7 @@ async function checkSubscription(request, options = {}) {
   } catch (error) {
     console.error("Check subscription failed:", error);
     if (error instanceof import_core.SolvaPayError) {
-      return import_server16.NextResponse.json(
-        { error: error.message },
-        { status: 500 }
-      );
+      return import_server16.NextResponse.json({ error: error.message }, { status: 500 });
     }
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
     return import_server16.NextResponse.json(
@@ -446,18 +450,6 @@ async function checkSubscription(request, options = {}) {
     );
   }
 }
-function clearSubscriptionCache(userId) {
-  const deduplicator = getSharedDeduplicator();
-  deduplicator.clearCache(userId);
-}
-function clearAllSubscriptionCache() {
-  const deduplicator = getSharedDeduplicator();
-  deduplicator.clearAllCache();
-}
-function getSubscriptionCacheStats() {
-  const deduplicator = getSharedDeduplicator();
-  return deduplicator.getStats();
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cancelSubscription,

package/dist/index.d.cts

@@ -3,6 +3,128 @@ import * as _solvapay_server from '@solvapay/server';
 import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
 import { AuthAdapter } from '@solvapay/auth';
 
+/**
+ * Subscription Cache Utilities
+ *
+ * Cache management functions for subscription data.
+ * Separated from index.ts to avoid circular dependencies.
+ */
+/**
+ * Request deduplication and caching options
+ */
+interface RequestDeduplicationOptions {
+    /**
+     * Time-to-live for cached results in milliseconds (default: 2000)
+     * Set to 0 to disable caching (only deduplicate concurrent requests)
+     */
+    cacheTTL?: number;
+    /**
+     * Maximum cache size before cleanup (default: 1000)
+     * When exceeded, oldest entries are removed
+     */
+    maxCacheSize?: number;
+    /**
+     * Whether to cache error results (default: true)
+     * When false, only successful results are cached
+     */
+    cacheErrors?: boolean;
+}
+/**
+ * Subscription check result
+ */
+interface SubscriptionCheckResult {
+    customerRef: string;
+    email?: string;
+    name?: string;
+    subscriptions: Array<{
+        reference: string;
+        planName?: string;
+        agentName?: string;
+        status?: string;
+        startDate?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Clear subscription cache for a specific user.
+ *
+ * Useful when you know subscription status has changed (e.g., after a successful
+ * checkout, subscription update, or cancellation). This forces the next
+ * `checkSubscription()` call to fetch fresh data from the backend.
+ *
+ * @param userId - User ID to clear cache for
+ *
+ * @example
+ * ```typescript
+ * import { clearSubscriptionCache } from '@solvapay/next';
+ *
+ * // After successful payment
+ * await processPayment(request, body);
+ * clearSubscriptionCache(userId); // Force refresh on next check
+ * ```
+ *
+ * @see {@link checkSubscription} for subscription checking
+ * @see {@link clearAllSubscriptionCache} to clear all cache entries
+ * @since 1.0.0
+ */
+declare function clearSubscriptionCache(userId: string): void;
+/**
+ * Clear all subscription cache entries.
+ *
+ * Useful for testing, debugging, or when you need to force fresh lookups
+ * for all users. This clears both the in-flight request cache and the
+ * result cache.
+ *
+ * @example
+ * ```typescript
+ * import { clearAllSubscriptionCache } from '@solvapay/next';
+ *
+ * // In a test setup
+ * beforeEach(() => {
+ *   clearAllSubscriptionCache();
+ * });
+ * ```
+ *
+ * @see {@link clearSubscriptionCache} to clear cache for a specific user
+ * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @since 1.0.0
+ */
+declare function clearAllSubscriptionCache(): void;
+/**
+ * Get subscription cache statistics for monitoring and debugging.
+ *
+ * Returns the current state of the subscription cache, including:
+ * - Number of in-flight requests (being deduplicated)
+ * - Number of cached results
+ *
+ * @returns Cache statistics object
+ * @returns inFlight - Number of currently in-flight requests
+ * @returns cached - Number of cached results
+ *
+ * @example
+ * ```typescript
+ * import { getSubscriptionCacheStats } from '@solvapay/next';
+ *
+ * // In a monitoring endpoint
+ * export async function GET() {
+ *   const stats = getSubscriptionCacheStats();
+ *   return Response.json({
+ *     cache: {
+ *       inFlight: stats.inFlight,
+ *       cached: stats.cached
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link checkSubscription} for subscription checking
+ * @since 1.0.0
+ */
+declare function getSubscriptionCacheStats(): {
+    inFlight: number;
+    cached: number;
+};
+
 /**
  * Next.js Authentication Helpers
  *
@@ -10,11 +132,37 @@ import { AuthAdapter } from '@solvapay/auth';
  */
 
 /**
- * Get authenticated user - Next.js wrapper
+ * Get authenticated user information from a Next.js request.
  *
- * @param request - Next.js request object
+ * This is a Next.js-specific wrapper around `getAuthenticatedUserCore` that
+ * returns NextResponse for errors instead of ErrorResult. Extracts user ID,
+ * email, and name from authenticated requests.
+ *
+ * @param request - Next.js request object (NextRequest or Request)
  * @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 NextResponse error
+ *
+ * @example
+ * ```typescript
+ * import { NextRequest, NextResponse } from 'next/server';
+ * import { getAuthenticatedUser } from '@solvapay/next';
+ *
+ * export async function GET(request: NextRequest) {
+ *   const userResult = await getAuthenticatedUser(request);
+ *
+ *   if (userResult instanceof NextResponse) {
+ *     return userResult; // Error response
+ *   }
+ *
+ *   const { userId, email, name } = userResult;
+ *   return NextResponse.json({ userId, email, name });
+ * }
+ * ```
+ *
+ * @see {@link getAuthenticatedUserCore} for the core implementation
+ * @since 1.0.0
  */
 declare function getAuthenticatedUser(request: globalThis.Request, options?: {
     includeEmail?: boolean;
@@ -95,10 +243,12 @@ declare function processPayment(request: globalThis.Request, body: {
 declare function createCheckoutSession(request: globalThis.Request, body: {
     agentRef: string;
     planRef?: string;
+    returnUrl?: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
+    returnUrl?: string;
 }): Promise<{
     sessionId: string;
     checkoutUrl: string;
@@ -124,7 +274,6 @@ declare function createCustomerSession(request: globalThis.Request, options?: {
  *
  * Next.js-specific wrappers for subscription helpers.
  */
-
 /**
  * Cancel subscription - Next.js wrapper
  *
@@ -138,7 +287,7 @@ declare function cancelSubscription(request: globalThis.Request, body: {
     reason?: string;
 }, options?: {
     solvaPay?: SolvaPay;
-}): Promise<any | NextResponse>;
+}): Promise<Record<string, unknown> | NextResponse>;
 
 /**
  * Next.js Plans Helper
@@ -146,7 +295,6 @@ declare function cancelSubscription(request: globalThis.Request, body: {
  * Next.js-specific wrapper for plans helper.
  * This is a public route - no authentication required.
  */
-
 /**
  * List plans - Next.js wrapper
  *
@@ -154,7 +302,7 @@ declare function cancelSubscription(request: globalThis.Request, body: {
  * @returns Plans response or NextResponse error
  */
 declare function listPlans(request: globalThis.Request): Promise<{
-    plans: any[];
+    plans: Array<Record<string, unknown>>;
     agentRef: string;
 } | NextResponse>;
 
@@ -340,49 +488,17 @@ declare function createSupabaseAuthMiddleware(options?: SupabaseAuthMiddlewareOp
  * like request deduplication and caching.
  */
 
-/**
- * Request deduplication and caching options
- */
-interface RequestDeduplicationOptions {
-    /**
-     * Time-to-live for cached results in milliseconds (default: 2000)
-     * Set to 0 to disable caching (only deduplicate concurrent requests)
-     */
-    cacheTTL?: number;
-    /**
-     * Maximum cache size before cleanup (default: 1000)
-     * When exceeded, oldest entries are removed
-     */
-    maxCacheSize?: number;
-    /**
-     * Whether to cache error results (default: true)
-     * When false, only successful results are cached
-     */
-    cacheErrors?: boolean;
-}
-/**
- * Subscription check result
- */
-interface SubscriptionCheckResult {
-    customerRef: string;
-    email?: string;
-    name?: string;
-    subscriptions: Array<{
-        reference: string;
-        planName?: string;
-        agentName?: string;
-        status?: string;
-        startDate?: string;
-        [key: string]: unknown;
-    }>;
-}
 /**
  * Options for checking subscriptions
  */
 interface CheckSubscriptionOptions {
     /**
      * Request deduplication options
-     * Default: { cacheTTL: 2000, maxCacheSize: 1000, cacheErrors: true }
+     *
+     * Default values:
+     * - `cacheTTL`: 2000ms
+     * - `maxCacheSize`: 1000
+     * - `cacheErrors`: true
      */
     deduplication?: RequestDeduplicationOptions;
     /**
@@ -402,59 +518,49 @@ interface CheckSubscriptionOptions {
     includeName?: boolean;
 }
 /**
- * Check user subscription status
+ * Check user subscription status with automatic deduplication and caching.
  *
- * This helper function:
+ * This Next.js helper function provides optimized subscription checking with:
+ * - Automatic request deduplication (concurrent requests share the same promise)
+ * - Short-term caching (2 seconds) to prevent duplicate sequential requests
+ * - Fast path optimization using cached customer references from client
+ * - Automatic customer creation if needed
+ *
+ * The function:
  * 1. Extracts user ID from request (via requireUserId from @solvapay/auth)
- * 2. Gets user email and name from Supabase JWT token
- * 3. Ensures customer exists in SolvaPay
- * 4. Returns customer subscription information
- * 5. Handles deduplication automatically
+ * 2. Gets user email and name from Supabase JWT token (if available)
+ * 3. Validates cached customer reference (if provided via header)
+ * 4. Ensures customer exists in SolvaPay backend
+ * 5. Returns customer subscription information
  *
- * @param request - Next.js request object (NextRequest extends Request, so Request is accepted)
+ * @param request - Next.js request object (NextRequest extends Request)
  * @param options - Configuration options
- * @returns Subscription check result or error response
+ * @param options.deduplication - Request deduplication options (see {@link RequestDeduplicationOptions})
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @param options.includeEmail - Whether to include email in response (default: true)
+ * @param options.includeName - Whether to include name in response (default: true)
+ * @returns Subscription check result with customer data and subscriptions, or NextResponse error
  *
  * @example
  * ```typescript
- * import { NextRequest } from 'next/server';
+ * import { NextRequest, NextResponse } from 'next/server';
  * import { checkSubscription } from '@solvapay/next';
  *
  * export async function GET(request: NextRequest) {
  *   const result = await checkSubscription(request);
+ *
  *   if (result instanceof NextResponse) {
  *     return result; // Error response
  *   }
+ *
  *   return NextResponse.json(result);
  * }
  * ```
- */
-declare function checkSubscription(request: Request, options?: CheckSubscriptionOptions): Promise<SubscriptionCheckResult | NextResponse>;
-/**
- * Clear subscription cache for a specific user
- *
- * Useful when you know subscription status has changed
- * (e.g., after a successful checkout or subscription update)
- *
- * @param userId - User ID to clear cache for
- */
-declare function clearSubscriptionCache(userId: string): void;
-/**
- * Clear all subscription cache entries
- *
- * Useful for testing or when you need to force fresh lookups
- */
-declare function clearAllSubscriptionCache(): void;
-/**
- * Get subscription cache statistics
  *
- * Useful for monitoring and debugging
- *
- * @returns Cache statistics
+ * @see {@link clearSubscriptionCache} for cache management
+ * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @since 1.0.0
  */
-declare function getSubscriptionCacheStats(): {
-    inFlight: number;
-    cached: number;
-};
+declare function checkSubscription(request: Request, options?: CheckSubscriptionOptions): Promise<SubscriptionCheckResult | NextResponse>;
 
 export { type AuthMiddlewareOptions, type CheckSubscriptionOptions, type RequestDeduplicationOptions, type SubscriptionCheckResult, type SupabaseAuthMiddlewareOptions, cancelSubscription, checkSubscription, clearAllSubscriptionCache, clearSubscriptionCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getSubscriptionCacheStats, listPlans, processPayment, syncCustomer };