@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/gemini-cache-api.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GeminiCacheAPI 鈥?Explicit Context Caching for Gemini generateContent.
+ *
+ * Manages named cached content resources that can be referenced in
+ * generateContent requests via the `cachedContent` field.
+ *
+ * REST endpoints:
+ *   POST   /v1beta/cachedContents          鈥?create cache
+ *   GET    /v1beta/cachedContents           鈥?list caches
+ *   GET    /v1beta/cachedContents/{name}    鈥?get cache metadata
+ *   PATCH  /v1beta/cachedContents/{name}    鈥?update TTL
+ *   DELETE /v1beta/cachedContents/{name}    鈥?delete cache
+ *
+ * Minimum cacheable content: 1024 tokens (Flash) / 4096 tokens (Pro).
+ * TTL default: 1 hour. Storage: ~$1.00/hour/MTok (Flash series).
+ *
+ * Docs: https://ai.google.dev/gemini-api/docs/caching
+ */
+export interface GeminiCacheCreateOptions {
+    /** Model to use, e.g. "models/gemini-3-flash-preview" */
+    model: string;
+    /** Contents to cache (same format as generateContent contents) */
+    contents: Array<Record<string, unknown>>;
+    /** Optional system instruction to include in cache */
+    systemInstruction?: Record<string, unknown>;
+    /** Time-to-live, e.g. "300s" for 5 minutes. Default: "3600s" (1 hour) */
+    ttl?: string;
+    /** Human-readable name for identifying the cache */
+    displayName?: string;
+}
+export interface GeminiCachedContent {
+    /** Resource name, e.g. "cachedContents/abc123" */
+    name: string;
+    /** Model this cache is bound to */
+    model: string;
+    /** Display name (if set) */
+    displayName?: string;
+    /** Token usage metadata */
+    usageMetadata?: {
+        totalTokenCount?: number;
+    };
+    /** Creation time (ISO 8601) */
+    createTime?: string;
+    /** Last update time (ISO 8601) */
+    updateTime?: string;
+    /** Expiration time (ISO 8601) */
+    expireTime?: string;
+}
+export declare class GeminiCacheAPI {
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: {
+        baseUrl: string;
+        timeoutMs?: number;
+    });
+    /**
+     * Create a new cached content resource.
+     * The cache name returned can be passed as `cachedContent` in generateContent.
+     */
+    createCache(options: GeminiCacheCreateOptions, apiKey: string, signal?: AbortSignal): Promise<GeminiCachedContent>;
+    /**
+     * Get metadata for a cached content resource.
+     */
+    getCache(name: string, apiKey: string, signal?: AbortSignal): Promise<GeminiCachedContent>;
+    /**
+     * List all cached content resources.
+     */
+    listCaches(apiKey: string, options?: {
+        pageSize?: number;
+        pageToken?: string;
+    }, signal?: AbortSignal): Promise<{
+        cachedContents: GeminiCachedContent[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * Update a cache's TTL or expiration time.
+     */
+    updateCache(name: string, update: {
+        ttl?: string;
+        expireTime?: string;
+    }, apiKey: string, signal?: AbortSignal): Promise<GeminiCachedContent>;
+    /**
+     * Delete a cached content resource.
+     */
+    deleteCache(name: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+}

package/dist/transports/gemini-cache-api.js

@@ -0,0 +1,141 @@
+/**
+ * GeminiCacheAPI 鈥?Explicit Context Caching for Gemini generateContent.
+ *
+ * Manages named cached content resources that can be referenced in
+ * generateContent requests via the `cachedContent` field.
+ *
+ * REST endpoints:
+ *   POST   /v1beta/cachedContents          鈥?create cache
+ *   GET    /v1beta/cachedContents           鈥?list caches
+ *   GET    /v1beta/cachedContents/{name}    鈥?get cache metadata
+ *   PATCH  /v1beta/cachedContents/{name}    鈥?update TTL
+ *   DELETE /v1beta/cachedContents/{name}    鈥?delete cache
+ *
+ * Minimum cacheable content: 1024 tokens (Flash) / 4096 tokens (Pro).
+ * TTL default: 1 hour. Storage: ~$1.00/hour/MTok (Flash series).
+ *
+ * Docs: https://ai.google.dev/gemini-api/docs/caching
+ */
+const DEFAULT_TIMEOUT_MS = 60_000;
+// 鈹€鈹€ API Client 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+export class GeminiCacheAPI {
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Create a new cached content resource.
+     * The cache name returned can be passed as `cachedContent` in generateContent.
+     */
+    async createCache(options, apiKey, signal) {
+        const url = `${this.baseUrl}/cachedContents`;
+        const body = {
+            model: options.model.startsWith("models/") ? options.model : `models/${options.model}`,
+            contents: options.contents,
+        };
+        if (options.systemInstruction) {
+            body.systemInstruction = options.systemInstruction;
+        }
+        if (options.ttl)
+            body.ttl = options.ttl;
+        if (options.displayName)
+            body.displayName = options.displayName;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-goog-api-key": apiKey,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini cache create error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Get metadata for a cached content resource.
+     */
+    async getCache(name, apiKey, signal) {
+        const url = `${this.baseUrl}/${name}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini cache get error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * List all cached content resources.
+     */
+    async listCaches(apiKey, options, signal) {
+        const params = new URLSearchParams();
+        if (options?.pageSize)
+            params.set("pageSize", String(options.pageSize));
+        if (options?.pageToken)
+            params.set("pageToken", options.pageToken);
+        const url = `${this.baseUrl}/cachedContents?${params.toString()}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini cache list error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        const data = (await res.json());
+        return {
+            cachedContents: data.cachedContents ?? [],
+            nextPageToken: data.nextPageToken,
+        };
+    }
+    /**
+     * Update a cache's TTL or expiration time.
+     */
+    async updateCache(name, update, apiKey, signal) {
+        const url = `${this.baseUrl}/${name}`;
+        const body = {};
+        if (update.ttl)
+            body.ttl = update.ttl;
+        if (update.expireTime)
+            body.expireTime = update.expireTime;
+        const res = await fetch(url, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json",
+                "x-goog-api-key": apiKey,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini cache update error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Delete a cached content resource.
+     */
+    async deleteCache(name, apiKey, signal) {
+        const url = `${this.baseUrl}/${name}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini cache delete error ${res.status}: ${text.slice(0, 500)}`);
+        }
+    }
+}

package/dist/transports/gemini-file-api.d.ts

@@ -0,0 +1,90 @@
+/**
+ * GeminiFileAPI 鈥?Gemini File API for uploading and managing files.
+ *
+ * Files uploaded via this API can be referenced in generateContent requests
+ * using `file_data: { file_uri, mime_type }` parts.
+ *
+ * Upload uses the resumable upload protocol (2-step):
+ *   1. POST /upload/v1beta/files 鈫?get upload URL (response header)
+ *   2. PUT {upload_url} with file bytes 鈫?get file info
+ *
+ * Other operations:
+ *   GET    /v1beta/files           鈥?list files
+ *   GET    /v1beta/files/{name}    鈥?get file metadata
+ *   DELETE /v1beta/files/{name}    鈥?delete file
+ *
+ * Files expire after 48 hours. Max 2GB per file, 20GB per project.
+ *
+ * Docs: https://ai.google.dev/gemini-api/docs/files
+ */
+export interface GeminiFileInfo {
+    /** Resource name, e.g. "files/abc123" */
+    name: string;
+    /** Display name (set during upload) */
+    displayName?: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes?: string;
+    /** File URI for use in generateContent, e.g. "https://generativelanguage.googleapis.com/v1beta/files/abc123" */
+    uri: string;
+    /** Processing state: PROCESSING | ACTIVE | FAILED */
+    state: string;
+    /** Creation time (ISO 8601) */
+    createTime?: string;
+    /** Last update time (ISO 8601) */
+    updateTime?: string;
+    /** Expiration time (ISO 8601) */
+    expirationTime?: string;
+    /** Error info if state is FAILED */
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare class GeminiFileAPI {
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: {
+        baseUrl: string;
+        timeoutMs?: number;
+    });
+    /**
+     * Upload a file using the resumable upload protocol.
+     *
+     * Step 1: Initiate upload 鈫?get upload URL from response header
+     * Step 2: Upload bytes to that URL 鈫?get file metadata
+     *
+     * @returns GeminiFileInfo with .uri for use in generateContent
+     */
+    uploadFile(file: Blob | Buffer, apiKey: string, options?: {
+        mimeType?: string;
+        displayName?: string;
+    }, signal?: AbortSignal): Promise<GeminiFileInfo>;
+    /**
+     * Wait for a file to finish processing (state 鈫?ACTIVE).
+     * Some file types (video, audio) require server-side processing.
+     */
+    waitForProcessing(name: string, apiKey: string, options?: {
+        pollIntervalMs?: number;
+        maxWaitMs?: number;
+    }): Promise<GeminiFileInfo>;
+    /**
+     * Get metadata for an uploaded file.
+     */
+    getFile(name: string, apiKey: string, signal?: AbortSignal): Promise<GeminiFileInfo>;
+    /**
+     * List uploaded files.
+     */
+    listFiles(apiKey: string, options?: {
+        pageSize?: number;
+        pageToken?: string;
+    }, signal?: AbortSignal): Promise<{
+        files: GeminiFileInfo[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * Delete an uploaded file.
+     */
+    deleteFile(name: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+}

package/dist/transports/gemini-file-api.js

@@ -0,0 +1,164 @@
+/**
+ * GeminiFileAPI 鈥?Gemini File API for uploading and managing files.
+ *
+ * Files uploaded via this API can be referenced in generateContent requests
+ * using `file_data: { file_uri, mime_type }` parts.
+ *
+ * Upload uses the resumable upload protocol (2-step):
+ *   1. POST /upload/v1beta/files 鈫?get upload URL (response header)
+ *   2. PUT {upload_url} with file bytes 鈫?get file info
+ *
+ * Other operations:
+ *   GET    /v1beta/files           鈥?list files
+ *   GET    /v1beta/files/{name}    鈥?get file metadata
+ *   DELETE /v1beta/files/{name}    鈥?delete file
+ *
+ * Files expire after 48 hours. Max 2GB per file, 20GB per project.
+ *
+ * Docs: https://ai.google.dev/gemini-api/docs/files
+ */
+const DEFAULT_TIMEOUT_MS = 300_000; // 5 min for uploads
+// 鈹€鈹€ API Client 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+export class GeminiFileAPI {
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        // baseUrl should be e.g. "https://generativelanguage.googleapis.com/v1beta"
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Upload a file using the resumable upload protocol.
+     *
+     * Step 1: Initiate upload 鈫?get upload URL from response header
+     * Step 2: Upload bytes to that URL 鈫?get file metadata
+     *
+     * @returns GeminiFileInfo with .uri for use in generateContent
+     */
+    async uploadFile(file, apiKey, options, signal) {
+        const bytes = file instanceof Blob ? Buffer.from(await file.arrayBuffer()) : file;
+        const mimeType = options?.mimeType ?? "application/octet-stream";
+        const displayName = options?.displayName ?? "upload";
+        // Derive the upload base from our API base
+        // e.g. "https://generativelanguage.googleapis.com/v1beta"
+        //    鈫?"https://generativelanguage.googleapis.com/upload/v1beta/files"
+        const uploadInitUrl = this.baseUrl.replace(/(\/v1beta)$/, "/upload$1/files");
+        // Step 1: Initiate resumable upload
+        const initRes = await fetch(uploadInitUrl, {
+            method: "POST",
+            headers: {
+                "x-goog-api-key": apiKey,
+                "X-Goog-Upload-Protocol": "resumable",
+                "X-Goog-Upload-Command": "start",
+                "X-Goog-Upload-Header-Content-Length": String(bytes.length),
+                "X-Goog-Upload-Header-Content-Type": mimeType,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                file: { display_name: displayName },
+            }),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!initRes.ok) {
+            const text = await initRes.text().catch(() => "");
+            throw new Error(`Gemini file upload init error ${initRes.status}: ${text.slice(0, 500)}`);
+        }
+        // Extract upload URL from response header
+        const uploadUrl = initRes.headers.get("x-goog-upload-url");
+        if (!uploadUrl) {
+            throw new Error("Gemini file upload: missing x-goog-upload-url in response headers");
+        }
+        // Step 2: Upload the actual bytes
+        const uploadRes = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Length": String(bytes.length),
+                "X-Goog-Upload-Offset": "0",
+                "X-Goog-Upload-Command": "upload, finalize",
+            },
+            body: bytes,
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!uploadRes.ok) {
+            const text = await uploadRes.text().catch(() => "");
+            throw new Error(`Gemini file upload error ${uploadRes.status}: ${text.slice(0, 500)}`);
+        }
+        const data = (await uploadRes.json());
+        return data.file;
+    }
+    /**
+     * Wait for a file to finish processing (state 鈫?ACTIVE).
+     * Some file types (video, audio) require server-side processing.
+     */
+    async waitForProcessing(name, apiKey, options) {
+        const pollInterval = options?.pollIntervalMs ?? 2500;
+        const maxWait = options?.maxWaitMs ?? 120_000;
+        const start = Date.now();
+        while (Date.now() - start < maxWait) {
+            const file = await this.getFile(name, apiKey);
+            if (file.state === "ACTIVE")
+                return file;
+            if (file.state === "FAILED") {
+                throw new Error(`Gemini file processing failed: ${file.error?.message ?? "unknown error"}`);
+            }
+            await new Promise((r) => setTimeout(r, pollInterval));
+        }
+        throw new Error(`Gemini file processing timed out after ${maxWait}ms`);
+    }
+    /**
+     * Get metadata for an uploaded file.
+     */
+    async getFile(name, apiKey, signal) {
+        const url = `${this.baseUrl}/${name}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini file get error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * List uploaded files.
+     */
+    async listFiles(apiKey, options, signal) {
+        const params = new URLSearchParams();
+        if (options?.pageSize)
+            params.set("pageSize", String(options.pageSize));
+        if (options?.pageToken)
+            params.set("pageToken", options.pageToken);
+        const url = `${this.baseUrl}/files?${params.toString()}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini file list error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        const data = (await res.json());
+        return {
+            files: data.files ?? [],
+            nextPageToken: data.nextPageToken,
+        };
+    }
+    /**
+     * Delete an uploaded file.
+     */
+    async deleteFile(name, apiKey, signal) {
+        const url = `${this.baseUrl}/${name}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini file delete error ${res.status}: ${text.slice(0, 500)}`);
+        }
+    }
+}

package/dist/transports/gemini-generatecontent.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Gemini generateContent TransportNative Gemini API streaming implementation.
+ *
+ * Targets Gemini 3 series exclusively (3.1 Pro, 3 Flash, 3.1 Flash-Lite).
+ * Uses the native Gemini REST API instead of the OpenAI compatibility layer,
+ * unlocking Gemini-exclusive features unavailable via the compat endpoint:
+ *   - thinkingConfig (thinkingLevelG3 native control)
+ *   - Google Search / Maps Grounding
+ *   - Code Execution
+ *   - Safety Settings fine-grained control
+ *   - Thought Signatures for multi-turn reasoning continuity
+ *   - URL Context / File Search
+ *   - systemInstruction top-level field
+ *
+ * Streaming endpoint: POST .../models/{model}:streamGenerateContent?alt=sse
+ * Non-streaming:      POST .../models/{model}:generateContent
+ * Auth: x-goog-api-key header
+ *
+ * Protocol reference: https://ai.google.dev/gemini-api/docs
+ * Aligned with gemini-ProviderMax.md native protocol strategy.
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
+export interface GeminiGenerateContentTransportConfig {
+    /** Base URL, e.g. "https://generativelanguage.googleapis.com/v1beta" */
+    baseUrl: string;
+    /** Per-request timeout in ms (default 180_000) */
+    timeoutMs?: number;
+    /** Provider-specific quirks */
+    quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
+}
+export declare class GeminiGenerateContentTransport implements LLMTransport {
+    private baseUrl;
+    private timeoutMs;
+    private quirks;
+    private fileUploadAdapter?;
+    constructor(config: GeminiGenerateContentTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    private buildRequestBody;
+    private buildTools;
+    private buildToolConfig;
+    private buildGenerationConfig;
+    private fetchAndStream;
+    /**
+     * Parse SSE stream with 90s idle watchdog (CC parity).
+     */
+    private parseSSEStreamWithWatchdog;
+    /**
+     * Process a single Gemini response chunk, yielding LLMChunk events.
+     */
+    private processResponse;
+    private nonStreamingFallback;
+}