@witqq/agent-sdk 0.6.0 → 0.7.0

package/dist/chat/server.d.ts

@@ -0,0 +1,287 @@
+import { IChatRuntime } from './runtime.js';
+import { W as WritableResponse$1 } from '../transport-D1OaUgRk.js';
+import { A as AuthToken, d as CopilotAuthToken, C as ClaudeAuthToken } from '../types-Bh5AhqD-.js';
+import './core.js';
+import '../types-CqvUAYxt.js';
+import 'zod';
+import '../types-DLZzlJxt.js';
+import './sessions.js';
+import './storage.js';
+import '../errors-BDLbNu9w.js';
+import './context.js';
+
+/**
+ * createChatHandler — maps RemoteChatRuntime contract endpoints to IChatRuntime calls.
+ *
+ * Implements all 10 routes from the RemoteChatRuntime server endpoint contract:
+ * - POST   /sessions/create          → runtime.createSession()
+ * - GET    /sessions/{id}            → runtime.getSession()
+ * - GET    /sessions                 → runtime.listSessions()
+ * - DELETE /sessions/{id}            → runtime.deleteSession()
+ * - POST   /sessions/{id}/archive    → runtime.archiveSession()
+ * - POST   /send                     → runtime.send() via SSE
+ * - POST   /abort                    → runtime.abort()
+ * - GET    /models                   → runtime.listModels()
+ * - POST   /backend/switch           → runtime.switchBackend()
+ * - POST   /model/switch             → runtime.switchModel()
+ */
+
+/** Minimal readable request interface (node:http IncomingMessage subset) */
+interface ReadableRequest {
+    readonly method?: string;
+    readonly url?: string;
+    on(event: "data", listener: (chunk: Buffer | string) => void): void;
+    on(event: "end", listener: () => void): void;
+}
+/**
+ * Writable HTTP response interface for chat handler.
+ * Extends the transport's WritableResponse with setHeader() and body-accepting end().
+ */
+interface WritableResponse extends WritableResponse$1 {
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/** Configuration for createChatHandler */
+interface ChatHandlerOptions {
+    /** Route prefix to strip from URL before matching. Default: "" (no prefix) */
+    prefix?: string;
+    /** Maximum request body size in bytes. Default: 1MB (1048576) */
+    maxBodySize?: number;
+    /** SSE heartbeat interval in milliseconds. 0 or undefined disables heartbeat. */
+    heartbeatMs?: number;
+}
+/**
+ * Create an HTTP request handler that maps RemoteChatRuntime contract
+ * endpoints to IChatRuntime method calls.
+ *
+ * @param runtime - The chat runtime instance to serve
+ * @param options - Handler configuration
+ * @returns Async request handler `(req, res) => Promise<void>`
+ *
+ * @example
+ * ```ts
+ * const handler = createChatHandler(runtime, { prefix: "/api/chat" });
+ * http.createServer(async (req, res) => {
+ *   if (req.url?.startsWith("/api/chat")) {
+ *     await handler(req, res);
+ *     return;
+ *   }
+ *   res.writeHead(404).end();
+ * });
+ * ```
+ */
+declare function createChatHandler(runtime: IChatRuntime, options?: ChatHandlerOptions): (req: ReadableRequest, res: WritableResponse) => Promise<void>;
+
+/**
+ * Token storage abstraction and default filesystem implementation.
+ */
+
+/** Token storage interface for server-side token management */
+interface ITokenStore {
+    /** Save a token for a provider. Overwrites if exists. */
+    save(provider: string, token: AuthToken): Promise<void>;
+    /** Load a previously saved token. Returns null if not found. */
+    load(provider: string): Promise<AuthToken | null>;
+    /** Remove a specific provider's token. */
+    clear(provider: string): Promise<void>;
+    /** Remove all stored tokens. */
+    clearAll(): Promise<void>;
+    /** List provider names that have saved tokens. */
+    list(): Promise<string[]>;
+}
+/** In-memory token store for testing and ephemeral use */
+declare class InMemoryTokenStore implements ITokenStore {
+    private readonly tokens;
+    save(provider: string, token: AuthToken): Promise<void>;
+    load(provider: string): Promise<AuthToken | null>;
+    clear(provider: string): Promise<void>;
+    clearAll(): Promise<void>;
+    list(): Promise<string[]>;
+}
+/** Options for FileTokenStore */
+interface FileTokenStoreOptions {
+    /** Directory to store token JSON files. Default: ".tokens" in cwd */
+    directory: string;
+}
+/** Filesystem-based token store using JSON files (one per provider) */
+declare class FileTokenStore implements ITokenStore {
+    private readonly dir;
+    constructor(options: FileTokenStoreOptions);
+    save(provider: string, token: AuthToken): Promise<void>;
+    load(provider: string): Promise<AuthToken | null>;
+    clear(provider: string): Promise<void>;
+    clearAll(): Promise<void>;
+    list(): Promise<string[]>;
+    private filePath;
+}
+
+/**
+ * createAuthHandler — server-mediated authentication for all three backends.
+ *
+ * Routes:
+ * - POST /auth/start            → Start auth flow (copilot device flow, claude OAuth, vercel-ai passthrough)
+ * - POST /auth/copilot/poll     → Poll for Copilot device flow completion
+ * - POST /auth/claude/complete  → Exchange Claude OAuth code for token
+ * - POST /auth/vercel/complete  → Submit Vercel AI API key
+ * - GET  /tokens/saved          → List providers with saved tokens
+ * - POST /tokens/use            → Load and activate a saved token
+ * - POST /tokens/clear          → Clear all saved tokens and invoke onLogout
+ * - POST /auth/dispose          → Clear pending flows and invoke onLogout
+ */
+
+/** Auth provider names recognized by the handler */
+type AuthProvider = "copilot" | "claude" | "vercel-ai";
+/** Copilot auth class interface (matches CopilotAuth public API) */
+interface ICopilotAuth {
+    startDeviceFlow(options?: {
+        scopes?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        userCode: string;
+        verificationUrl: string;
+        waitForToken: (signal?: AbortSignal) => Promise<CopilotAuthToken>;
+    }>;
+}
+/** Claude auth class interface (matches ClaudeAuth public API) */
+interface IClaudeAuth {
+    startOAuthFlow(options?: {
+        redirectUri?: string;
+        scopes?: string;
+    }): {
+        authorizeUrl: string;
+        completeAuth: (codeOrUrl: string) => Promise<ClaudeAuthToken>;
+    };
+}
+/** Callback invoked after successful authentication */
+type OnAuthCallback = (provider: AuthProvider, token: AuthToken) => void | Promise<void>;
+/** Configuration for createAuthHandler */
+interface AuthHandlerOptions {
+    /** Token storage implementation */
+    tokenStore: ITokenStore;
+    /** Factory for creating CopilotAuth instances */
+    createCopilotAuth?: () => ICopilotAuth;
+    /** Factory for creating ClaudeAuth instances */
+    createClaudeAuth?: () => IClaudeAuth;
+    /** Called after successful authentication for any provider */
+    onAuth?: OnAuthCallback;
+    /** Called when dispose/logout is requested */
+    onLogout?: () => void | Promise<void>;
+    /** Route prefix to strip from URL before matching. Default: "" */
+    prefix?: string;
+    /** Maximum request body size in bytes. Default: 1MB */
+    maxBodySize?: number;
+}
+/**
+ * Create an HTTP request handler for server-mediated authentication.
+ *
+ * @param options - Auth handler configuration (token store, auth factories, callbacks)
+ * @returns Async request handler `(req, res) => Promise<void>`
+ *
+ * @example
+ * ```ts
+ * import { CopilotAuth, ClaudeAuth } from "@witqq/agent-sdk/auth";
+ *
+ * const authHandler = createAuthHandler({
+ *   tokenStore: new FileTokenStore({ directory: ".tokens" }),
+ *   createCopilotAuth: () => new CopilotAuth(),
+ *   createClaudeAuth: () => new ClaudeAuth(),
+ *   onAuth: (provider, token) => {
+ *     // Rebuild runtime with new credentials
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthHandler(options: AuthHandlerOptions): (req: ReadableRequest, res: WritableResponse) => Promise<void>;
+
+/**
+ * CORS middleware — standalone composable function.
+ * Returns true if it fully handled the request (OPTIONS preflight),
+ * false if the caller should continue processing.
+ */
+/** Configuration for CORS middleware */
+interface CorsOptions {
+    /** Allowed origins. Default: "*" (any origin) */
+    origin?: string | string[];
+    /** Allowed HTTP methods. Default: common REST methods */
+    methods?: string[];
+    /** Allowed request headers. Default: ["Content-Type"] */
+    headers?: string[];
+    /** Max age for preflight cache in seconds. Default: 86400 (24h) */
+    maxAge?: number;
+}
+/** Minimal request interface for CORS */
+interface CorsRequest {
+    readonly method?: string;
+    readonly headers?: Record<string, string | string[] | undefined>;
+}
+/** Minimal response interface for CORS */
+interface CorsResponse {
+    setHeader(name: string, value: string): void;
+    writeHead(statusCode: number): void;
+    end(): void;
+}
+/**
+ * Create a CORS middleware function.
+ *
+ * @returns A function that sets CORS headers and handles OPTIONS preflight.
+ *          Returns `true` if the request was fully handled (preflight),
+ *          `false` if the caller should continue processing.
+ */
+declare function corsMiddleware(options?: CorsOptions): (req: CorsRequest, res: CorsResponse) => boolean;
+
+/**
+ * createChatServer — one-call setup combining runtime, chat handler, auth handler, CORS,
+ * and static file serving into a single HTTP request handler.
+ *
+ * Routes:
+ * - CORS preflight (OPTIONS) on all paths
+ * - {chatPrefix}/*   → createChatHandler routes
+ * - {authPrefix}/*   → createAuthHandler routes (if tokenStore provided)
+ * - {staticPrefix}/* → static file serving (if staticDir provided)
+ * - Everything else  → 404
+ */
+
+/** Configuration for createChatServer */
+interface ChatServerOptions {
+    /** The chat runtime instance to serve */
+    runtime: IChatRuntime;
+    /** Prefix for chat API routes. Default: "/api/chat" */
+    chatPrefix?: string;
+    /** Auth handler options. If provided, auth routes are mounted. */
+    auth?: AuthHandlerOptions;
+    /** Prefix for auth routes. Default: "/api/auth" */
+    authPrefix?: string;
+    /** CORS options. Pass false to disable CORS. Default: enabled with permissive settings */
+    cors?: CorsOptions | false;
+    /** Directory to serve static files from. Omit to disable static serving. */
+    staticDir?: string;
+    /** Prefix for static file routes. Default: "/" */
+    staticPrefix?: string;
+    /** Chat handler options (maxBodySize, etc.) */
+    chatHandlerOptions?: Omit<ChatHandlerOptions, "prefix">;
+}
+/** Request handler type returned by createChatServer */
+type RequestHandler = (req: ReadableRequest, res: WritableResponse) => Promise<void>;
+/**
+ * Create a combined HTTP request handler that routes to chat, auth, static, or 404.
+ *
+ * @param options - Server configuration
+ * @returns Async request handler
+ *
+ * @example
+ * ```ts
+ * import http from "node:http";
+ * import { createChatServer } from "@witqq/agent-sdk/chat/server";
+ *
+ * const handler = createChatServer({
+ *   runtime,
+ *   auth: { tokenStore },
+ *   staticDir: "./public",
+ * });
+ *
+ * http.createServer(handler).listen(3000);
+ * ```
+ */
+declare function createChatServer(options: ChatServerOptions): RequestHandler;
+
+export { type AuthHandlerOptions, type AuthProvider, type ChatHandlerOptions, type ChatServerOptions, type CorsOptions, FileTokenStore, type FileTokenStoreOptions, type IClaudeAuth, type ICopilotAuth, type ITokenStore, InMemoryTokenStore, type OnAuthCallback, type ReadableRequest, type RequestHandler, type WritableResponse, corsMiddleware, createAuthHandler, createChatHandler, createChatServer };