@solvapay/next 1.0.0-preview.10

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+import { NextResponse, NextRequest } from 'next/server';
+import * as _solvapay_server from '@solvapay/server';
+import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
+import { AuthAdapter } from '@solvapay/auth';
+
+/**
+ * Next.js Authentication Helpers
+ *
+ * Next.js-specific wrappers for authentication helpers.
+ */
+
+/**
+ * Get authenticated user - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param options - Configuration options
+ * @returns Authenticated user info or NextResponse error
+ */
+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>;
+
+/**
+ * Create payment intent - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param body - Payment intent parameters
+ * @param options - Configuration options
+ * @returns Payment intent response or NextResponse error
+ */
+declare function createPaymentIntent(request: globalThis.Request, body: {
+    planRef: string;
+    agentRef: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    id: string;
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef: string;
+} | NextResponse>;
+/**
+ * Process payment - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param body - Payment processing parameters
+ * @param options - Configuration options
+ * @returns Process payment result or NextResponse error
+ */
+declare function processPayment(request: globalThis.Request, body: {
+    paymentIntentId: string;
+    agentRef: string;
+    planRef?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<_solvapay_server.ProcessPaymentResult | NextResponse>;
+
+/**
+ * Next.js Checkout Helpers
+ *
+ * Next.js-specific wrappers for checkout helpers.
+ */
+
+/**
+ * Create checkout session - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param body - Checkout session parameters
+ * @param options - Configuration options
+ * @returns Checkout session response or NextResponse error
+ */
+declare function createCheckoutSession(request: globalThis.Request, body: {
+    agentRef: string;
+    planRef?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    checkoutUrl: string;
+} | NextResponse>;
+/**
+ * Create customer session - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param options - Configuration options
+ * @returns Customer session response or NextResponse error
+ */
+declare function createCustomerSession(request: globalThis.Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    customerUrl: string;
+} | NextResponse>;
+
+/**
+ * Next.js Subscription Helpers
+ *
+ * Next.js-specific wrappers for subscription helpers.
+ */
+
+/**
+ * Cancel subscription - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @param body - Cancellation parameters
+ * @param options - Configuration options
+ * @returns Cancelled subscription response or NextResponse error
+ */
+declare function cancelSubscription(request: globalThis.Request, body: {
+    subscriptionRef: string;
+    reason?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<any | NextResponse>;
+
+/**
+ * Next.js Plans Helper
+ *
+ * Next.js-specific wrapper for plans helper.
+ * This is a public route - no authentication required.
+ */
+
+/**
+ * List plans - Next.js wrapper
+ *
+ * @param request - Next.js request object
+ * @returns Plans response or NextResponse error
+ */
+declare function listPlans(request: globalThis.Request): Promise<{
+    plans: any[];
+    agentRef: 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
+ *
+ * @example
+ * ```typescript
+ * 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 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,
+ * });
+ * ```
+ */
+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
+ *
+ * @example
+ * ```typescript
+ * import { createSupabaseAuthMiddleware } from '@solvapay/next';
+ *
+ * export const middleware = createSupabaseAuthMiddleware({
+ *   publicRoutes: ['/api/list-plans'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/api/:path*'],
+ * };
+ * ```
+ */
+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.
+ */
+
+/**
+ * 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 }
+     */
+    deduplication?: RequestDeduplicationOptions;
+    /**
+     * Custom SolvaPay instance (optional)
+     * If not provided, a new instance will be created
+     */
+    solvaPay?: SolvaPay;
+    /**
+     * Whether to include user email in customer data
+     * Default: true
+     */
+    includeEmail?: boolean;
+    /**
+     * Whether to include user name in customer data
+     * Default: true
+     */
+    includeName?: boolean;
+}
+/**
+ * Check user subscription status
+ *
+ * This helper 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
+ *
+ * @param request - Next.js request object (NextRequest extends Request, so Request is accepted)
+ * @param options - Configuration options
+ * @returns Subscription check result or error response
+ *
+ * @example
+ * ```typescript
+ * import { NextRequest } 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
+ */
+declare function getSubscriptionCacheStats(): {
+    inFlight: number;
+    cached: number;
+};
+
+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 };