@providerprotocol/ai 0.0.16 → 0.0.18

package/dist/proxy/index.d.ts

@@ -0,0 +1,611 @@
+import { d as Provider, f as ModelReference } from '../provider-D5MO3-pS.js';
+import { M as Message, b as MessageJSON, T as Turn, $ as TurnJSON, g as StreamEvent, S as StreamResult, J as JSONSchema, u as ToolMetadata, c as Tool } from '../stream-BjyVzBxV.js';
+
+/**
+ * @fileoverview Proxy provider types.
+ *
+ * Defines the configuration options and parameters for the proxy provider,
+ * which transports PP requests over HTTP to a backend server.
+ *
+ * @module providers/proxy/types
+ */
+/**
+ * Proxy-specific LLM parameters.
+ *
+ * These parameters are passed through to the backend server.
+ * The server decides how to interpret them based on its own provider.
+ */
+interface ProxyLLMParams {
+    /** Parameters are passed through to the backend */
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for creating a proxy provider.
+ */
+interface ProxyProviderOptions {
+    /** The endpoint URL to proxy requests to */
+    endpoint: string;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Per-request options for proxy calls.
+ */
+interface ProxyRequestOptions {
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+}
+
+/**
+ * @fileoverview Serialization utilities for proxy transport.
+ *
+ * Handles converting PP types to/from JSON for HTTP transport.
+ * These are pure functions with no side effects.
+ *
+ * @module providers/proxy/serialization
+ */
+
+/**
+ * Convert a Message to MessageJSON format.
+ */
+declare function serializeMessage(m: Message): MessageJSON;
+/**
+ * Reconstruct a Message from MessageJSON format.
+ */
+declare function deserializeMessage(json: MessageJSON): Message;
+/**
+ * Serialize a Turn to JSON-transportable format.
+ */
+declare function serializeTurn(turn: Turn): TurnJSON;
+/**
+ * Serialize a StreamEvent for JSON transport.
+ * Converts Uint8Array data to base64 string.
+ */
+declare function serializeStreamEvent(event: StreamEvent): StreamEvent;
+/**
+ * Deserialize a StreamEvent from JSON transport.
+ * Converts base64 string data back to Uint8Array.
+ */
+declare function deserializeStreamEvent(event: StreamEvent): StreamEvent;
+
+/**
+ * @fileoverview H3/Nitro/Nuxt adapter for proxy server.
+ *
+ * Provides utilities for using PP proxy with H3-based servers
+ * (Nuxt, Nitro, or standalone H3).
+ *
+ * @example
+ * ```typescript
+ * // Nuxt server route: server/api/ai.post.ts
+ * import { llm, anthropic } from '@providerprotocol/ai';
+ * import { parseBody } from '@providerprotocol/ai/proxy';
+ * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const body = await readBody(event);
+ *   const { messages, system, params } = parseBody(body);
+ *   const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
+ *
+ *   const wantsStream = getHeader(event, 'accept')?.includes('text/event-stream');
+ *   if (wantsStream) {
+ *     return h3Adapter.streamSSE(instance.stream(messages), event);
+ *   } else {
+ *     const turn = await instance.generate(messages);
+ *     return h3Adapter.sendJSON(turn, event);
+ *   }
+ * });
+ * ```
+ *
+ * @module providers/proxy/server/h3
+ */
+
+/**
+ * H3 Event interface (minimal type to avoid dependency).
+ */
+interface H3Event {
+    node: {
+        res: {
+            setHeader(name: string, value: string): void;
+            write(chunk: string): boolean;
+            end(): void;
+        };
+    };
+}
+/**
+ * Send a Turn as JSON response.
+ *
+ * @param turn - The completed inference turn
+ * @param event - H3 event object
+ * @returns Serialized turn data
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate(messages);
+ * return h3Adapter.sendJSON(turn, event);
+ * ```
+ */
+declare function sendJSON$2(turn: Turn, event: H3Event): unknown;
+/**
+ * Stream a StreamResult as Server-Sent Events.
+ *
+ * @param stream - The StreamResult from instance.stream()
+ * @param event - H3 event object
+ *
+ * @example
+ * ```typescript
+ * const stream = instance.stream(messages);
+ * return h3Adapter.streamSSE(stream, event);
+ * ```
+ */
+declare function streamSSE$2(stream: StreamResult, event: H3Event): void;
+/**
+ * Create a ReadableStream for H3's sendStream utility.
+ *
+ * Use this with H3's sendStream for better integration:
+ * ```typescript
+ * import { sendStream } from 'h3';
+ * return sendStream(event, h3Adapter.createSSEStream(stream));
+ * ```
+ *
+ * @param stream - The StreamResult from instance.stream()
+ * @returns A ReadableStream of SSE data
+ */
+declare function createSSEStream(stream: StreamResult): ReadableStream<Uint8Array>;
+/**
+ * Send an error response.
+ *
+ * @param message - Error message
+ * @param status - HTTP status code
+ * @param event - H3 event object
+ * @returns Error object for H3 to serialize
+ */
+declare function sendError$2(message: string, status: number, event: H3Event): {
+    error: string;
+    statusCode: number;
+};
+/**
+ * H3/Nitro/Nuxt adapter utilities.
+ */
+declare const h3: {
+    sendJSON: typeof sendJSON$2;
+    streamSSE: typeof streamSSE$2;
+    createSSEStream: typeof createSSEStream;
+    sendError: typeof sendError$2;
+};
+
+/**
+ * @fileoverview Fastify adapter for proxy server.
+ *
+ * Provides utilities for using PP proxy with Fastify servers.
+ * These adapters convert PP types to Fastify-compatible responses.
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { llm, anthropic } from '@providerprotocol/ai';
+ * import { parseBody } from '@providerprotocol/ai/proxy';
+ * import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
+ *
+ * const app = Fastify();
+ *
+ * app.post('/api/ai', async (request, reply) => {
+ *   const { messages, system, params } = parseBody(request.body);
+ *   const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
+ *
+ *   if (request.headers.accept?.includes('text/event-stream')) {
+ *     return fastifyAdapter.streamSSE(instance.stream(messages), reply);
+ *   } else {
+ *     const turn = await instance.generate(messages);
+ *     return fastifyAdapter.sendJSON(turn, reply);
+ *   }
+ * });
+ * ```
+ *
+ * @module providers/proxy/server/fastify
+ */
+
+/**
+ * Fastify Reply interface (minimal type to avoid dependency).
+ */
+interface FastifyReply {
+    header(name: string, value: string): FastifyReply;
+    status(code: number): FastifyReply;
+    send(payload: unknown): FastifyReply;
+    raw: {
+        write(chunk: string): boolean;
+        end(): void;
+    };
+}
+/**
+ * Send a Turn as JSON response.
+ *
+ * @param turn - The completed inference turn
+ * @param reply - Fastify reply object
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate(messages);
+ * return fastifyAdapter.sendJSON(turn, reply);
+ * ```
+ */
+declare function sendJSON$1(turn: Turn, reply: FastifyReply): FastifyReply;
+/**
+ * Stream a StreamResult as Server-Sent Events.
+ *
+ * @param stream - The StreamResult from instance.stream()
+ * @param reply - Fastify reply object
+ *
+ * @example
+ * ```typescript
+ * const stream = instance.stream(messages);
+ * return fastifyAdapter.streamSSE(stream, reply);
+ * ```
+ */
+declare function streamSSE$1(stream: StreamResult, reply: FastifyReply): FastifyReply;
+/**
+ * Send an error response.
+ *
+ * @param message - Error message
+ * @param status - HTTP status code
+ * @param reply - Fastify reply object
+ */
+declare function sendError$1(message: string, status: number, reply: FastifyReply): FastifyReply;
+/**
+ * Fastify adapter utilities.
+ */
+declare const fastify: {
+    sendJSON: typeof sendJSON$1;
+    streamSSE: typeof streamSSE$1;
+    sendError: typeof sendError$1;
+};
+
+/**
+ * @fileoverview Express/Connect adapter for proxy server.
+ *
+ * Provides utilities for using PP proxy with Express.js or Connect-based servers.
+ * These adapters convert PP types to Express-compatible responses.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { llm, anthropic } from '@providerprotocol/ai';
+ * import { parseBody, bindTools } from '@providerprotocol/ai/proxy';
+ * import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * app.post('/api/ai', async (req, res) => {
+ *   const { messages, system, params } = parseBody(req.body);
+ *   const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
+ *
+ *   if (req.headers.accept?.includes('text/event-stream')) {
+ *     expressAdapter.streamSSE(instance.stream(messages), res);
+ *   } else {
+ *     const turn = await instance.generate(messages);
+ *     expressAdapter.sendJSON(turn, res);
+ *   }
+ * });
+ * ```
+ *
+ * @module providers/proxy/server/express
+ */
+
+/**
+ * Express Response interface (minimal type to avoid dependency).
+ */
+interface ExpressResponse {
+    setHeader(name: string, value: string): void;
+    status(code: number): ExpressResponse;
+    write(chunk: string): boolean;
+    end(): void;
+    json(body: unknown): void;
+}
+/**
+ * Send a Turn as JSON response.
+ *
+ * @param turn - The completed inference turn
+ * @param res - Express response object
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate(messages);
+ * expressAdapter.sendJSON(turn, res);
+ * ```
+ */
+declare function sendJSON(turn: Turn, res: ExpressResponse): void;
+/**
+ * Stream a StreamResult as Server-Sent Events.
+ *
+ * @param stream - The StreamResult from instance.stream()
+ * @param res - Express response object
+ *
+ * @example
+ * ```typescript
+ * const stream = instance.stream(messages);
+ * expressAdapter.streamSSE(stream, res);
+ * ```
+ */
+declare function streamSSE(stream: StreamResult, res: ExpressResponse): void;
+/**
+ * Send an error response.
+ *
+ * @param message - Error message
+ * @param status - HTTP status code
+ * @param res - Express response object
+ */
+declare function sendError(message: string, status: number, res: ExpressResponse): void;
+/**
+ * Express adapter utilities.
+ */
+declare const express: {
+    sendJSON: typeof sendJSON;
+    streamSSE: typeof streamSSE;
+    sendError: typeof sendError;
+};
+
+/**
+ * @fileoverview Web API adapter for proxy server.
+ *
+ * Provides utilities for using PP proxy with Web API native frameworks
+ * (Bun, Deno, Next.js App Router, Cloudflare Workers).
+ *
+ * These utilities return standard Web API Response objects that work
+ * directly with modern runtimes.
+ *
+ * @example
+ * ```typescript
+ * import { llm, anthropic } from '@providerprotocol/ai';
+ * import { parseBody, toJSON, toSSE } from '@providerprotocol/ai/proxy';
+ *
+ * // Bun.serve / Deno.serve / Next.js App Router
+ * export async function POST(req: Request) {
+ *   const { messages, system } = parseBody(await req.json());
+ *   const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
+ *
+ *   if (req.headers.get('accept')?.includes('text/event-stream')) {
+ *     return toSSE(instance.stream(messages));
+ *   }
+ *   return toJSON(await instance.generate(messages));
+ * }
+ * ```
+ *
+ * @module providers/proxy/server/webapi
+ */
+
+/**
+ * Parsed request body from a proxy HTTP request.
+ * This is just the deserialized PP data from the request body.
+ */
+interface ParsedRequest {
+    messages: Message[];
+    system?: string | unknown[];
+    params?: Record<string, unknown>;
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters: JSONSchema;
+        metadata?: ToolMetadata;
+    }>;
+    structure?: JSONSchema;
+}
+/**
+ * Parse an HTTP request body into PP types.
+ *
+ * @param body - The JSON-parsed request body
+ * @returns Deserialized PP data
+ *
+ * @example
+ * ```typescript
+ * const body = await req.json();
+ * const { messages, system, params } = parseBody(body);
+ *
+ * const instance = llm({ model: anthropic('...'), system, params });
+ * const turn = await instance.generate(messages);
+ * ```
+ */
+declare function parseBody(body: unknown): ParsedRequest;
+/**
+ * Create a JSON Response from a Turn.
+ *
+ * @param turn - The completed inference turn
+ * @returns HTTP Response with JSON body
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate(messages);
+ * return toJSON(turn);
+ * ```
+ */
+declare function toJSON(turn: Turn): Response;
+/**
+ * Create an SSE Response from a StreamResult.
+ *
+ * Streams PP StreamEvents as SSE, then sends the final Turn data.
+ *
+ * @param stream - The StreamResult from instance.stream()
+ * @returns HTTP Response with SSE body
+ *
+ * @example
+ * ```typescript
+ * const stream = instance.stream(messages);
+ * return toSSE(stream);
+ * ```
+ */
+declare function toSSE(stream: StreamResult): Response;
+/**
+ * Create an error Response.
+ *
+ * @param message - Error message
+ * @param status - HTTP status code (default: 500)
+ * @returns HTTP Response with error body
+ */
+declare function toError(message: string, status?: number): Response;
+/**
+ * Bind tool schemas to implementation functions.
+ *
+ * Takes tool schemas from the request and binds them to your
+ * server-side implementations.
+ *
+ * @param schemas - Tool schemas from the request
+ * @param implementations - Map of tool name to implementation
+ * @returns Array of complete Tool objects
+ *
+ * @example
+ * ```typescript
+ * const { tools: schemas } = parseBody(body);
+ *
+ * const tools = bindTools(schemas, {
+ *   get_weather: async ({ location }) => fetchWeather(location),
+ *   search: async ({ query }) => searchDB(query),
+ * });
+ *
+ * const instance = llm({ model, tools });
+ * ```
+ */
+declare function bindTools(schemas: ParsedRequest['tools'], implementations: Record<string, (params: unknown) => unknown | Promise<unknown>>): Tool[];
+/**
+ * Web API adapter utilities.
+ *
+ * For use with Bun, Deno, Next.js App Router, Cloudflare Workers,
+ * and other frameworks that support Web API Response.
+ */
+declare const webapi: {
+    parseBody: typeof parseBody;
+    toJSON: typeof toJSON;
+    toSSE: typeof toSSE;
+    toError: typeof toError;
+    bindTools: typeof bindTools;
+};
+
+/**
+ * @fileoverview Shared types for proxy server adapters.
+ *
+ * @module providers/proxy/server/types
+ */
+
+/**
+ * Parsed request body from a proxy HTTP request.
+ */
+interface ParsedBody {
+    messages: Message[];
+    system?: string | unknown[];
+    params?: Record<string, unknown>;
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters: JSONSchema;
+        metadata?: ToolMetadata;
+    }>;
+    structure?: JSONSchema;
+}
+/**
+ * Handler function signature for proxy endpoints.
+ * Takes parsed request data and returns either a Turn or StreamResult.
+ */
+type ProxyHandler = (body: ParsedBody, meta: RequestMeta) => Promise<Turn> | StreamResult | Promise<StreamResult>;
+/**
+ * Metadata about the incoming request.
+ */
+interface RequestMeta {
+    /** Whether the client wants a streaming response */
+    wantsStream: boolean;
+    /** Raw headers from the request */
+    headers: Record<string, string | undefined>;
+}
+/**
+ * Options for adapter middleware.
+ */
+interface AdapterOptions {
+    /** Custom error handler */
+    onError?: (error: Error) => {
+        message: string;
+        status: number;
+    };
+}
+
+/**
+ * Server adapters namespace.
+ *
+ * Contains framework-specific adapters for Web API, Express, Fastify, and H3.
+ */
+declare const server: {
+    /** Web API adapter (Bun, Deno, Next.js, Workers) */
+    webapi: {
+        parseBody: typeof parseBody;
+        toJSON: typeof toJSON;
+        toSSE: typeof toSSE;
+        toError: typeof toError;
+        bindTools: typeof bindTools;
+    };
+    /** Express/Connect adapter */
+    express: {
+        sendJSON: typeof sendJSON;
+        streamSSE: typeof streamSSE;
+        sendError: typeof sendError;
+    };
+    /** Fastify adapter */
+    fastify: {
+        sendJSON: typeof sendJSON$1;
+        streamSSE: typeof streamSSE$1;
+        sendError: typeof sendError$1;
+    };
+    /** H3/Nitro/Nuxt adapter */
+    h3: {
+        sendJSON: typeof sendJSON$2;
+        streamSSE: typeof streamSSE$2;
+        createSSEStream: typeof createSSEStream;
+        sendError: typeof sendError$2;
+    };
+};
+
+/**
+ * Creates a proxy provider that transports PP requests over HTTP to a backend server.
+ *
+ * The proxy acts as a pure transport layer - PP types go in, PP types come out.
+ * The modelId is passed through to the backend, which decides which actual model to use.
+ *
+ * @param options - Configuration for the proxy endpoint
+ * @returns A provider that can be used with llm()
+ *
+ * @example
+ * ```typescript
+ * import { proxy } from './providers/proxy';
+ * import { llm } from './core/llm';
+ *
+ * const backend = proxy({ endpoint: '/api/ai' });
+ *
+ * const model = llm({
+ *   model: backend('gpt-4o'),
+ *   system: 'You are a helpful assistant.',
+ * });
+ *
+ * const turn = await model.generate('Hello!');
+ * ```
+ */
+declare function proxy(options: ProxyProviderOptions): Provider<ProxyRequestOptions>;
+/**
+ * Shorthand for creating a proxy model reference with default model ID.
+ *
+ * Creates a proxy provider and immediately returns a model reference using
+ * 'default' as the model identifier. Useful for simple single-endpoint setups.
+ *
+ * @param endpoint - The URL to proxy requests to
+ * @returns A model reference for use with llm()
+ *
+ * @example
+ * ```typescript
+ * import { proxyModel } from './providers/proxy';
+ * import { llm } from './core/llm';
+ *
+ * const model = llm({ model: proxyModel('/api/ai') });
+ * const turn = await model.generate('Hello!');
+ * ```
+ */
+declare function proxyModel(endpoint: string): ModelReference<ProxyRequestOptions>;
+
+export { type AdapterOptions, type ParsedBody, type ParsedRequest, type ProxyHandler, type ProxyLLMParams, type ProxyProviderOptions, type ProxyRequestOptions, type RequestMeta, TurnJSON, bindTools, deserializeMessage, deserializeStreamEvent, express, fastify, h3, parseBody, proxy, proxyModel, serializeMessage, serializeStreamEvent, serializeTurn, server, toError, toJSON, toSSE, webapi };