@langchain/google 0.1.0

package/dist/chat_models/types.d.ts

@@ -0,0 +1,250 @@
+import { Prettify } from "../utils/misc.js";
+import { Gemini } from "./api-types.js";
+import { BindToolsInput } from "@langchain/core/language_models/chat_models";
+import { InteropZodType } from "@langchain/core/utils/types";
+
+//#region src/chat_models/types.d.ts
+interface ChatGoogleFields {
+  /**
+   * The temperature is used for sampling during response generation, which
+   * occurs when topP and topK are applied. Temperature controls the degree of
+   * randomness in token selection. Lower temperatures are good for prompts that
+   * require a less open-ended or creative response, while higher temperatures
+   * can lead to more diverse or creative results.
+   *
+   * Specify a lower value for less random responses and a higher value for more
+   * random responses.
+   */
+  temperature?: number;
+  /**
+   * Top-P changes how the model selects tokens for output. Tokens are selected
+   * from the most probable to least probable until the sum of their
+   * probabilities equals the top-P value.
+   *
+   * Specify a lower value for less random responses and a higher value for more
+   * random responses.
+   */
+  topP?: number;
+  /**
+   * Top-K changes how the model selects tokens for output. A top-K of 1 means
+   * the selected token is the most probable among all tokens in the model's
+   * vocabulary (also called greedy decoding), while a top-K of 3 means that the
+   * next token is selected from among the 3 most probable tokens (using
+   * temperature).
+   */
+  topK?: number;
+  /**
+   * Maximum number of tokens that can be generated in the response. A token is
+   * approximately four characters. 100 tokens correspond to roughly 60-80 words.
+   * Specify a lower value for shorter responses and a higher value for
+   * potentially longer responses.
+   */
+  maxOutputTokens?: number;
+  /**
+   * Positive values penalize tokens that already appear in the generated text,
+   * increasing the probability of generating more diverse content.
+   */
+  presencePenalty?: number;
+  /**
+   * Positive values penalize tokens that repeatedly appear in the generated
+   * text, decreasing the probability of repeating content.
+   */
+  frequencyPenalty?: number;
+  /**
+   * Specifies a list of strings that tells the model to stop generating text if
+   * one of the strings is encountered in the response. If a string appears
+   * multiple times in the response, then the response truncates where it's
+   * first encountered. The strings are case-sensitive.
+   */
+  stopSequences?: string[];
+  /**
+   * When seed is fixed to a specific value, the model makes a best effort to
+   * provide the same response for repeated requests. Deterministic output isn't
+   * guaranteed. Also, changing the model or parameter settings, such as the
+   * temperature, can cause variations in the response even when you use the
+   * same seed value. By default, a random seed value is used.
+   */
+  seed?: number;
+  /**
+   * If true, returns the log probabilities of the tokens that were chosen by
+   * the model at each step. By default, this parameter is set to false.
+   */
+  responseLogprobs?: boolean;
+  /**
+   * Returns the log probabilities of the top candidate tokens at each generation
+   * step. The model's chosen token might not be the same as the top candidate
+   * token at each step. Specify the number of candidates to return by using an
+   * integer value in the range of 1-20.
+   */
+  logprobs?: number;
+  /**
+   * Per request settings for blocking unsafe content
+   */
+  safetySettings?: Prettify<Gemini.SafetySetting>[];
+  /**
+   * Configuration for the model's thinking process
+   */
+  thinkingConfig?: Prettify<Gemini.ThinkingConfig>;
+  /**
+   * The schema that the generated response should match.
+   * Can be a Zod schema or a JSON Schema object.
+   * When set, the response will be structured according to this schema
+   * and `responseMimeType` will automatically be set to "application/json".
+   */
+  responseSchema?: InteropZodType | Record<string, unknown>;
+  /**
+   * A list of tools the model may use to generate the next response.
+   * Can be LangChain tools, OpenAI tools, or Gemini function declarations.
+   */
+  tools?: BindToolsInput[];
+  /**
+   * The requested modalities of the response.
+   * Represents the set of modalities that the model can return.
+   * An empty list is equivalent to requesting only text.
+   */
+  responseModalities?: Prettify<Gemini.GenerativeLanguageModality>[];
+  /**
+   * If true, enables enhanced civic answers feature.
+   */
+  enableEnhancedCivicAnswers?: boolean;
+  /**
+   * Speech generation configuration.
+   * You can use either Google's definition of the speech configuration,
+   * or a simplified version we've defined (which can be as simple
+   * as the name of a pre-defined voice).
+   */
+  speechConfig?: Prettify<Gemini.SpeechConfig> | SimplifiedSpeechConfig;
+  /**
+   * Configuration for image generation.
+   */
+  imageConfig?: Prettify<Gemini.ImageConfig>;
+  /**
+   * Media resolution for input media processing.
+   */
+  mediaResolution?: Prettify<Gemini.MediaResolution>;
+  /**
+   * The number of reasoning tokens that the model should generate.
+   * If explicitly set, then the reasoning blocks will be returned.
+   */
+  maxReasoningTokens?: number;
+  /**
+   * An alias for `maxReasoningTokens` for compatibility.
+   */
+  thinkingBudget?: number;
+  /**
+   * An alias for `maxReasoningTokens` under Gemini 2.5 or
+   * the primary thinking/reasoning setting for Gemini 3.
+   * If explicitly set, then the reasoning blocks will be returned.
+   */
+  reasoningEffort?: Gemini.ThinkingLevel;
+  /**
+   * An alias for `reasoningEffort` for compatibility.
+   */
+  thinkingLevel?: Gemini.ThinkingLevel;
+}
+declare module "./api-types.js" {
+  namespace Gemini {
+    namespace Part {
+      type CodeExecutionResult = Pick<Gemini.Part, "codeExecutionResult">;
+      type ExecutableCode = Pick<Gemini.Part, "executableCode">;
+      type FileData = Pick<Gemini.Part, "fileData" | "videoMetadata">;
+      type FunctionCall = Required<Pick<Gemini.Part, "functionCall">> & Pick<Gemini.Part, "thoughtSignature">;
+      type FunctionResponse = Pick<Gemini.Part, "functionResponse">;
+      type InlineData = Pick<Gemini.Part, "inlineData" | "videoMetadata">;
+      type MediaResolution = Pick<Gemini.Part, "mediaResolution">;
+      type PartMetadata = Pick<Gemini.Part, "partMetadata">;
+      type Text = Pick<Gemini.Part, "text">;
+      type Thought = Pick<Gemini.Part, "thought">;
+      type ThoughtSignature = Pick<Gemini.Part, "thoughtSignature">;
+    }
+    namespace PrebuiltVoiceConfig {
+      /**
+       * The name of a prebuilt voice that can be used for speech synthesis.
+       *
+       * Extracted as a non-nullable type from the GeminiBase.PrebuiltVoiceConfig["voiceName"] property.
+       */
+      type VoiceName = NonNullable<Gemini.PrebuiltVoiceConfig["voiceName"]>;
+    }
+    namespace SpeakerVoiceConfig {
+      /**
+       * The speaker identifier for a custom or multi-speaker TTS configuration.
+       *
+       * Extracted as a non-nullable type from the GeminiBase.SpeakerVoiceConfig["speaker"] property.
+       */
+      type Speaker = NonNullable<Gemini.SpeakerVoiceConfig["speaker"]>;
+    }
+    namespace SpeechConfig {
+      /**
+       * The BCP-47 language code for speech synthesis (e.g., "en-US").
+       *
+       * Extracted as a non-nullable type from the GeminiBase.SpeechConfig["languageCode"] property.
+       */
+      type LanguageCode = NonNullable<Gemini.SpeechConfig["languageCode"]>;
+    }
+    /**
+     * The level of "thinking" or reasoning configured for the model.
+     *
+     * Corresponds to GeminiBase.ThinkingConfig["thinkingLevel"].
+     */
+    type ThinkingLevel = Gemini.ThinkingConfig["thinkingLevel"];
+    /**
+     * The role of a content message. The spec types this as `string`, but
+     * the API only accepts these specific values.
+     */
+    type Role = "user" | "model" | "function";
+    /**
+     * Alias for the unwieldy generated grounding support type name.
+     */
+    type GroundingSupport = Gemini.GoogleAiGenerativelanguageV1betaGroundingSupport;
+    /**
+     * Alias for the unwieldy generated segment type name.
+     */
+    type Segment = Gemini.GoogleAiGenerativelanguageV1betaSegment;
+    namespace Tools {
+      /**
+       * The mode for function calling configuration, extracted from the
+       * FunctionCallingConfig interface.
+       */
+      type FunctionCallingConfigMode = Gemini.Tools.FunctionCallingConfig["mode"];
+    }
+    /**
+     * Legacy URL retrieval metadata (predecessor of UrlContextMetadata).
+     * Not in the current OpenAPI spec but still returned by the API.
+     */
+    interface UrlRetrievalMetadata {
+      urlRetrievalContexts?: Array<Gemini.UrlMetadata>;
+    }
+    interface Candidate {
+      /** @deprecated Use urlContextMetadata instead. */
+      readonly urlRetrievalMetadata?: UrlRetrievalMetadata;
+    }
+  }
+}
+/**
+ * Simplified speaker/name pair for multi-speaker config.
+ * - `speaker` derived from SpeakerVoiceConfig["speaker"]
+ * - `name` is the prebuilt voice name
+ */
+interface SpeechSpeakerName {
+  speaker: Gemini.SpeakerVoiceConfig.Speaker;
+  name: Gemini.PrebuiltVoiceConfig.VoiceName;
+}
+/** A voice can be a prebuilt voice name, a speaker/name pair, or an array of pairs */
+type SpeechVoice = Gemini.PrebuiltVoiceConfig.VoiceName | SpeechSpeakerName | SpeechSpeakerName[];
+/** Voice with language code (derived from SpeechConfig's languageCode) */
+interface SpeechVoiceLanguage {
+  voice: SpeechVoice;
+  languageCode: Gemini.SpeechConfig.LanguageCode;
+}
+/** Voices with language code */
+interface SpeechVoicesLanguage {
+  voices: SpeechVoice;
+  languageCode: Gemini.SpeechConfig.LanguageCode;
+}
+/** Simplified language config (with voice or voices) */
+type SimplifiedSpeechLanguageConfig = SpeechVoiceLanguage | SpeechVoicesLanguage;
+/** Top-level simplified config: just a voice, or voice+language */
+type SimplifiedSpeechConfig = SpeechVoice | SimplifiedSpeechLanguageConfig;
+//#endregion
+export { ChatGoogleFields };
+//# sourceMappingURL=types.d.ts.map

package/dist/clients/index.cjs

@@ -0,0 +1,219 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_const = require('../const.cjs');
+const require_misc = require('../utils/misc.cjs');
+const require_errors = require('../utils/errors.cjs');
+const require_gcp_auth = require('../utils/gcp-auth.cjs');
+const __langchain_core_utils_env = require_rolldown_runtime.__toESM(require("@langchain/core/utils/env"));
+
+//#region src/clients/index.ts
+/**
+* Abstract base class for API clients that interact with Google services.
+*
+* This class defines the contract for API clients, requiring implementations
+* to provide a fetch method that handles HTTP requests with appropriate
+* authentication headers. Concrete implementations should handle different
+* authentication strategies (API keys, service account credentials, etc.)
+* based on the runtime environment.
+*
+* @abstract
+*
+* @example
+* ```typescript
+* class MyApiClient extends ApiClient {
+*   async fetch(request: Request): Promise<Response> {
+*     // Add authentication headers
+*     request.headers.set('Authorization', 'Bearer token');
+*     return fetch(request);
+*   }
+* }
+* ```
+*/
+var ApiClient = class {
+	/**
+	* For some credential methods, we know what the project ID is.
+	* This is necessary for OAuth-based access to Vertex
+	*/
+	async getProjectId() {
+		return "unknown-project-id";
+	}
+};
+/**
+* Web-compatible API client for Google services.
+*
+* This client provides authentication for Google API requests in web environments
+* (browsers, edge functions, etc.) where the google-auth-library is not available.
+* It supports two authentication methods:
+*
+* 1. **API Key Authentication**: Simple key-based authentication suitable for
+*    public APIs and client-side applications.
+*
+* 2. **Service Account Credentials**: OAuth2-based authentication using GCP
+*    service account keys. The client automatically handles token generation
+*    and caching.
+*
+* The client follows this authentication priority:
+* 1. Explicit `apiKey` parameter
+* 2. `GOOGLE_API_KEY` environment variable
+* 3. Explicit `credentials` parameter
+* 4. `GOOGLE_CLOUD_CREDENTIALS` environment variable
+*
+* @extends ApiClient
+*
+* @example
+* ```typescript
+* // Using API key
+* const client = new WebApiClient({
+*   apiKey: 'your-api-key'
+* });
+*
+* // Using service account credentials
+* const client = new WebApiClient({
+*   credentials: {
+*     type: "service_account",
+*     project_id: "my-project",
+*     private_key_id: "key-id",
+*     private_key: "-----BEGIN PRIVATE KEY-----\n...",
+*     client_email: "service-account@project.iam.gserviceaccount.com",
+*     // ... other required fields
+*   }
+* });
+*
+* // Using environment variables
+* // Set GOOGLE_API_KEY or GOOGLE_CLOUD_CREDENTIALS
+* const client = new WebApiClient({});
+*
+* // Make authenticated requests
+* const request = new Request('https://api.google.com/...');
+* const response = await client.fetch(request);
+* ```
+*
+* @remarks
+* - API keys are added via the `X-Goog-Api-Key` header
+* - Service account tokens are added via the `Authorization` header with Bearer scheme
+* - Tokens are automatically cached and refreshed as needed
+* - For Node.js environments with advanced auth requirements, use NodeApiClient instead
+*
+* @see {@link NodeApiClient} for Node.js-specific authentication options
+* @see {@link GCPCredentials} for service account credential structure
+*/
+var WebApiClient = class extends ApiClient {
+	hasApiKey() {
+		return typeof this.apiKey === "string" && this.apiKey !== "";
+	}
+	async getProjectId() {
+		if (typeof this.credentials !== "undefined") return this.credentials.project_id;
+		else return super.getProjectId();
+	}
+	/**
+	* The Google API key used for authentication, if provided.
+	*
+	* This value is resolved from either the constructor parameter or the
+	* `GOOGLE_API_KEY` environment variable.
+	*
+	* @protected
+	*/
+	apiKey;
+	/**
+	* The normalized GCP service account credentials, if provided.
+	*
+	* This value is resolved from either the constructor parameter or the
+	* `GOOGLE_CLOUD_CREDENTIALS` environment variable, and is normalized
+	* to ensure immutability.
+	*
+	* @protected
+	*/
+	credentials;
+	/**
+	* Creates a new WebApiClient instance.
+	*
+	* The constructor initializes authentication credentials by checking:
+	* 1. Explicit parameters passed to the constructor
+	* 2. Environment variables (`GOOGLE_API_KEY`, `GOOGLE_CLOUD_CREDENTIALS`)
+	*
+	* Credentials are normalized and frozen to prevent accidental modification.
+	*
+	* @param params - Configuration parameters for the client
+	*
+	* @example
+	* ```typescript
+	* // Minimal configuration (uses environment variables)
+	* const client = new WebApiClient({});
+	*
+	* // With explicit API key
+	* const client = new WebApiClient({
+	*   apiKey: 'your-api-key'
+	* });
+	*
+	* // With service account credentials as JSON string
+	* const client = new WebApiClient({
+	*   credentials: '{"type":"service_account",...}'
+	* });
+	*
+	* // With service account credentials as object
+	* const client = new WebApiClient({
+	*   credentials: {
+	*     type: "service_account",
+	*     // ... other fields
+	*   }
+	* });
+	* ```
+	*/
+	constructor(params) {
+		super();
+		this.params = params;
+		this.apiKey = params.apiKey ?? (0, __langchain_core_utils_env.getEnvironmentVariable)("GOOGLE_API_KEY");
+		this.credentials = require_misc.iife(() => {
+			if (params.credentials) return require_gcp_auth.normalizeGCPCredentials(params.credentials);
+			const credentialsVar = (0, __langchain_core_utils_env.getEnvironmentVariable)("GOOGLE_CLOUD_CREDENTIALS");
+			if (credentialsVar) return require_gcp_auth.normalizeGCPCredentials(credentialsVar);
+			return void 0;
+		});
+	}
+	/**
+	* Executes an HTTP request with appropriate Google API authentication.
+	*
+	* This method adds authentication headers to the request based on the
+	* configured authentication method:
+	*
+	* - If an API key is configured, adds the `X-Goog-Api-Key` header
+	* - If service account credentials are configured, generates an access token
+	*   and adds it via the `Authorization` header with Bearer scheme
+	*
+	* The authentication priority is:
+	* 1. API key (if provided)
+	* 2. Service account credentials (if provided)
+	*
+	* @param request - The HTTP request to execute. Headers will be modified
+	*                  in-place to include authentication information.
+	* @returns A Promise that resolves to the HTTP response
+	*
+	* @throws {AuthError} If no authentication method is available (neither apiKey
+	*                     nor credentials), or if service account authentication
+	*                     fails (e.g., invalid credentials, network error, or
+	*                     token generation failure)
+	*
+	* @example
+	* ```typescript
+	* const client = new WebApiClient({ apiKey: 'your-key' });
+	* const request = new Request('https://generativelanguage.googleapis.com/v1/models');
+	* const response = await client.fetch(request);
+	* const data = await response.json();
+	* ```
+	*
+	* @remarks
+	* - The request object is modified in-place by adding headers
+	* - Service account tokens are automatically cached and refreshed
+	* - If both API key and credentials are provided, API key takes precedence
+	*/
+	async fetch(request) {
+		if (!this.apiKey && !this.credentials) throw new require_errors.AuthError({ message: "No authentication method available. Please provide either an apiKey or credentials." });
+		if (this.apiKey) request.headers.set(require_const.GOOGLE_API_KEY_HEADER, this.apiKey);
+		if (this.credentials) request.headers.set(require_const.GCP_API_KEY_HEADER, `Bearer ${await require_gcp_auth.getGCPCredentialsAccessToken(this.credentials)}`);
+		return fetch(request);
+	}
+};
+
+//#endregion
+exports.ApiClient = ApiClient;
+exports.WebApiClient = WebApiClient;
+//# sourceMappingURL=index.cjs.map

package/dist/clients/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["params: WebApiClientParams","iife","normalizeGCPCredentials","request: Request","AuthError","GOOGLE_API_KEY_HEADER","GCP_API_KEY_HEADER","getGCPCredentialsAccessToken"],"sources":["../../src/clients/index.ts"],"sourcesContent":["import { getEnvironmentVariable } from \"@langchain/core/utils/env\";\nimport { GCP_API_KEY_HEADER, GOOGLE_API_KEY_HEADER } from \"../const.js\";\nimport {\n  GCPCredentials,\n  getGCPCredentialsAccessToken,\n  normalizeGCPCredentials,\n} from \"../utils/gcp-auth.js\";\nimport { AuthError } from \"../utils/errors.js\";\nimport { iife } from \"../utils/misc.js\";\n\n/**\n * Abstract base class for API clients that interact with Google services.\n *\n * This class defines the contract for API clients, requiring implementations\n * to provide a fetch method that handles HTTP requests with appropriate\n * authentication headers. Concrete implementations should handle different\n * authentication strategies (API keys, service account credentials, etc.)\n * based on the runtime environment.\n *\n * @abstract\n *\n * @example\n * ```typescript\n * class MyApiClient extends ApiClient {\n *   async fetch(request: Request): Promise<Response> {\n *     // Add authentication headers\n *     request.headers.set('Authorization', 'Bearer token');\n *     return fetch(request);\n *   }\n * }\n * ```\n */\nexport abstract class ApiClient {\n  /**\n   * Has an API Key been set for this client?\n   */\n  abstract hasApiKey(): boolean;\n\n  /**\n   * For some credential methods, we know what the project ID is.\n   * This is necessary for OAuth-based access to Vertex\n   */\n  async getProjectId(): Promise<string> {\n    return \"unknown-project-id\";\n  }\n\n  /**\n   * Executes an HTTP request with appropriate authentication.\n   *\n   * Implementations should add necessary authentication headers to the request\n   * before forwarding it to the underlying fetch implementation.\n   *\n   * @param request - The HTTP request to execute\n   * @returns A Promise that resolves to the HTTP response\n   *\n   * @abstract\n   */\n  abstract fetch(request: Request): Promise<Response>;\n}\n\n/**\n * Configuration parameters for the WebApiClient.\n *\n * This interface defines the authentication options available for web-based\n * API clients. Authentication can be provided via an API key or GCP service\n * account credentials. The client will automatically check environment variables\n * if explicit values are not provided.\n *\n * @interface\n */\nexport interface WebApiClientParams {\n  /**\n   * Google API key for authentication.\n   *\n   * If not provided, the client will attempt to read from the\n   * `GOOGLE_API_KEY` environment variable.\n   *\n   * @see https://cloud.google.com/docs/authentication/api-keys\n   */\n  apiKey?: string;\n\n  /**\n   * GCP service account credentials for authentication.\n   *\n   * Can be provided as either:\n   * - A JSON string containing the service account key\n   * - A GCPCredentials object\n   *\n   * If not provided, the client will attempt to read from the\n   * `GOOGLE_CLOUD_CREDENTIALS` environment variable.\n   *\n   * @see https://cloud.google.com/iam/docs/creating-managing-service-account-keys\n   */\n  credentials?: string | GCPCredentials;\n\n  /**\n   * Google Auth options configuration.\n   *\n   * @deprecated This option is not supported in web environments.\n   *             Import from `@langchain/google/node` to configure google auth options\n   *             using the NodeApiClient instead.\n   */\n  googleAuthOptions?: never;\n}\n\n/**\n * Web-compatible API client for Google services.\n *\n * This client provides authentication for Google API requests in web environments\n * (browsers, edge functions, etc.) where the google-auth-library is not available.\n * It supports two authentication methods:\n *\n * 1. **API Key Authentication**: Simple key-based authentication suitable for\n *    public APIs and client-side applications.\n *\n * 2. **Service Account Credentials**: OAuth2-based authentication using GCP\n *    service account keys. The client automatically handles token generation\n *    and caching.\n *\n * The client follows this authentication priority:\n * 1. Explicit `apiKey` parameter\n * 2. `GOOGLE_API_KEY` environment variable\n * 3. Explicit `credentials` parameter\n * 4. `GOOGLE_CLOUD_CREDENTIALS` environment variable\n *\n * @extends ApiClient\n *\n * @example\n * ```typescript\n * // Using API key\n * const client = new WebApiClient({\n *   apiKey: 'your-api-key'\n * });\n *\n * // Using service account credentials\n * const client = new WebApiClient({\n *   credentials: {\n *     type: \"service_account\",\n *     project_id: \"my-project\",\n *     private_key_id: \"key-id\",\n *     private_key: \"-----BEGIN PRIVATE KEY-----\\n...\",\n *     client_email: \"service-account@project.iam.gserviceaccount.com\",\n *     // ... other required fields\n *   }\n * });\n *\n * // Using environment variables\n * // Set GOOGLE_API_KEY or GOOGLE_CLOUD_CREDENTIALS\n * const client = new WebApiClient({});\n *\n * // Make authenticated requests\n * const request = new Request('https://api.google.com/...');\n * const response = await client.fetch(request);\n * ```\n *\n * @remarks\n * - API keys are added via the `X-Goog-Api-Key` header\n * - Service account tokens are added via the `Authorization` header with Bearer scheme\n * - Tokens are automatically cached and refreshed as needed\n * - For Node.js environments with advanced auth requirements, use NodeApiClient instead\n *\n * @see {@link NodeApiClient} for Node.js-specific authentication options\n * @see {@link GCPCredentials} for service account credential structure\n */\nexport class WebApiClient extends ApiClient {\n  hasApiKey(): boolean {\n    return typeof this.apiKey === \"string\" && this.apiKey !== \"\";\n  }\n\n  async getProjectId(): Promise<string> {\n    if (typeof this.credentials !== \"undefined\") {\n      return this.credentials.project_id;\n    } else {\n      return super.getProjectId();\n    }\n  }\n\n  /**\n   * The Google API key used for authentication, if provided.\n   *\n   * This value is resolved from either the constructor parameter or the\n   * `GOOGLE_API_KEY` environment variable.\n   *\n   * @protected\n   */\n  protected apiKey?: string;\n\n  /**\n   * The normalized GCP service account credentials, if provided.\n   *\n   * This value is resolved from either the constructor parameter or the\n   * `GOOGLE_CLOUD_CREDENTIALS` environment variable, and is normalized\n   * to ensure immutability.\n   *\n   * @protected\n   */\n  protected credentials?: GCPCredentials;\n\n  /**\n   * Creates a new WebApiClient instance.\n   *\n   * The constructor initializes authentication credentials by checking:\n   * 1. Explicit parameters passed to the constructor\n   * 2. Environment variables (`GOOGLE_API_KEY`, `GOOGLE_CLOUD_CREDENTIALS`)\n   *\n   * Credentials are normalized and frozen to prevent accidental modification.\n   *\n   * @param params - Configuration parameters for the client\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration (uses environment variables)\n   * const client = new WebApiClient({});\n   *\n   * // With explicit API key\n   * const client = new WebApiClient({\n   *   apiKey: 'your-api-key'\n   * });\n   *\n   * // With service account credentials as JSON string\n   * const client = new WebApiClient({\n   *   credentials: '{\"type\":\"service_account\",...}'\n   * });\n   *\n   * // With service account credentials as object\n   * const client = new WebApiClient({\n   *   credentials: {\n   *     type: \"service_account\",\n   *     // ... other fields\n   *   }\n   * });\n   * ```\n   */\n  constructor(protected params: WebApiClientParams) {\n    super();\n    this.apiKey = params.apiKey ?? getEnvironmentVariable(\"GOOGLE_API_KEY\");\n    this.credentials = iife(() => {\n      if (params.credentials) {\n        return normalizeGCPCredentials(params.credentials);\n      }\n      const credentialsVar = getEnvironmentVariable(\"GOOGLE_CLOUD_CREDENTIALS\");\n      if (credentialsVar) {\n        return normalizeGCPCredentials(credentialsVar);\n      }\n      return undefined;\n    });\n  }\n\n  /**\n   * Executes an HTTP request with appropriate Google API authentication.\n   *\n   * This method adds authentication headers to the request based on the\n   * configured authentication method:\n   *\n   * - If an API key is configured, adds the `X-Goog-Api-Key` header\n   * - If service account credentials are configured, generates an access token\n   *   and adds it via the `Authorization` header with Bearer scheme\n   *\n   * The authentication priority is:\n   * 1. API key (if provided)\n   * 2. Service account credentials (if provided)\n   *\n   * @param request - The HTTP request to execute. Headers will be modified\n   *                  in-place to include authentication information.\n   * @returns A Promise that resolves to the HTTP response\n   *\n   * @throws {AuthError} If no authentication method is available (neither apiKey\n   *                     nor credentials), or if service account authentication\n   *                     fails (e.g., invalid credentials, network error, or\n   *                     token generation failure)\n   *\n   * @example\n   * ```typescript\n   * const client = new WebApiClient({ apiKey: 'your-key' });\n   * const request = new Request('https://generativelanguage.googleapis.com/v1/models');\n   * const response = await client.fetch(request);\n   * const data = await response.json();\n   * ```\n   *\n   * @remarks\n   * - The request object is modified in-place by adding headers\n   * - Service account tokens are automatically cached and refreshed\n   * - If both API key and credentials are provided, API key takes precedence\n   */\n  async fetch(request: Request): Promise<Response> {\n    if (!this.apiKey && !this.credentials) {\n      throw new AuthError({\n        message:\n          \"No authentication method available. Please provide either an apiKey or credentials.\",\n      });\n    }\n    if (this.apiKey) {\n      request.headers.set(GOOGLE_API_KEY_HEADER, this.apiKey);\n    }\n    if (this.credentials) {\n      request.headers.set(\n        GCP_API_KEY_HEADER,\n        `Bearer ${await getGCPCredentialsAccessToken(this.credentials)}`\n      );\n    }\n    return fetch(request);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAsB,YAAtB,MAAgC;;;;;CAU9B,MAAM,eAAgC;AACpC,SAAO;CACR;AAcF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0GD,IAAa,eAAb,cAAkC,UAAU;CAC1C,YAAqB;AACnB,SAAO,OAAO,KAAK,WAAW,YAAY,KAAK,WAAW;CAC3D;CAED,MAAM,eAAgC;AACpC,MAAI,OAAO,KAAK,gBAAgB,YAC9B,QAAO,KAAK,YAAY;MAExB,QAAO,MAAM,cAAc;CAE9B;;;;;;;;;CAUD,AAAU;;;;;;;;;;CAWV,AAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCV,YAAsBA,QAA4B;EAChD,OAAO;EADa;EAEpB,KAAK,SAAS,OAAO,iEAAiC,iBAAiB;EACvE,KAAK,cAAcC,kBAAK,MAAM;AAC5B,OAAI,OAAO,YACT,QAAOC,yCAAwB,OAAO,YAAY;GAEpD,MAAM,wEAAwC,2BAA2B;AACzE,OAAI,eACF,QAAOA,yCAAwB,eAAe;AAEhD,UAAO;EACR,EAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCD,MAAM,MAAMC,SAAqC;AAC/C,MAAI,CAAC,KAAK,UAAU,CAAC,KAAK,YACxB,OAAM,IAAIC,yBAAU,EAClB,SACE,sFACH;AAEH,MAAI,KAAK,QACP,QAAQ,QAAQ,IAAIC,qCAAuB,KAAK,OAAO;AAEzD,MAAI,KAAK,aACP,QAAQ,QAAQ,IACdC,kCACA,CAAC,OAAO,EAAE,MAAMC,8CAA6B,KAAK,YAAY,EAAE,CACjE;AAEH,SAAO,MAAM,QAAQ;CACtB;AACF"}

package/dist/clients/index.d.cts

@@ -0,0 +1,49 @@
+//#region src/clients/index.d.ts
+/**
+ * Abstract base class for API clients that interact with Google services.
+ *
+ * This class defines the contract for API clients, requiring implementations
+ * to provide a fetch method that handles HTTP requests with appropriate
+ * authentication headers. Concrete implementations should handle different
+ * authentication strategies (API keys, service account credentials, etc.)
+ * based on the runtime environment.
+ *
+ * @abstract
+ *
+ * @example
+ * ```typescript
+ * class MyApiClient extends ApiClient {
+ *   async fetch(request: Request): Promise<Response> {
+ *     // Add authentication headers
+ *     request.headers.set('Authorization', 'Bearer token');
+ *     return fetch(request);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ApiClient {
+  /**
+   * Has an API Key been set for this client?
+   */
+  abstract hasApiKey(): boolean;
+  /**
+   * For some credential methods, we know what the project ID is.
+   * This is necessary for OAuth-based access to Vertex
+   */
+  getProjectId(): Promise<string>;
+  /**
+   * Executes an HTTP request with appropriate authentication.
+   *
+   * Implementations should add necessary authentication headers to the request
+   * before forwarding it to the underlying fetch implementation.
+   *
+   * @param request - The HTTP request to execute
+   * @returns A Promise that resolves to the HTTP response
+   *
+   * @abstract
+   */
+  abstract fetch(request: Request): Promise<Response>;
+}
+//#endregion
+export { ApiClient };
+//# sourceMappingURL=index.d.cts.map

package/dist/clients/index.d.ts

@@ -0,0 +1,49 @@
+//#region src/clients/index.d.ts
+/**
+ * Abstract base class for API clients that interact with Google services.
+ *
+ * This class defines the contract for API clients, requiring implementations
+ * to provide a fetch method that handles HTTP requests with appropriate
+ * authentication headers. Concrete implementations should handle different
+ * authentication strategies (API keys, service account credentials, etc.)
+ * based on the runtime environment.
+ *
+ * @abstract
+ *
+ * @example
+ * ```typescript
+ * class MyApiClient extends ApiClient {
+ *   async fetch(request: Request): Promise<Response> {
+ *     // Add authentication headers
+ *     request.headers.set('Authorization', 'Bearer token');
+ *     return fetch(request);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ApiClient {
+  /**
+   * Has an API Key been set for this client?
+   */
+  abstract hasApiKey(): boolean;
+  /**
+   * For some credential methods, we know what the project ID is.
+   * This is necessary for OAuth-based access to Vertex
+   */
+  getProjectId(): Promise<string>;
+  /**
+   * Executes an HTTP request with appropriate authentication.
+   *
+   * Implementations should add necessary authentication headers to the request
+   * before forwarding it to the underlying fetch implementation.
+   *
+   * @param request - The HTTP request to execute
+   * @returns A Promise that resolves to the HTTP response
+   *
+   * @abstract
+   */
+  abstract fetch(request: Request): Promise<Response>;
+}
+//#endregion
+export { ApiClient };
+//# sourceMappingURL=index.d.ts.map