@providerprotocol/ai 0.0.19 → 0.0.21

package/README.md

@@ -314,43 +314,116 @@ try {
 
 **Error Codes:** `AUTHENTICATION_FAILED`, `RATE_LIMITED`, `CONTEXT_LENGTH_EXCEEDED`, `MODEL_NOT_FOUND`, `INVALID_REQUEST`, `INVALID_RESPONSE`, `CONTENT_FILTERED`, `QUOTA_EXCEEDED`, `PROVIDER_ERROR`, `NETWORK_ERROR`, `TIMEOUT`, `CANCELLED`
 
-## Proxy Server
+## API Gateway / Proxy
 
-Build backend proxies to hide API keys from clients.
+Build AI API gateways with your own authentication. Users authenticate with your platform - AI provider keys stay hidden on the server.
 
-### Server
+> **Security Note:** The proxy works without any configuration, but this means **no authentication by default**. Always add your own auth layer in production - the examples below show how.
+
+### Server (Bun/Deno/Cloudflare Workers)
 
 ```typescript
 import { llm } from '@providerprotocol/ai';
 import { anthropic } from '@providerprotocol/ai/anthropic';
-import { webapi, parseBody, toJSON, toSSE } from '@providerprotocol/ai/proxy';
+import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
+import { parseBody, toJSON, toSSE, toError } from '@providerprotocol/ai/proxy';
 
-const claude = llm({ model: anthropic('claude-sonnet-4-20250514') });
+// Server manages AI provider keys - users never see them
+const claude = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  config: {
+    apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
+    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
+  },
+});
 
 Bun.serve({
   port: 3000,
-  fetch: webapi(async (req) => {
+  async fetch(req) {
+    // Authenticate with YOUR platform credentials
+    const token = req.headers.get('Authorization')?.replace('Bearer ', '');
+    const user = await validatePlatformToken(token ?? '');
+    if (!user) return toError('Unauthorized', 401);
+
+    // Rate limit, track usage, bill user, etc.
+    await trackUsage(user.id);
+
     const { messages, system, params } = parseBody(await req.json());
 
     if (params?.stream) {
       return toSSE(claude.stream(messages, { system }));
     }
-
     return toJSON(await claude.generate(messages, { system }));
-  }),
+  },
 });
 ```
 
 ### Client
 
+Clients authenticate with your platform token. They get automatic retry on network failures to your proxy.
+
 ```typescript
 import { llm } from '@providerprotocol/ai';
 import { proxy } from '@providerprotocol/ai/proxy';
+import { ExponentialBackoff } from '@providerprotocol/ai/http';
+
+const claude = llm({
+  model: proxy('https://api.yourplatform.com/ai'),
+  config: {
+    headers: { 'Authorization': 'Bearer user-platform-token' },
+    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
+    timeout: 30000,
+  },
+});
 
-const claude = llm({ model: proxy('http://localhost:3000') });
 const turn = await claude.generate('Hello!');
 ```
 
+### Framework Adapters
+
+Server adapters for Express, Fastify, and Nuxt/H3:
+
+```typescript
+// Express
+import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
+app.post('/ai', authMiddleware, async (req, res) => {
+  const { messages, system, params } = parseBody(req.body);
+  if (params?.stream) {
+    expressAdapter.streamSSE(claude.stream(messages, { system }), res);
+  } else {
+    expressAdapter.sendJSON(await claude.generate(messages, { system }), res);
+  }
+});
+
+// Fastify
+import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
+app.post('/ai', async (request, reply) => {
+  const { messages, system, params } = parseBody(request.body);
+  if (params?.stream) {
+    return fastifyAdapter.streamSSE(claude.stream(messages, { system }), reply);
+  }
+  return fastifyAdapter.sendJSON(await claude.generate(messages, { system }), reply);
+});
+
+// Nuxt/H3 (server/api/ai.post.ts)
+import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
+export default defineEventHandler(async (event) => {
+  const { messages, system, params } = parseBody(await readBody(event));
+  if (params?.stream) {
+    return h3Adapter.streamSSE(claude.stream(messages, { system }), event);
+  }
+  return h3Adapter.sendJSON(await claude.generate(messages, { system }), event);
+});
+```
+
+**What this enables:**
+- Users auth with your platform credentials (JWT, API keys, sessions)
+- You manage/rotate AI provider keys centrally
+- Per-user rate limiting, usage tracking, billing
+- Model access control (different users get different models)
+- Request/response logging, content filtering
+- Double-layer retry: client retries to proxy, server retries to AI provider
+
 ## xAI API Modes
 
 xAI supports multiple API compatibility modes:

package/dist/anthropic/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Provider } from '../provider-BBMBZuGn.js';
+import { g as Provider } from '../provider-DGQHYE6I.js';
 
 /**
  * @fileoverview Anthropic API type definitions.
@@ -6,6 +6,83 @@ import { d as Provider } from '../provider-BBMBZuGn.js';
  * Contains TypeScript interfaces for Anthropic's Messages API request/response
  * structures, streaming events, and provider-specific parameters.
  */
+/**
+ * Known Anthropic beta header values.
+ *
+ * Beta features are enabled by passing these values in the `betas` config option
+ * or via the `anthropic-beta` HTTP header. Multiple betas can be enabled simultaneously.
+ *
+ * @example
+ * ```typescript
+ * import { anthropic, betas } from 'provider-protocol/anthropic';
+ *
+ * // Using the betas config option (recommended)
+ * const provider = anthropic('claude-sonnet-4-20250514', {
+ *   betas: [betas.structuredOutputs, betas.interleavedThinking],
+ * });
+ *
+ * // Or use string values directly for new/unlisted betas
+ * const provider = anthropic('claude-sonnet-4-20250514', {
+ *   betas: ['new-beta-2025-12-01'],
+ * });
+ * ```
+ */
+declare const betas: {
+    /** Guaranteed JSON schema conformance for responses. Available for Claude Sonnet 4.5+. */
+    readonly structuredOutputs: "structured-outputs-2025-11-13";
+    /** Enables Claude to think between tool calls in Claude 4 models. */
+    readonly interleavedThinking: "interleaved-thinking-2025-05-14";
+    /** Developer mode for full thinking output visibility. */
+    readonly devFullThinking: "dev-full-thinking-2025-05-14";
+    /** Effort parameter for Claude Opus 4.5 - controls response thoroughness vs efficiency. */
+    readonly effort: "effort-2025-11-24";
+    /** Legacy computer use tool (Claude 3.x models). */
+    readonly computerUseLegacy: "computer-use-2024-10-22";
+    /** Computer use tool for Claude 4 models (mouse, keyboard, screenshots). */
+    readonly computerUse: "computer-use-2025-01-24";
+    /** Computer use tool for Claude Opus 4.5 with additional commands. */
+    readonly computerUseOpus: "computer-use-2025-11-24";
+    /** Enables up to 8,192 output tokens from Claude Sonnet 3.5. */
+    readonly maxTokens35Sonnet: "max-tokens-3-5-sonnet-2024-07-15";
+    /** Enables 128K token output length. */
+    readonly output128k: "output-128k-2025-02-19";
+    /** Enables 1 million token context window for Claude Sonnet 4. */
+    readonly context1m: "context-1m-2025-08-07";
+    /** Reduces output token consumption by up to 70% for tool calls. */
+    readonly tokenEfficientTools: "token-efficient-tools-2025-02-19";
+    /** Streams tool use parameters without buffering/JSON validation. */
+    readonly fineGrainedToolStreaming: "fine-grained-tool-streaming-2025-05-14";
+    /** Code execution tool for running Python/Bash in secure sandbox. */
+    readonly codeExecution: "code-execution-2025-08-25";
+    /** Advanced tool use: Tool Search, Programmatic Tool Calling, Tool Use Examples. */
+    readonly advancedToolUse: "advanced-tool-use-2025-11-20";
+    /** Files API for uploading and managing files. */
+    readonly filesApi: "files-api-2025-04-14";
+    /** PDF document support. */
+    readonly pdfs: "pdfs-2024-09-25";
+    /** MCP connector to connect to remote MCP servers. */
+    readonly mcpClient: "mcp-client-2025-04-04";
+    /** Updated MCP client. */
+    readonly mcpClientLatest: "mcp-client-2025-11-20";
+    /** Prompt caching for reduced latency and costs. Now works automatically with cache_control. */
+    readonly promptCaching: "prompt-caching-2024-07-31";
+    /** Enables 1-hour cache TTL (vs default 5-minute). */
+    readonly extendedCacheTtl: "extended-cache-ttl-2025-04-11";
+    /** Automatic tool call clearing for context management. */
+    readonly contextManagement: "context-management-2025-06-27";
+    /** Handling for when model context window is exceeded. */
+    readonly modelContextWindowExceeded: "model-context-window-exceeded-2025-08-26";
+    /** Message Batches API for async processing at 50% cost. */
+    readonly messageBatches: "message-batches-2024-09-24";
+    /** Token counting endpoint. */
+    readonly tokenCounting: "token-counting-2024-11-01";
+    /** Agent Skills for specialized tasks (PowerPoint, Excel, Word, PDF). */
+    readonly skills: "skills-2025-10-02";
+};
+/** Type representing any valid beta key from the betas object. */
+type BetaKey = keyof typeof betas;
+/** Type representing a beta value (either a known constant or arbitrary string). */
+type BetaValue = (typeof betas)[BetaKey] | string;
 /**
  * Provider-specific parameters for Anthropic Claude models.
  *
@@ -68,7 +145,7 @@ interface AnthropicLLMParams {
      * const model = llm({
      *   model: anthropic('claude-sonnet-4-20250514'),
      *   params: {
-     *     builtInTools: [
+     *     tools: [
      *       tools.webSearch({ max_uses: 5 }),
      *       tools.codeExecution(),
      *     ],
@@ -76,13 +153,56 @@ interface AnthropicLLMParams {
      * });
      * ```
      */
-    builtInTools?: AnthropicBuiltInTool[];
+    tools?: AnthropicBuiltInTool[];
     /**
      * Container ID for code execution tool reuse.
      * Pass the container ID from a previous response to reuse the same environment.
      */
     container?: string;
 }
+/**
+ * Request body structure for Anthropic's Messages API.
+ *
+ * This interface represents the full request payload sent to the
+ * `/v1/messages` endpoint.
+ */
+/**
+ * Native structured output format configuration.
+ *
+ * When provided, Claude's response will be constrained to match the
+ * specified JSON schema. Requires the beta header `structured-outputs-2025-11-13`.
+ *
+ * @example
+ * ```typescript
+ * const outputFormat: AnthropicOutputFormat = {
+ *   type: 'json_schema',
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'integer' },
+ *     },
+ *     required: ['name', 'age'],
+ *     additionalProperties: false,
+ *   },
+ * };
+ * ```
+ */
+interface AnthropicOutputFormat {
+    /** Output format type - currently only 'json_schema' is supported. */
+    type: 'json_schema';
+    /** JSON Schema defining the expected response structure. */
+    schema: {
+        /** Schema type (always 'object' for structured outputs). */
+        type: 'object';
+        /** Property definitions for each field. */
+        properties: Record<string, unknown>;
+        /** List of required property names. */
+        required?: string[];
+        /** Must be false for structured outputs. */
+        additionalProperties?: false;
+    };
+}
 /**
  * Anthropic-specific HTTP headers for API requests.
  *
@@ -454,7 +574,7 @@ declare function toolSearchTool(options?: {
  * const model = llm({
  *   model: anthropic('claude-sonnet-4-20250514'),
  *   params: {
- *     builtInTools: [
+ *     tools: [
  *       tools.webSearch({ max_uses: 5 }),
  *       tools.codeExecution(),
  *     ],
@@ -478,25 +598,75 @@ declare const tools: {
 };
 
 /**
- * Anthropic provider instance for the Universal Provider Protocol.
+ * Options for configuring an Anthropic model reference.
+ *
+ * @example
+ * ```typescript
+ * import { anthropic, betas } from 'provider-protocol/anthropic';
+ *
+ * // Enable structured outputs beta
+ * const model = anthropic('claude-sonnet-4-20250514', {
+ *   betas: [betas.structuredOutputs],
+ * });
+ *
+ * // Enable multiple betas
+ * const modelWithBetas = anthropic('claude-sonnet-4-20250514', {
+ *   betas: [betas.structuredOutputs, betas.interleavedThinking],
+ * });
+ *
+ * // Use string values for new/unlisted betas
+ * const modelWithCustomBeta = anthropic('claude-sonnet-4-20250514', {
+ *   betas: ['new-beta-2025-12-01'],
+ * });
+ * ```
+ */
+interface AnthropicModelOptions {
+    /**
+     * Beta features to enable for this model.
+     *
+     * Use values from the `betas` export or pass arbitrary strings for new betas.
+     * Multiple betas are combined into a comma-separated `anthropic-beta` header.
+     */
+    betas?: BetaValue[];
+}
+/**
+ * Anthropic provider for the Universal Provider Protocol.
  *
  * Provides access to Claude language models through a unified interface.
- * Currently supports the LLM modality with full streaming, tool use,
- * structured output, and image input capabilities.
+ * Supports LLM modality with streaming, tool use, structured output,
+ * and image input capabilities.
+ *
+ * @param modelId - The model identifier (e.g., 'claude-sonnet-4-20250514')
+ * @param options - Optional configuration including beta features
+ * @returns A model reference for use with `llm()`
  *
  * @example
  * ```typescript
- * import { anthropic } from './providers/anthropic';
+ * import { anthropic, betas } from 'provider-protocol/anthropic';
+ * import { llm } from 'provider-protocol';
+ *
+ * // Basic usage
+ * const model = llm({ model: anthropic('claude-sonnet-4-20250514') });
+ *
+ * // With structured outputs beta
+ * const modelWithBetas = llm({
+ *   model: anthropic('claude-sonnet-4-20250514', {
+ *     betas: [betas.structuredOutputs],
+ *   }),
+ *   structure: { properties: { name: { type: 'string' } } },
+ * });
  *
- * const claude = anthropic.llm.bind('claude-sonnet-4-20250514');
- * const response = await claude.complete({
- *   messages: [new UserMessage([{ type: 'text', text: 'Hello!' }])],
- *   config: { apiKey: 'sk-...' },
+ * // With multiple betas
+ * const advancedModel = llm({
+ *   model: anthropic('claude-sonnet-4-20250514', {
+ *     betas: [betas.structuredOutputs, betas.tokenEfficientTools],
+ *   }),
  * });
  * ```
  *
+ * @see {@link betas} for available beta features
  * @see {@link AnthropicLLMParams} for provider-specific parameters
  */
-declare const anthropic: Provider<unknown>;
+declare const anthropic: Provider<AnthropicModelOptions>;
 
-export { type AnthropicBashTool, type AnthropicBuiltInTool, type AnthropicCodeExecutionTool, type AnthropicComputerTool, type AnthropicHeaders, type AnthropicLLMParams, type AnthropicTextEditorTool, type AnthropicToolSearchTool, type AnthropicUserLocation, type AnthropicWebSearchTool, anthropic, tools };
+export { type AnthropicBashTool, type AnthropicBuiltInTool, type AnthropicCodeExecutionTool, type AnthropicComputerTool, type AnthropicHeaders, type AnthropicLLMParams, type AnthropicModelOptions, type AnthropicOutputFormat, type AnthropicTextEditorTool, type AnthropicToolSearchTool, type AnthropicUserLocation, type AnthropicWebSearchTool, type BetaKey, type BetaValue, anthropic, betas, tools };