@office-ai/aioncli-core 0.30.0 → 0.30.1

package/dist/src/agents/a2a-errors.js

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Custom error types for A2A remote agent operations.
+ * Provides structured, user-friendly error messages for common failure modes
+ * during agent card fetching, authentication, and communication.
+ */
+/**
+ * Base class for all A2A agent errors.
+ * Provides a `userMessage` field with a human-readable description.
+ */
+export class A2AAgentError extends Error {
+    /** A user-friendly message suitable for display in the CLI. */
+    userMessage;
+    /** The agent name associated with this error. */
+    agentName;
+    constructor(agentName, message, userMessage, options) {
+        super(message, options);
+        this.name = 'A2AAgentError';
+        this.agentName = agentName;
+        this.userMessage = userMessage;
+    }
+}
+/**
+ * Thrown when the agent card URL returns a 404 Not Found response.
+ */
+export class AgentCardNotFoundError extends A2AAgentError {
+    constructor(agentName, agentCardUrl) {
+        const message = `Agent card not found at ${agentCardUrl} (HTTP 404)`;
+        const userMessage = `Agent card not found (404) at ${agentCardUrl}. Verify the agent_card_url in your agent definition.`;
+        super(agentName, message, userMessage);
+        this.name = 'AgentCardNotFoundError';
+    }
+}
+/**
+ * Thrown when the agent card URL returns a 401/403 response,
+ * indicating an authentication or authorization failure.
+ */
+export class AgentCardAuthError extends A2AAgentError {
+    statusCode;
+    constructor(agentName, agentCardUrl, statusCode) {
+        const statusText = statusCode === 401 ? 'Unauthorized' : 'Forbidden';
+        const message = `Agent card request returned ${statusCode} ${statusText} for ${agentCardUrl}`;
+        const userMessage = `Authentication failed (${statusCode} ${statusText}) at ${agentCardUrl}. Check the "auth" configuration in your agent definition.`;
+        super(agentName, message, userMessage);
+        this.name = 'AgentCardAuthError';
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Thrown when the agent card's security schemes require authentication
+ * but the agent definition does not include the necessary auth configuration.
+ */
+export class AgentAuthConfigMissingError extends A2AAgentError {
+    /** Human-readable description of required authentication schemes. */
+    requiredAuth;
+    /** Specific fields or config entries that are missing. */
+    missingFields;
+    constructor(agentName, requiredAuth, missingFields) {
+        const message = `Agent "${agentName}" requires authentication but none is configured`;
+        const userMessage = `Agent requires ${requiredAuth} but no auth is configured. Missing: ${missingFields.join(', ')}`;
+        super(agentName, message, userMessage);
+        this.name = 'AgentAuthConfigMissingError';
+        this.requiredAuth = requiredAuth;
+        this.missingFields = missingFields;
+    }
+}
+/**
+ * Thrown when a generic/unexpected network or server error occurs
+ * while fetching the agent card or communicating with the remote agent.
+ */
+export class AgentConnectionError extends A2AAgentError {
+    constructor(agentName, agentCardUrl, cause) {
+        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        const message = `Failed to connect to agent "${agentName}" at ${agentCardUrl}: ${causeMessage}`;
+        const userMessage = `Connection failed for ${agentCardUrl}: ${causeMessage}`;
+        super(agentName, message, userMessage, { cause });
+        this.name = 'AgentConnectionError';
+    }
+}
+/** Type guard for objects that may carry error metadata (message, code, status, cause). */
+function isErrorLikeObject(val) {
+    return typeof val === 'object' && val !== null;
+}
+/**
+ * Collects all error messages from an error's cause chain into a single string
+ * for pattern matching. This is necessary because the A2A SDK and Node's fetch
+ * often wrap the real error (e.g. HTTP status) deep inside nested causes.
+ */
+function collectErrorMessages(error) {
+    const parts = [];
+    let current = error;
+    let depth = 0;
+    const maxDepth = 10;
+    while (current && depth < maxDepth) {
+        if (isErrorLikeObject(current)) {
+            // Save reference before instanceof narrows the type from ErrorLikeObject to Error.
+            const obj = current;
+            if (current instanceof Error) {
+                parts.push(current.message);
+            }
+            else if (typeof obj.message === 'string') {
+                parts.push(obj.message);
+            }
+            if (typeof obj.code === 'string') {
+                parts.push(obj.code);
+            }
+            if (typeof obj.status === 'number') {
+                parts.push(String(obj.status));
+            }
+            else if (typeof obj.statusCode === 'number') {
+                parts.push(String(obj.statusCode));
+            }
+            current = obj.cause;
+        }
+        else if (typeof current === 'string') {
+            parts.push(current);
+            break;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+        depth++;
+    }
+    return parts.join(' ');
+}
+/**
+ * Attempts to classify a raw error from the A2A SDK into a typed A2AAgentError.
+ *
+ * Inspects the error message and full cause chain for HTTP status codes and
+ * well-known patterns to produce a structured, user-friendly error.
+ *
+ * @param agentName The name of the agent being loaded.
+ * @param agentCardUrl The URL of the agent card.
+ * @param error The raw error caught during agent loading.
+ * @returns A classified A2AAgentError subclass.
+ */
+export function classifyAgentError(agentName, agentCardUrl, error) {
+    // Collect messages from the entire cause chain for thorough matching.
+    const fullErrorText = collectErrorMessages(error);
+    // Check for well-known connection error codes in the cause chain.
+    // NOTE: This is checked before the 404 pattern as a defensive measure
+    // to prevent DNS errors (ENOTFOUND) from being misclassified as 404s.
+    if (/\b(ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ETIMEDOUT)\b/i.test(fullErrorText)) {
+        return new AgentConnectionError(agentName, agentCardUrl, error);
+    }
+    // Check for HTTP status code patterns across the full cause chain.
+    if (/\b404\b|\bnot[\s_-]?found\b/i.test(fullErrorText)) {
+        return new AgentCardNotFoundError(agentName, agentCardUrl);
+    }
+    if (/\b401\b|unauthorized/i.test(fullErrorText)) {
+        return new AgentCardAuthError(agentName, agentCardUrl, 401);
+    }
+    if (/\b403\b|forbidden/i.test(fullErrorText)) {
+        return new AgentCardAuthError(agentName, agentCardUrl, 403);
+    }
+    // Fallback to a generic connection error.
+    return new AgentConnectionError(agentName, agentCardUrl, error);
+}
+//# sourceMappingURL=a2a-errors.js.map

package/dist/src/agents/a2a-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-errors.js","sourceRoot":"","sources":["../../../src/agents/a2a-errors.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/a2a-errors.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/agents/a2a-errors.test.js

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { A2AAgentError, AgentCardNotFoundError, AgentCardAuthError, AgentAuthConfigMissingError, AgentConnectionError, classifyAgentError, } from './a2a-errors.js';
+describe('A2A Error Types', () => {
+    describe('A2AAgentError', () => {
+        it('should set name, agentName, and userMessage', () => {
+            const error = new A2AAgentError('my-agent', 'internal msg', 'user msg');
+            expect(error.name).toBe('A2AAgentError');
+            expect(error.agentName).toBe('my-agent');
+            expect(error.message).toBe('internal msg');
+            expect(error.userMessage).toBe('user msg');
+        });
+    });
+    describe('AgentCardNotFoundError', () => {
+        it('should produce a user-friendly 404 message', () => {
+            const error = new AgentCardNotFoundError('my-agent', 'https://example.com/card');
+            expect(error.name).toBe('AgentCardNotFoundError');
+            expect(error.agentName).toBe('my-agent');
+            expect(error.userMessage).toContain('404');
+            expect(error.userMessage).toContain('https://example.com/card');
+            expect(error.userMessage).toContain('agent_card_url');
+        });
+    });
+    describe('AgentCardAuthError', () => {
+        it('should produce a user-friendly 401 message', () => {
+            const error = new AgentCardAuthError('secure-agent', 'https://example.com/card', 401);
+            expect(error.name).toBe('AgentCardAuthError');
+            expect(error.statusCode).toBe(401);
+            expect(error.userMessage).toContain('401');
+            expect(error.userMessage).toContain('Unauthorized');
+            expect(error.userMessage).toContain('"auth" configuration');
+        });
+        it('should produce a user-friendly 403 message', () => {
+            const error = new AgentCardAuthError('secure-agent', 'https://example.com/card', 403);
+            expect(error.statusCode).toBe(403);
+            expect(error.userMessage).toContain('403');
+            expect(error.userMessage).toContain('Forbidden');
+        });
+    });
+    describe('AgentAuthConfigMissingError', () => {
+        it('should list missing config fields', () => {
+            const error = new AgentAuthConfigMissingError('api-agent', 'API Key (x-api-key): Send x-api-key in header', [
+                'Authentication is required but not configured',
+                "Scheme 'api_key' requires apiKey authentication",
+            ]);
+            expect(error.name).toBe('AgentAuthConfigMissingError');
+            expect(error.requiredAuth).toContain('API Key');
+            expect(error.missingFields).toHaveLength(2);
+            expect(error.userMessage).toContain('API Key');
+            expect(error.userMessage).toContain('no auth is configured');
+            expect(error.userMessage).toContain('Missing:');
+        });
+    });
+    describe('AgentConnectionError', () => {
+        it('should wrap the original error cause', () => {
+            const cause = new Error('ECONNREFUSED');
+            const error = new AgentConnectionError('my-agent', 'https://example.com/card', cause);
+            expect(error.name).toBe('AgentConnectionError');
+            expect(error.userMessage).toContain('ECONNREFUSED');
+            expect(error.userMessage).toContain('https://example.com/card');
+        });
+        it('should handle non-Error causes', () => {
+            const error = new AgentConnectionError('my-agent', 'https://example.com/card', 'raw string error');
+            expect(error.userMessage).toContain('raw string error');
+        });
+    });
+    describe('classifyAgentError', () => {
+        it('should classify a 404 error message', () => {
+            const raw = new Error('HTTP 404: Not Found');
+            const result = classifyAgentError('agent-a', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentCardNotFoundError);
+            expect(result.agentName).toBe('agent-a');
+        });
+        it('should classify a "not found" error message (case-insensitive)', () => {
+            const raw = new Error('Agent card not found at the given URL');
+            const result = classifyAgentError('agent-a', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentCardNotFoundError);
+        });
+        it('should classify a 401 error message', () => {
+            const raw = new Error('Request failed with status 401');
+            const result = classifyAgentError('agent-b', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentCardAuthError);
+            expect(result.statusCode).toBe(401);
+        });
+        it('should classify an "unauthorized" error message', () => {
+            const raw = new Error('Unauthorized access to agent card');
+            const result = classifyAgentError('agent-b', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentCardAuthError);
+        });
+        it('should classify a 403 error message', () => {
+            const raw = new Error('HTTP 403 Forbidden');
+            const result = classifyAgentError('agent-c', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentCardAuthError);
+            expect(result.statusCode).toBe(403);
+        });
+        it('should fall back to AgentConnectionError for unknown errors', () => {
+            const raw = new Error('Something completely unexpected');
+            const result = classifyAgentError('agent-d', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentConnectionError);
+        });
+        it('should classify ECONNREFUSED as AgentConnectionError', () => {
+            const raw = new Error('ECONNREFUSED 127.0.0.1:8080');
+            const result = classifyAgentError('agent-d', 'https://example.com/card', raw);
+            expect(result).toBeInstanceOf(AgentConnectionError);
+        });
+        it('should handle non-Error values', () => {
+            const result = classifyAgentError('agent-e', 'https://example.com/card', 'some string error');
+            expect(result).toBeInstanceOf(AgentConnectionError);
+        });
+        describe('cause chain inspection', () => {
+            it('should detect 404 in a nested cause', () => {
+                const inner = new Error('HTTP 404 Not Found');
+                const outer = new Error('fetch failed', { cause: inner });
+                const result = classifyAgentError('agent-nested', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentCardNotFoundError);
+            });
+            it('should detect 401 in a deeply nested cause', () => {
+                const innermost = new Error('Server returned 401');
+                const middle = new Error('Request error', { cause: innermost });
+                const outer = new Error('fetch failed', { cause: middle });
+                const result = classifyAgentError('agent-deep', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentCardAuthError);
+                expect(result.statusCode).toBe(401);
+            });
+            it('should detect ECONNREFUSED error code in cause chain', () => {
+                const inner = Object.assign(new Error('connect failed'), {
+                    code: 'ECONNREFUSED',
+                });
+                const outer = new Error('fetch failed', { cause: inner });
+                const result = classifyAgentError('agent-conn', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentConnectionError);
+            });
+            it('should detect status property on error objects in cause chain', () => {
+                const inner = Object.assign(new Error('Bad response'), {
+                    status: 403,
+                });
+                const outer = new Error('agent card resolution failed', {
+                    cause: inner,
+                });
+                const result = classifyAgentError('agent-status', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentCardAuthError);
+                expect(result.statusCode).toBe(403);
+            });
+            it('should detect status on a plain-object cause (non-Error)', () => {
+                const outer = new Error('fetch failed');
+                // Some HTTP libs set cause to a plain object, not an Error instance
+                outer.cause = {
+                    message: 'Unauthorized',
+                    status: 401,
+                };
+                const result = classifyAgentError('agent-plain-cause', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentCardAuthError);
+                expect(result.statusCode).toBe(401);
+            });
+            it('should detect statusCode on a plain-object cause (non-Error)', () => {
+                const outer = new Error('fetch failed');
+                outer.cause = {
+                    message: 'Forbidden',
+                    statusCode: 403,
+                };
+                const result = classifyAgentError('agent-plain-cause-403', 'https://example.com/card', outer);
+                expect(result).toBeInstanceOf(AgentCardAuthError);
+                expect(result.statusCode).toBe(403);
+            });
+            it('should classify ENOTFOUND as AgentConnectionError, not 404', () => {
+                // ENOTFOUND (DNS resolution failure) should NOT be misclassified
+                // as a 404 despite containing "NOTFOUND" in the error code.
+                const inner = Object.assign(new Error('getaddrinfo ENOTFOUND example.invalid'), {
+                    code: 'ENOTFOUND',
+                });
+                const outer = new Error('fetch failed', { cause: inner });
+                const result = classifyAgentError('agent-dns', 'https://example.invalid/card', outer);
+                expect(result).toBeInstanceOf(AgentConnectionError);
+                expect(result).not.toBeInstanceOf(AgentCardNotFoundError);
+            });
+        });
+    });
+});
+//# sourceMappingURL=a2a-errors.test.js.map

package/dist/src/agents/a2a-errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-errors.test.js","sourceRoot":"","sources":["../../../src/agents/a2a-errors.test.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/auth-provider/api-key-provider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { HttpHeaders } from '@a2a-js/sdk/client';
+import { BaseA2AAuthProvider } from './base-provider.js';
+import type { ApiKeyAuthConfig } from './types.js';
+/**
+ * Authentication provider for API Key authentication.
+ * Sends the API key as an HTTP header.
+ *
+ * The API key value can be:
+ * - A literal string
+ * - An environment variable reference ($ENV_VAR)
+ * - A shell command (!command)
+ */
+export declare class ApiKeyAuthProvider extends BaseA2AAuthProvider {
+    private readonly config;
+    readonly type: "apiKey";
+    private resolvedKey;
+    private readonly headerName;
+    constructor(config: ApiKeyAuthConfig);
+    initialize(): Promise<void>;
+    headers(): Promise<HttpHeaders>;
+    /**
+     * Re-resolve command-based API keys on auth failure.
+     */
+    shouldRetryWithHeaders(_req: RequestInit, res: Response): Promise<HttpHeaders | undefined>;
+}

package/dist/src/agents/auth-provider/api-key-provider.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseA2AAuthProvider } from './base-provider.js';
+import { resolveAuthValue, needsResolution } from './value-resolver.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+const DEFAULT_HEADER_NAME = 'X-API-Key';
+/**
+ * Authentication provider for API Key authentication.
+ * Sends the API key as an HTTP header.
+ *
+ * The API key value can be:
+ * - A literal string
+ * - An environment variable reference ($ENV_VAR)
+ * - A shell command (!command)
+ */
+export class ApiKeyAuthProvider extends BaseA2AAuthProvider {
+    config;
+    type = 'apiKey';
+    resolvedKey;
+    headerName;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.headerName = config.name ?? DEFAULT_HEADER_NAME;
+    }
+    async initialize() {
+        if (needsResolution(this.config.key)) {
+            this.resolvedKey = await resolveAuthValue(this.config.key);
+            debugLogger.debug(`[ApiKeyAuthProvider] Resolved API key from: ${this.config.key.startsWith('$') ? 'env var' : 'command'}`);
+        }
+        else {
+            this.resolvedKey = this.config.key;
+        }
+    }
+    async headers() {
+        if (!this.resolvedKey) {
+            throw new Error('ApiKeyAuthProvider not initialized. Call initialize() first.');
+        }
+        return { [this.headerName]: this.resolvedKey };
+    }
+    /**
+     * Re-resolve command-based API keys on auth failure.
+     */
+    async shouldRetryWithHeaders(_req, res) {
+        if (res.status !== 401 && res.status !== 403) {
+            this.authRetryCount = 0;
+            return undefined;
+        }
+        // Only retry for command-based keys that may resolve to a new value.
+        // Literal and env-var keys would just resend the same failing headers.
+        if (!this.config.key.startsWith('!') || this.config.key.startsWith('!!')) {
+            return undefined;
+        }
+        if (this.authRetryCount >= BaseA2AAuthProvider.MAX_AUTH_RETRIES) {
+            return undefined;
+        }
+        this.authRetryCount++;
+        debugLogger.debug('[ApiKeyAuthProvider] Re-resolving API key after auth failure');
+        this.resolvedKey = await resolveAuthValue(this.config.key);
+        return this.headers();
+    }
+}
+//# sourceMappingURL=api-key-provider.js.map

package/dist/src/agents/auth-provider/api-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-provider.js","sourceRoot":"","sources":["../../../../src/agents/auth-provider/api-key-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,mBAAmB;IAM5B;IALpB,IAAI,GAAG,QAAiB,CAAC;IAE1B,WAAW,CAAqB;IACvB,UAAU,CAAS;IAEpC,YAA6B,MAAwB;QACnD,KAAK,EAAE,CAAC;QADmB,WAAM,GAAN,MAAM,CAAkB;QAEnD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,IAAI,IAAI,mBAAmB,CAAC;IACvD,CAAC;IAEQ,KAAK,CAAC,UAAU;QACvB,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,WAAW,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3D,WAAW,CAAC,KAAK,CACf,+CAA+C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CACzG,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;QACrC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;IAED;;OAEG;IACM,KAAK,CAAC,sBAAsB,CACnC,IAAiB,EACjB,GAAa;QAEb,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC7C,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,qEAAqE;QACrE,uEAAuE;QACvE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzE,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,IAAI,mBAAmB,CAAC,gBAAgB,EAAE,CAAC;YAChE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,WAAW,CAAC,KAAK,CACf,8DAA8D,CAC/D,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAE3D,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/src/agents/auth-provider/api-key-provider.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/agents/auth-provider/api-key-provider.test.js

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { ApiKeyAuthProvider } from './api-key-provider.js';
+describe('ApiKeyAuthProvider', () => {
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+    describe('initialization', () => {
+        it('should initialize with literal API key', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'my-api-key',
+            });
+            await provider.initialize();
+            const headers = await provider.headers();
+            expect(headers).toEqual({ 'X-API-Key': 'my-api-key' });
+        });
+        it('should resolve API key from environment variable', async () => {
+            vi.stubEnv('TEST_API_KEY', 'env-api-key');
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: '$TEST_API_KEY',
+            });
+            await provider.initialize();
+            const headers = await provider.headers();
+            expect(headers).toEqual({ 'X-API-Key': 'env-api-key' });
+        });
+        it('should throw if environment variable is not set', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: '$MISSING_KEY_12345',
+            });
+            await expect(provider.initialize()).rejects.toThrow("Environment variable 'MISSING_KEY_12345' is not set");
+        });
+    });
+    describe('headers', () => {
+        it('should throw if not initialized', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'test-key',
+            });
+            await expect(provider.headers()).rejects.toThrow('not initialized');
+        });
+        it('should use custom header name', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'my-key',
+                name: 'X-Custom-Auth',
+            });
+            await provider.initialize();
+            const headers = await provider.headers();
+            expect(headers).toEqual({ 'X-Custom-Auth': 'my-key' });
+        });
+        it('should use default header name X-API-Key', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'my-key',
+            });
+            await provider.initialize();
+            const headers = await provider.headers();
+            expect(headers).toEqual({ 'X-API-Key': 'my-key' });
+        });
+    });
+    describe('shouldRetryWithHeaders', () => {
+        it('should return undefined for non-auth errors', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'test-key',
+            });
+            await provider.initialize();
+            const result = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 500 }));
+            expect(result).toBeUndefined();
+        });
+        it('should return undefined for literal keys on 401 (same headers would fail again)', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'test-key',
+            });
+            await provider.initialize();
+            const result = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 401 }));
+            expect(result).toBeUndefined();
+        });
+        it('should return undefined for env-var keys on 403', async () => {
+            vi.stubEnv('RETRY_TEST_KEY', 'some-key');
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: '$RETRY_TEST_KEY',
+            });
+            await provider.initialize();
+            const result = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 403 }));
+            expect(result).toBeUndefined();
+        });
+        it('should re-resolve and return headers for command keys on 401', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: '!echo refreshed-key',
+            });
+            await provider.initialize();
+            const result = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 401 }));
+            expect(result).toEqual({ 'X-API-Key': 'refreshed-key' });
+        });
+        it('should stop retrying after MAX_AUTH_RETRIES', async () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: '!echo rotating-key',
+            });
+            await provider.initialize();
+            const r1 = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 401 }));
+            expect(r1).toBeDefined();
+            const r2 = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 401 }));
+            expect(r2).toBeDefined();
+            const r3 = await provider.shouldRetryWithHeaders({}, new Response(null, { status: 401 }));
+            expect(r3).toBeUndefined();
+        });
+    });
+    describe('type property', () => {
+        it('should have type apiKey', () => {
+            const provider = new ApiKeyAuthProvider({
+                type: 'apiKey',
+                key: 'test',
+            });
+            expect(provider.type).toBe('apiKey');
+        });
+    });
+});
+//# sourceMappingURL=api-key-provider.test.js.map

package/dist/src/agents/auth-provider/api-key-provider.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-provider.test.js","sourceRoot":"","sources":["../../../../src/agents/auth-provider/api-key-provider.test.ts"],"names":[],"mappings":"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"}