@solvapay/next 1.0.0-preview.8 → 1.0.1-preview.1

package/dist/index.d.cts

@@ -1,14 +1,14 @@
-import { NextResponse } from 'next/server';
-import { SolvaPay } from '@solvapay/server';
+import { NextResponse, NextRequest } from 'next/server';
+import * as _solvapay_server from '@solvapay/server';
+import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
+import { AuthAdapter } from '@solvapay/auth';
 
 /**
- * SolvaPay Next.js SDK
+ * Purchase Cache Utilities
  *
- * Framework-specific helpers and utilities for Next.js API routes.
- * These utilities provide common patterns with built-in optimizations
- * like request deduplication and caching.
+ * Cache management functions for purchase data.
+ * Separated from index.ts to avoid circular dependencies.
  */
-
 /**
  * Request deduplication and caching options
  */
@@ -30,28 +30,443 @@ interface RequestDeduplicationOptions {
     cacheErrors?: boolean;
 }
 /**
- * Subscription check result
+ * Purchase check result
  */
-interface SubscriptionCheckResult {
+interface PurchaseCheckResult {
     customerRef: string;
     email?: string;
     name?: string;
-    subscriptions: Array<{
+    purchases: Array<{
         reference: string;
-        planName?: string;
-        agentName?: string;
+        productName?: string;
+        productReference?: string;
         status?: string;
         startDate?: string;
+        planSnapshot?: {
+            meterId?: string;
+            limit?: number;
+            freeUnits?: number;
+        };
+        usage?: {
+            used?: number;
+            overageUnits?: number;
+            overageCost?: number;
+            periodStart?: string;
+            periodEnd?: string;
+        };
         [key: string]: unknown;
     }>;
 }
 /**
- * Options for checking subscriptions
+ * Clear purchase cache for a specific user.
+ *
+ * Useful when you know purchase status has changed (e.g., after a successful
+ * checkout, purchase update, or cancellation). This forces the next
+ * `checkPurchase()` call to fetch fresh data from the backend.
+ *
+ * @param userId - User ID to clear cache for
+ *
+ * @example
+ * ```typescript
+ * import { clearPurchaseCache } from '@solvapay/next';
+ *
+ * // After successful payment
+ * await processPayment(request, body);
+ * clearPurchaseCache(userId); // Force refresh on next check
+ * ```
+ *
+ * @see {@link checkPurchase} for purchase checking
+ * @see {@link clearAllPurchaseCache} to clear all cache entries
+ * @since 1.0.0
+ */
+declare function clearPurchaseCache(userId: string): void;
+/**
+ * Clear all purchase 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 { clearAllPurchaseCache } from '@solvapay/next';
+ *
+ * // In a test setup
+ * beforeEach(() => {
+ *   clearAllPurchaseCache();
+ * });
+ * ```
+ *
+ * @see {@link clearPurchaseCache} to clear cache for a specific user
+ * @see {@link getPurchaseCacheStats} for cache monitoring
+ * @since 1.0.0
+ */
+declare function clearAllPurchaseCache(): void;
+/**
+ * Get purchase cache statistics for monitoring and debugging.
+ *
+ * Returns the current state of the purchase 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 { getPurchaseCacheStats } from '@solvapay/next';
+ *
+ * // In a monitoring endpoint
+ * export async function GET() {
+ *   const stats = getPurchaseCacheStats();
+ *   return Response.json({
+ *     cache: {
+ *       inFlight: stats.inFlight,
+ *       cached: stats.cached
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link checkPurchase} for purchase checking
+ * @since 1.0.0
+ */
+declare function getPurchaseCacheStats(): {
+    inFlight: number;
+    cached: number;
+};
+
+/**
+ * Next.js Authentication Helpers
+ *
+ * Next.js-specific wrappers for authentication helpers.
+ */
+
+/**
+ * Get authenticated user information from a Next.js request.
+ *
+ * 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;
+    includeName?: boolean;
+}): Promise<AuthenticatedUser | NextResponse>;
+
+/**
+ * Next.js Customer Helpers
+ *
+ * Next.js-specific wrappers for customer helpers.
+ */
+
+/**
+ * Sync customer - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param options - Configuration options
+ * @returns Customer reference or NextResponse error
+ */
+declare function syncCustomer(request: globalThis.Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<string | NextResponse>;
+
+declare function createPaymentIntent(request: globalThis.Request, body: {
+    planRef: string;
+    productRef: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    id: string;
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef: string;
+} | NextResponse>;
+declare function processPaymentIntent(request: globalThis.Request, body: {
+    paymentIntentId: string;
+    productRef: string;
+    planRef?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<_solvapay_server.ProcessPaymentResult | NextResponse>;
+
+/**
+ * Next.js Checkout Helpers
+ */
+
+declare function createCheckoutSession(request: globalThis.Request, body: {
+    productRef: string;
+    planRef?: string;
+    returnUrl?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+    returnUrl?: string;
+}): Promise<{
+    sessionId: string;
+    checkoutUrl: string;
+} | NextResponse>;
+declare function createCustomerSession(request: globalThis.Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    customerUrl: string;
+} | NextResponse>;
+
+/**
+ * Next.js Purchase Cancellation Helpers
+ */
+/**
+ * Cancel purchase - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param body - Cancellation parameters
+ * @param options - Configuration options
+ * @returns Cancelled purchase response or NextResponse error
+ */
+declare function cancelRenewal(request: globalThis.Request, body: {
+    purchaseRef: string;
+    reason?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<Record<string, unknown> | NextResponse>;
+
+/**
+ * Next.js Plans Helper
+ */
+declare function listPlans(request: globalThis.Request): Promise<{
+    plans: Array<Record<string, unknown>>;
+    productRef: string;
+} | NextResponse>;
+
+/**
+ * Next.js Middleware Helpers
+ *
+ * Helpers for creating authentication middleware in Next.js.
+ * Works with any AuthAdapter implementation (Supabase, custom, etc.)
+ */
+
+/**
+ * Configuration options for authentication middleware
+ */
+interface AuthMiddlewareOptions {
+    /**
+     * Auth adapter instance to use for extracting user IDs from requests
+     * You can use SupabaseAuthAdapter, MockAuthAdapter, or create your own
+     */
+    adapter: AuthAdapter;
+    /**
+     * Public routes that don't require authentication
+     * Routes are matched using pathname.startsWith()
+     */
+    publicRoutes?: string[];
+    /**
+     * Header name to store the user ID (default: 'x-user-id')
+     */
+    userIdHeader?: string;
+}
+/**
+ * Creates a Next.js middleware function for authentication
+ *
+ * This helper:
+ * 1. Uses the provided AuthAdapter to extract userId from requests
+ * 2. Handles public vs protected routes
+ * 3. Adds userId to request headers for downstream routes
+ * 4. Returns appropriate error responses for auth failures
+ *
+ * @param options - Configuration options
+ * @returns Next.js middleware function (can be exported as `middleware` or `proxy`)
+ *
+ * @example Next.js 15
+ * ```typescript
+ * // middleware.ts (at project root)
+ * import { createAuthMiddleware } from '@solvapay/next';
+ * import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+ *
+ * const adapter = new SupabaseAuthAdapter({
+ *   jwtSecret: process.env.SUPABASE_JWT_SECRET!,
+ * });
+ *
+ * export const middleware = createAuthMiddleware({
+ *   adapter,
+ *   publicRoutes: ['/api/list-plans'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/api/:path*'],
+ * };
+ * ```
+ *
+ * @example Next.js 16 with src/ folder
+ * ```typescript
+ * // src/proxy.ts (in src/ folder, not project root)
+ * import { createAuthMiddleware } from '@solvapay/next';
+ * import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+ *
+ * const adapter = new SupabaseAuthAdapter({
+ *   jwtSecret: process.env.SUPABASE_JWT_SECRET!,
+ * });
+ *
+ * // Use 'proxy' export for Next.js 16 (no deprecation warning)
+ * export const proxy = createAuthMiddleware({
+ *   adapter,
+ *   publicRoutes: ['/api/list-plans'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/api/:path*'],
+ * };
+ * ```
+ *
+ * @example Custom adapter
+ * ```typescript
+ * import { createAuthMiddleware } from '@solvapay/next';
+ * import type { AuthAdapter } from '@solvapay/auth';
+ *
+ * const myAdapter: AuthAdapter = {
+ *   async getUserIdFromRequest(req) {
+ *     // Your custom auth logic
+ *     return userId;
+ *   },
+ * };
+ *
+ * export const middleware = createAuthMiddleware({
+ *   adapter: myAdapter,
+ * });
+ * ```
+ *
+ * **File Location Notes:**
+ * - **Next.js 15**: Place `middleware.ts` at project root
+ * - **Next.js 16 without `src/` folder**: Place `middleware.ts` or `proxy.ts` at project root
+ * - **Next.js 16 with `src/` folder**: Place `src/proxy.ts` or `src/middleware.ts` (in `src/` folder, not root)
+ *
+ * **Note:** Next.js 16 renamed "middleware" to "proxy". You can export the return value as either
+ * `middleware` or `proxy` - both work, but `proxy` is recommended to avoid deprecation warnings.
+ */
+declare function createAuthMiddleware(options: AuthMiddlewareOptions): (request: NextRequest) => Promise<NextResponse<unknown>>;
+/**
+ * Configuration options for Supabase authentication middleware
+ */
+interface SupabaseAuthMiddlewareOptions {
+    /**
+     * Supabase JWT secret (from Supabase dashboard: Settings → API → JWT Secret)
+     * If not provided, will use SUPABASE_JWT_SECRET environment variable
+     */
+    jwtSecret?: string;
+    /**
+     * Public routes that don't require authentication
+     * Routes are matched using pathname.startsWith()
+     */
+    publicRoutes?: string[];
+    /**
+     * Header name to store the user ID (default: 'x-user-id')
+     */
+    userIdHeader?: string;
+}
+/**
+ * Creates a Next.js middleware function for Supabase authentication
+ *
+ * Convenience function that creates a SupabaseAuthAdapter and wraps it with createAuthMiddleware.
+ * Only use this if you're using Supabase - otherwise use createAuthMiddleware with your own adapter.
+ *
+ * Uses dynamic import to avoid requiring Supabase as a dependency in @solvapay/next.
+ *
+ * @param options - Configuration options
+ * @returns Next.js middleware function (can be exported as `middleware` or `proxy`)
+ *
+ * @example Next.js 15
+ * ```typescript
+ * // middleware.ts (at project root)
+ * import { createSupabaseAuthMiddleware } from '@solvapay/next';
+ *
+ * export const middleware = createSupabaseAuthMiddleware({
+ *   publicRoutes: ['/api/list-plans'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/api/:path*'],
+ * };
+ * ```
+ *
+ * @example Next.js 16 with src/ folder
+ * ```typescript
+ * // src/proxy.ts (in src/ folder, not project root)
+ * import { createSupabaseAuthMiddleware } from '@solvapay/next';
+ *
+ * // Use 'proxy' export for Next.js 16 (no deprecation warning)
+ * export const proxy = createSupabaseAuthMiddleware({
+ *   publicRoutes: ['/api/list-plans'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/api/:path*'],
+ * };
+ * ```
+ *
+ * **File Location Notes:**
+ * - **Next.js 15**: Place `middleware.ts` at project root
+ * - **Next.js 16 without `src/` folder**: Place `middleware.ts` or `proxy.ts` at project root
+ * - **Next.js 16 with `src/` folder**: Place `src/proxy.ts` or `src/middleware.ts` (in `src/` folder, not root)
+ *
+ * **Note:** Next.js 16 renamed "middleware" to "proxy". You can export the return value as either
+ * `middleware` or `proxy` - both work, but `proxy` is recommended to avoid deprecation warnings.
+ */
+declare function createSupabaseAuthMiddleware(options?: SupabaseAuthMiddlewareOptions): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+/**
+ * SolvaPay Next.js SDK
+ *
+ * Framework-specific helpers and utilities for Next.js API routes.
+ * These utilities provide common patterns with built-in optimizations
+ * like request deduplication and caching.
+ */
+
+/**
+ * Options for checking purchases
  */
-interface CheckSubscriptionOptions {
+interface CheckPurchaseOptions {
     /**
      * Request deduplication options
-     * Default: { cacheTTL: 2000, maxCacheSize: 1000, cacheErrors: true }
+     *
+     * Default values:
+     * - `cacheTTL`: 2000ms
+     * - `maxCacheSize`: 1000
+     * - `cacheErrors`: true
      */
     deduplication?: RequestDeduplicationOptions;
     /**
@@ -71,59 +486,49 @@ interface CheckSubscriptionOptions {
     includeName?: boolean;
 }
 /**
- * Check user subscription status
+ * Check user purchase status with automatic deduplication and caching.
+ *
+ * This Next.js helper function provides optimized purchase 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
  *
- * This helper function:
+ * 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 purchase 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 Purchase check result with customer data and purchases, or NextResponse error
  *
  * @example
  * ```typescript
- * import { NextRequest } from 'next/server';
- * import { checkSubscription } from '@solvapay/next';
+ * import { NextRequest, NextResponse } from 'next/server';
+ * import { checkPurchase } from '@solvapay/next';
  *
  * export async function GET(request: NextRequest) {
- *   const result = await checkSubscription(request);
+ *   const result = await checkPurchase(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 clearPurchaseCache} for cache management
+ * @see {@link getPurchaseCacheStats} for cache monitoring
+ * @since 1.0.0
  */
-declare function getSubscriptionCacheStats(): {
-    inFlight: number;
-    cached: number;
-};
+declare function checkPurchase(request: Request, options?: CheckPurchaseOptions): Promise<PurchaseCheckResult | NextResponse>;
 
-export { type CheckSubscriptionOptions, type RequestDeduplicationOptions, type SubscriptionCheckResult, checkSubscription, clearAllSubscriptionCache, clearSubscriptionCache, getSubscriptionCacheStats };
+export { type AuthMiddlewareOptions, type CheckPurchaseOptions, type PurchaseCheckResult, type RequestDeduplicationOptions, type SupabaseAuthMiddlewareOptions, cancelRenewal, checkPurchase, clearAllPurchaseCache, clearPurchaseCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getPurchaseCacheStats, listPlans, processPaymentIntent, syncCustomer };