@gullabs/google 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,591 @@
+import { AuthMaterial, ProviderAdapter, Logger } from '@gullabs/core';
+import { ZodTypeAny } from 'zod';
+
+/**
+ * Structural GeminiClientLike interface + buildGoogleClient factory.
+ *
+ * This module defines the structural interface the adapter depends on.
+ * The real @google/genai SDK is imported ONLY in buildGoogleClient so tests
+ * can inject a fake without pulling in the real SDK.
+ *
+ * @module
+ */
+
+/**
+ * Default HTTP transport timeout for Gemini Flex service-tier calls (ms).
+ *
+ * The default per-attempt transport (httpOptions) timeout applied ONLY when a
+ * flex call provides no explicit `timeoutMs`. Set to 25 minutes (1_500_000 ms)
+ * to cover the ~20-minute flex workload ceiling with margin.  The @google/genai
+ * SDK defaults to 1 minute, which would terminate a long flex call prematurely.
+ * Callers SHOULD still set `timeoutMs` for a precise per-attempt ceiling; this
+ * value is only the backstop for callers that do not.
+ */
+declare const FLEX_DEFAULT_TIMEOUT_MS = 1500000;
+/**
+ * Buffer added above `timeoutMs` when setting the SDK transport timeout.
+ *
+ * When `timeoutMs` is set, the engine arms an AbortSignal at exactly
+ * `timeoutMs`.  If the SDK transport timer fired at the same instant it
+ * could preempt the signal and produce a raw SDK error instead of the
+ * engine's clean `kind:'timeout'`.  By setting the transport timeout to
+ * `timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS` we ensure the engine's
+ * AbortSignal always fires first.
+ */
+declare const TRANSPORT_TIMEOUT_BUFFER_MS = 5000;
+/** A single text/thought part in a Gemini candidate content. */
+interface GeminiPartShape {
+    text?: string;
+    /**
+     * Present and `true` on thought-summary parts.
+     * Real field name in @google/genai Candidate.content.parts: `thought`.
+     */
+    thought?: boolean;
+}
+/** A candidate returned by Gemini generateContent. */
+interface GeminiCandidateShape {
+    content?: {
+        parts?: GeminiPartShape[];
+    };
+    /**
+     * Why the model stopped.
+     * Real SDK enum (FinishReason): "STOP", "MAX_TOKENS", "SAFETY",
+     * "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", etc.
+     */
+    finishReason?: string;
+    /**
+     * Grounding metadata returned when Google Search grounding is active.
+     * Real SDK type: GroundingMetadata. Kept as `unknown` to avoid a hard
+     * coupling to @google/genai types; cast to JsonValue at the adapter boundary.
+     */
+    groundingMetadata?: unknown;
+}
+/**
+ * Token usage metadata returned alongside a Gemini response.
+ *
+ * Real type: GenerateContentResponseUsageMetadata.
+ * NOTE: thoughtsTokenCount is SEPARATE from candidatesTokenCount.
+ * The adapter must add them to get GROSS outputTokens.
+ */
+interface GeminiUsageMetadataShape {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    cachedContentTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+}
+/**
+ * Structural equivalent of @google/genai's GenerateContentResponse.
+ * Only the fields the adapter reads are represented here.
+ */
+interface GeminiResponseShape {
+    candidates?: GeminiCandidateShape[];
+    usageMetadata?: GeminiUsageMetadataShape;
+    /** Real field: GenerateContentResponse.modelVersion */
+    modelVersion?: string;
+    /** Real field: GenerateContentResponse.responseId */
+    responseId?: string;
+    /**
+     * Safety-block metadata.
+     * Real type: GenerateContentResponsePromptFeedback.
+     * Present when the prompt (not output) was blocked by safety filters.
+     */
+    promptFeedback?: {
+        /** Real type: BlockedReason (string enum). e.g. "SAFETY", "OTHER". */
+        blockReason?: string;
+        blockReasonMessage?: string;
+        safetyRatings?: unknown[];
+    };
+}
+/**
+ * Per-part media-resolution hint emitted on inline/file parts.
+ * Real type: @google/genai `PartMediaResolution`; `level` values come from
+ * the `PartMediaResolutionLevel` string enum (we only emit the LOW/MEDIUM/HIGH
+ * subset our normalized `mediaResolution` maps to).
+ */
+interface GeminiPartMediaResolution {
+    level?: 'MEDIA_RESOLUTION_LOW' | 'MEDIA_RESOLUTION_MEDIUM' | 'MEDIA_RESOLUTION_HIGH';
+}
+/** A text part in a content object we construct. */
+interface GeminiTextContentPart {
+    text: string;
+}
+/**
+ * An inline binary media part in a content object we construct.
+ * `data` must be raw base64 — no `data:…;base64,` prefix.
+ */
+interface GeminiInlineDataContentPart {
+    inlineData: {
+        /** IANA media type, e.g. `"image/png"`. */
+        mimeType: string;
+        /** Raw base64-encoded bytes (no data-URL prefix). */
+        data: string;
+    };
+    /** Optional per-part media-resolution hint (real field: `Part.mediaResolution`). */
+    mediaResolution?: GeminiPartMediaResolution;
+}
+/**
+ * A provider-hosted file reference part in a content object we construct.
+ * The Gemini service dereferences `fileUri` server-side.
+ */
+interface GeminiFileDataContentPart {
+    fileData: {
+        /** IANA media type of the referenced file. */
+        mimeType: string;
+        /** Provider-assigned file URI, e.g. from the Gemini File API. */
+        fileUri: string;
+    };
+    /** Optional per-part media-resolution hint (real field: `Part.mediaResolution`). */
+    mediaResolution?: GeminiPartMediaResolution;
+}
+/**
+ * Union of all part shapes the adapter may produce for `GeminiContent.parts`.
+ * Each member (including the optional per-part `mediaResolution`) is a
+ * structural subset of the real `@google/genai` `Part` type for the fields we use.
+ */
+type GeminiContentPart = GeminiTextContentPart | GeminiInlineDataContentPart | GeminiFileDataContentPart;
+/** A content object (message) we construct. */
+interface GeminiContent {
+    role: string;
+    parts: GeminiContentPart[];
+}
+/**
+ * Schema shape we pass as responseSchema.
+ * Structurally compatible with @google/genai Schema.
+ */
+interface GeminiSchema {
+    type?: string;
+    description?: string;
+    properties?: Record<string, GeminiSchema>;
+    required?: string[];
+    items?: GeminiSchema;
+    enum?: string[];
+    nullable?: boolean;
+    format?: string;
+}
+/**
+ * Thinking configuration.
+ * Real type: ThinkingConfig in @google/genai.
+ * - thinkingBudget: 0 = DISABLED, -1 = AUTOMATIC
+ * - thinkingLevel: ThinkingLevel enum ("LOW", "MEDIUM", "HIGH", "MINIMAL")
+ */
+interface GeminiThinkingConfig {
+    includeThoughts?: boolean;
+    thinkingBudget?: number;
+    /**
+     * Real type: ThinkingLevel enum.
+     * Values: "LOW" | "MEDIUM" | "HIGH" | "MINIMAL" | "THINKING_LEVEL_UNSPECIFIED"
+     */
+    thinkingLevel?: string;
+}
+/**
+ * Config object passed in GenerateContentParameters.config.
+ * Real type: GenerateContentConfig.
+ * abortSignal is inside config, NOT in the top-level params.
+ */
+interface GeminiGenerateConfig {
+    systemInstruction?: {
+        parts: GeminiContentPart[];
+    };
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxOutputTokens?: number;
+    stopSequences?: string[];
+    responseMimeType?: string;
+    responseSchema?: GeminiSchema;
+    thinkingConfig?: GeminiThinkingConfig;
+    /** Real type: ServiceTier enum. Values: "flex" | "standard". */
+    serviceTier?: string;
+    /** Real field: GenerateContentConfig.abortSignal (NOT in top-level params). */
+    abortSignal?: AbortSignal;
+    /**
+     * Per-request HTTP options forwarded to the @google/genai transport.
+     * We use this to set a transport-level timeout that is >= the AbortSignal
+     * deadline so the SDK fetch does not preempt the abort.
+     *
+     * Real field: GenerateContentConfig.httpOptions.timeout (milliseconds).
+     * Real field: GenerateContentConfig.httpOptions.headers (Record<string,string>).
+     *   Used by FIX A-1 to inject Vertex flex routing headers.
+     */
+    httpOptions?: {
+        timeout?: number;
+        headers?: Record<string, string>;
+    };
+}
+/**
+ * Parameters for models.generateContent.
+ * Real type: GenerateContentParameters.
+ */
+interface GeminiGenerateParams {
+    model: string;
+    contents: GeminiContent[];
+    config?: GeminiGenerateConfig;
+}
+/**
+ * Structural interface for the @google/genai client surface the adapter uses.
+ *
+ * Satisfied by:
+ * - The real GoogleGenAI client (via buildGoogleClient wrapper).
+ * - FakeGeminiClient from @gullabs/testing (its generateContent accepts unknown).
+ */
+interface GeminiClientLike {
+    models: {
+        generateContent(params: GeminiGenerateParams): Promise<GeminiResponseShape>;
+    };
+}
+/**
+ * Build a real @google/genai client from AuthMaterial.
+ *
+ * Returns a GeminiClientLike wrapper around the real GoogleGenAI client.
+ * Only API-key authentication is supported; Vertex AI is not.
+ *
+ * @param auth - API key credentials ({ apiKey }).
+ */
+declare function buildGoogleClient(auth: AuthMaterial): Promise<GeminiClientLike>;
+
+/**
+ * geminiAdapter — @gullabs/google Gemini provider adapter.
+ *
+ * Pure request⇄response mapping over @google/genai (via GeminiClientLike).
+ * Never persists, never computes cost, never loops.
+ *
+ * @module
+ */
+
+interface GeminiAdapterOptions {
+    /**
+     * Inject a pre-built client (real or fake).
+     * When omitted, `buildGoogleClient` is called with `ctx.auth` at call time,
+     * inside the classified try/catch so any construction failure is wrapped
+     * as a typed `LlmError`.
+     */
+    client?: GeminiClientLike;
+    /**
+     * @internal Testing-only.
+     *
+     * Override the default `buildGoogleClient` factory.  Allows unit tests to
+     * simulate construction failures (e.g. bad credentials) without importing
+     * the real `@google/genai` SDK.  Never set this in production code.
+     */
+    _clientFactory?: (auth: AuthMaterial) => GeminiClientLike | Promise<GeminiClientLike>;
+}
+/**
+ * Create a Gemini provider adapter.
+ *
+ * @param opts.client - Optional pre-built client (e.g. for testing).
+ */
+declare function geminiAdapter(opts?: GeminiAdapterOptions): ProviderAdapter;
+
+/**
+ * zodToGeminiSchema — best-effort Zod-to-Gemini Schema converter.
+ *
+ * Supports common shapes: object, string, number (int detection), boolean,
+ * array, enum, optional, nullable, default, literal.
+ *
+ * Returns `undefined` for unsupported shapes — the caller emits a Warning and
+ * falls back to plain JSON output without a responseSchema.  The engine always
+ * Zod-validates output regardless; this is only a best-effort model hint.
+ *
+ * @module
+ */
+
+/**
+ * Convert a Zod schema to a Gemini Schema object.
+ *
+ * @param schema - Any Zod type.
+ * @returns A GeminiSchema on success; `undefined` for unsupported shapes.
+ */
+declare function zodToGeminiSchema(schema: ZodTypeAny): GeminiSchema | undefined;
+
+/**
+ * GoogleFileStore — thin wrapper over the Gemini File API.
+ *
+ * Handles upload + polling until ACTIVE, and tracked deletion.
+ * Injectable sleep and client for tests (no network required).
+ *
+ * @module
+ */
+
+/** A handle to a file stored in the Gemini File API. */
+interface GoogleFileHandle {
+    /** Resource name, e.g. "files/abc123". */
+    name: string;
+    /** URI to pass as FileUriPart.uri in an LlmRequest. */
+    uri: string;
+    mimeType: string;
+    /** Provider auto-deletes ~48 h after upload. Absent when not returned. */
+    expiresAt?: Date;
+}
+/**
+ * Minimal structural interface for the Gemini Files client surface we use.
+ * Satisfied by the real ai.files object or a test fake.
+ */
+interface GeminiFilesClientLike {
+    upload(params: {
+        file: Uint8Array | Blob;
+        config?: {
+            mimeType?: string;
+            displayName?: string;
+        };
+    }): Promise<{
+        name?: string;
+        uri?: string;
+        mimeType?: string;
+        state?: string;
+        expirationTime?: string;
+    }>;
+    get(params: {
+        name: string;
+    }): Promise<{
+        name?: string;
+        uri?: string;
+        mimeType?: string;
+        state?: string;
+        expirationTime?: string;
+    }>;
+    delete(params: {
+        name: string;
+    }): Promise<void>;
+}
+interface GoogleFileStoreOptions {
+    auth: AuthMaterial;
+    /** Injectable client for tests; skips SDK import when provided. */
+    client?: GeminiFilesClientLike;
+    /** Called on delete failures instead of rethrowing. Default: console.error. */
+    onDeleteError?: (name: string, err: unknown) => void;
+    /** Optional structured logger. When provided, routes delete failures to logger.error. */
+    logger?: Logger;
+    poll?: {
+        /** Delay between state polls. Default: 3000 ms. */
+        intervalMs?: number;
+        /** Max time to wait for ACTIVE. Default: 300 000 ms (5 min). */
+        timeoutMs?: number;
+    };
+    /** Injectable sleep for tests. Default: real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable clock for deterministic tests. Default: `Date.now`. */
+    now?: () => number;
+}
+/**
+ * **Auth snapshot note:** this store captures the `AuthMaterial` at construction
+ * time and memoizes a single SDK client from it (`clientPromise`).  This is
+ * correct and sufficient for static API keys.  If refreshable credentials
+ * (short-lived OAuth/STS tokens) are added in the future, this memoization is
+ * the seam that will need rework: the cached client would hold stale credentials
+ * for the lifetime of a long-lived store instance.  At that point, the store
+ * will need to either rebuild the client on each operation or accept a
+ * credential-resolver callback rather than a plain `AuthMaterial` value.
+ * See ADR-020 in DECISIONS.md.
+ */
+declare class GoogleFileStore {
+    private readonly auth;
+    private readonly clientOverride;
+    private readonly onDeleteError;
+    private readonly logger;
+    private readonly intervalMs;
+    private readonly timeoutMs;
+    private readonly sleep;
+    private readonly now;
+    /** Memoised client promise — built at most once per store instance. */
+    private clientPromise;
+    constructor(opts: GoogleFileStoreOptions);
+    private getClient;
+    /**
+     * Upload bytes to the Gemini File API and wait until the file is ACTIVE.
+     *
+     * @param source  - Raw bytes or Blob.
+     * @param mimeType - IANA media type, e.g. `"image/png"`.
+     * @param opts    - Optional display name.
+     */
+    upload(source: Uint8Array | Blob, mimeType: string, opts?: {
+        displayName?: string;
+        signal?: AbortSignal;
+    }): Promise<GoogleFileHandle>;
+    /**
+     * Delete a single uploaded file.
+     * Errors are forwarded to `onDeleteError` and NOT rethrown.
+     */
+    delete(handle: GoogleFileHandle): Promise<void>;
+    /**
+     * Delete multiple files.
+     * Each failure is individually forwarded to `onDeleteError`; none are thrown.
+     */
+    deleteAll(handles: GoogleFileHandle[]): Promise<void>;
+}
+
+/**
+ * GoogleCacheStore — thin wrapper over the Gemini Context Cache API.
+ *
+ * Manages create / get-or-create / refresh / delete lifecycle for cached
+ * contents.  In-memory cache entries are PROCESS-SCOPED; they are not shared
+ * across processes, workers, or restarts.
+ *
+ * Injectable client and `now` function keep tests free of network and clock.
+ *
+ * @module
+ */
+
+/**
+ * A handle to a cached content resource in the Gemini Context Cache API.
+ *
+ * Pass `cacheName` as `providerOptions.google.cachedContent` in LlmRequest.
+ */
+interface GoogleCacheHandle {
+    /** Resource name, e.g. "cachedContents/xyz". */
+    cacheName: string;
+    /**
+     * Local view of when the cache expires (server-authoritative; computed from
+     * ttl or parsed from the server response `expireTime`).
+     */
+    expiresAt: Date;
+    /** Caches are model-bound; never use a handle with a different model. */
+    model: string;
+}
+/** Key used to look up or create an entry in the in-process cache map. */
+interface CacheKey {
+    model: string;
+    /** Caller-chosen stable identifier, e.g. a hash of the cached content. */
+    stableKey: string;
+}
+/**
+ * Minimal structural interface for the Gemini Caches client surface we use.
+ * Satisfied by the real `ai.caches` object or a test fake.
+ */
+interface GeminiCachesClientLike {
+    create(params: {
+        model: string;
+        config: {
+            contents?: unknown;
+            systemInstruction?: unknown;
+            ttl?: string;
+            displayName?: string;
+        };
+    }): Promise<{
+        name?: string;
+        model?: string;
+        expireTime?: string;
+    }>;
+    update(params: {
+        name: string;
+        config: {
+            ttl?: string;
+            expireTime?: string;
+        };
+    }): Promise<{
+        name?: string;
+        expireTime?: string;
+    }>;
+    delete(params: {
+        name: string;
+    }): Promise<unknown>;
+}
+interface GoogleCacheStoreOptions {
+    auth: AuthMaterial;
+    /** Injectable client for tests; skips SDK import when provided. */
+    client?: GeminiCachesClientLike;
+    /**
+     * When true, concurrent `getOrCreate` calls for the same key share one
+     * in-flight create.  Default false.
+     */
+    coalesce?: boolean;
+    /**
+     * Subtracted from the local expiry so we stop using a cache slightly before
+     * the server evicts it.  Default 30 s.
+     */
+    expirySkewSeconds?: number;
+    /** Called on delete failures instead of rethrowing. */
+    onDeleteError?: (cacheName: string, err: unknown) => void;
+    /** Optional structured logger. When provided, routes delete failures to logger.error. */
+    logger?: Logger;
+    /** Injectable clock for deterministic tests.  Default: `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Process-scoped helper for the Gemini Context Cache API.
+ *
+ * NOTE: `getOrCreate` reuse is PROCESS-SCOPED only.  Entries survive only for
+ * the lifetime of this `GoogleCacheStore` instance.  Across restarts, new
+ * caches will be created (and old ones will be server-evicted after their TTL).
+ *
+ * **Auth snapshot note:** this store captures the `AuthMaterial` at construction
+ * time and memoizes a single SDK client from it (`clientPromise`).  This is
+ * correct and sufficient for static API keys.  If refreshable credentials
+ * (short-lived OAuth/STS tokens) are added in the future, this memoization is
+ * the seam that will need rework: the cached client would hold stale credentials
+ * for the lifetime of a long-lived store instance.  At that point, the store
+ * will need to either rebuild the client on each operation or accept a
+ * credential-resolver callback rather than a plain `AuthMaterial` value.
+ * See ADR-020 in DECISIONS.md.
+ */
+declare class GoogleCacheStore {
+    private readonly auth;
+    private readonly clientOverride;
+    private readonly coalesce;
+    private readonly skewMs;
+    private readonly onDeleteError;
+    private readonly logger;
+    private readonly now;
+    /** Memoised client promise — built at most once per store instance. */
+    private clientPromise;
+    /** In-process cache of live handles, keyed by `${model}:${stableKey}`. */
+    private readonly entries;
+    /** In-flight create promises when coalescing is enabled. */
+    private readonly inflight;
+    constructor(opts: GoogleCacheStoreOptions);
+    private getClient;
+    private isLive;
+    /**
+     * Create a new cached content resource.
+     *
+     * The `expiresAt` on the returned handle is computed from the server's
+     * `expireTime` when available, with a local-clock fallback of
+     * `now + ttlSeconds * 1000`.
+     */
+    create(input: {
+        model: string;
+        ttlSeconds: number;
+        contents?: unknown;
+        systemInstruction?: unknown;
+        displayName?: string;
+    }): Promise<GoogleCacheHandle>;
+    /**
+     * Return a live cached-content handle, creating one if none exists or the
+     * cached entry has expired (accounting for skew).
+     *
+     * Reuse is PROCESS-SCOPED only — this store instance's in-memory map.
+     *
+     * When `coalesce` is enabled, concurrent calls for the same key share one
+     * in-flight create.
+     */
+    getOrCreate(key: CacheKey, factory: () => Promise<{
+        ttlSeconds: number;
+        contents?: unknown;
+        systemInstruction?: unknown;
+    }>): Promise<GoogleCacheHandle>;
+    /**
+     * Extend the cache TTL if it will expire within `thresholdSeconds`.
+     *
+     * Fail-open: if the update call throws, the original handle is returned
+     * unchanged.  This method NEVER throws.
+     *
+     * @param handle - Handle to potentially refresh.
+     * @param opts.thresholdSeconds - Extend if expiry is within this many seconds.
+     *   Default 300.
+     * @param opts.extensionSeconds - New TTL to set.  Default: original TTL from
+     *   entries map, or 3600 s when the handle was not created via `getOrCreate`.
+     */
+    refreshIfExpiringSoon(handle: GoogleCacheHandle, opts?: {
+        thresholdSeconds?: number;
+        extensionSeconds?: number;
+    }): Promise<GoogleCacheHandle>;
+    /**
+     * Delete a cached content resource.
+     *
+     * Errors are forwarded to `onDeleteError` and NOT rethrown.
+     * The handle is removed from the in-process entries map regardless.
+     */
+    delete(handle: GoogleCacheHandle): Promise<void>;
+}
+
+export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiFilesClientLike, type GeminiSchema, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, zodToGeminiSchema };