@providerprotocol/ai 0.0.18 → 0.0.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +364 -111
  2. package/dist/anthropic/index.d.ts +1 -1
  3. package/dist/anthropic/index.js +6 -6
  4. package/dist/chunk-P5IRTEM5.js +120 -0
  5. package/dist/chunk-P5IRTEM5.js.map +1 -0
  6. package/dist/{chunk-5FEAOEXV.js → chunk-U3FZWV4U.js} +53 -102
  7. package/dist/chunk-U3FZWV4U.js.map +1 -0
  8. package/dist/chunk-WAKD3OO5.js +224 -0
  9. package/dist/chunk-WAKD3OO5.js.map +1 -0
  10. package/dist/content-DEl3z_W2.d.ts +276 -0
  11. package/dist/google/index.d.ts +3 -1
  12. package/dist/google/index.js +123 -7
  13. package/dist/google/index.js.map +1 -1
  14. package/dist/http/index.d.ts +2 -2
  15. package/dist/http/index.js +4 -3
  16. package/dist/image-Dhq-Yuq4.d.ts +456 -0
  17. package/dist/index.d.ts +55 -163
  18. package/dist/index.js +81 -213
  19. package/dist/index.js.map +1 -1
  20. package/dist/ollama/index.d.ts +1 -1
  21. package/dist/ollama/index.js +6 -6
  22. package/dist/openai/index.d.ts +47 -20
  23. package/dist/openai/index.js +310 -7
  24. package/dist/openai/index.js.map +1 -1
  25. package/dist/openrouter/index.d.ts +1 -1
  26. package/dist/openrouter/index.js +6 -6
  27. package/dist/{provider-D5MO3-pS.d.ts → provider-BBMBZuGn.d.ts} +11 -11
  28. package/dist/proxy/index.d.ts +310 -86
  29. package/dist/proxy/index.js +33 -59
  30. package/dist/proxy/index.js.map +1 -1
  31. package/dist/{retry-DZ4Sqmxp.d.ts → retry-DR7YRJDz.d.ts} +1 -1
  32. package/dist/{stream-BjyVzBxV.d.ts → stream-DRHy6q1a.d.ts} +2 -275
  33. package/dist/xai/index.d.ts +29 -1
  34. package/dist/xai/index.js +119 -7
  35. package/dist/xai/index.js.map +1 -1
  36. package/package.json +1 -1
  37. package/dist/chunk-5FEAOEXV.js.map +0 -1
  38. package/dist/chunk-DZQHVGNV.js +0 -71
  39. package/dist/chunk-DZQHVGNV.js.map +0 -1
@@ -1,4 +1,4 @@
1
- import { d as Provider, f as ModelReference, b as LLMHandler, c as EmbeddingHandler } from '../provider-D5MO3-pS.js';
1
+ import { d as Provider, f as ModelReference, b as LLMHandler, c as EmbeddingHandler } from '../provider-BBMBZuGn.js';
2
2
 
3
3
  /**
4
4
  * @fileoverview OpenRouter Embeddings API Handler
@@ -8,14 +8,14 @@ import {
8
8
  parseSSEStream
9
9
  } from "../chunk-Z7RBRCRN.js";
10
10
  import {
11
- doFetch,
12
- doStreamFetch,
13
- normalizeHttpError,
14
11
  resolveApiKey
15
- } from "../chunk-5FEAOEXV.js";
12
+ } from "../chunk-P5IRTEM5.js";
16
13
  import {
17
- UPPError
18
- } from "../chunk-DZQHVGNV.js";
14
+ UPPError,
15
+ doFetch,
16
+ doStreamFetch,
17
+ normalizeHttpError
18
+ } from "../chunk-U3FZWV4U.js";
19
19
 
20
20
  // src/providers/openrouter/transform.completions.ts
21
21
  function transformRequest(request, modelId) {
@@ -308,7 +308,7 @@ interface ModelReference<TOptions = unknown> {
308
308
  * @typeParam TParams - Provider-specific parameter type
309
309
  * @internal
310
310
  */
311
- interface LLMHandler<TParams = any> {
311
+ interface LLMHandler<TParams = unknown> {
312
312
  /**
313
313
  * Binds a model ID to create an executable model instance.
314
314
  *
@@ -333,7 +333,7 @@ interface LLMHandler<TParams = any> {
333
333
  * @typeParam TParams - Provider-specific parameter type
334
334
  * @internal
335
335
  */
336
- interface EmbeddingHandler<TParams = any> {
336
+ interface EmbeddingHandler<TParams = unknown> {
337
337
  /** Supported input types for embeddings */
338
338
  readonly supportedInputs: ('text' | 'image')[];
339
339
  /**
@@ -359,7 +359,7 @@ interface EmbeddingHandler<TParams = any> {
359
359
  * @typeParam TParams - Provider-specific parameter type
360
360
  * @internal
361
361
  */
362
- interface ImageHandler<TParams = any> {
362
+ interface ImageHandler<TParams = unknown> {
363
363
  /**
364
364
  * Binds a model ID to create an executable image model.
365
365
  *
@@ -382,7 +382,7 @@ interface ImageHandler<TParams = any> {
382
382
  *
383
383
  * @typeParam TParams - Provider-specific parameter type
384
384
  */
385
- interface BoundLLMModel<TParams = any> {
385
+ interface BoundLLMModel<TParams = unknown> {
386
386
  /** The model identifier */
387
387
  readonly modelId: string;
388
388
  /** Reference to the parent provider */
@@ -396,7 +396,7 @@ interface BoundLLMModel<TParams = any> {
396
396
  *
397
397
  * @typeParam TParams - Provider-specific parameter type
398
398
  */
399
- interface BoundEmbeddingModel<TParams = any> {
399
+ interface BoundEmbeddingModel<TParams = unknown> {
400
400
  /** The model identifier */
401
401
  readonly modelId: string;
402
402
  /** Reference to the parent provider */
@@ -419,7 +419,7 @@ interface BoundEmbeddingModel<TParams = any> {
419
419
  * Request passed to provider's embed method.
420
420
  * @internal
421
421
  */
422
- interface EmbeddingRequest<TParams = any> {
422
+ interface EmbeddingRequest<TParams = unknown> {
423
423
  /** Inputs to embed */
424
424
  inputs: EmbeddingInput[];
425
425
  /** Provider-specific parameters (passed through unchanged) */
@@ -480,7 +480,7 @@ type EmbeddingInput = string | {
480
480
  *
481
481
  * @typeParam TParams - Provider-specific parameter type
482
482
  */
483
- interface BoundImageModel<TParams = any> {
483
+ interface BoundImageModel<TParams = unknown> {
484
484
  /** The model identifier */
485
485
  readonly modelId: string;
486
486
  /** Reference to the parent provider */
@@ -535,7 +535,7 @@ interface Provider<TOptions = unknown> {
535
535
  * @typeParam TParams - Model-specific parameters type
536
536
  * @typeParam TOptions - Provider-specific options type
537
537
  */
538
- type LLMProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
538
+ type LLMProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
539
539
  readonly modalities: {
540
540
  llm: LLMHandler<TParams>;
541
541
  };
@@ -548,7 +548,7 @@ type LLMProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
548
548
  * @typeParam TParams - Model-specific parameters type
549
549
  * @typeParam TOptions - Provider-specific options type
550
550
  */
551
- type EmbeddingProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
551
+ type EmbeddingProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
552
552
  readonly modalities: {
553
553
  embedding: EmbeddingHandler<TParams>;
554
554
  };
@@ -561,10 +561,10 @@ type EmbeddingProvider<TParams = any, TOptions = unknown> = Provider<TOptions> &
561
561
  * @typeParam TParams - Model-specific parameters type
562
562
  * @typeParam TOptions - Provider-specific options type
563
563
  */
564
- type ImageProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
564
+ type ImageProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
565
565
  readonly modalities: {
566
566
  image: ImageHandler<TParams>;
567
567
  };
568
568
  };
569
569
 
570
- export { type BoundEmbeddingModel as B, type EmbeddingInput as E, type ImageHandler as I, type KeyStrategy as K, type LLMProvider as L, type Modality as M, type ProviderConfig as P, type RetryStrategy as R, UPPError as U, type EmbeddingUsage as a, type LLMHandler as b, type EmbeddingHandler as c, type Provider as d, type ErrorCode as e, type ModelReference as f, type EmbeddingProvider as g, type ImageProvider as h, type BoundImageModel as i, type EmbeddingRequest as j, type EmbeddingResponse as k, type EmbeddingVector as l };
570
+ export { type BoundEmbeddingModel as B, type EmbeddingInput as E, type ImageHandler as I, type KeyStrategy as K, type LLMProvider as L, type Modality as M, type ProviderConfig as P, type RetryStrategy as R, UPPError as U, type EmbeddingUsage as a, type LLMHandler as b, type EmbeddingHandler as c, type Provider as d, type ErrorCode as e, type ModelReference as f, type EmbeddingProvider as g, type ImageProvider as h, type EmbeddingRequest as i, type EmbeddingResponse as j, type EmbeddingVector as k };
@@ -1,5 +1,6 @@
1
- import { d as Provider, f as ModelReference } from '../provider-D5MO3-pS.js';
2
- 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';
1
+ import { d as Provider, f as ModelReference } from '../provider-BBMBZuGn.js';
2
+ import { M as Message, b as MessageJSON, T as Turn, H as TurnJSON, f as StreamEvent, S as StreamResult, J as JSONSchema, k as ToolMetadata, c as Tool } from '../stream-DRHy6q1a.js';
3
+ import '../content-DEl3z_W2.js';
3
4
 
4
5
  /**
5
6
  * @fileoverview Proxy provider types.
@@ -78,28 +79,6 @@ declare function deserializeStreamEvent(event: StreamEvent): StreamEvent;
78
79
  * Provides utilities for using PP proxy with H3-based servers
79
80
  * (Nuxt, Nitro, or standalone H3).
80
81
  *
81
- * @example
82
- * ```typescript
83
- * // Nuxt server route: server/api/ai.post.ts
84
- * import { llm, anthropic } from '@providerprotocol/ai';
85
- * import { parseBody } from '@providerprotocol/ai/proxy';
86
- * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
87
- *
88
- * export default defineEventHandler(async (event) => {
89
- * const body = await readBody(event);
90
- * const { messages, system, params } = parseBody(body);
91
- * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
92
- *
93
- * const wantsStream = getHeader(event, 'accept')?.includes('text/event-stream');
94
- * if (wantsStream) {
95
- * return h3Adapter.streamSSE(instance.stream(messages), event);
96
- * } else {
97
- * const turn = await instance.generate(messages);
98
- * return h3Adapter.sendJSON(turn, event);
99
- * }
100
- * });
101
- * ```
102
- *
103
82
  * @module providers/proxy/server/h3
104
83
  */
105
84
 
@@ -169,6 +148,72 @@ declare function sendError$2(message: string, status: number, event: H3Event): {
169
148
  };
170
149
  /**
171
150
  * H3/Nitro/Nuxt adapter utilities.
151
+ *
152
+ * @example Basic usage
153
+ * ```typescript
154
+ * // Nuxt server route: server/api/ai.post.ts
155
+ * import { llm } from '@providerprotocol/ai';
156
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
157
+ * import { parseBody } from '@providerprotocol/ai/proxy';
158
+ * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
159
+ *
160
+ * export default defineEventHandler(async (event) => {
161
+ * const body = await readBody(event);
162
+ * const { messages, system, params } = parseBody(body);
163
+ * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
164
+ *
165
+ * const wantsStream = getHeader(event, 'accept')?.includes('text/event-stream');
166
+ * if (wantsStream) {
167
+ * return h3Adapter.streamSSE(instance.stream(messages), event);
168
+ * } else {
169
+ * const turn = await instance.generate(messages);
170
+ * return h3Adapter.sendJSON(turn, event);
171
+ * }
172
+ * });
173
+ * ```
174
+ *
175
+ * @example API Gateway with authentication (Nuxt)
176
+ * ```typescript
177
+ * // server/api/ai.post.ts
178
+ * import { llm } from '@providerprotocol/ai';
179
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
180
+ * import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
181
+ * import { parseBody } from '@providerprotocol/ai/proxy';
182
+ * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
183
+ *
184
+ * // Server manages AI provider keys - users never see them
185
+ * const claude = llm({
186
+ * model: anthropic('claude-sonnet-4-20250514'),
187
+ * config: {
188
+ * apiKey: new RoundRobinKeys([
189
+ * process.env.ANTHROPIC_KEY_1!,
190
+ * process.env.ANTHROPIC_KEY_2!,
191
+ * ]),
192
+ * retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
193
+ * },
194
+ * });
195
+ *
196
+ * export default defineEventHandler(async (event) => {
197
+ * // Authenticate with your platform credentials
198
+ * const token = getHeader(event, 'authorization')?.replace('Bearer ', '');
199
+ * const user = await validatePlatformToken(token);
200
+ * if (!user) {
201
+ * throw createError({ statusCode: 401, message: 'Unauthorized' });
202
+ * }
203
+ *
204
+ * // Track usage per user
205
+ * // await trackUsage(user.id);
206
+ *
207
+ * const body = await readBody(event);
208
+ * const { messages, system, params } = parseBody(body);
209
+ *
210
+ * if (params?.stream) {
211
+ * return h3Adapter.streamSSE(claude.stream(messages, { system }), event);
212
+ * }
213
+ * const turn = await claude.generate(messages, { system });
214
+ * return h3Adapter.sendJSON(turn, event);
215
+ * });
216
+ * ```
172
217
  */
173
218
  declare const h3: {
174
219
  sendJSON: typeof sendJSON$2;
@@ -183,28 +228,6 @@ declare const h3: {
183
228
  * Provides utilities for using PP proxy with Fastify servers.
184
229
  * These adapters convert PP types to Fastify-compatible responses.
185
230
  *
186
- * @example
187
- * ```typescript
188
- * import Fastify from 'fastify';
189
- * import { llm, anthropic } from '@providerprotocol/ai';
190
- * import { parseBody } from '@providerprotocol/ai/proxy';
191
- * import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
192
- *
193
- * const app = Fastify();
194
- *
195
- * app.post('/api/ai', async (request, reply) => {
196
- * const { messages, system, params } = parseBody(request.body);
197
- * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
198
- *
199
- * if (request.headers.accept?.includes('text/event-stream')) {
200
- * return fastifyAdapter.streamSSE(instance.stream(messages), reply);
201
- * } else {
202
- * const turn = await instance.generate(messages);
203
- * return fastifyAdapter.sendJSON(turn, reply);
204
- * }
205
- * });
206
- * ```
207
- *
208
231
  * @module providers/proxy/server/fastify
209
232
  */
210
233
 
@@ -256,6 +279,74 @@ declare function streamSSE$1(stream: StreamResult, reply: FastifyReply): Fastify
256
279
  declare function sendError$1(message: string, status: number, reply: FastifyReply): FastifyReply;
257
280
  /**
258
281
  * Fastify adapter utilities.
282
+ *
283
+ * @example Basic usage
284
+ * ```typescript
285
+ * import Fastify from 'fastify';
286
+ * import { llm } from '@providerprotocol/ai';
287
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
288
+ * import { parseBody } from '@providerprotocol/ai/proxy';
289
+ * import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
290
+ *
291
+ * const app = Fastify();
292
+ *
293
+ * app.post('/api/ai', async (request, reply) => {
294
+ * const { messages, system, params } = parseBody(request.body);
295
+ * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
296
+ *
297
+ * if (request.headers.accept?.includes('text/event-stream')) {
298
+ * return fastifyAdapter.streamSSE(instance.stream(messages), reply);
299
+ * } else {
300
+ * const turn = await instance.generate(messages);
301
+ * return fastifyAdapter.sendJSON(turn, reply);
302
+ * }
303
+ * });
304
+ * ```
305
+ *
306
+ * @example API Gateway with authentication
307
+ * ```typescript
308
+ * import Fastify from 'fastify';
309
+ * import { llm } from '@providerprotocol/ai';
310
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
311
+ * import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
312
+ * import { parseBody } from '@providerprotocol/ai/proxy';
313
+ * import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
314
+ *
315
+ * const app = Fastify();
316
+ *
317
+ * // Server manages AI provider keys - users never see them
318
+ * const claude = llm({
319
+ * model: anthropic('claude-sonnet-4-20250514'),
320
+ * config: {
321
+ * apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
322
+ * retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
323
+ * },
324
+ * });
325
+ *
326
+ * // Auth hook for your platform
327
+ * app.addHook('preHandler', async (request, reply) => {
328
+ * const token = request.headers.authorization?.replace('Bearer ', '');
329
+ * const user = await validatePlatformToken(token);
330
+ * if (!user) {
331
+ * reply.status(401).send({ error: 'Unauthorized' });
332
+ * return;
333
+ * }
334
+ * request.user = user;
335
+ * });
336
+ *
337
+ * app.post('/api/ai', async (request, reply) => {
338
+ * // Track usage per user
339
+ * // await trackUsage(request.user.id);
340
+ *
341
+ * const { messages, system, params } = parseBody(request.body);
342
+ *
343
+ * if (params?.stream) {
344
+ * return fastifyAdapter.streamSSE(claude.stream(messages, { system }), reply);
345
+ * }
346
+ * const turn = await claude.generate(messages, { system });
347
+ * return fastifyAdapter.sendJSON(turn, reply);
348
+ * });
349
+ * ```
259
350
  */
260
351
  declare const fastify: {
261
352
  sendJSON: typeof sendJSON$1;
@@ -269,29 +360,6 @@ declare const fastify: {
269
360
  * Provides utilities for using PP proxy with Express.js or Connect-based servers.
270
361
  * These adapters convert PP types to Express-compatible responses.
271
362
  *
272
- * @example
273
- * ```typescript
274
- * import express from 'express';
275
- * import { llm, anthropic } from '@providerprotocol/ai';
276
- * import { parseBody, bindTools } from '@providerprotocol/ai/proxy';
277
- * import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
278
- *
279
- * const app = express();
280
- * app.use(express.json());
281
- *
282
- * app.post('/api/ai', async (req, res) => {
283
- * const { messages, system, params } = parseBody(req.body);
284
- * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
285
- *
286
- * if (req.headers.accept?.includes('text/event-stream')) {
287
- * expressAdapter.streamSSE(instance.stream(messages), res);
288
- * } else {
289
- * const turn = await instance.generate(messages);
290
- * expressAdapter.sendJSON(turn, res);
291
- * }
292
- * });
293
- * ```
294
- *
295
363
  * @module providers/proxy/server/express
296
364
  */
297
365
 
@@ -341,6 +409,75 @@ declare function streamSSE(stream: StreamResult, res: ExpressResponse): void;
341
409
  declare function sendError(message: string, status: number, res: ExpressResponse): void;
342
410
  /**
343
411
  * Express adapter utilities.
412
+ *
413
+ * @example Basic usage
414
+ * ```typescript
415
+ * import express from 'express';
416
+ * import { llm } from '@providerprotocol/ai';
417
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
418
+ * import { parseBody } from '@providerprotocol/ai/proxy';
419
+ * import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
420
+ *
421
+ * const app = express();
422
+ * app.use(express.json());
423
+ *
424
+ * app.post('/api/ai', async (req, res) => {
425
+ * const { messages, system, params } = parseBody(req.body);
426
+ * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
427
+ *
428
+ * if (req.headers.accept?.includes('text/event-stream')) {
429
+ * expressAdapter.streamSSE(instance.stream(messages), res);
430
+ * } else {
431
+ * const turn = await instance.generate(messages);
432
+ * expressAdapter.sendJSON(turn, res);
433
+ * }
434
+ * });
435
+ * ```
436
+ *
437
+ * @example API Gateway with authentication
438
+ * ```typescript
439
+ * import express from 'express';
440
+ * import { llm } from '@providerprotocol/ai';
441
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
442
+ * import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
443
+ * import { parseBody } from '@providerprotocol/ai/proxy';
444
+ * import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
445
+ *
446
+ * const app = express();
447
+ * app.use(express.json());
448
+ *
449
+ * // Your platform's auth middleware
450
+ * async function authMiddleware(req, res, next) {
451
+ * const token = req.headers.authorization?.replace('Bearer ', '');
452
+ * const user = await validatePlatformToken(token);
453
+ * if (!user) return res.status(401).json({ error: 'Unauthorized' });
454
+ * req.user = user;
455
+ * next();
456
+ * }
457
+ *
458
+ * // Server manages AI provider keys - users never see them
459
+ * const claude = llm({
460
+ * model: anthropic('claude-sonnet-4-20250514'),
461
+ * config: {
462
+ * apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
463
+ * retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
464
+ * },
465
+ * });
466
+ *
467
+ * app.post('/api/ai', authMiddleware, async (req, res) => {
468
+ * // Track usage per user
469
+ * // await trackUsage(req.user.id);
470
+ *
471
+ * const { messages, system, params } = parseBody(req.body);
472
+ *
473
+ * if (params?.stream) {
474
+ * expressAdapter.streamSSE(claude.stream(messages, { system }), res);
475
+ * } else {
476
+ * const turn = await claude.generate(messages, { system });
477
+ * expressAdapter.sendJSON(turn, res);
478
+ * }
479
+ * });
480
+ * ```
344
481
  */
345
482
  declare const express: {
346
483
  sendJSON: typeof sendJSON;
@@ -357,23 +494,6 @@ declare const express: {
357
494
  * These utilities return standard Web API Response objects that work
358
495
  * directly with modern runtimes.
359
496
  *
360
- * @example
361
- * ```typescript
362
- * import { llm, anthropic } from '@providerprotocol/ai';
363
- * import { parseBody, toJSON, toSSE } from '@providerprotocol/ai/proxy';
364
- *
365
- * // Bun.serve / Deno.serve / Next.js App Router
366
- * export async function POST(req: Request) {
367
- * const { messages, system } = parseBody(await req.json());
368
- * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
369
- *
370
- * if (req.headers.get('accept')?.includes('text/event-stream')) {
371
- * return toSSE(instance.stream(messages));
372
- * }
373
- * return toJSON(await instance.generate(messages));
374
- * }
375
- * ```
376
- *
377
497
  * @module providers/proxy/server/webapi
378
498
  */
379
499
 
@@ -473,6 +593,70 @@ declare function bindTools(schemas: ParsedRequest['tools'], implementations: Rec
473
593
  *
474
594
  * For use with Bun, Deno, Next.js App Router, Cloudflare Workers,
475
595
  * and other frameworks that support Web API Response.
596
+ *
597
+ * **Security Note:** The proxy works without configuration, meaning no
598
+ * authentication by default. Always add your own auth layer in production.
599
+ *
600
+ * @example Basic usage
601
+ * ```typescript
602
+ * import { llm } from '@providerprotocol/ai';
603
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
604
+ * import { parseBody, toJSON, toSSE } from '@providerprotocol/ai/proxy';
605
+ *
606
+ * // Bun.serve / Deno.serve / Next.js App Router
607
+ * export async function POST(req: Request) {
608
+ * const { messages, system } = parseBody(await req.json());
609
+ * const instance = llm({ model: anthropic('claude-sonnet-4-20250514'), system });
610
+ *
611
+ * if (req.headers.get('accept')?.includes('text/event-stream')) {
612
+ * return toSSE(instance.stream(messages));
613
+ * }
614
+ * return toJSON(await instance.generate(messages));
615
+ * }
616
+ * ```
617
+ *
618
+ * @example API Gateway with authentication
619
+ * ```typescript
620
+ * import { llm } from '@providerprotocol/ai';
621
+ * import { anthropic } from '@providerprotocol/ai/anthropic';
622
+ * import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
623
+ * import { parseBody, toJSON, toSSE, toError } from '@providerprotocol/ai/proxy';
624
+ *
625
+ * // Your platform's user validation
626
+ * async function validateToken(token: string): Promise<{ id: string } | null> {
627
+ * // Verify JWT, check database, etc.
628
+ * return token ? { id: 'user-123' } : null;
629
+ * }
630
+ *
631
+ * // Server manages AI provider keys - users never see them
632
+ * const claude = llm({
633
+ * model: anthropic('claude-sonnet-4-20250514'),
634
+ * config: {
635
+ * apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
636
+ * retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
637
+ * },
638
+ * });
639
+ *
640
+ * Bun.serve({
641
+ * port: 3000,
642
+ * async fetch(req) {
643
+ * // Authenticate with YOUR platform credentials
644
+ * const token = req.headers.get('Authorization')?.replace('Bearer ', '');
645
+ * const user = await validateToken(token ?? '');
646
+ * if (!user) return toError('Unauthorized', 401);
647
+ *
648
+ * // Rate limit, track usage, bill user, etc.
649
+ * // await trackUsage(user.id);
650
+ *
651
+ * const { messages, system, params } = parseBody(await req.json());
652
+ *
653
+ * if (params?.stream) {
654
+ * return toSSE(claude.stream(messages, { system }));
655
+ * }
656
+ * return toJSON(await claude.generate(messages, { system }));
657
+ * },
658
+ * });
659
+ * ```
476
660
  */
477
661
  declare const webapi: {
478
662
  parseBody: typeof parseBody;
@@ -532,6 +716,46 @@ interface AdapterOptions {
532
716
  * Server adapters namespace.
533
717
  *
534
718
  * Contains framework-specific adapters for Web API, Express, Fastify, and H3.
719
+ *
720
+ * @example Express
721
+ * ```typescript
722
+ * import { express } from '@providerprotocol/ai/proxy/server';
723
+ *
724
+ * app.post('/api/ai', async (req, res) => {
725
+ * const { messages } = parseBody(req.body);
726
+ * if (req.headers.accept?.includes('text/event-stream')) {
727
+ * express.streamSSE(instance.stream(messages), res);
728
+ * } else {
729
+ * express.sendJSON(await instance.generate(messages), res);
730
+ * }
731
+ * });
732
+ * ```
733
+ *
734
+ * @example Fastify
735
+ * ```typescript
736
+ * import { fastify } from '@providerprotocol/ai/proxy/server';
737
+ *
738
+ * app.post('/api/ai', async (request, reply) => {
739
+ * const { messages } = parseBody(request.body);
740
+ * if (request.headers.accept?.includes('text/event-stream')) {
741
+ * return fastify.streamSSE(instance.stream(messages), reply);
742
+ * }
743
+ * return fastify.sendJSON(await instance.generate(messages), reply);
744
+ * });
745
+ * ```
746
+ *
747
+ * @example H3/Nuxt
748
+ * ```typescript
749
+ * import { h3 } from '@providerprotocol/ai/proxy/server';
750
+ *
751
+ * export default defineEventHandler(async (event) => {
752
+ * const { messages } = parseBody(await readBody(event));
753
+ * if (getHeader(event, 'accept')?.includes('text/event-stream')) {
754
+ * return h3.streamSSE(instance.stream(messages), event);
755
+ * }
756
+ * return h3.sendJSON(await instance.generate(messages), event);
757
+ * });
758
+ * ```
535
759
  */
536
760
  declare const server: {
537
761
  /** Web API adapter (Bun, Deno, Next.js, Workers) */