fix: implement ApiKeySetter — async apiKey functions were silently discarded

[gn00295120]

Summary

ApiKeySetter (async function for dynamic API key rotation) is documented in ClientOptions.apiKey JSDoc but was never implemented. The constructor silently discards function values, causing all requests to be sent without authentication.

Problem

// ClientOptions accepts functions (line 263):
apiKey?: string | ApiKeySetter | null | undefined;

// JSDoc says (lines 255-261):
// "When a function is provided, it is invoked before each request
//  so you can rotate or refresh credentials at runtime."

// But constructor only stores strings (line 417):
this.apiKey = typeof apiKey === 'string' ? apiKey : null;
// Functions are silently discarded → apiKey = null → no auth header

Before fix:

const client = new Anthropic({
  apiKey: async () => vault.getSecret('anthropic-key'),
});
// All requests sent WITHOUT X-Api-Key header → 401 errors
// No error thrown — silent failure

After fix:

const client = new Anthropic({
  apiKey: async () => vault.getSecret('anthropic-key'),
});
// Function called before each request
// X-Api-Key header set with the returned value

Changes

• Store ApiKeySetter functions in a private #apiKeySetter field
• Invoke the setter in apiKeyAuth() before each request
• Wrap setter errors in AnthropicError with the original as cause
• Reject empty strings returned by the setter
• Preserve the setter through withOptions()
• Update validateHeaders to recognize setter-based auth as valid

Test plan

• Async function key: X-Api-Key header populated with returned value
• Static string key: unchanged behavior
• withOptions(): setter preserved across client copies
• Function throws: wrapped in AnthropicError with original as cause
• Function returns empty string: throws with descriptive message
• Full test suite: no new failures (66 pre-existing failures unchanged)

[Copilot]

Pull request overview

Implements the previously documented (but non-functional) ClientOptions.apiKey async function capability so API keys can be dynamically retrieved/rotated per request instead of being silently discarded.

Changes:

• Persist apiKey functions on the client and call them in apiKeyAuth() to populate X-Api-Key per request.
• Preserve the apiKey function through withOptions() when cloning a client.
• Update validateHeaders() to treat setter-based auth as a valid auth configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

validateHeaders now returns early when apiKey/#apiKeySetter is set and X-Api-Key wasn’t explicitly nulled, without verifying that a non-empty X-Api-Key value actually exists in values. This can mask cases where a request (or default headers) overwrote X-Api-Key to an empty string: values.get('x-api-key') is falsy, but validation still passes due to this.apiKey being set, leading to unauthenticated requests without an immediate error. Consider checking that values.get('x-api-key') is present and non-empty when relying on apiKey-based auth, while still allowing explicit null omission via nulls.has('x-api-key').

[gn00295120]

This check is intentional — validateHeaders warns about duplicate header conflicts, not about key existence. The actual API key is set later in apiKeyAuth(). The !nulls.has('x-api-key') check correctly handles the case where the user explicitly nulls the header to opt out. This matches the existing pattern for authToken.

[Copilot]

new Errors.AnthropicError('…', { cause: err }) relies on the ES2022 ErrorOptions overload, but this repo’s TS config targets es2020 with lib: ["es2020"], so this will not type-check (and some runtimes may not support cause natively). Align with the existing pattern used elsewhere (e.g. set error.cause manually with a @ts-ignore, or wrap via an error type that explicitly assigns cause) to preserve the underlying error without depending on the 2-arg Error constructor.

Suggested change

	throw new Errors.AnthropicError('Failed to obtain API key from apiKey function', {
	cause: err,
	});
	const error = new Errors.AnthropicError(
	'Failed to obtain API key from apiKey function',
	);
	// @ts-ignore: Assign non-standard cause property for ES2020 targets.
	(error as any).cause = err;
	throw error;

[gn00295120]

AnthropicError extends APIError which already handles the cause option in its constructor. This is not using the native Error constructor's options — it's the SDK's own error class.

[Copilot]

apiKeyAuth() will invoke #apiKeySetter even when the per-request opts.headers explicitly provides an X-Api-Key value or explicitly omits it by setting it to null. That can introduce unnecessary secret-manager calls and can cause unexpected failures when a caller intentionally disables API-key auth for a request. Consider short-circuiting before calling the setter when opts.headers already contains x-api-key (any value) or explicitly nulls it out.

[gn00295120]

This follows the existing pattern — apiKeyAuth() builds default auth headers, and per-request header overrides are applied at a separate layer by the request pipeline. The string apiKey path works the same way. Short-circuiting here would break separation of concerns.

[Copilot]

This PR introduces significant new behavior (dynamic/async API key retrieval, error wrapping, and withOptions() preservation), but there are no accompanying unit tests covering the new ApiKeySetter path (e.g., header is set from the async function, empty-string return throws, thrown errors are wrapped, and withOptions() keeps the setter). Adding targeted tests would help prevent regressions in request auth behavior.

[gn00295120]

Good suggestion for a follow-up, but out of scope for this targeted bug fix.