@spfn/core 0.1.0-alpha.1

package/dist/auto-loader-C44TcLmM.d.ts

@@ -0,0 +1,125 @@
+import { Hono } from 'hono';
+
+/**
+ * Extend Hono Context to support skipMiddlewares metadata
+ */
+declare module 'hono' {
+    interface ContextVariableMap {
+        _skipMiddlewares?: string[];
+    }
+}
+/**
+ * AutoRouteLoader: Simplified File-based Routing System
+ *
+ * ## Features
+ * - 📁 Auto-discovery: Scans routes directory and auto-registers
+ * - 🔄 Dynamic routes: [id] → :id, [...slug] → *
+ * - 📊 Statistics: Route registration stats for dashboard
+ * - 🏷️ Grouping: Natural grouping by directory structure
+ *
+ * ## Usage
+ * ```typescript
+ * const app = new Hono();
+ * await loadRoutes(app);
+ * ```
+ */
+type RouteInfo = {
+    /** URL path (e.g., /users/:id) */
+    path: string;
+    /** File path relative to routes dir */
+    file: string;
+    /** Route metadata from export */
+    meta?: {
+        description?: string;
+        tags?: string[];
+        auth?: boolean;
+        [key: string]: unknown;
+    };
+    /** Priority (1=static, 2=dynamic, 3=catch-all) */
+    priority: number;
+};
+type RouteStats = {
+    total: number;
+    byPriority: {
+        static: number;
+        dynamic: number;
+        catchAll: number;
+    };
+    byTag: Record<string, number>;
+    routes: RouteInfo[];
+};
+declare class AutoRouteLoader {
+    private routesDir;
+    private routes;
+    private registeredRoutes;
+    private debug;
+    private readonly middlewares;
+    constructor(routesDir: string, debug?: boolean, middlewares?: Array<{
+        name: string;
+        handler: any;
+    }>);
+    /**
+     * Load all routes from directory
+     */
+    load(app: Hono): Promise<RouteStats>;
+    /**
+     * Get route statistics
+     */
+    getStats(): RouteStats;
+    /**
+     * Recursively scan directory for .ts files
+     */
+    private scanFiles;
+    /**
+     * Check if file is a valid route file
+     */
+    private isValidRouteFile;
+    /**
+     * Load and register a single route
+     * Returns true if successful, false if failed
+     */
+    private loadRoute;
+    /**
+     * Convert file path to URL path
+     *
+     * Examples:
+     * - users/index.ts → /users
+     * - users/[id].ts → /users/:id
+     * - posts/[...slug].ts → /posts/*
+     */
+    private fileToPath;
+    /**
+     * Calculate route priority
+     * 1 = static, 2 = dynamic, 3 = catch-all
+     */
+    private calculatePriority;
+    /**
+     * Normalize path for conflict detection
+     *
+     * Converts dynamic parameter names to generic placeholders:
+     * - /users/:id → /users/:param
+     * - /users/:userId → /users/:param (conflict!)
+     * - /posts/* → /posts/* (unchanged)
+     *
+     * This allows detection of routes with different param names
+     * that would match the same URL patterns.
+     */
+    private normalizePath;
+    /**
+     * Log statistics
+     */
+    private logStats;
+}
+/**
+ * Load routes from default location (src/server/routes)
+ */
+declare function loadRoutes(app: Hono, options?: {
+    routesDir?: string;
+    debug?: boolean;
+    middlewares?: Array<{
+        name: string;
+        handler: any;
+    }>;
+}): Promise<RouteStats>;
+
+export { AutoRouteLoader as A, type RouteInfo as R, type RouteStats as a, loadRoutes as l };

package/dist/bind-pssq1NRT.d.ts

@@ -0,0 +1,34 @@
+import { Context } from 'hono';
+import { R as RouteContract, c as RouteContext } from './types-SlzTr8ZO.js';
+
+/**
+ * Contract-based Route Handler Wrapper
+ *
+ * Binds a contract to a route handler, providing automatic validation
+ * and type-safe context creation.
+ *
+ * ## Features
+ * - ✅ Automatic params/query/body validation using TypeBox
+ * - ✅ Type-safe RouteContext with contract-based inference
+ * - ✅ Clean separation: bind() for validation, Hono for middleware
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Basic usage
+ * export const GET = bind(contract, async (c) => {
+ *     return c.json({ data: 'public' });
+ * });
+ *
+ * // For middleware, use Hono's app-level or route-level middleware:
+ * // app.use('/api/*', authMiddleware);
+ * // app.get('/users/:id', authMiddleware, bind(contract, handler));
+ * ```
+ *
+ * @param contract - Route contract defining params, query, body, response schemas
+ * @param handler - Route handler function
+ * @returns Hono-compatible handler function
+ */
+declare function bind<TContract extends RouteContract>(contract: TContract, handler: (c: RouteContext<TContract>) => Response | Promise<Response>): (rawContext: Context) => Promise<Response>;
+
+export { bind as b };

package/dist/client/index.d.ts

@@ -0,0 +1,174 @@
+import '../auto-loader-C44TcLmM.js';
+import { R as RouteContract, I as InferContract } from '../types-SlzTr8ZO.js';
+import 'hono';
+import 'hono/utils/http-status';
+import '@sinclair/typebox';
+
+/**
+ * Contract-Based API Client
+ *
+ * Type-safe HTTP client that works with RouteContract for full end-to-end type safety
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@spfn/core/client';
+ * import { getUserContract } from './contracts';
+ *
+ * const client = createClient({ baseUrl: 'http://localhost:4000' });
+ * const user = await client.call(getUserContract, { params: { id: '123' } });
+ * // ✅ user is fully typed based on contract.response
+ * ```
+ */
+
+/**
+ * Request interceptor function
+ *
+ * Allows modifying request before it's sent
+ */
+type RequestInterceptor = (url: string, init: RequestInit) => Promise<RequestInit> | RequestInit;
+/**
+ * Client configuration
+ */
+interface ClientConfig {
+    /**
+     * API base URL (e.g., http://localhost:4000)
+     * Can be overridden per request
+     */
+    baseUrl?: string;
+    /**
+     * Default headers to include in all requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation (for testing or custom behavior)
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Request options for API calls
+ */
+interface CallOptions<TContract extends RouteContract> {
+    /**
+     * Path parameters (for dynamic routes like /users/:id)
+     */
+    params?: InferContract<TContract>['params'];
+    /**
+     * Query parameters (for URL query strings)
+     */
+    query?: InferContract<TContract>['query'];
+    /**
+     * Request body (for POST, PUT, PATCH)
+     */
+    body?: InferContract<TContract>['body'];
+    /**
+     * Additional headers for this specific request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override base URL for this request
+     */
+    baseUrl?: string;
+}
+/**
+ * API Client Error
+ */
+declare class ApiClientError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    readonly response?: unknown | undefined;
+    constructor(message: string, status: number, statusText: string, url: string, response?: unknown | undefined);
+}
+/**
+ * Contract-based API Client
+ */
+declare class ContractClient {
+    private readonly config;
+    private readonly interceptors;
+    constructor(config?: ClientConfig);
+    /**
+     * Add request interceptor
+     *
+     * Interceptors are executed in the order they are added
+     *
+     * @example
+     * ```ts
+     * client.use(async (url, init) => {
+     *   // Add auth header
+     *   return {
+     *     ...init,
+     *     headers: {
+     *       ...init.headers,
+     *       Authorization: `Bearer ${token}`
+     *     }
+     *   };
+     * });
+     * ```
+     */
+    use(interceptor: RequestInterceptor): void;
+    /**
+     * Make a type-safe API call using a contract
+     *
+     * @example
+     * ```ts
+     * const getUserContract = {
+     *   params: Type.Object({ id: Type.String() }),
+     *   response: Type.Object({ id: Type.Number(), name: Type.String() })
+     * } as const satisfies RouteContract;
+     *
+     * const user = await client.call('/users/:id', getUserContract, {
+     *   params: { id: '123' }
+     * });
+     * // ✅ user.name is typed as string
+     * ```
+     */
+    call<TContract extends RouteContract>(path: string, contract: TContract, options?: CallOptions<TContract>): Promise<InferContract<TContract>['response']>;
+    /**
+     * Create a new client with merged configuration
+     *
+     * Useful for creating clients with specific auth tokens or custom headers
+     *
+     * @example
+     * ```ts
+     * const authClient = client.withConfig({
+     *   headers: { Authorization: `Bearer ${token}` }
+     * });
+     * ```
+     */
+    withConfig(config: Partial<ClientConfig>): ContractClient;
+}
+/**
+ * Create a new contract-based API client
+ *
+ * @example
+ * ```ts
+ * const client = createClient({
+ *   baseUrl: 'http://localhost:4000',
+ *   headers: { 'X-Custom': 'header' }
+ * });
+ *
+ * const user = await client.call('/users/:id', getUserContract, {
+ *   params: { id: '123' }
+ * });
+ * ```
+ */
+declare function createClient(config?: ClientConfig): ContractClient;
+/**
+ * Default client instance
+ *
+ * @example
+ * ```ts
+ * import { client } from '@spfn/core/client';
+ *
+ * const user = await client.call('/users/:id', getUserContract, {
+ *   params: { id: '123' }
+ * });
+ * ```
+ */
+declare const client: ContractClient;
+
+export { ApiClientError, type CallOptions, type ClientConfig, ContractClient, type RequestInterceptor, client, createClient };

package/dist/client/index.js

@@ -0,0 +1,179 @@
+// src/client/contract-client.ts
+var ApiClientError = class extends Error {
+  constructor(message, status, statusText, url, response) {
+    super(message);
+    this.status = status;
+    this.statusText = statusText;
+    this.url = url;
+    this.response = response;
+    this.name = "ApiClientError";
+  }
+};
+function buildUrl(path, params) {
+  if (!params) return path;
+  let url = path;
+  for (const [key, value] of Object.entries(params)) {
+    url = url.replace(`:${key}`, String(value));
+  }
+  return url;
+}
+function buildQuery(query) {
+  if (!query || Object.keys(query).length === 0) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (Array.isArray(value)) {
+      value.forEach((v) => params.append(key, String(v)));
+    } else if (value !== void 0 && value !== null) {
+      params.append(key, String(value));
+    }
+  }
+  const queryString = params.toString();
+  return queryString ? `?${queryString}` : "";
+}
+function getHttpMethod(contract, options) {
+  if ("method" in contract && typeof contract.method === "string") {
+    return contract.method.toUpperCase();
+  }
+  if (options?.body !== void 0) {
+    return "POST";
+  }
+  return "GET";
+}
+var ContractClient = class _ContractClient {
+  config;
+  interceptors = [];
+  constructor(config = {}) {
+    this.config = {
+      baseUrl: config.baseUrl || process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000",
+      headers: config.headers || {},
+      timeout: config.timeout || 3e4,
+      fetch: config.fetch || globalThis.fetch
+    };
+  }
+  /**
+   * Add request interceptor
+   *
+   * Interceptors are executed in the order they are added
+   *
+   * @example
+   * ```ts
+   * client.use(async (url, init) => {
+   *   // Add auth header
+   *   return {
+   *     ...init,
+   *     headers: {
+   *       ...init.headers,
+   *       Authorization: `Bearer ${token}`
+   *     }
+   *   };
+   * });
+   * ```
+   */
+  use(interceptor) {
+    this.interceptors.push(interceptor);
+  }
+  /**
+   * Make a type-safe API call using a contract
+   *
+   * @example
+   * ```ts
+   * const getUserContract = {
+   *   params: Type.Object({ id: Type.String() }),
+   *   response: Type.Object({ id: Type.Number(), name: Type.String() })
+   * } as const satisfies RouteContract;
+   *
+   * const user = await client.call('/users/:id', getUserContract, {
+   *   params: { id: '123' }
+   * });
+   * // ✅ user.name is typed as string
+   * ```
+   */
+  async call(path, contract, options) {
+    const baseUrl = options?.baseUrl || this.config.baseUrl;
+    const urlPath = buildUrl(path, options?.params);
+    const queryString = buildQuery(options?.query);
+    const url = `${baseUrl}${urlPath}${queryString}`;
+    const method = getHttpMethod(contract, options);
+    const headers = {
+      ...this.config.headers,
+      ...options?.headers
+    };
+    if (options?.body !== void 0 && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    let init = {
+      method,
+      headers
+    };
+    if (options?.body !== void 0) {
+      init.body = JSON.stringify(options.body);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    init.signal = controller.signal;
+    for (const interceptor of this.interceptors) {
+      init = await interceptor(url, init);
+    }
+    const response = await this.config.fetch(url, init).catch((error) => {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ApiClientError(
+          `${method} ${urlPath} timed out after ${this.config.timeout}ms`,
+          0,
+          "Timeout",
+          url
+        );
+      }
+      if (error instanceof Error) {
+        throw new ApiClientError(
+          `${method} ${urlPath} network error: ${error.message}`,
+          0,
+          "Network Error",
+          url
+        );
+      }
+      throw error;
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      throw new ApiClientError(
+        `${method} ${urlPath} failed: ${response.status} ${response.statusText}`,
+        response.status,
+        response.statusText,
+        url,
+        errorBody
+      );
+    }
+    const data = await response.json();
+    return data;
+  }
+  /**
+   * Create a new client with merged configuration
+   *
+   * Useful for creating clients with specific auth tokens or custom headers
+   *
+   * @example
+   * ```ts
+   * const authClient = client.withConfig({
+   *   headers: { Authorization: `Bearer ${token}` }
+   * });
+   * ```
+   */
+  withConfig(config) {
+    return new _ContractClient({
+      baseUrl: config.baseUrl || this.config.baseUrl,
+      headers: { ...this.config.headers, ...config.headers },
+      timeout: config.timeout || this.config.timeout,
+      fetch: config.fetch || this.config.fetch
+    });
+  }
+};
+function createClient(config) {
+  return new ContractClient(config);
+}
+var client = createClient();
+
+export { ApiClientError, ContractClient, client, createClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/contract-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Contract-Based API Client\n *\n * Type-safe HTTP client that works with RouteContract for full end-to-end type safety\n *\n * @example\n * ```ts\n * import { createClient } from '@spfn/core/client';\n * import { getUserContract } from './contracts';\n *\n * const client = createClient({ baseUrl: 'http://localhost:4000' });\n * const user = await client.call(getUserContract, { params: { id: '123' } });\n * // ✅ user is fully typed based on contract.response\n * ```\n */\n\nimport type { RouteContract, InferContract } from '../route';\n\n/**\n * Request interceptor function\n *\n * Allows modifying request before it's sent\n */\nexport type RequestInterceptor = (\n    url: string,\n    init: RequestInit\n) => Promise<RequestInit> | RequestInit;\n\n/**\n * Client configuration\n */\nexport interface ClientConfig\n{\n    /**\n     * API base URL (e.g., http://localhost:4000)\n     * Can be overridden per request\n     */\n    baseUrl?: string;\n\n    /**\n     * Default headers to include in all requests\n     */\n    headers?: Record<string, string>;\n\n    /**\n     * Request timeout in milliseconds\n     */\n    timeout?: number;\n\n    /**\n     * Custom fetch implementation (for testing or custom behavior)\n     */\n    fetch?: typeof fetch;\n}\n\n/**\n * Request options for API calls\n */\nexport interface CallOptions<TContract extends RouteContract>\n{\n    /**\n     * Path parameters (for dynamic routes like /users/:id)\n     */\n    params?: InferContract<TContract>['params'];\n\n    /**\n     * Query parameters (for URL query strings)\n     */\n    query?: InferContract<TContract>['query'];\n\n    /**\n     * Request body (for POST, PUT, PATCH)\n     */\n    body?: InferContract<TContract>['body'];\n\n    /**\n     * Additional headers for this specific request\n     */\n    headers?: Record<string, string>;\n\n    /**\n     * Override base URL for this request\n     */\n    baseUrl?: string;\n}\n\n/**\n * API Client Error\n */\nexport class ApiClientError extends Error\n{\n    constructor(\n        message: string,\n        public readonly status: number,\n        public readonly statusText: string,\n        public readonly url: string,\n        public readonly response?: unknown\n    )\n    {\n        super(message);\n        this.name = 'ApiClientError';\n    }\n}\n\n/**\n * Build URL with path parameters replaced\n *\n * @example\n * buildUrl('/users/:id', { id: '123' }) → '/users/123'\n * buildUrl('/posts/:postId/comments/:id', { postId: '1', id: '2' }) → '/posts/1/comments/2'\n */\nfunction buildUrl(path: string, params?: Record<string, string | number>): string\n{\n    if (!params) return path;\n\n    let url = path;\n    for (const [key, value] of Object.entries(params))\n    {\n        url = url.replace(`:${key}`, String(value));\n    }\n\n    return url;\n}\n\n/**\n * Build query string from object\n *\n * @example\n * buildQuery({ page: '1', limit: '10' }) → '?page=1&limit=10'\n */\nfunction buildQuery(query?: Record<string, string | string[] | number | boolean>): string\n{\n    if (!query || Object.keys(query).length === 0) return '';\n\n    const params = new URLSearchParams();\n    for (const [key, value] of Object.entries(query))\n    {\n        if (Array.isArray(value))\n        {\n            value.forEach((v) => params.append(key, String(v)));\n        }\n        else if (value !== undefined && value !== null)\n        {\n            params.append(key, String(value));\n        }\n    }\n\n    const queryString = params.toString();\n    return queryString ? `?${queryString}` : '';\n}\n\n/**\n * Extract HTTP method from contract or infer from request type\n */\nfunction getHttpMethod<TContract extends RouteContract>(\n    contract: TContract,\n    options?: CallOptions<TContract>\n): string\n{\n    // If contract has explicit method, use it\n    if ('method' in contract && typeof contract.method === 'string')\n    {\n        return contract.method.toUpperCase();\n    }\n\n    // Infer from presence of body\n    if (options?.body !== undefined)\n    {\n        return 'POST';\n    }\n\n    // Default to GET\n    return 'GET';\n}\n\n/**\n * Contract-based API Client\n */\nexport class ContractClient\n{\n    private readonly config: Required<ClientConfig>;\n    private readonly interceptors: RequestInterceptor[] = [];\n\n    constructor(config: ClientConfig = {})\n    {\n        this.config = {\n            baseUrl: config.baseUrl || process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000',\n            headers: config.headers || {},\n            timeout: config.timeout || 30000,\n            fetch: config.fetch || globalThis.fetch,\n        };\n    }\n\n    /**\n     * Add request interceptor\n     *\n     * Interceptors are executed in the order they are added\n     *\n     * @example\n     * ```ts\n     * client.use(async (url, init) => {\n     *   // Add auth header\n     *   return {\n     *     ...init,\n     *     headers: {\n     *       ...init.headers,\n     *       Authorization: `Bearer ${token}`\n     *     }\n     *   };\n     * });\n     * ```\n     */\n    use(interceptor: RequestInterceptor): void\n    {\n        this.interceptors.push(interceptor);\n    }\n\n    /**\n     * Make a type-safe API call using a contract\n     *\n     * @example\n     * ```ts\n     * const getUserContract = {\n     *   params: Type.Object({ id: Type.String() }),\n     *   response: Type.Object({ id: Type.Number(), name: Type.String() })\n     * } as const satisfies RouteContract;\n     *\n     * const user = await client.call('/users/:id', getUserContract, {\n     *   params: { id: '123' }\n     * });\n     * // ✅ user.name is typed as string\n     * ```\n     */\n    async call<TContract extends RouteContract>(\n        path: string,\n        contract: TContract,\n        options?: CallOptions<TContract>\n    ): Promise<InferContract<TContract>['response']>\n    {\n        // Build URL\n        const baseUrl = options?.baseUrl || this.config.baseUrl;\n        const urlPath = buildUrl(path, options?.params as Record<string, string | number>);\n        const queryString = buildQuery(options?.query as Record<string, string | string[] | number | boolean>);\n        const url = `${baseUrl}${urlPath}${queryString}`;\n\n        // Determine HTTP method\n        const method = getHttpMethod(contract, options);\n\n        // Build headers\n        const headers: Record<string, string> = {\n            ...this.config.headers,\n            ...options?.headers,\n        };\n\n        // Add Content-Type for requests with body\n        if (options?.body !== undefined && !headers['Content-Type'])\n        {\n            headers['Content-Type'] = 'application/json';\n        }\n\n        // Build request init\n        let init: RequestInit = {\n            method,\n            headers,\n        };\n\n        // Add body for POST/PUT/PATCH\n        if (options?.body !== undefined)\n        {\n            init.body = JSON.stringify(options.body);\n        }\n\n        // Create abort controller for timeout\n        const controller = new AbortController();\n        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);\n        init.signal = controller.signal;\n\n        // Execute interceptors\n        for (const interceptor of this.interceptors)\n        {\n            init = await interceptor(url, init);\n        }\n\n        // Make request\n        const response = await this.config.fetch(url, init).catch((error) =>\n        {\n            clearTimeout(timeoutId);\n\n            // Handle abort (timeout)\n            if (error instanceof Error && error.name === 'AbortError')\n            {\n                throw new ApiClientError(\n                    `${method} ${urlPath} timed out after ${this.config.timeout}ms`,\n                    0,\n                    'Timeout',\n                    url\n                );\n            }\n\n            // Handle network errors\n            if (error instanceof Error)\n            {\n                throw new ApiClientError(\n                    `${method} ${urlPath} network error: ${error.message}`,\n                    0,\n                    'Network Error',\n                    url\n                );\n            }\n\n            // Unknown error\n            throw error;\n        });\n\n        // Clear timeout\n        clearTimeout(timeoutId);\n\n        // Handle non-OK responses\n        if (!response.ok)\n        {\n            const errorBody = await response.json().catch(() => null);\n            throw new ApiClientError(\n                `${method} ${urlPath} failed: ${response.status} ${response.statusText}`,\n                response.status,\n                response.statusText,\n                url,\n                errorBody\n            );\n        }\n\n        // Parse and return response\n        const data = await response.json();\n        return data as InferContract<TContract>['response'];\n    }\n\n    /**\n     * Create a new client with merged configuration\n     *\n     * Useful for creating clients with specific auth tokens or custom headers\n     *\n     * @example\n     * ```ts\n     * const authClient = client.withConfig({\n     *   headers: { Authorization: `Bearer ${token}` }\n     * });\n     * ```\n     */\n    withConfig(config: Partial<ClientConfig>): ContractClient\n    {\n        return new ContractClient({\n            baseUrl: config.baseUrl || this.config.baseUrl,\n            headers: { ...this.config.headers, ...config.headers },\n            timeout: config.timeout || this.config.timeout,\n            fetch: config.fetch || this.config.fetch,\n        });\n    }\n}\n\n/**\n * Create a new contract-based API client\n *\n * @example\n * ```ts\n * const client = createClient({\n *   baseUrl: 'http://localhost:4000',\n *   headers: { 'X-Custom': 'header' }\n * });\n *\n * const user = await client.call('/users/:id', getUserContract, {\n *   params: { id: '123' }\n * });\n * ```\n */\nexport function createClient(config?: ClientConfig): ContractClient\n{\n    return new ContractClient(config);\n}\n\n/**\n * Default client instance\n *\n * @example\n * ```ts\n * import { client } from '@spfn/core/client';\n *\n * const user = await client.call('/users/:id', getUserContract, {\n *   params: { id: '123' }\n * });\n * ```\n */\nexport const client = createClient();"]}

package/dist/codegen/index.d.ts

@@ -0,0 +1,126 @@
+import { d as HttpMethod } from '../types-SlzTr8ZO.js';
+import 'hono';
+import 'hono/utils/http-status';
+import '@sinclair/typebox';
+
+/**
+ * Code Generation Types
+ *
+ * Types for contract detection and client code generation
+ */
+
+/**
+ * Route-Contract mapping extracted from contract files
+ */
+interface RouteContractMapping {
+    /** HTTP method (GET, POST, etc.) */
+    method: HttpMethod;
+    /** URL path (e.g., /users/:id) */
+    path: string;
+    /** Contract variable name (e.g., getUserContract) */
+    contractName: string;
+    /** Import path for the contract (e.g., @/contracts/users) */
+    contractImportPath: string;
+    /** Route file path */
+    routeFile: string;
+    /** Contract source file path (resolved) */
+    contractFile?: string;
+}
+/**
+ * Grouped routes by resource
+ */
+interface ResourceRoutes {
+    [resource: string]: RouteContractMapping[];
+}
+/**
+ * Client generation options
+ */
+interface ClientGenerationOptions {
+    /** Routes directory to scan */
+    routesDir: string;
+    /** Output file path for generated client */
+    outputPath: string;
+    /** Base URL for the API client */
+    baseUrl?: string;
+    /** Include type imports? */
+    includeTypes?: boolean;
+    /** Generate JSDoc comments? */
+    includeJsDoc?: boolean;
+}
+/**
+ * Generation statistics
+ */
+interface GenerationStats {
+    /** Total routes scanned */
+    routesScanned: number;
+    /** Routes with contracts found */
+    contractsFound: number;
+    /** Unique contract files */
+    contractFiles: number;
+    /** Resources generated */
+    resourcesGenerated: number;
+    /** Total methods generated */
+    methodsGenerated: number;
+    /** Generation time in ms */
+    duration: number;
+}
+
+/**
+ * Contract Scanner
+ *
+ * Scans server/contracts directory and extracts exported contracts
+ */
+
+/**
+ * Scan routes directory for contract.ts files and extract contract exports
+ *
+ * @param routesDir - Path to server/routes directory
+ * @returns Array of contract-to-route mappings
+ */
+declare function scanContracts(routesDir: string): Promise<RouteContractMapping[]>;
+
+/**
+ * Route Scanner Utilities
+ *
+ * Helper functions for grouping and organizing route-contract mappings
+ */
+
+/**
+ * Group mappings by resource
+ */
+declare function groupByResource(mappings: RouteContractMapping[]): Record<string, RouteContractMapping[]>;
+
+/**
+ * Client Code Generator
+ *
+ * Generates type-safe API client code from route-contract mappings
+ */
+
+/**
+ * Generate API client code
+ */
+declare function generateClient(mappings: RouteContractMapping[], options: ClientGenerationOptions): Promise<GenerationStats>;
+
+/**
+ * Contract Watcher & Client Generator
+ *
+ * Watches contract files and regenerates client code
+ */
+interface WatchGenerateOptions {
+    /** Routes directory (default: src/server/routes) */
+    routesDir?: string;
+    /** Output path for generated client (default: src/lib/api/client.ts) */
+    outputPath?: string;
+    /** Base URL for API client */
+    baseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Watch contracts and generate client code
+ *
+ * This file is meant to be run with tsx --watch
+ */
+declare function watchAndGenerate(options?: WatchGenerateOptions): Promise<void>;
+
+export { type ClientGenerationOptions, type GenerationStats, HttpMethod, type ResourceRoutes, type RouteContractMapping, generateClient, groupByResource, scanContracts, watchAndGenerate };