@spfn/core 0.1.0-alpha.86 → 0.2.0-beta.1

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

@@ -1,9 +1,221 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { Router } from '@spfn/core/route';
+import { InterceptorRule as InterceptorRule$1 } from '@spfn/core/nextjs/server';
+import { S as SetCookie } from '../types-DRG2XMTR.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
+ * ```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 });
+ * ```
+ */
+
+interface RpcProxyConfig<TRouter extends Router<any>> extends Omit<TypedProxyConfig, 'onRequest' | 'onResponse'> {
+    /**
+     * The router containing all route definitions
+     *
+     * Package routes registered via `.packages()` are automatically recognized.
+     *
+     * @example
+     * ```typescript
+     * // router.ts
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getHealth,
+     * })
+     * .packages([authRouter, cmsAppRouter]);
+     *
+     * // api/rpc/[routeName]/route.ts
+     * export const { GET, POST } = createRpcProxy({
+     *     router: appRouter,
+     * });
+     * ```
+     */
+    router: 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,
+ * 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
  *
@@ -85,18 +297,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 +349,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 +394,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;
 /**
- * Create proxy with custom configuration and interceptors
+ * Check if method matches pattern
  *
- * @param config - Proxy configuration with interceptors
- * @returns HTTP method handlers for Next.js API routes
+ * @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
  *
- * @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();
- *       }
- *     }
- *   ]
- * });
- * ```
+ * @param rules - All interceptor rules
+ * @param path - Request path
+ * @param method - Request method
+ * @returns Matched interceptors
  */
-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 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>;
 
 /**
  * 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 +544,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 +561,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 +580,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 ProxyRequestInterceptor, type ProxyResponseInterceptor, type RequestInterceptor, type RequestInterceptorContext, type RequestInterceptorResult, type ResponseInterceptor, type ResponseInterceptorContext, type ResponseInterceptorResult, type RpcProxyConfig, type TypedProxyConfig, createRpcProxy, executeRequestInterceptors, executeResponseInterceptors, filterMatchingInterceptors, interceptorRegistry, matchMethod, matchPath, registerInterceptors };