@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.10

package/dist/{client/nextjs/index.d.ts → nextjs/server.d.ts}

@@ -1,9 +1,267 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { Router, HttpMethod } from '@spfn/core/route';
+import { InterceptorRule as InterceptorRule$1 } from '@spfn/core/nextjs/server';
+import { f as SetCookie } from '../types-BOPTApC2.js';
+import '@sinclair/typebox';
+import '@spfn/core/errors';
 
 /**
- * SPFN Next.js Proxy Interceptor Types
+ * Request interceptor result
+ */
+interface RequestInterceptorResult {
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Response interceptor result
+ */
+interface ResponseInterceptorResult {
+    response: Response;
+    body: any;
+}
+/**
+ * Request interceptor function
+ */
+type ProxyRequestInterceptor = (req: NextRequest, url: string) => Promise<RequestInterceptorResult> | RequestInterceptorResult;
+/**
+ * Response interceptor function
+ */
+type ProxyResponseInterceptor = (response: Response, body: any) => Promise<ResponseInterceptorResult> | ResponseInterceptorResult;
+/**
+ * Proxy configuration
+ */
+interface TypedProxyConfig {
+    /**
+     * SPFN API base URL
+     *
+     * @default process.env.SPFN_API_URL || 'http://localhost:8790'
+     */
+    apiUrl?: string;
+    /**
+     * Enable debug logging
+     *
+     * @default process.env.NODE_ENV === 'development'
+     */
+    debug?: boolean;
+    /**
+     * Request timeout in milliseconds
+     *
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom headers to add to all forwarded requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Simple request interceptor - modify request before forwarding
+     *
+     * For simple use cases. Use `interceptors` for advanced features like:
+     * - Path/method matching
+     * - Cookie setting
+     * - Multiple interceptors with chaining
+     */
+    onRequest?: ProxyRequestInterceptor;
+    /**
+     * Simple response interceptor - modify response before returning
+     *
+     * For simple use cases. Use `interceptors` for advanced features.
+     */
+    onResponse?: ProxyResponseInterceptor;
+    /**
+     * Advanced interceptors with path matching, cookie support, and chaining
+     *
+     * @example
+     * ```typescript
+     * interceptors: [{
+     *   pathPattern: '/_auth/*',
+     *   method: 'POST',
+     *   request: async (ctx, next) => {
+     *     ctx.headers['Authorization'] = 'Bearer token';
+     *     await next();
+     *   },
+     *   response: async (ctx, next) => {
+     *     ctx.setCookies.push({
+     *       name: 'session',
+     *       value: 'xxx',
+     *       options: { httpOnly: true, maxAge: 3600 }
+     *     });
+     *     await next();
+     *   }
+     * }]
+     * ```
+     */
+    interceptors?: InterceptorRule$1[];
+    /**
+     * Enable automatic interceptor discovery from registry
+     *
+     * When enabled, interceptors registered via registerInterceptors()
+     * are automatically applied.
+     *
+     * @default true
+     */
+    autoDiscoverInterceptors?: boolean;
+    /**
+     * Disable interceptors from specific packages
+     *
+     * @example ['auth', 'storage']
+     */
+    disableAutoInterceptors?: string[];
+}
+
+/**
+ * RPC-Style Proxy for define-route System
+ *
+ * Next.js API Route handler that resolves routeName to method/path
+ * and forwards requests to SPFN backend.
+ *
+ * @example Using routeMap (recommended - no server code loaded)
+ * ```typescript
+ * // app/api/rpc/[routeName]/route.ts
+ * import { routeMap } from '@/generated/route-map';
+ * import { createRpcProxy } from '@spfn/core/nextjs/proxy';
+ *
+ * export const { GET, POST } = createRpcProxy({ routeMap });
+ * ```
+ *
+ * @example Using router (legacy - loads full server code)
+ * ```typescript
+ * // app/api/rpc/[routeName]/route.ts
+ * import { appRouter } from '@/server/router';
+ * import { createRpcProxy } from '@spfn/core/nextjs/proxy';
+ *
+ * export const { GET, POST } = createRpcProxy({ router: appRouter });
+ * ```
  */
 
+/**
+ * Route info from generated route map
+ */
+interface RouteMapEntry {
+    method: HttpMethod;
+    path: string;
+}
+/**
+ * Generated route map type
+ */
+type RouteMap = Record<string, RouteMapEntry>;
+/**
+ * Base config for RPC proxy
+ */
+interface RpcProxyBaseConfig extends Omit<TypedProxyConfig, 'onRequest' | 'onResponse'> {
+}
+/**
+ * Config using routeMap (recommended)
+ *
+ * Uses generated route map file - no server code loaded in Next.js process.
+ */
+interface RpcProxyRouteMapConfig extends RpcProxyBaseConfig {
+    /**
+     * Generated route map containing routeName → {method, path} mappings
+     *
+     * @example
+     * ```typescript
+     * import { routeMap } from '@/generated/route-map';
+     *
+     * export const { GET, POST } = createRpcProxy({ routeMap });
+     * ```
+     */
+    routeMap: RouteMap;
+    router?: never;
+}
+/**
+ * Config using router (legacy)
+ *
+ * @deprecated Use routeMap instead to avoid loading server code in Next.js process
+ */
+interface RpcProxyRouterConfig<TRouter extends Router<any>> extends RpcProxyBaseConfig {
+    /**
+     * The router containing all route definitions
+     *
+     * @deprecated Use routeMap instead - router imports all server code
+     *
+     * @example
+     * ```typescript
+     * export const { GET, POST } = createRpcProxy({
+     *     router: appRouter,
+     * });
+     * ```
+     */
+    router: TRouter;
+    routeMap?: never;
+}
+/**
+ * Combined config type
+ */
+type RpcProxyConfig<TRouter extends Router<any> = Router<any>> = RpcProxyRouteMapConfig | RpcProxyRouterConfig<TRouter>;
+/**
+ * Create RPC proxy handler for Next.js API Route
+ *
+ * Handles requests in the format:
+ * - GET /api/rpc/{routeName}?input={...}
+ * - POST /api/rpc/{routeName} with body
+ *
+ * Resolves routeName to actual HTTP method and path from the router or routeMap,
+ * then forwards to SPFN backend.
+ */
+declare function createRpcProxy<TRouter extends Router<any>>(config: RpcProxyConfig<TRouter>): {
+    GET: (req: NextRequest, context: {
+        params: Promise<{
+            routeName?: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    POST: (req: NextRequest, context: {
+        params: Promise<{
+            routeName?: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+};
+
+/**
+ * Interceptor Rule
+ *
+ * Defines when and how to intercept requests/responses
+ */
+interface InterceptorRule {
+    /**
+     * Path pattern to match
+     *
+     * - String with wildcards: '/_auth/*', '/users/:id'
+     * - RegExp: /^\/_auth\/.+$/
+     * - '*' matches all paths
+     *
+     * @example
+     * ```typescript
+     * pathPattern: '/_auth/*'      // matches /_auth/login, /_auth/register
+     * pathPattern: '/users/:id'    // matches /users/123, /users/456
+     * pathPattern: /^\/_auth\/.+$/ // regex match
+     * pathPattern: '*'             // matches all paths
+     * ```
+     */
+    pathPattern: string | RegExp;
+    /**
+     * HTTP method(s) to match (optional)
+     *
+     * - Single method: 'POST'
+     * - Multiple methods: ['POST', 'PUT']
+     * - Omit to match all methods
+     *
+     * @default undefined (matches all methods)
+     */
+    method?: string | string[];
+    /**
+     * Request interceptor
+     *
+     * Called before SPFN API request
+     */
+    request?: RequestInterceptor;
+    /**
+     * Response interceptor
+     *
+     * Called after SPFN API response
+     */
+    response?: ResponseInterceptor;
+}
 /**
  * Request Interceptor Context
  *
@@ -68,6 +326,7 @@ interface ResponseInterceptorContext {
      * Response data (mutable)
      */
     response: {
+        ok: boolean;
         status: number;
         statusText: string;
         headers: Headers;
@@ -85,18 +344,7 @@ interface ResponseInterceptorContext {
      * });
      * ```
      */
-    setCookies: Array<{
-        name: string;
-        value: string;
-        options?: {
-            httpOnly?: boolean;
-            secure?: boolean;
-            sameSite?: 'strict' | 'lax' | 'none';
-            maxAge?: number;
-            path?: string;
-            domain?: string;
-        };
-    }>;
+    setCookies: SetCookie[];
     /**
      * Metadata shared from request interceptors
      */
@@ -148,51 +396,6 @@ type RequestInterceptor = (context: RequestInterceptorContext, next: () => Promi
  * ```
  */
 type ResponseInterceptor = (context: ResponseInterceptorContext, next: () => Promise<void>) => Promise<void>;
-/**
- * Interceptor Rule
- *
- * Defines when and how to intercept requests/responses
- */
-interface InterceptorRule {
-    /**
-     * Path pattern to match
-     *
-     * - String with wildcards: '/_auth/*', '/users/:id'
-     * - RegExp: /^\/_auth\/.+$/
-     * - '*' matches all paths
-     *
-     * @example
-     * ```typescript
-     * pathPattern: '/_auth/*'      // matches /_auth/login, /_auth/register
-     * pathPattern: '/users/:id'    // matches /users/123, /users/456
-     * pathPattern: /^\/_auth\/.+$/ // regex match
-     * pathPattern: '*'             // matches all paths
-     * ```
-     */
-    pathPattern: string | RegExp;
-    /**
-     * HTTP method(s) to match (optional)
-     *
-     * - Single method: 'POST'
-     * - Multiple methods: ['POST', 'PUT']
-     * - Omit to match all methods
-     *
-     * @default undefined (matches all methods)
-     */
-    method?: string | string[];
-    /**
-     * Request interceptor
-     *
-     * Called before SPFN API request
-     */
-    request?: RequestInterceptor;
-    /**
-     * Response interceptor
-     *
-     * Called after SPFN API response
-     */
-    response?: ResponseInterceptor;
-}
 /**
  * Proxy Configuration
  */
@@ -238,156 +441,90 @@ interface ProxyConfig {
 }
 
 /**
- * SPFN Next.js API Route Proxy with Interceptor Pattern
+ * SPFN Next.js Proxy Interceptor Execution Engine
+ */
+
+/**
+ * Check if path matches pattern
  *
- * Automatically proxies requests to SPFN API server with:
- * - Cookie forwarding
- * - Request/Response interceptors
- * - Flexible header manipulation
+ * Supports:
+ * - Wildcards: '/_auth/*' matches '/_auth/login'
+ * - Path params: '/users/:id' matches '/users/123'
+ * - RegExp: /^\/_auth\/.+$/ matches '/_auth/login'
+ * - Exact match: '/_auth/login' matches '/_auth/login'
+ * - All: '*' matches any path
  *
- * Usage:
- * ```typescript
- * // Basic usage (no interceptors)
- * // app/api/actions/[...path]/route.ts
- * export { GET, POST, PUT, DELETE, PATCH } from '@spfn/core/nextjs';
- *
- * // With interceptors
- * import { createProxy } from '@spfn/core/nextjs';
- *
- * export const { GET, POST } = createProxy({
- *   interceptors: [
- *     {
- *       pathPattern: '/_auth/*',
- *       request: async (ctx, next) => {
- *         ctx.headers['Authorization'] = 'Bearer token';
- *         await next();
- *       }
- *     }
- *   ]
- * });
- * ```
+ * @param path - Request path to test
+ * @param pattern - Pattern to match against
+ * @returns True if path matches pattern
  */
-
+declare function matchPath(path: string, pattern: string | RegExp): boolean;
+/**
+ * Check if method matches pattern
+ *
+ * @param method - Request method (e.g., 'POST')
+ * @param pattern - Method pattern (e.g., 'POST' or ['POST', 'PUT'])
+ * @returns True if method matches pattern
+ */
+declare function matchMethod(method: string, pattern?: string | string[]): boolean;
+/**
+ * Filter interceptors that match the request
+ *
+ * @param rules - All interceptor rules
+ * @param path - Request path
+ * @param method - Request method
+ * @returns Matched interceptors
+ */
+declare function filterMatchingInterceptors(rules: InterceptorRule[], path: string, method: string): InterceptorRule[];
 /**
- * Create proxy with custom configuration and interceptors
+ * Execute request interceptors in chain
  *
- * @param config - Proxy configuration with interceptors
- * @returns HTTP method handlers for Next.js API routes
+ * Interceptors are executed in order:
+ * 1. First registered interceptor
+ * 2. Second registered interceptor
+ * 3. ... and so on
  *
- * @example
- * ```typescript
- * // app/api/actions/[...path]/route.ts
- * import { createProxy } from '@spfn/core/nextjs';
- *
- * export const { GET, POST, PUT, DELETE, PATCH } = createProxy({
- *   apiUrl: 'http://localhost:8790',
- *   debug: true,
- *   interceptors: [
- *     {
- *       pathPattern: '/_auth/*',
- *       method: 'POST',
- *       request: async (ctx, next) => {
- *         const session = await getSession();
- *         if (session) {
- *           ctx.headers['Authorization'] = `Bearer ${session.token}`;
- *         }
- *         await next();
- *       },
- *       response: async (ctx, next) => {
- *         if (ctx.response.status === 200) {
- *           ctx.setCookies.push({
- *             name: 'session',
- *             value: ctx.response.body.token,
- *             options: { httpOnly: true, maxAge: 3600 }
- *           });
- *         }
- *         await next();
- *       }
- *     }
- *   ]
- * });
- * ```
+ * Each interceptor must call next() to continue the chain.
+ * If next() is not called, the chain stops and remaining interceptors are skipped.
+ *
+ * @param context - Request interceptor context
+ * @param interceptors - Interceptors to execute
  */
-declare function createProxy(config?: ProxyConfig): {
-    GET: (request: NextRequest, context: {
-        params: Promise<{
-            path: string[];
-        }> | {
-            path: string[];
-        };
-    }) => Promise<NextResponse<unknown>>;
-    POST: (request: NextRequest, context: {
-        params: Promise<{
-            path: string[];
-        }> | {
-            path: string[];
-        };
-    }) => Promise<NextResponse<unknown>>;
-    PUT: (request: NextRequest, context: {
-        params: Promise<{
-            path: string[];
-        }> | {
-            path: string[];
-        };
-    }) => Promise<NextResponse<unknown>>;
-    PATCH: (request: NextRequest, context: {
-        params: Promise<{
-            path: string[];
-        }> | {
-            path: string[];
-        };
-    }) => Promise<NextResponse<unknown>>;
-    DELETE: (request: NextRequest, context: {
-        params: Promise<{
-            path: string[];
-        }> | {
-            path: string[];
-        };
-    }) => Promise<NextResponse<unknown>>;
-};
-declare const GET: (request: NextRequest, context: {
-    params: Promise<{
-        path: string[];
-    }> | {
-        path: string[];
-    };
-}) => Promise<NextResponse<unknown>>;
-declare const POST: (request: NextRequest, context: {
-    params: Promise<{
-        path: string[];
-    }> | {
-        path: string[];
-    };
-}) => Promise<NextResponse<unknown>>;
-declare const PUT: (request: NextRequest, context: {
-    params: Promise<{
-        path: string[];
-    }> | {
-        path: string[];
-    };
-}) => Promise<NextResponse<unknown>>;
-declare const PATCH: (request: NextRequest, context: {
-    params: Promise<{
-        path: string[];
-    }> | {
-        path: string[];
-    };
-}) => Promise<NextResponse<unknown>>;
-declare const DELETE: (request: NextRequest, context: {
-    params: Promise<{
-        path: string[];
-    }> | {
-        path: string[];
-    };
-}) => Promise<NextResponse<unknown>>;
+declare function executeRequestInterceptors(context: RequestInterceptorContext, interceptors: RequestInterceptor[]): Promise<void>;
+/**
+ * Execute response interceptors in chain
+ *
+ * Interceptors are executed in order:
+ * 1. First registered interceptor
+ * 2. Second registered interceptor
+ * 3. ... and so on
+ *
+ * Each interceptor must call next() to continue the chain.
+ * If next() is not called, the chain stops and remaining interceptors are skipped.
+ *
+ * @param context - Response interceptor context
+ * @param interceptors - Interceptors to execute
+ */
+declare function executeResponseInterceptors(context: ResponseInterceptorContext, interceptors: ResponseInterceptor[]): Promise<void>;
 
 /**
  * Global Interceptor Registry
  *
  * Allows packages to automatically register their interceptors
  * for Next.js proxy without manual configuration.
+ *
+ * Uses globalThis for persistence across module reloads (HMR).
  */
 
+/**
+ * Extend globalThis with interceptor registry
+ *
+ * Using globalThis allows the registry to persist across module reloads (HMR).
+ * preventing duplicate registrations during development with HMR.
+ */
+declare global {
+    var __SPFN_INTERCEPTOR_REGISTRY__: InterceptorRegistry | undefined;
+}
 /**
  * Global interceptor registry
  *
@@ -454,6 +591,9 @@ declare class InterceptorRegistry {
 }
 /**
  * Global singleton registry instance
+ *
+ * Uses globalThis to persist across module reloads (HMR).
+ * This prevents duplicate registrations during development.
  */
 declare const interceptorRegistry: InterceptorRegistry;
 /**
@@ -468,7 +608,7 @@ declare const interceptorRegistry: InterceptorRegistry;
  * @example
  * ```typescript
  * // packages/auth/src/adapters/nextjs/interceptors/index.ts
- * import { registerInterceptors } from '@spfn/core/client/nextjs';
+ * import { registerInterceptors } from '@spfn/core/nextjs';
  *
  * const authInterceptors = [
  *   {
@@ -487,71 +627,4 @@ declare const interceptorRegistry: InterceptorRegistry;
  */
 declare function registerInterceptors(packageName: string, interceptors: InterceptorRule[]): void;
 
-/**
- * SPFN Next.js Proxy Interceptor Execution Engine
- */
-
-/**
- * Check if path matches pattern
- *
- * Supports:
- * - Wildcards: '/_auth/*' matches '/_auth/login'
- * - Path params: '/users/:id' matches '/users/123'
- * - RegExp: /^\/_auth\/.+$/ matches '/_auth/login'
- * - Exact match: '/_auth/login' matches '/_auth/login'
- * - All: '*' matches any path
- *
- * @param path - Request path to test
- * @param pattern - Pattern to match against
- * @returns True if path matches pattern
- */
-declare function matchPath(path: string, pattern: string | RegExp): boolean;
-/**
- * Check if method matches pattern
- *
- * @param method - Request method (e.g., 'POST')
- * @param pattern - Method pattern (e.g., 'POST' or ['POST', 'PUT'])
- * @returns True if method matches pattern
- */
-declare function matchMethod(method: string, pattern?: string | string[]): boolean;
-/**
- * Filter interceptors that match the request
- *
- * @param rules - All interceptor rules
- * @param path - Request path
- * @param method - Request method
- * @returns Matched interceptors
- */
-declare function filterMatchingInterceptors(rules: InterceptorRule[], path: string, method: string): InterceptorRule[];
-/**
- * Execute request interceptors in chain
- *
- * Interceptors are executed in order:
- * 1. First registered interceptor
- * 2. Second registered interceptor
- * 3. ... and so on
- *
- * Each interceptor must call next() to continue the chain.
- * If next() is not called, the chain stops and remaining interceptors are skipped.
- *
- * @param context - Request interceptor context
- * @param interceptors - Interceptors to execute
- */
-declare function executeRequestInterceptors(context: RequestInterceptorContext, interceptors: RequestInterceptor[]): Promise<void>;
-/**
- * Execute response interceptors in chain
- *
- * Interceptors are executed in order:
- * 1. First registered interceptor
- * 2. Second registered interceptor
- * 3. ... and so on
- *
- * Each interceptor must call next() to continue the chain.
- * If next() is not called, the chain stops and remaining interceptors are skipped.
- *
- * @param context - Response interceptor context
- * @param interceptors - Interceptors to execute
- */
-declare function executeResponseInterceptors(context: ResponseInterceptorContext, interceptors: ResponseInterceptor[]): Promise<void>;
-
-export { DELETE, GET, type InterceptorRule, PATCH, POST, PUT, type ProxyConfig, type RequestInterceptor, type RequestInterceptorContext, type ResponseInterceptor, type ResponseInterceptorContext, createProxy, executeRequestInterceptors, executeResponseInterceptors, filterMatchingInterceptors, interceptorRegistry, matchMethod, matchPath, registerInterceptors };
+export { type InterceptorRule, type ProxyConfig, type RequestInterceptor, type RequestInterceptorContext, type ResponseInterceptor, type ResponseInterceptorContext, type RpcProxyConfig, createRpcProxy, executeRequestInterceptors, executeResponseInterceptors, filterMatchingInterceptors, interceptorRegistry, matchMethod, matchPath, registerInterceptors };