@langchain/google 0.1.0

package/dist/clients/node.d.ts

@@ -0,0 +1,59 @@
+import { GCPCredentials } from "../utils/gcp-auth.js";
+import { GoogleAuth, GoogleAuthOptions } from "google-auth-library";
+
+//#region src/clients/node.d.ts
+
+/**
+ * Configuration parameters for the NodeApiClient.
+ *
+ * This interface defines the authentication options available for Node.js-based
+ * API clients. Authentication can be provided via an API key, GCP service
+ * account credentials, or advanced Google Auth options. The client will
+ * automatically check environment variables if explicit values are not provided.
+ *
+ * @interface
+ */
+interface NodeApiClientParams {
+  /**
+   * Google API key for authentication.
+   *
+   * If not provided, the client will attempt to read from the
+   * `GOOGLE_API_KEY` environment variable.
+   *
+   * @see https://cloud.google.com/docs/authentication/api-keys
+   */
+  apiKey?: string;
+  /**
+   * GCP service account credentials for authentication.
+   *
+   * Can be provided as either:
+   * - A JSON string containing the service account key
+   * - A GCPCredentials object
+   *
+   * If not provided, the client will attempt to read from the
+   * `GOOGLE_CLOUD_CREDENTIALS` environment variable.
+   *
+   * @see https://cloud.google.com/iam/docs/creating-managing-service-account-keys
+   */
+  credentials?: string | GCPCredentials;
+  /**
+   * Google Auth options configuration.
+   *
+   * Provides fine-grained control over authentication behavior using the
+   * google-auth-library. This option enables:
+   * - Custom OAuth2 scopes
+   * - Application Default Credentials (ADC)
+   * - Impersonation and delegation
+   * - Custom credential sources
+   *
+   * When provided, this takes precedence over simple credential-based auth
+   * but is lower priority than API key authentication.
+   *
+   * @see https://github.com/googleapis/google-auth-library-nodejs
+   * @see https://cloud.google.com/docs/authentication/application-default-credentials
+   */
+  googleAuthOptions?: GoogleAuthOptions;
+}
+//#endregion
+export { NodeApiClientParams };
+//# sourceMappingURL=node.d.ts.map

package/dist/clients/node.js

@@ -0,0 +1,325 @@
+import { GCP_API_KEY_HEADER, GOOGLE_API_KEY_HEADER } from "../const.js";
+import { iife } from "../utils/misc.js";
+import { ConfigurationError } from "../utils/errors.js";
+import { getGCPCredentialsAccessToken, normalizeGCPCredentials } from "../utils/gcp-auth.js";
+import { ApiClient } from "./index.js";
+import { getEnvironmentVariable } from "@langchain/core/utils/env";
+import { GoogleAuth } from "google-auth-library";
+
+//#region src/clients/node.ts
+/**
+* Node.js-specific API client for Google services.
+*
+* This client provides comprehensive authentication for Google API requests in
+* Node.js environments, leveraging the full capabilities of the google-auth-library.
+* It supports three authentication methods with the following priority:
+*
+* 1. **API Key Authentication**: Simple key-based authentication suitable for
+*    public APIs and development environments.
+*
+* 2. **Service Account Credentials**: OAuth2-based authentication using GCP
+*    service account keys. The client automatically handles token generation
+*    and caching using a web-compatible implementation.
+*
+* 3. **Google Auth Library**: Advanced authentication using google-auth-library,
+*    supporting Application Default Credentials (ADC), custom scopes, and
+*    various credential sources.
+*
+* 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
+* 5. `googleAuthOptions` parameter
+* 6. Application Default Credentials (if googleAuthOptions is provided without explicit credentials)
+*
+* @extends ApiClient
+*
+* @example
+* ```typescript
+* // Using API key
+* const client = new NodeApiClient({
+*   apiKey: 'your-api-key'
+* });
+*
+* // Using service account credentials
+* const client = new NodeApiClient({
+*   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 Google Auth with custom scopes
+* const client = new NodeApiClient({
+*   googleAuthOptions: {
+*     scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+*     keyFilename: '/path/to/service-account-key.json'
+*   }
+* });
+*
+* // Using Application Default Credentials
+* const client = new NodeApiClient({
+*   googleAuthOptions: {}
+* });
+*
+* // Using environment variables
+* // Set GOOGLE_API_KEY or GOOGLE_CLOUD_CREDENTIALS
+* const client = new NodeApiClient();
+*
+* // 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
+* - Google Auth headers are automatically generated and added by google-auth-library
+* - Tokens are automatically cached and refreshed as needed
+* - For web/edge environments without google-auth-library, use WebApiClient instead
+*
+* @see {@link WebApiClient} for web-compatible authentication without google-auth-library
+* @see {@link GCPCredentials} for service account credential structure
+* @see {@link GoogleAuthOptions} for advanced authentication configuration
+*/
+var NodeApiClient = class extends ApiClient {
+	hasApiKey() {
+		return typeof this.apiKey === "string" && this.apiKey !== "";
+	}
+	async getProjectId() {
+		if (typeof this.credentials !== "undefined") return this.credentials.project_id;
+		else if (typeof this.googleAuth !== "undefined") return this.googleAuth.getProjectId();
+		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;
+	/**
+	* The Google Auth instance for advanced authentication, if configured.
+	*
+	* This instance is created when `googleAuthOptions` is provided and
+	* handles Application Default Credentials, custom scopes, and other
+	* advanced authentication scenarios.
+	*
+	* @protected
+	*/
+	googleAuth;
+	/**
+	* Creates a new NodeApiClient instance.
+	*
+	* The constructor initializes authentication credentials by checking:
+	* 1. Explicit parameters passed to the constructor
+	* 2. Environment variables (`GOOGLE_API_KEY`, `GOOGLE_CLOUD_CREDENTIALS`)
+	* 3. Application Default Credentials (if googleAuthOptions is provided)
+	*
+	* Credentials are normalized and frozen to prevent accidental modification.
+	* The GoogleAuth instance is lazily initialized only when googleAuthOptions
+	* is provided.
+	*
+	* @param params - Configuration parameters for the client. Defaults to an empty object.
+	*
+	* @example
+	* ```typescript
+	* // Minimal configuration (uses environment variables or ADC)
+	* const client = new NodeApiClient();
+	*
+	* // 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 NodeApiClient({
+	*   credentials: {
+	*     type: "service_account",
+	*     // ... other fields
+	*   }
+	* });
+	*
+	* // With Google Auth options
+	* const client = new NodeApiClient({
+	*   googleAuthOptions: {
+	*     scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+	*     projectId: 'my-project'
+	*   }
+	* });
+	* ```
+	*/
+	constructor(params = {}) {
+		super();
+		this.params = params;
+		this.apiKey = params.apiKey ?? getEnvironmentVariable("GOOGLE_API_KEY");
+		this.credentials = iife(() => {
+			if (params.credentials) return normalizeGCPCredentials(params.credentials);
+			const credentialsVar = getEnvironmentVariable("GOOGLE_CLOUD_CREDENTIALS");
+			if (credentialsVar) return normalizeGCPCredentials(credentialsVar);
+			return void 0;
+		});
+		this.googleAuth = iife(() => {
+			if (params.googleAuthOptions) return new GoogleAuth(params.googleAuthOptions);
+			if (!this.apiKey && !this.credentials) return new GoogleAuth();
+			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, following this priority:
+	*
+	* 1. If an API key is configured, adds the `X-Goog-Api-Key` header
+	* 2. If service account credentials are configured, generates an access token
+	*    and adds it via the `Authorization` header with Bearer scheme
+	* 3. If Google Auth is configured, uses google-auth-library to generate
+	*    appropriate authentication headers (may include Authorization, x-goog-user-project, etc.)
+	*
+	* The authentication priority ensures that explicit API keys take precedence,
+	* followed by service account credentials, and finally Google Auth options.
+	*
+	* @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 service account authentication fails (e.g., invalid
+	*                     credentials, network error, or token generation failure)
+	* @throws {Error} If Google Auth authentication fails (e.g., missing credentials,
+	*                 invalid configuration, or ADC not available)
+	*
+	* @example
+	* ```typescript
+	* const client = new NodeApiClient({ 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
+	* - Google Auth tokens are managed by google-auth-library with automatic refresh
+	* - Only one authentication method is used per request (based on priority)
+	* - Google Auth may add multiple headers depending on the authentication type
+	*/
+	async fetch(request) {
+		if (this.apiKey) request.headers.set(GOOGLE_API_KEY_HEADER, this.apiKey);
+		else if (this.credentials) request.headers.set(GCP_API_KEY_HEADER, `Bearer ${getGCPCredentialsAccessToken(this.credentials)}`);
+		else if (this.googleAuth) {
+			const authHeaders = await this.googleAuth.getRequestHeaders(request.url);
+			authHeaders.forEach((value, key) => {
+				if (value !== null) request.headers.set(key, value);
+			});
+		}
+		return fetch(request);
+	}
+};
+/**
+* Ensures that Google Auth options include required OAuth2 scopes.
+*
+* This utility function validates and augments GoogleAuthOptions to ensure
+* that all required OAuth2 scopes are present. It handles three scenarios:
+*
+* 1. **No auth options provided**: Creates new options with required scopes
+* 2. **Auth options without scopes**: Adds required scopes to existing options
+* 3. **Auth options with scopes**: Validates that all required scopes are present
+*
+* This is particularly useful when working with Google APIs that require specific
+* scopes for access, ensuring that authentication is properly configured before
+* making API requests.
+*
+* @param authOptions - The existing Google Auth options to validate/augment.
+*                      Can be undefined or an empty object.
+* @param requiredScopes - Array of OAuth2 scope URLs that must be present.
+*                         These are typically Google API scope URLs like
+*                         'https://www.googleapis.com/auth/cloud-platform'
+* @returns The validated/augmented GoogleAuthOptions with all required scopes
+*
+* @throws {Error} If authOptions already has scopes but is missing any of the
+*                 required scopes. This prevents accidental scope reduction that
+*                 could break API access.
+*
+* @example
+* ```typescript
+* // Create new options with required scopes
+* const options = ensureAuthScopes(undefined, [
+*   'https://www.googleapis.com/auth/cloud-platform'
+* ]);
+* // Result: { scopes: ['https://www.googleapis.com/auth/cloud-platform'] }
+*
+* // Add scopes to existing options
+* const options = ensureAuthScopes(
+*   { projectId: 'my-project' },
+*   ['https://www.googleapis.com/auth/cloud-platform']
+* );
+* // Result: { projectId: 'my-project', scopes: [...] }
+*
+* // Validate existing scopes
+* const options = ensureAuthScopes(
+*   { scopes: ['https://www.googleapis.com/auth/cloud-platform'] },
+*   ['https://www.googleapis.com/auth/cloud-platform']
+* );
+* // Result: Original options (validation passed)
+*
+* // Error case - missing required scope
+* try {
+*   ensureAuthScopes(
+*     { scopes: ['https://www.googleapis.com/auth/userinfo.email'] },
+*     ['https://www.googleapis.com/auth/cloud-platform']
+*   );
+* } catch (error) {
+*   // Error: Invalid auth scopes. Scopes must include ...
+* }
+* ```
+*
+* @remarks
+* - Scopes can be provided as a string or array of strings in GoogleAuthOptions
+* - The function normalizes single-string scopes to arrays for validation
+* - Required scopes are not automatically added if existing scopes are present;
+*   instead, an error is thrown to prevent unintended scope changes
+* - This function does not modify the original authOptions object
+*
+* @see https://developers.google.com/identity/protocols/oauth2/scopes
+* @see {@link GoogleAuthOptions} for the full authentication configuration interface
+*/
+function ensureAuthScopes(authOptions, requiredScopes) {
+	if (!authOptions) return { scopes: requiredScopes };
+	else if (!authOptions.scopes) return {
+		...authOptions,
+		scopes: requiredScopes
+	};
+	else {
+		const existingScopes = Array.isArray(authOptions.scopes) ? authOptions.scopes : [authOptions.scopes];
+		const missingScopes = requiredScopes.filter((scope) => !existingScopes.includes(scope));
+		if (missingScopes.length > 0) throw new ConfigurationError(`Invalid auth scopes. Scopes must include ${requiredScopes.join(", ")}`);
+	}
+	return authOptions;
+}
+
+//#endregion
+export { NodeApiClient, ensureAuthScopes };
+//# sourceMappingURL=node.js.map

package/dist/clients/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","names":["params: NodeApiClientParams","request: Request","authOptions: GoogleAuthOptions","requiredScopes: string[]"],"sources":["../../src/clients/node.ts"],"sourcesContent":["import { GoogleAuth, type GoogleAuthOptions } from \"google-auth-library\";\nimport { getEnvironmentVariable } from \"@langchain/core/utils/env\";\nimport { GCP_API_KEY_HEADER, GOOGLE_API_KEY_HEADER } from \"../const.js\";\nimport { ApiClient } from \"./index.js\";\nimport {\n  GCPCredentials,\n  getGCPCredentialsAccessToken,\n  normalizeGCPCredentials,\n} from \"../utils/gcp-auth.js\";\nimport { ConfigurationError } from \"../utils/errors.js\";\nimport { iife } from \"../utils/misc.js\";\n\n/**\n * Configuration parameters for the NodeApiClient.\n *\n * This interface defines the authentication options available for Node.js-based\n * API clients. Authentication can be provided via an API key, GCP service\n * account credentials, or advanced Google Auth options. The client will\n * automatically check environment variables if explicit values are not provided.\n *\n * @interface\n */\nexport interface NodeApiClientParams {\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   * Provides fine-grained control over authentication behavior using the\n   * google-auth-library. This option enables:\n   * - Custom OAuth2 scopes\n   * - Application Default Credentials (ADC)\n   * - Impersonation and delegation\n   * - Custom credential sources\n   *\n   * When provided, this takes precedence over simple credential-based auth\n   * but is lower priority than API key authentication.\n   *\n   * @see https://github.com/googleapis/google-auth-library-nodejs\n   * @see https://cloud.google.com/docs/authentication/application-default-credentials\n   */\n  googleAuthOptions?: GoogleAuthOptions;\n}\n\n/**\n * Node.js-specific API client for Google services.\n *\n * This client provides comprehensive authentication for Google API requests in\n * Node.js environments, leveraging the full capabilities of the google-auth-library.\n * It supports three authentication methods with the following priority:\n *\n * 1. **API Key Authentication**: Simple key-based authentication suitable for\n *    public APIs and development environments.\n *\n * 2. **Service Account Credentials**: OAuth2-based authentication using GCP\n *    service account keys. The client automatically handles token generation\n *    and caching using a web-compatible implementation.\n *\n * 3. **Google Auth Library**: Advanced authentication using google-auth-library,\n *    supporting Application Default Credentials (ADC), custom scopes, and\n *    various credential sources.\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 * 5. `googleAuthOptions` parameter\n * 6. Application Default Credentials (if googleAuthOptions is provided without explicit credentials)\n *\n * @extends ApiClient\n *\n * @example\n * ```typescript\n * // Using API key\n * const client = new NodeApiClient({\n *   apiKey: 'your-api-key'\n * });\n *\n * // Using service account credentials\n * const client = new NodeApiClient({\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 Google Auth with custom scopes\n * const client = new NodeApiClient({\n *   googleAuthOptions: {\n *     scopes: ['https://www.googleapis.com/auth/cloud-platform'],\n *     keyFilename: '/path/to/service-account-key.json'\n *   }\n * });\n *\n * // Using Application Default Credentials\n * const client = new NodeApiClient({\n *   googleAuthOptions: {}\n * });\n *\n * // Using environment variables\n * // Set GOOGLE_API_KEY or GOOGLE_CLOUD_CREDENTIALS\n * const client = new NodeApiClient();\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 * - Google Auth headers are automatically generated and added by google-auth-library\n * - Tokens are automatically cached and refreshed as needed\n * - For web/edge environments without google-auth-library, use WebApiClient instead\n *\n * @see {@link WebApiClient} for web-compatible authentication without google-auth-library\n * @see {@link GCPCredentials} for service account credential structure\n * @see {@link GoogleAuthOptions} for advanced authentication configuration\n */\nexport class NodeApiClient 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 if (typeof this.googleAuth !== \"undefined\") {\n      return this.googleAuth.getProjectId();\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   * The Google Auth instance for advanced authentication, if configured.\n   *\n   * This instance is created when `googleAuthOptions` is provided and\n   * handles Application Default Credentials, custom scopes, and other\n   * advanced authentication scenarios.\n   *\n   * @protected\n   */\n  protected googleAuth?: GoogleAuth;\n\n  /**\n   * Creates a new NodeApiClient 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   * 3. Application Default Credentials (if googleAuthOptions is provided)\n   *\n   * Credentials are normalized and frozen to prevent accidental modification.\n   * The GoogleAuth instance is lazily initialized only when googleAuthOptions\n   * is provided.\n   *\n   * @param params - Configuration parameters for the client. Defaults to an empty object.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration (uses environment variables or ADC)\n   * const client = new NodeApiClient();\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 NodeApiClient({\n   *   credentials: {\n   *     type: \"service_account\",\n   *     // ... other fields\n   *   }\n   * });\n   *\n   * // With Google Auth options\n   * const client = new NodeApiClient({\n   *   googleAuthOptions: {\n   *     scopes: ['https://www.googleapis.com/auth/cloud-platform'],\n   *     projectId: 'my-project'\n   *   }\n   * });\n   * ```\n   */\n  constructor(protected params: NodeApiClientParams = {}) {\n    super();\n\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    this.googleAuth = iife(() => {\n      if (params.googleAuthOptions) {\n        return new GoogleAuth(params.googleAuthOptions);\n      }\n      if (!this.apiKey && !this.credentials) {\n        return new GoogleAuth();\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, following this priority:\n   *\n   * 1. If an API key is configured, adds the `X-Goog-Api-Key` header\n   * 2. If service account credentials are configured, generates an access token\n   *    and adds it via the `Authorization` header with Bearer scheme\n   * 3. If Google Auth is configured, uses google-auth-library to generate\n   *    appropriate authentication headers (may include Authorization, x-goog-user-project, etc.)\n   *\n   * The authentication priority ensures that explicit API keys take precedence,\n   * followed by service account credentials, and finally Google Auth options.\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 service account authentication fails (e.g., invalid\n   *                     credentials, network error, or token generation failure)\n   * @throws {Error} If Google Auth authentication fails (e.g., missing credentials,\n   *                 invalid configuration, or ADC not available)\n   *\n   * @example\n   * ```typescript\n   * const client = new NodeApiClient({ 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   * - Google Auth tokens are managed by google-auth-library with automatic refresh\n   * - Only one authentication method is used per request (based on priority)\n   * - Google Auth may add multiple headers depending on the authentication type\n   */\n  async fetch(request: Request): Promise<Response> {\n    if (this.apiKey) {\n      request.headers.set(GOOGLE_API_KEY_HEADER, this.apiKey);\n    } else if (this.credentials) {\n      request.headers.set(\n        GCP_API_KEY_HEADER,\n        `Bearer ${getGCPCredentialsAccessToken(this.credentials)}`\n      );\n    } else if (this.googleAuth) {\n      const authHeaders = await this.googleAuth.getRequestHeaders(request.url);\n      authHeaders.forEach((value, key) => {\n        if (value !== null) {\n          request.headers.set(key, value);\n        }\n      });\n    }\n    return fetch(request);\n  }\n}\n\n/**\n * Ensures that Google Auth options include required OAuth2 scopes.\n *\n * This utility function validates and augments GoogleAuthOptions to ensure\n * that all required OAuth2 scopes are present. It handles three scenarios:\n *\n * 1. **No auth options provided**: Creates new options with required scopes\n * 2. **Auth options without scopes**: Adds required scopes to existing options\n * 3. **Auth options with scopes**: Validates that all required scopes are present\n *\n * This is particularly useful when working with Google APIs that require specific\n * scopes for access, ensuring that authentication is properly configured before\n * making API requests.\n *\n * @param authOptions - The existing Google Auth options to validate/augment.\n *                      Can be undefined or an empty object.\n * @param requiredScopes - Array of OAuth2 scope URLs that must be present.\n *                         These are typically Google API scope URLs like\n *                         'https://www.googleapis.com/auth/cloud-platform'\n * @returns The validated/augmented GoogleAuthOptions with all required scopes\n *\n * @throws {Error} If authOptions already has scopes but is missing any of the\n *                 required scopes. This prevents accidental scope reduction that\n *                 could break API access.\n *\n * @example\n * ```typescript\n * // Create new options with required scopes\n * const options = ensureAuthScopes(undefined, [\n *   'https://www.googleapis.com/auth/cloud-platform'\n * ]);\n * // Result: { scopes: ['https://www.googleapis.com/auth/cloud-platform'] }\n *\n * // Add scopes to existing options\n * const options = ensureAuthScopes(\n *   { projectId: 'my-project' },\n *   ['https://www.googleapis.com/auth/cloud-platform']\n * );\n * // Result: { projectId: 'my-project', scopes: [...] }\n *\n * // Validate existing scopes\n * const options = ensureAuthScopes(\n *   { scopes: ['https://www.googleapis.com/auth/cloud-platform'] },\n *   ['https://www.googleapis.com/auth/cloud-platform']\n * );\n * // Result: Original options (validation passed)\n *\n * // Error case - missing required scope\n * try {\n *   ensureAuthScopes(\n *     { scopes: ['https://www.googleapis.com/auth/userinfo.email'] },\n *     ['https://www.googleapis.com/auth/cloud-platform']\n *   );\n * } catch (error) {\n *   // Error: Invalid auth scopes. Scopes must include ...\n * }\n * ```\n *\n * @remarks\n * - Scopes can be provided as a string or array of strings in GoogleAuthOptions\n * - The function normalizes single-string scopes to arrays for validation\n * - Required scopes are not automatically added if existing scopes are present;\n *   instead, an error is thrown to prevent unintended scope changes\n * - This function does not modify the original authOptions object\n *\n * @see https://developers.google.com/identity/protocols/oauth2/scopes\n * @see {@link GoogleAuthOptions} for the full authentication configuration interface\n */\nexport function ensureAuthScopes(\n  authOptions: GoogleAuthOptions,\n  requiredScopes: string[]\n): GoogleAuthOptions {\n  if (!authOptions) {\n    return { scopes: requiredScopes };\n  } else if (!authOptions.scopes) {\n    return { ...authOptions, scopes: requiredScopes };\n  } else {\n    const existingScopes = Array.isArray(authOptions.scopes)\n      ? authOptions.scopes\n      : [authOptions.scopes];\n    const missingScopes = requiredScopes.filter(\n      (scope) => !existingScopes.includes(scope)\n    );\n    if (missingScopes.length > 0) {\n      throw new ConfigurationError(\n        `Invalid auth scopes. Scopes must include ${requiredScopes.join(\", \")}`\n      );\n    }\n  }\n  return authOptions;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkJA,IAAa,gBAAb,cAAmC,UAAU;CAC3C,YAAqB;AACnB,SAAO,OAAO,KAAK,WAAW,YAAY,KAAK,WAAW;CAC3D;CAED,MAAM,eAAgC;AACpC,MAAI,OAAO,KAAK,gBAAgB,YAC9B,QAAO,KAAK,YAAY;WACf,OAAO,KAAK,eAAe,YACpC,QAAO,KAAK,WAAW,cAAc;MAErC,QAAO,MAAM,cAAc;CAE9B;;;;;;;;;CAUD,AAAU;;;;;;;;;;CAWV,AAAU;;;;;;;;;;CAWV,AAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDV,YAAsBA,SAA8B,CAAE,GAAE;EACtD,OAAO;EADa;EAGpB,KAAK,SAAS,OAAO,UAAU,uBAAuB,iBAAiB;EACvE,KAAK,cAAc,KAAK,MAAM;AAC5B,OAAI,OAAO,YACT,QAAO,wBAAwB,OAAO,YAAY;GAEpD,MAAM,iBAAiB,uBAAuB,2BAA2B;AACzE,OAAI,eACF,QAAO,wBAAwB,eAAe;AAEhD,UAAO;EACR,EAAC;EACF,KAAK,aAAa,KAAK,MAAM;AAC3B,OAAI,OAAO,kBACT,QAAO,IAAI,WAAW,OAAO;AAE/B,OAAI,CAAC,KAAK,UAAU,CAAC,KAAK,YACxB,QAAO,IAAI;AAEb,UAAO;EACR,EAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCD,MAAM,MAAMC,SAAqC;AAC/C,MAAI,KAAK,QACP,QAAQ,QAAQ,IAAI,uBAAuB,KAAK,OAAO;WAC9C,KAAK,aACd,QAAQ,QAAQ,IACd,oBACA,CAAC,OAAO,EAAE,6BAA6B,KAAK,YAAY,EAAE,CAC3D;WACQ,KAAK,YAAY;GAC1B,MAAM,cAAc,MAAM,KAAK,WAAW,kBAAkB,QAAQ,IAAI;GACxE,YAAY,QAAQ,CAAC,OAAO,QAAQ;AAClC,QAAI,UAAU,MACZ,QAAQ,QAAQ,IAAI,KAAK,MAAM;GAElC,EAAC;EACH;AACD,SAAO,MAAM,QAAQ;CACtB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsED,SAAgB,iBACdC,aACAC,gBACmB;AACnB,KAAI,CAAC,YACH,QAAO,EAAE,QAAQ,eAAgB;UACxB,CAAC,YAAY,OACtB,QAAO;EAAE,GAAG;EAAa,QAAQ;CAAgB;MAC5C;EACL,MAAM,iBAAiB,MAAM,QAAQ,YAAY,OAAO,GACpD,YAAY,SACZ,CAAC,YAAY,MAAO;EACxB,MAAM,gBAAgB,eAAe,OACnC,CAAC,UAAU,CAAC,eAAe,SAAS,MAAM,CAC3C;AACD,MAAI,cAAc,SAAS,EACzB,OAAM,IAAI,mBACR,CAAC,yCAAyC,EAAE,eAAe,KAAK,KAAK,EAAE;CAG5E;AACD,QAAO;AACR"}

package/dist/const.cjs

@@ -0,0 +1,13 @@
+
+//#region src/const.ts
+const GOOGLE_API_KEY_HEADER = "x-goog-api-key";
+const GCP_API_KEY_HEADER = "Authorization";
+const GENERATIVE_AI_AUTH_SCOPES = ["https://www.googleapis.com/auth/generative-language"];
+const VERTEX_AI_AUTH_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"];
+
+//#endregion
+exports.GCP_API_KEY_HEADER = GCP_API_KEY_HEADER;
+exports.GENERATIVE_AI_AUTH_SCOPES = GENERATIVE_AI_AUTH_SCOPES;
+exports.GOOGLE_API_KEY_HEADER = GOOGLE_API_KEY_HEADER;
+exports.VERTEX_AI_AUTH_SCOPES = VERTEX_AI_AUTH_SCOPES;
+//# sourceMappingURL=const.cjs.map

package/dist/const.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.cjs","names":[],"sources":["../src/const.ts"],"sourcesContent":["export const GOOGLE_API_KEY_HEADER = \"x-goog-api-key\";\n\nexport const GCP_API_KEY_HEADER = \"Authorization\";\n\nexport const GENERATIVE_AI_AUTH_SCOPES = [\n  \"https://www.googleapis.com/auth/generative-language\",\n];\n\nexport const VERTEX_AI_AUTH_SCOPES = [\n  \"https://www.googleapis.com/auth/cloud-platform\",\n];\n"],"mappings":";;AAAA,MAAa,wBAAwB;AAErC,MAAa,qBAAqB;AAElC,MAAa,4BAA4B,CACvC,qDACD;AAED,MAAa,wBAAwB,CACnC,gDACD"}

package/dist/const.js

@@ -0,0 +1,9 @@
+//#region src/const.ts
+const GOOGLE_API_KEY_HEADER = "x-goog-api-key";
+const GCP_API_KEY_HEADER = "Authorization";
+const GENERATIVE_AI_AUTH_SCOPES = ["https://www.googleapis.com/auth/generative-language"];
+const VERTEX_AI_AUTH_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"];
+
+//#endregion
+export { GCP_API_KEY_HEADER, GENERATIVE_AI_AUTH_SCOPES, GOOGLE_API_KEY_HEADER, VERTEX_AI_AUTH_SCOPES };
+//# sourceMappingURL=const.js.map

package/dist/const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.js","names":[],"sources":["../src/const.ts"],"sourcesContent":["export const GOOGLE_API_KEY_HEADER = \"x-goog-api-key\";\n\nexport const GCP_API_KEY_HEADER = \"Authorization\";\n\nexport const GENERATIVE_AI_AUTH_SCOPES = [\n  \"https://www.googleapis.com/auth/generative-language\",\n];\n\nexport const VERTEX_AI_AUTH_SCOPES = [\n  \"https://www.googleapis.com/auth/cloud-platform\",\n];\n"],"mappings":";AAAA,MAAa,wBAAwB;AAErC,MAAa,qBAAqB;AAElC,MAAa,4BAA4B,CACvC,qDACD;AAED,MAAa,wBAAwB,CACnC,gDACD"}