shokupan 0.9.0 → 0.10.1

package/dist/plugins/application/openapi/analyzer.impl.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Route information extracted from AST
+ */
+export interface RouteInfo {
+    method: string;
+    path: string;
+    handlerName?: string;
+    handlerSource?: string;
+    requestTypes?: {
+        body?: any;
+        query?: Record<string, string>;
+        params?: Record<string, string>;
+        headers?: Record<string, string>;
+    };
+    responseType?: string;
+    responseSchema?: any;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    operationId?: string;
+    emits?: {
+        event: string;
+        payload?: any;
+        location?: {
+            startLine: number;
+            endLine: number;
+        };
+    }[];
+    sourceContext?: {
+        file: string;
+        startLine: number;
+        endLine: number;
+        highlights?: {
+            startLine: number;
+            endLine: number;
+            type: 'emit' | 'return-success' | 'return-warning';
+        }[];
+    };
+}
+/**
+ * Dependency information
+ */
+interface DependencyInfo {
+    packageName: string;
+    version?: string;
+    importPath: string;
+    isExternal: boolean;
+}
+/**
+ * Application/Router instance found in code
+ */
+export interface ApplicationInstance {
+    name: string;
+    filePath: string;
+    className: 'Shokupan' | 'ShokupanRouter' | 'Controller';
+    controllerPrefix?: string;
+    routes: RouteInfo[];
+    mounted: MountInfo[];
+}
+interface MountInfo {
+    prefix: string;
+    target: string;
+    targetFilePath?: string;
+    dependency?: DependencyInfo;
+    sourceContext?: {
+        file: string;
+        startLine: number;
+        endLine: number;
+    };
+}
+/**
+ * Main analyzer class
+ */
+export declare class OpenAPIAnalyzer {
+    private rootDir;
+    private files;
+    private applications;
+    private program?;
+    private entrypoint?;
+    constructor(rootDir: string, entrypoint?: string);
+    /**
+     * Main analysis entry point
+     */
+    /**
+     * Main analysis entry point
+     */
+    analyze(): Promise<{
+        applications: ApplicationInstance[];
+    }>;
+    /**
+     * Remove GenericModules that are not mounted by any Shokupan application/router
+     */
+    private pruneApplications;
+    /**
+     * Recursively scan directory for TypeScript/JavaScript files
+     */
+    private scanDirectory;
+    /**
+     * Process source maps to reconstruct TypeScript
+     */
+    private processSourceMaps;
+    /**
+     * Parse TypeScript files and create AST
+     */
+    private parseTypeScriptFiles;
+    /**
+     * Find all Shokupan/ShokupanRouter instances
+     */
+    private findApplications;
+    /**
+     * Visit AST node to find application instances
+     */
+    private visitNode;
+    /**
+     * Extract route information from applications
+     */
+    private extractRoutes;
+    /**
+     * Extract routes from a Controller class
+     */
+    private extractRoutesFromController;
+    /**
+     * Extract routes from a specific file
+     */
+    private extractRoutesFromFile;
+    /**
+     * Extract route information from a route call (e.g., app.get('/path', handler))
+     */
+    private extractRouteFromCall;
+    /**
+     * Analyze a route handler to extract type information
+     */
+    private analyzeHandler;
+    /**
+     * Convert an Expression node to an OpenAPI schema (best effort)
+     */
+    private convertExpressionToSchema;
+    /**
+     * Check if an expression is a call to ctx.body()
+     */
+    private isCtxBodyCall;
+    /**
+     * Convert a TypeScript TypeNode to an OpenAPI schema
+     */
+    private convertTypeNodeToSchema;
+    /**
+     * Extract mount information from mount call
+     */
+    private extractMountFromCall;
+    /**
+     * Check if a reference is to an external dependency
+     */
+    private checkIfExternalDependency;
+    /**
+     * Get package version from package.json
+     */
+    private getPackageVersion;
+    /**
+     * Generate OpenAPI specification
+     */
+    generateOpenAPISpec(): any;
+}
+/**
+ * Analyze a directory and generate OpenAPI spec
+ */
+export declare function analyzeDirectory(directory: string): Promise<any>;
+export {};

package/dist/plugins/application/scalar.d.ts

@@ -21,6 +21,11 @@ export type ScalarPluginOptions = {
      * Only works with TypeScript entrypoints.
      */
     enableStaticAnalysis?: boolean;
+    /**
+     * Path to mount the plugin to.
+     * @default '/reference'
+     */
+    path?: string;
 };
 /**
  * Scalar plugin. This plugin provides an API reference interface for your API.
@@ -29,8 +34,10 @@ export type ScalarPluginOptions = {
  */
 export declare class ScalarPlugin extends ShokupanRouter<any> implements ShokupanPlugin {
     private readonly pluginOptions;
+    private eta;
     constructor(pluginOptions?: ScalarPluginOptions);
-    onInit(app: Shokupan, options?: ShokupanPluginOptions): void;
-    private init;
+    onInit(app: Shokupan, options?: ShokupanPluginOptions): Promise<void>;
+    private ensureEta;
+    private initRoutes;
     onMount(parent: ShokupanRouter<any>): void;
 }

package/dist/router.d.ts

@@ -1,5 +1,6 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
+import { SurrealDatastore } from './util/datastore';
 import { $appRoot, $childControllers, $childRouters, $isApplication, $isMounted, $isRouter, $mountPath, $parent, $routes } from './util/symbol';
 import { GuardAPISpec, HeadersInit, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, RouteParams, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './util/types';
 export declare const RouterRegistry: Map<string, ShokupanRouter<any>>;
@@ -73,73 +74,92 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     private [$parent];
     [$childRouters]: ShokupanRouter<T>[];
     [$childControllers]: ShokupanController[];
+    get db(): SurrealDatastore | undefined;
     private hookCache;
     private hooksInitialized;
     middleware: Middleware[];
-    get rootConfig(): {
-        [x: string]: any;
-        port?: number;
-        hostname?: string;
-        development?: boolean;
-        enableAsyncLocalStorage?: boolean;
-        enableOpenApiGen?: boolean;
-        reusePort?: boolean;
-        controllersOnly?: boolean;
+    get rootConfig(): Partial<{
+        [key: string]: any;
+        port: number;
+        hostname: string;
+        development: boolean;
+        enableAsyncLocalStorage: boolean;
+        enableOpenApiGen: boolean;
+        enableAsyncApiGen: boolean;
+        reusePort: boolean;
+        controllersOnly: boolean;
         enableTracing?: boolean;
         jsonParser?: "native" | "parse-json" | "secure-json-parse";
         autoBackpressureFeedback?: boolean;
         autoBackpressureLevel?: number;
-        enableMiddlewareTracking?: boolean;
+        enableMiddlewareTracking: boolean;
         middlewareTrackingMaxCapacity?: number;
         enableHTTPBridge?: boolean;
         websocketErrorHandler?: (err: any, ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
         idGenerator?: () => string;
         middlewareTrackingTTL?: number;
-        httpLogger?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void;
-        logger?: {
-            verbose?: boolean;
-            info?: (msg: string, props: Record<string, any>) => void;
-            debug?: (msg: string, props: Record<string, any>) => void;
-            warning?: (msg: string, props: Record<string, any>) => void;
-            error?: (msg: string, props: Record<string, any>) => void;
-            fatal?: (msg: string, props: Record<string, any>) => void;
+        httpLogger: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void;
+        logger: {
+            verbose: boolean;
+            info: (msg: string, props: Record<string, any>) => void;
+            debug: (msg: string, props: Record<string, any>) => void;
+            warning: (msg: string, props: Record<string, any>) => void;
+            error: (msg: string, props: Record<string, any>) => void;
+            fatal: (msg: string, props: Record<string, any>) => void;
         };
-        readTimeout?: number;
-        requestTimeout?: number;
-        writeTimeout?: number;
-        renderer?: JSXRenderer;
-        serverFactory?: import('.').ServerFactory;
-        hooks?: {
-            onError?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, error: unknown) => void | Promise<void>;
-            onRequestStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onResponseStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
-            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
-            beforeValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
-            afterValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
-            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-        } | {
-            onError?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, error: unknown) => void | Promise<void>;
-            onRequestStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onResponseStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
-            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
-            beforeValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
-            afterValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
-            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
-        }[];
-        validateStatusCodes?: boolean;
-    };
+        readTimeout: number;
+        requestTimeout: number;
+        writeTimeout: number;
+        renderer: JSXRenderer;
+        serverFactory: import('.').ServerFactory;
+        hooks: ShokupanHooks<Record<string, any>> | ShokupanHooks<Record<string, any>>[];
+        validateStatusCodes: boolean;
+        surreal?: {
+            engines?: import('surrealdb').Engines;
+            url?: string;
+            connectOptions?: import('surrealdb').ConnectOptions;
+            namespace?: string;
+            database?: string;
+        };
+        aiPlugin?: {
+            enabled?: boolean;
+            name_for_human?: string;
+            name_for_model?: string;
+            description_for_human?: string;
+            description_for_model?: string;
+            auth?: {
+                type: "none" | "service_http" | "user_http" | "oauth";
+                [key: string]: any;
+            };
+            api?: {
+                type: "openapi";
+                url?: string;
+                is_user_authenticated?: boolean;
+            };
+            logo_url?: string;
+            contact_email?: string;
+            legal_info_url?: string;
+        };
+        apiCatalog?: {
+            enabled?: boolean;
+            versions?: Array<{
+                name: string;
+                url: string;
+                spec_url: string;
+            }>;
+        };
+    }>;
     get root(): Shokupan<any>;
     [$routes]: ShokupanRoute[];
     private trie;
     metadata?: RouteMetadata;
     private currentGuards;
     private eventHandlers;
+    /**
+     * Registers middleware for this router.
+     * Middleware will run for all routes matched by this router.
+     */
+    use(middleware: Middleware): this;
     getComponentRegistry(): {
         metadata: RouteMetadata;
         middleware: {
@@ -186,6 +206,10 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Finds an event handler(s) by name.
      */
     findEvent(name: string): ShokupanHandler<T>[] | null;
+    /**
+     * Returns all registered event handlers.
+     */
+    getEventHandlers(): Map<string, ShokupanHandler<T>[]>;
     /**
      * Mounts a controller instance to a path prefix.
      *
@@ -251,7 +275,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param arg.renderer - JSX renderer for the route
      * @param arg.controller - Controller for the route
      */
-    add({ method, path, spec, handler, regex: customRegex, group, requestTimeout, renderer, controller }: {
+    add({ method, path, spec, handler, regex: customRegex, group, requestTimeout, renderer, controller, metadata, middleware }: {
         method: Method;
         path: string;
         spec?: MethodAPISpec;
@@ -261,6 +285,11 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         requestTimeout?: number;
         renderer?: JSXRenderer;
         controller?: any;
+        metadata?: {
+            file: string;
+            line: number;
+        };
+        middleware?: Middleware[];
     }): this;
     /**
      * Adds a GET route to the router.
@@ -397,7 +426,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Generates an OpenAPI 3.1 Document by recursing through the router and its descendants.
      * Now includes runtime analysis of handler functions to infer request/response types.
      */
-    generateApiSpec(options?: OpenAPIOptions): any;
+    generateApiSpec(options?: OpenAPIOptions): Promise<any>;
     private ensureHooksInitialized;
-    runHooks(name: keyof ShokupanHooks, ...args: any[]): Promise<void>;
+    runHooks(name: keyof ShokupanHooks, ...args: any[]): void | Promise<void[]>;
 }

package/dist/shokupan.d.ts

@@ -2,6 +2,7 @@ import { $dispatch } from './util/symbol';
 import { Middleware, ProcessResult, RequestOptions, ShokupanConfig, ShokupanPlugin } from './util/types';
 import { Server } from 'bun';
 import { ShokupanRouter } from './router';
+import { SurrealDatastore } from './util/datastore';
 import { ShokupanRequest } from './util/request';
 /**
  * Shokupan Application
@@ -70,18 +71,23 @@ import { ShokupanRequest } from './util/request';
 export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     readonly applicationConfig: ShokupanConfig;
     openApiSpec?: any;
+    asyncApiSpec?: any;
     private composedMiddleware?;
     private cpuMonitor?;
     private server?;
+    private datastore?;
+    dbPromise?: Promise<any>;
+    get db(): SurrealDatastore | undefined;
     get logger(): {
-        verbose?: boolean;
-        info?: (msg: string, props: Record<string, any>) => void;
-        debug?: (msg: string, props: Record<string, any>) => void;
-        warning?: (msg: string, props: Record<string, any>) => void;
-        error?: (msg: string, props: Record<string, any>) => void;
-        fatal?: (msg: string, props: Record<string, any>) => void;
+        verbose: boolean;
+        info: (msg: string, props: Record<string, any>) => void;
+        debug: (msg: string, props: Record<string, any>) => void;
+        warning: (msg: string, props: Record<string, any>) => void;
+        error: (msg: string, props: Record<string, any>) => void;
+        fatal: (msg: string, props: Record<string, any>) => void;
     };
     constructor(applicationConfig?: ShokupanConfig);
+    private initDatastore;
     /**
      * Adds middleware to the application.
      */
@@ -109,7 +115,7 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * @param port - The port to listen on. If not specified, the port from the configuration is used. If that is not specified, port 3000 is used.
      * @returns The server instance.
      */
-    listen(port?: number): Promise<Server>;
+    listen(port?: number): Promise<Server<any>>;
     /**
      * Stops the application server.
      *
@@ -142,6 +148,6 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * @param server - The server instance.
      * @returns The response to send.
      */
-    fetch(req: Request, server?: Server): Promise<Response>;
+    fetch(req: Request, server?: Server<any>): Promise<Response>;
     private handleRequest;
 }

package/dist/util/datastore.d.ts

@@ -1,7 +1,71 @@
-import { RecordId, Range, Table } from 'surrealdb';
-export declare const datastore: {
-    get<T extends Record<string, any>>(recordId: RecordId | Table | Range<any, any>): Promise<T>;
-    set(recordId: RecordId, value: Record<string, any>): Promise<any>;
-    query<T extends Record<string, any>>(query: string, vars?: Record<string, unknown>): Promise<T>;
-    readonly ready: Promise<any>;
-};
+import { RecordId, Surreal, RecordIdRange, Table } from 'surrealdb';
+export declare class SurrealDatastore {
+    private readonly db;
+    constructor(db: Surreal);
+    createSchema(): void;
+    /**
+     * Select a record or contents of a table by its ID.
+     */
+    select<T = unknown>(id: RecordId | RecordIdRange | Table): Promise<(T extends object ? T extends {
+        id: infer Id;
+    } ? Id extends RecordId<string, import('surrealdb').RecordIdValue> ? T : Id extends import('surrealdb').RecordIdValue ? {
+        id: RecordId<string, Id>;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & T : {
+        id: RecordId;
+    }) extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never>;
+    /**
+     * Merge update data into a record by its ID.
+     */
+    merge<T extends Record<string, any>>(id: RecordId, data: T): Promise<(T extends object ? T extends {
+        id: infer Id;
+    } ? Id extends RecordId<string, import('surrealdb').RecordIdValue> ? T : Id extends import('surrealdb').RecordIdValue ? {
+        id: RecordId<string, Id>;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & T : {
+        id: RecordId;
+    }) extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never>;
+    /**
+     * Create a record by its ID.
+     */
+    create<T extends Record<string, any>>(id: RecordId, data: Omit<T, 'id'>): Promise<{
+        id: RecordId;
+    }>;
+    /**
+     * Upsert a record by its ID.
+     */
+    upsert<T extends Record<string, any>>(id: RecordId, data: T): Promise<(T extends object ? T extends {
+        id: infer Id;
+    } ? Id extends RecordId<string, import('surrealdb').RecordIdValue> ? T : Id extends import('surrealdb').RecordIdValue ? {
+        id: RecordId<string, Id>;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & Omit<T, "id"> : {
+        id: RecordId;
+    } & T : {
+        id: RecordId;
+    }) extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never>;
+    /**
+     * Delete a record by its ID.
+     */
+    delete(id: RecordId): Promise<{
+        id: RecordId;
+    }>;
+    /**
+     * Run a SurrealDB query.
+     */
+    query<T extends Array<unknown>>(query: string, vars?: Record<string, any>): Promise<T extends [] ? unknown[] : { [K in keyof T]: T[K]; }>;
+    /**
+     * Create a relationship between two records.
+     */
+    relate(fromId: any, edgeId: any, toId: any, data?: Record<string, any>): Promise<{
+        [x: string]: /*elided*/ any;
+    }>;
+    disconnect(): Promise<true>;
+}

package/dist/util/decorators.d.ts

@@ -1,5 +1,5 @@
 import { RateLimitOptions } from '../plugins/middleware/rate-limit';
-import { GuardAPISpec, MethodAPISpec, Middleware } from './types';
+import { AsyncAPISpec, GuardAPISpec, MethodAPISpec, Middleware } from './types';
 /**
  * Class Decorator: Defines the base path for a controller.
  */
@@ -35,7 +35,7 @@ export declare const Ctx: (name?: string) => (target: any, propertyKey: string,
 /**
  * Decorator: Overrides the OpenAPI specification for a route.
  */
-export declare function Spec(spec: MethodAPISpec | GuardAPISpec): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function Spec(spec: MethodAPISpec | GuardAPISpec | AsyncAPISpec): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Decorator: Binds a method to the GET HTTP verb.
  */

package/dist/util/types.d.ts

@@ -1,6 +1,7 @@
 import { OpenAPI } from '@scalar/openapi-types';
 import { Server } from 'bun';
 import { Server as NodeServer } from 'node:http';
+import { ConnectOptions, Engines } from 'surrealdb';
 import { ShokupanContext } from '../context';
 import { $isRouter } from './symbol';
 export type HeadersInit = Headers | Record<string, string> | [string, string][];
@@ -61,6 +62,27 @@ export interface OpenAPIOptions {
     defaultTagGroup?: string;
     defaultTag?: string;
 }
+export interface AsyncAPIOptions {
+    info?: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    defaultTag?: string;
+}
+export interface AsyncAPISpec {
+    type?: 'publish' | 'subscribe';
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    message?: {
+        name?: string;
+        title?: string;
+        summary?: string;
+        payload?: any;
+        headers?: any;
+    };
+}
 export interface ShokupanHooks<T = any> {
     onError?: (ctx: ShokupanContext<T>, error: unknown) => void | Promise<void>;
     onRequestStart?: (ctx: ShokupanContext<T>) => void | Promise<void>;
@@ -97,7 +119,7 @@ export declare enum RouteParamType {
     CONTEXT = "CONTEXT"
 }
 export interface ServerFactory {
-    (options: any): Server | Promise<Server> | NodeServer | Promise<NodeServer>;
+    (options: any): Server<any> | Promise<Server<any>> | NodeServer | Promise<NodeServer>;
 }
 export type NextFn = () => Promise<any>;
 export type Middleware = ((ctx: ShokupanContext<unknown>, next: NextFn) => Promise<any> | any) & {
@@ -167,7 +189,7 @@ export type ShokupanRoute = {
     /**
      * OpenAPI spec for the route
      */
-    handlerSpec?: MethodAPISpec;
+    handlerSpec?: MethodAPISpec | AsyncAPISpec;
     /**
      * Group for the route
      */
@@ -209,8 +231,12 @@ export type ShokupanRoute = {
      * Controller instance this route belongs to
      */
     controller?: any;
+    /**
+     * Middleware stack metadata for this route (Controller/Method level)
+     */
+    middleware?: Middleware[];
 };
-export type ShokupanConfig<T extends Record<string, any> = Record<string, any>> = DeepPartial<{
+export type ShokupanConfig<T extends Record<string, any> = Record<string, any>> = Partial<{
     /**
      * The port to be used for the server.
      * @default 3000
@@ -237,6 +263,11 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     enableOpenApiGen: boolean;
+    /**
+     * Whether to enable AsyncAPI generation.
+     * @default false
+     */
+    enableAsyncApiGen: boolean;
     /**
      * Whether to reuse the port.
      * @default false
@@ -379,6 +410,68 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     validateStatusCodes: boolean;
+    /**
+     * Configuration for SurrealDB.
+     */
+    surreal?: {
+        /**
+         * SurrealDB engines.
+         * @default Embedded
+         */
+        engines?: Engines;
+        /**
+         * SurrealDB connection URL.
+         * @default 'rocksdb://database'
+         */
+        url?: string;
+        /**
+         * SurrealDB connection options.
+         */
+        connectOptions?: ConnectOptions;
+        /**
+         * SurrealDB namespace.
+         */
+        namespace?: string;
+        /**
+         * SurrealDB database.
+         */
+        database?: string;
+    };
+    /**
+     * Configuration for the AI Plugin manifest (.well-known/ai-plugin.json).
+     * If enabled, Shokupan will serve the manifest at the standard location.
+     */
+    aiPlugin?: {
+        enabled?: boolean;
+        name_for_human?: string;
+        name_for_model?: string;
+        description_for_human?: string;
+        description_for_model?: string;
+        auth?: {
+            type: 'none' | 'service_http' | 'user_http' | 'oauth';
+            [key: string]: any;
+        };
+        api?: {
+            type: 'openapi';
+            url?: string;
+            is_user_authenticated?: boolean;
+        };
+        logo_url?: string;
+        contact_email?: string;
+        legal_info_url?: string;
+    };
+    /**
+     * Configuration for the API Catalog (.well-known/api-catalog).
+     * If enabled, Shokupan will serve the catalog at the standard location.
+     */
+    apiCatalog?: {
+        enabled?: boolean;
+        versions?: Array<{
+            name: string;
+            url: string;
+            spec_url: string;
+        }>;
+    };
     /**
      * Any other config options are allowed, but will be ignored.
      * @deprecated