@pancake-apps/server 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import { RequestHandler } from 'express';
+import { z } from 'zod';
+
+/**
+ * Content Security Policy configuration for UI resources
+ */
+interface ContentSecurityPolicy {
+    /** Domains allowed for connect-src (fetch, WebSocket, etc.) */
+    connectDomains?: string[];
+    /** Domains allowed for loading resources (images, fonts, etc.) */
+    resourceDomains?: string[];
+    /** Domains allowed for script-src */
+    scriptDomains?: string[];
+}
+/**
+ * UI definition for views and tools
+ */
+interface UIDefinition {
+    /** Path to HTML file or inline HTML (starts with "<") */
+    html: string;
+    /** Display name for the UI */
+    name?: string;
+    /** Whether the host should render a border around the UI */
+    prefersBorder?: boolean;
+    /** Whether the UI should auto-resize based on content */
+    autoResize?: boolean;
+    /** Content Security Policy for the UI iframe */
+    csp?: ContentSecurityPolicy;
+    /** Domain for cross-origin UIs */
+    domain?: string;
+}
+/**
+ * Visibility options for tools/views
+ * - 'model': Only visible to the AI model
+ * - 'app': Only visible to the UI/app
+ * - 'both': Visible to both model and app
+ */
+type Visibility = 'model' | 'app' | 'both';
+/**
+ * Protocol types for client detection
+ */
+type Protocol = 'mcp' | 'openai' | 'mock';
+/**
+ * Host context provided by MCP or OpenAI hosts
+ */
+interface HostContext {
+    /** Current theme */
+    theme: 'light' | 'dark';
+    /** Current display mode */
+    displayMode: 'inline' | 'fullscreen' | 'pip';
+    /** Available display modes */
+    availableDisplayModes: string[];
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** User's locale (e.g., 'en-US') */
+    locale: string;
+    /** User's timezone */
+    timeZone: string;
+    /** Platform type */
+    platform: 'desktop' | 'mobile' | 'web';
+    /** Current view identifier (if applicable) */
+    view?: string;
+    /** Safe area insets for mobile */
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+
+/**
+ * Base context passed to all handlers
+ */
+interface BaseContext {
+    /** Unique identifier for this request */
+    requestId: string;
+    /** Session identifier (if available) */
+    sessionId?: string;
+    /** Additional metadata from the protocol */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Context passed to view handlers
+ */
+interface ViewContext extends BaseContext {
+    /** Name of the view being rendered */
+    viewName: string;
+}
+/**
+ * Context passed to action handlers
+ */
+interface ActionContext extends BaseContext {
+    /** Name of the action being executed */
+    actionName: string;
+}
+/**
+ * Context passed to data handlers
+ */
+interface DataContext extends BaseContext {
+    /** Name of the data fetcher being called */
+    dataName: string;
+}
+/**
+ * Context passed to low-level tool handlers
+ */
+interface ToolContext extends BaseContext {
+    /** Name of the tool being called */
+    toolName: string;
+}
+
+/**
+ * Configuration for defining a view
+ *
+ * Views are MCP tools + resources that display a UI.
+ * They can optionally fetch data to pass to the UI.
+ */
+interface ViewConfig<TInput extends z.ZodType = z.ZodTypeAny, TData extends z.ZodType = z.ZodTypeAny> {
+    /** Description of what this view shows */
+    description: string;
+    /** Input schema for view parameters (optional) */
+    input?: TInput;
+    /** Schema for data returned to the UI (optional) */
+    data?: TData;
+    /**
+     * Handler that fetches data for the view.
+     * The returned data is passed to the UI via viewParams.data
+     */
+    handler?: (input: z.infer<TInput>, ctx: ViewContext) => Promise<z.infer<TData>>;
+    /** UI definition (required for views) */
+    ui: UIDefinition;
+    /** Visibility settings */
+    visibility?: Visibility;
+}
+/**
+ * Internal normalized view definition
+ */
+interface ViewDefinition<TInput extends z.ZodType = z.ZodTypeAny, TData extends z.ZodType = z.ZodTypeAny> {
+    readonly _type: 'view';
+    readonly name: string;
+    readonly description: string;
+    readonly input: TInput | undefined;
+    readonly data: TData | undefined;
+    readonly handler: ((input: z.infer<TInput>, ctx: ViewContext) => Promise<z.infer<TData>>) | undefined;
+    readonly ui: UIDefinition;
+    readonly visibility: Visibility;
+}
+/**
+ * Metadata for discovered views (from JSON files)
+ */
+interface ViewMetadata {
+    /** Description of the view */
+    description: string;
+    /** JSON Schema for input parameters */
+    input?: Record<string, unknown>;
+    /** JSON Schema for data output */
+    data?: Record<string, unknown>;
+    /** Visibility settings */
+    visibility?: Visibility;
+}
+/**
+ * Result of view discovery
+ */
+interface DiscoveredView {
+    /** View name (derived from filename/folder) */
+    name: string;
+    /** Path to the HTML file */
+    htmlPath: string;
+    /** Parsed metadata */
+    metadata: ViewMetadata;
+}
+
+/**
+ * Configuration for defining an action
+ *
+ * Actions are MCP tools that perform write operations.
+ * They can be called from the UI via window.pancake.dispatch()
+ */
+interface ActionConfig<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    /** Description of what this action does */
+    description: string;
+    /** Input schema for action parameters */
+    input: TInput;
+    /** Output schema for action result */
+    output: TOutput;
+    /** Handler that executes the action */
+    handler: (input: z.infer<TInput>, ctx: ActionContext) => Promise<z.infer<TOutput>>;
+    /** Optional UI for action confirmation/result display */
+    ui?: UIDefinition;
+    /** Visibility settings (default: 'both') */
+    visibility?: Visibility;
+}
+/**
+ * Internal normalized action definition
+ */
+interface ActionDefinition<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    readonly _type: 'action';
+    readonly name: string;
+    readonly description: string;
+    readonly input: TInput;
+    readonly output: TOutput;
+    readonly handler: (input: z.infer<TInput>, ctx: ActionContext) => Promise<z.infer<TOutput>>;
+    readonly ui: UIDefinition | undefined;
+    readonly visibility: Visibility;
+}
+
+/**
+ * Configuration for defining a data fetcher
+ *
+ * Data fetchers are MCP tools that perform read operations.
+ * They can be called from the UI via window.pancake.getData()
+ */
+interface DataConfig<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    /** Description of what data this fetches */
+    description: string;
+    /** Input schema for query parameters */
+    input: TInput;
+    /** Output schema for returned data */
+    output: TOutput;
+    /** Handler that fetches the data */
+    handler: (input: z.infer<TInput>, ctx: DataContext) => Promise<z.infer<TOutput>>;
+    /** Visibility settings (default: 'both') */
+    visibility?: Visibility;
+}
+/**
+ * Internal normalized data definition
+ */
+interface DataDefinition<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    readonly _type: 'data';
+    readonly name: string;
+    readonly description: string;
+    readonly input: TInput;
+    readonly output: TOutput;
+    readonly handler: (input: z.infer<TInput>, ctx: DataContext) => Promise<z.infer<TOutput>>;
+    readonly visibility: Visibility;
+}
+
+/**
+ * Configuration for defining a low-level tool
+ *
+ * This is the base abstraction that Views, Actions, and Data
+ * are built upon. Use this for advanced use cases.
+ */
+interface ToolConfig<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    /** Tool name (must be unique) */
+    name: string;
+    /** Description of what this tool does */
+    description: string;
+    /** Input schema */
+    input: TInput;
+    /** Output schema */
+    output: TOutput;
+    /** Handler that executes the tool */
+    handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<z.infer<TOutput>>;
+    /** Optional UI to display with the tool */
+    ui?: UIDefinition;
+    /** Visibility settings */
+    visibility?: Visibility;
+}
+/**
+ * Internal normalized tool definition
+ */
+interface ToolDefinition<TInput extends z.ZodType = z.ZodTypeAny, TOutput extends z.ZodType = z.ZodTypeAny> {
+    readonly _type: 'tool';
+    readonly name: string;
+    readonly description: string;
+    readonly input: TInput;
+    readonly output: TOutput;
+    readonly handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<z.infer<TOutput>>;
+    readonly ui: UIDefinition | undefined;
+    readonly visibility: Visibility;
+}
+/**
+ * Internal tool representation used by the server
+ * This is what Views, Actions, and Data are normalized to
+ */
+interface InternalTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly outputSchema: Record<string, unknown>;
+    readonly handler: (input: unknown, ctx: ToolContext) => Promise<unknown>;
+    readonly ui: UIDefinition | undefined;
+    readonly visibility: Visibility;
+    readonly category: 'view' | 'action' | 'data' | 'tool';
+}
+
+/**
+ * CORS configuration
+ */
+interface CorsConfig {
+    /** Allowed origins */
+    origin?: string | string[] | boolean;
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Exposed headers */
+    exposedHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Preflight cache duration */
+    maxAge?: number;
+}
+/**
+ * OAuth configuration for protected endpoints
+ */
+interface OAuthConfig {
+    /** OAuth provider */
+    provider: string;
+    /** Client ID */
+    clientId: string;
+    /** Client secret */
+    clientSecret: string;
+    /** Authorization URL */
+    authorizationUrl: string;
+    /** Token URL */
+    tokenUrl: string;
+    /** Scopes to request */
+    scopes: string[];
+}
+/**
+ * Development server configuration
+ */
+interface DevServerConfig {
+    /** Vite dev server port (default: 5173) */
+    vitePort?: number;
+    /** Path prefix for Vite proxy */
+    proxyPath?: string;
+}
+/**
+ * Application configuration
+ */
+interface AppConfig {
+    /** Application name */
+    name: string;
+    /** Application version */
+    version: string;
+    /** View configurations */
+    views?: Record<string, ViewConfig>;
+    /** Action configurations */
+    actions?: Record<string, ActionConfig>;
+    /** Data fetcher configurations */
+    data?: Record<string, DataConfig>;
+    /** Low-level tool configurations (advanced) */
+    tools?: Record<string, ToolConfig>;
+    /** Middleware chain */
+    middleware?: Middleware[];
+    /** Plugins */
+    plugins?: Plugin[];
+    /** Additional configuration */
+    config?: {
+        /** CORS settings */
+        cors?: CorsConfig;
+        /** OAuth settings */
+        oauth?: OAuthConfig;
+        /** Enable debug mode */
+        debug?: boolean;
+        /** Custom MCP endpoint path (default: '/mcp') */
+        serverRoute?: string;
+        /** Development server settings */
+        devServer?: DevServerConfig;
+    };
+}
+/**
+ * Server start options
+ */
+interface StartOptions {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Host to bind to (default: '0.0.0.0') */
+    host?: string;
+    /** Transport type */
+    transport?: 'http' | 'stdio' | 'sse';
+}
+/**
+ * Application instance
+ */
+interface App {
+    /** Start the server */
+    start(options?: StartOptions): Promise<void>;
+    /** Stop the server */
+    stop(): Promise<void>;
+    /** Get Express middleware for custom server integration */
+    handler(): RequestHandler;
+    /** Handle a fetch request (for serverless/edge) */
+    handleRequest(req: Request): Promise<Response>;
+    /** Add middleware */
+    use(middleware: Middleware): void;
+    /** Subscribe to events */
+    on<K extends keyof EventMap>(event: K, handler: (payload: EventMap[K]) => void): () => void;
+}
+/**
+ * Middleware context
+ */
+interface MiddlewareContext {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly metadata: Record<string, unknown>;
+    readonly state: Map<string, unknown>;
+}
+/**
+ * Middleware function
+ */
+type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Plugin context
+ */
+interface PluginContext {
+    readonly app: AppConfig;
+    readonly plugin: Plugin;
+}
+/**
+ * Tool call context for plugins
+ */
+interface ToolCallContext {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly metadata: Record<string, unknown>;
+}
+/**
+ * Tool error context for plugins
+ */
+interface ToolErrorContext extends ToolCallContext {
+    readonly error: Error;
+}
+/**
+ * Plugin interface
+ */
+interface Plugin {
+    /** Plugin name */
+    name: string;
+    /** Plugin version */
+    version?: string;
+    /** Called when app is initialized */
+    onInit?(ctx: PluginContext): Promise<void>;
+    /** Called when server starts */
+    onStart?(ctx: PluginContext): Promise<void>;
+    /** Called when server shuts down */
+    onShutdown?(ctx: PluginContext): Promise<void>;
+    /** Called before a tool is executed */
+    beforeToolCall?(ctx: ToolCallContext): Promise<void>;
+    /** Called after a tool is executed */
+    afterToolCall?(ctx: ToolCallContext): Promise<void>;
+    /** Called when a tool throws an error */
+    onToolError?(ctx: ToolErrorContext): Promise<void>;
+}
+/**
+ * Event map for typed event emitter
+ */
+interface EventMap {
+    'app:init': {
+        config: AppConfig;
+    };
+    'app:start': {
+        port?: number;
+        transport: string;
+    };
+    'app:shutdown': {
+        graceful: boolean;
+    };
+    'tool:called': {
+        toolName: string;
+        input: unknown;
+    };
+    'tool:success': {
+        toolName: string;
+        result: unknown;
+        durationMs: number;
+    };
+    'tool:error': {
+        toolName: string;
+        error: Error;
+        durationMs: number;
+    };
+}
+
+/**
+ * Create a Pancake application.
+ *
+ * @example
+ * ```ts
+ * import { createApp, defineView, defineAction, defineData } from '@pancake-apps/server';
+ * import { z } from 'zod';
+ *
+ * const app = createApp({
+ *   name: 'my-app',
+ *   version: '1.0.0',
+ *   views: {
+ *     hello: defineView({
+ *       description: 'Greeting view',
+ *       input: z.object({ name: z.string() }),
+ *       ui: { html: './views/hello.html' },
+ *     }),
+ *   },
+ *   actions: {
+ *     save: defineAction({
+ *       description: 'Save data',
+ *       input: z.object({ data: z.string() }),
+ *       output: z.object({ success: z.boolean() }),
+ *       handler: async ({ data }) => ({ success: true }),
+ *     }),
+ *   },
+ * });
+ *
+ * app.start({ port: 3000 });
+ * ```
+ */
+declare function createApp(config: AppConfig): App;
+
+/**
+ * Check if a value is a ViewConfig
+ */
+declare function isViewConfig(value: unknown): value is ViewConfig;
+
+/**
+ * Check if a value is an ActionConfig
+ */
+declare function isActionConfig(value: unknown): value is ActionConfig;
+
+/**
+ * Check if a value is a DataConfig
+ */
+declare function isDataConfig(value: unknown): value is DataConfig;
+
+/**
+ * Check if a value is a ToolConfig
+ */
+declare function isToolConfig(value: unknown): value is ToolConfig;
+
+/**
+ * Discover views from a directory.
+ *
+ * Supports two patterns:
+ * 1. Flat files: `views/hello.html` + `views/hello.json`
+ * 2. Folder-based: `views/hello/index.html` + `views/hello/metadata.json`
+ *
+ * @example
+ * ```ts
+ * const app = createApp({
+ *   name: 'my-app',
+ *   version: '1.0.0',
+ *   views: {
+ *     ...discoverViews('./src/views'),
+ *   },
+ * });
+ * ```
+ */
+declare function discoverViews(dir: string): Record<string, ViewConfig>;
+/**
+ * Async version of discoverViews for dynamic usage
+ */
+declare function discoverViewsAsync(dir: string): Promise<Record<string, ViewConfig>>;
+
+export { type ActionConfig, type ActionContext, type ActionDefinition, type App, type AppConfig, type BaseContext, type ContentSecurityPolicy, type CorsConfig, type DataConfig, type DataContext, type DataDefinition, type DevServerConfig, type DiscoveredView, type EventMap, type HostContext, type InternalTool, type Middleware, type MiddlewareContext, type OAuthConfig, type Plugin, type PluginContext, type Protocol, type StartOptions, type ToolCallContext, type ToolConfig, type ToolContext, type ToolDefinition, type ToolErrorContext, type UIDefinition, type ViewConfig, type ViewContext, type ViewDefinition, type ViewMetadata, type Visibility, createApp, discoverViews, discoverViewsAsync, isActionConfig, isDataConfig, isToolConfig, isViewConfig };