@tanstack/ai-bedrock 0.0.1

package/src/converse/structured-output.ts

@@ -0,0 +1,24 @@
+import type { ToolConfiguration } from '@aws-sdk/client-bedrock-runtime'
+import type { DocumentType } from '@smithy/types'
+
+export const STRUCTURED_TOOL_NAME = 'structured_output'
+
+/**
+ * Converse has no native json_schema response_format. Structured output is
+ * achieved by forcing a single tool whose input schema is the requested output
+ * schema; the model's tool-use `input` is the structured result.
+ */
+export function buildStructuredToolConfig(schema: unknown): ToolConfiguration {
+  return {
+    tools: [
+      {
+        toolSpec: {
+          name: STRUCTURED_TOOL_NAME,
+          description: 'Return the final answer as structured JSON.',
+          inputSchema: { json: schema as DocumentType },
+        },
+      },
+    ],
+    toolChoice: { tool: { name: STRUCTURED_TOOL_NAME } },
+  }
+}

package/src/converse/tool-converter.ts

@@ -0,0 +1,49 @@
+import type {
+  ToolChoice,
+  ToolConfiguration,
+} from '@aws-sdk/client-bedrock-runtime'
+import type { DocumentType } from '@smithy/types'
+
+export interface ConverseToolInput {
+  name: string
+  description?: string
+  inputSchema: unknown
+}
+
+export type ToolChoiceInput =
+  | 'auto'
+  | 'required'
+  | 'none'
+  | { type: 'tool'; name: string }
+
+export function toToolConfig(
+  tools: Array<ConverseToolInput>,
+  choice: ToolChoiceInput | undefined,
+): ToolConfiguration | undefined {
+  if (!tools.length) return undefined
+  // `none` means "don't call tools" — omit the tool config entirely, since
+  // Bedrock treats a present tool config with no `toolChoice` as auto.
+  if (choice === 'none') return undefined
+  const toolChoice = mapChoice(choice)
+  return {
+    tools: tools.map((t) => ({
+      toolSpec: {
+        name: t.name,
+        ...(t.description ? { description: t.description } : {}),
+        inputSchema: { json: t.inputSchema as DocumentType },
+      },
+    })),
+    ...(toolChoice ? { toolChoice } : {}),
+  }
+}
+
+function mapChoice(
+  choice: ToolChoiceInput | undefined,
+): ToolChoice | undefined {
+  if (!choice || choice === 'auto') return { auto: {} }
+  if (choice === 'required') return { any: {} }
+  // `none` is handled earlier in toToolConfig (omits the tool config); this
+  // branch keeps the string union narrowed so `choice.name` type-checks.
+  if (choice === 'none') return undefined
+  return { tool: { name: choice.name } }
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+/**
+ * @module @tanstack/ai-bedrock
+ *
+ * Amazon Bedrock adapter for TanStack AI via Bedrock's OpenAI-compatible APIs
+ * and the native Converse API.  The public `bedrockText` / `createBedrockText`
+ * factory branches between the Converse adapter (DEFAULT), the Chat Completions
+ * adapter (`api: 'chat'`), and the Responses adapter (`api: 'responses'`).
+ */
+import { BedrockTextAdapter } from './adapters/text'
+import { BedrockResponsesTextAdapter } from './adapters/responses-text'
+import { BedrockConverseTextAdapter } from './adapters/converse-text'
+import { BEDROCK_CHAT_MODELS, BEDROCK_RESPONSES_MODELS } from './model-meta'
+import type { BedrockTextConfig } from './adapters/text'
+import type { BedrockResponsesConfig } from './adapters/responses-text'
+import type { BedrockConverseConfig } from './adapters/converse-text'
+import type { BedrockClientConfig } from './utils'
+import type {
+  BedrockChatModels,
+  BedrockConverseModels,
+  BedrockResponsesModels,
+} from './model-meta'
+
+/** Config for the branching factory's converse mode (default, or api: 'converse'). */
+export type BedrockConverseApiConfig = BedrockConverseConfig & {
+  api?: 'converse'
+}
+/** Config for the branching factory's chat mode (api: 'chat' required). */
+export type BedrockChatApiConfig = BedrockTextConfig & {
+  api: 'chat'
+}
+/** Config for the branching factory's responses mode (api: 'responses' required). */
+export type BedrockResponsesApiConfig = BedrockResponsesConfig & {
+  api: 'responses'
+}
+
+type AnyBedrockAdapter =
+  | BedrockConverseTextAdapter<BedrockConverseModels>
+  | BedrockTextAdapter<BedrockChatModels>
+  | BedrockResponsesTextAdapter<BedrockResponsesModels>
+
+/** Cast-free runtime guard: is this model in the Responses-capable subset? */
+function isResponsesModel(model: string): model is BedrockResponsesModels {
+  return BEDROCK_RESPONSES_MODELS.some((m) => m === model)
+}
+
+/** Cast-free runtime guard: is this model in the Chat-capable subset? */
+function isChatModel(model: string): model is BedrockChatModels {
+  return BEDROCK_CHAT_MODELS.some((m) => m === model)
+}
+
+/** Strip the `api` discriminator from a config without an unused-var lint error. */
+function stripApi<T extends { api?: unknown }>(config: T): Omit<T, 'api'> {
+  const { api, ...rest } = config
+  void api
+  return rest
+}
+
+/**
+ * Shared branching used by both public factories. Constructs the adapter
+ * classes directly so their constructors run the full auth cascade lazily
+ * (config.apiKey → BEDROCK_API_KEY → AWS_BEARER_TOKEN_BEDROCK → SigV4). No
+ * eager env-key fetch here, so `auth: 'sigv4'` never throws for a missing key.
+ *
+ * Default path → Converse adapter; opt-in via `api: 'chat'` or `api: 'responses'`.
+ */
+function build(
+  model: BedrockConverseModels,
+  config?: BedrockClientConfig & { api?: 'converse' | 'chat' | 'responses' },
+): AnyBedrockAdapter {
+  if (config?.api === 'responses') {
+    const rest = stripApi(config)
+    if (!isResponsesModel(model)) {
+      throw new Error(
+        `Model "${model}" is not available on the Bedrock Responses API. ` +
+          `Responses-capable models: ${BEDROCK_RESPONSES_MODELS.join(', ')}.`,
+      )
+    }
+    return new BedrockResponsesTextAdapter(rest, model)
+  }
+  if (config?.api === 'chat') {
+    if (!isChatModel(model)) {
+      throw new Error(
+        `Model "${model}" is not available on the Bedrock Chat Completions API. ` +
+          `Chat-capable models: ${BEDROCK_CHAT_MODELS.join(', ')}.`,
+      )
+    }
+    return new BedrockTextAdapter(stripApi(config), model)
+  }
+  // Default + explicit 'converse'
+  return new BedrockConverseTextAdapter(config ? stripApi(config) : {}, model)
+}
+
+// --- createBedrockText: explicit key, overloaded on `api` ---
+export function createBedrockText<TModel extends BedrockConverseModels>(
+  model: TModel,
+  apiKey: string,
+  config?: BedrockConverseApiConfig,
+): BedrockConverseTextAdapter<TModel>
+export function createBedrockText<TModel extends BedrockChatModels>(
+  model: TModel,
+  apiKey: string,
+  config: BedrockChatApiConfig,
+): BedrockTextAdapter<TModel>
+export function createBedrockText<TModel extends BedrockResponsesModels>(
+  model: TModel,
+  apiKey: string,
+  config: BedrockResponsesApiConfig,
+): BedrockResponsesTextAdapter<TModel>
+export function createBedrockText(
+  model: BedrockConverseModels,
+  apiKey: string,
+  config?:
+    | BedrockConverseApiConfig
+    | BedrockChatApiConfig
+    | BedrockResponsesApiConfig,
+): AnyBedrockAdapter {
+  // Explicit apiKey is authoritative — spread config first so it can't override.
+  return build(model, { ...config, apiKey })
+}
+
+// --- bedrockText: env-key counterpart, same overloads ---
+export function bedrockText<TModel extends BedrockConverseModels>(
+  model: TModel,
+  config?: BedrockConverseApiConfig,
+): BedrockConverseTextAdapter<TModel>
+export function bedrockText<TModel extends BedrockChatModels>(
+  model: TModel,
+  config: BedrockChatApiConfig,
+): BedrockTextAdapter<TModel>
+export function bedrockText<TModel extends BedrockResponsesModels>(
+  model: TModel,
+  config: BedrockResponsesApiConfig,
+): BedrockResponsesTextAdapter<TModel>
+export function bedrockText(
+  model: BedrockConverseModels,
+  config?:
+    | BedrockConverseApiConfig
+    | BedrockChatApiConfig
+    | BedrockResponsesApiConfig,
+): AnyBedrockAdapter {
+  // No eager env-key fetch: the adapter constructor resolves auth lazily so
+  // SigV4 (and the env-key fallback) work without a forced API key here.
+  return build(model, config)
+}
+
+// --- Re-exports ---
+export {
+  BedrockTextAdapter,
+  createBedrockChat,
+  type BedrockTextConfig,
+  type BedrockTextProviderOptions,
+} from './adapters/text'
+export {
+  BedrockResponsesTextAdapter,
+  createBedrockResponsesText,
+  type BedrockResponsesConfig,
+  type BedrockResponsesProviderOptions,
+} from './adapters/responses-text'
+export {
+  BedrockConverseTextAdapter,
+  createBedrockConverse,
+  type BedrockConverseConfig,
+} from './adapters/converse-text'
+export type { BedrockConverseProviderOptions } from './converse/provider-options'
+export {
+  resolveBedrockAuth,
+  withBedrockDefaults,
+  type BedrockClientConfig,
+  type BedrockEndpoint,
+  type ResolvedBedrockAuth,
+} from './utils'
+export {
+  BEDROCK_CHAT_MODELS,
+  BEDROCK_RESPONSES_MODELS,
+  BEDROCK_CONVERSE_MODELS,
+  type BedrockChatModels,
+  type BedrockResponsesModels,
+  type BedrockConverseModels,
+  type BedrockChatModelProviderOptionsByName,
+  type BedrockChatModelToolCapabilitiesByName,
+  type BedrockModelInputModalitiesByName,
+} from './model-meta'
+export type {
+  BedrockMessageMetadataByModality,
+  BedrockTextMetadata,
+  BedrockImageMetadata,
+  BedrockAudioMetadata,
+  BedrockVideoMetadata,
+  BedrockDocumentMetadata,
+} from './message-types'

package/src/message-types.ts

@@ -0,0 +1,24 @@
+/**
+ * Bedrock content-part metadata by modality, used for type inference when
+ * constructing multimodal messages. Bedrock's OpenAI-compatible Chat
+ * Completions accepts the standard OpenAI image-detail hint; other modalities
+ * carry no extra metadata today.
+ */
+export interface BedrockTextMetadata {}
+
+export interface BedrockImageMetadata {
+  /** Image processing detail: 'auto' (default), 'low', or 'high'. */
+  detail?: 'auto' | 'low' | 'high'
+}
+
+export interface BedrockAudioMetadata {}
+export interface BedrockVideoMetadata {}
+export interface BedrockDocumentMetadata {}
+
+export interface BedrockMessageMetadataByModality {
+  text: BedrockTextMetadata
+  image: BedrockImageMetadata
+  audio: BedrockAudioMetadata
+  video: BedrockVideoMetadata
+  document: BedrockDocumentMetadata
+}

package/src/model-catalog.generated.ts

@@ -0,0 +1,88 @@
+// GENERATED by scripts/fetch-bedrock-models.ts — do not edit by hand.
+// Refresh: AWS_REGION=us-east-1 pnpm tsx scripts/fetch-bedrock-models.ts
+export const GENERATED_BEDROCK_MODELS = [
+  {
+    id: 'openai.gpt-oss-120b-1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: true, responses: true },
+  },
+  {
+    id: 'openai.gpt-oss-20b-1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: true, responses: true },
+  },
+  {
+    id: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.anthropic.claude-3-5-sonnet-20241022-v2:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.anthropic.claude-3-5-haiku-20241022-v1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.amazon.nova-pro-v1:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.amazon.nova-lite-v1:0',
+    input: ['text', 'image', 'document'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.amazon.nova-micro-v1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.meta.llama3-3-70b-instruct-v1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.meta.llama4-maverick-17b-instruct-v1:0',
+    input: ['text', 'image'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.mistral.pixtral-large-2502-v1:0',
+    input: ['text', 'image'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+  {
+    id: 'us.deepseek.r1-v1:0',
+    input: ['text'],
+    output: ['text'],
+    apis: { converse: true, chat: false, responses: false },
+  },
+] as const

package/src/model-meta.ts

@@ -0,0 +1,69 @@
+import { GENERATED_BEDROCK_MODELS } from './model-catalog.generated'
+import type { BedrockTextProviderOptions } from './text/text-provider-options'
+import type { BedrockConverseProviderOptions } from './converse/provider-options'
+
+type Entry = (typeof GENERATED_BEDROCK_MODELS)[number]
+
+/**
+ * Type-level per-API filter over the generated catalog. Because the catalog is
+ * `as const`, `Extract` preserves literal `id` unions (no widening to `string`).
+ */
+type IdsWhere<TApi extends 'converse' | 'chat' | 'responses'> = Extract<
+  Entry,
+  { apis: Record<TApi, true> }
+>['id']
+
+export type BedrockConverseModels = IdsWhere<'converse'>
+export type BedrockChatModels = IdsWhere<'chat'>
+export type BedrockResponsesModels = IdsWhere<'responses'>
+
+/** Runtime catalogs. Cast-free narrowing via a type predicate (the ai-bedrock pattern). */
+// Every catalog entry advertises `converse: true` (Converse is the universal
+// Bedrock surface), so the id list is the full catalog — no runtime filter needed.
+export const BEDROCK_CONVERSE_MODELS: ReadonlyArray<BedrockConverseModels> =
+  GENERATED_BEDROCK_MODELS.map((m) => m.id)
+
+export const BEDROCK_CHAT_MODELS: ReadonlyArray<BedrockChatModels> =
+  GENERATED_BEDROCK_MODELS.filter(
+    (m): m is Extract<Entry, { apis: { chat: true } }> => m.apis.chat,
+  ).map((m) => m.id)
+
+export const BEDROCK_RESPONSES_MODELS: ReadonlyArray<BedrockResponsesModels> =
+  GENERATED_BEDROCK_MODELS.filter(
+    (m): m is Extract<Entry, { apis: { responses: true } }> => m.apis.responses,
+  ).map((m) => m.id)
+
+/** Per-model input modalities (drives type-safe multimodal content). Covers ALL models. */
+export type BedrockModelInputModalitiesByName = {
+  [E in Entry as E['id']]: E['input']
+}
+
+/** Provider options per model. Same options for every model; keyed over the full catalog. */
+export type BedrockChatModelProviderOptionsByName = {
+  [E in Entry as E['id']]: BedrockTextProviderOptions
+}
+
+/** Converse provider options per model (narrower than the Chat Completions set). */
+export type BedrockConverseModelProviderOptionsByName = {
+  [E in Entry as E['id']]: BedrockConverseProviderOptions
+}
+
+/** No provider-specific tools — empty tuple makes cross-provider ProviderTool a compile error. */
+export type BedrockChatModelToolCapabilitiesByName = {
+  [E in Entry as E['id']]: readonly []
+}
+
+export type ResolveProviderOptions<TModel extends string> =
+  TModel extends keyof BedrockChatModelProviderOptionsByName
+    ? BedrockChatModelProviderOptionsByName[TModel]
+    : BedrockTextProviderOptions
+
+export type ResolveConverseProviderOptions<TModel extends string> =
+  TModel extends keyof BedrockConverseModelProviderOptionsByName
+    ? BedrockConverseModelProviderOptionsByName[TModel]
+    : BedrockConverseProviderOptions
+
+export type ResolveInputModalities<TModel extends string> =
+  TModel extends keyof BedrockModelInputModalitiesByName
+    ? BedrockModelInputModalitiesByName[TModel]
+    : readonly ['text']

package/src/text/responses-provider-options.ts

@@ -0,0 +1,28 @@
+/**
+ * Bedrock Responses API provider options. Mantle's Responses endpoint adds
+ * stateful conversation management on top of the OpenAI Responses fields.
+ *
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html
+ */
+export interface BedrockResponsesProviderOptions {
+  /** Continue a stored conversation from a prior response. */
+  previous_response_id?: string | null
+  /** Whether Bedrock retains the response for 30 days (default true). Set false to opt out. */
+  store?: boolean | null
+  metadata?: { [key: string]: string } | null
+  max_output_tokens?: number | null
+  temperature?: number | null
+  top_p?: number | null
+  parallel_tool_calls?: boolean | null
+  tool_choice?:
+    | 'none'
+    | 'auto'
+    | 'required'
+    | { type: 'function'; name: string }
+    | null
+  /** Reasoning controls for reasoning-capable models. */
+  reasoning?: { effort?: 'low' | 'medium' | 'high' } | null
+  user?: string | null
+}
+
+export type ExternalResponsesProviderOptions = BedrockResponsesProviderOptions

package/src/text/text-provider-options.ts

@@ -0,0 +1,33 @@
+/**
+ * Bedrock Chat Completions provider options. Bedrock accepts the standard
+ * OpenAI Chat Completions request fields; we surface the commonly-used ones
+ * plus `reasoning_effort` (supported by gpt-oss and reasoning models).
+ *
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-openai.html
+ */
+export interface BedrockTextProviderOptions {
+  frequency_penalty?: number | null
+  presence_penalty?: number | null
+  logit_bias?: { [token: string]: number } | null
+  logprobs?: boolean | null
+  top_logprobs?: number | null
+  max_completion_tokens?: number | null
+  metadata?: { [key: string]: string } | null
+  n?: number | null
+  parallel_tool_calls?: boolean | null
+  /** gpt-oss / reasoning models: 'low' | 'medium' (default) | 'high'. */
+  reasoning_effort?: 'low' | 'medium' | 'high' | null
+  seed?: number | null
+  stop?: string | Array<string> | null
+  temperature?: number | null
+  tool_choice?:
+    | 'none'
+    | 'auto'
+    | 'required'
+    | { type: 'function'; function: { name: string } }
+    | null
+  top_p?: number | null
+  user?: string | null
+}
+
+export type ExternalTextProviderOptions = BedrockTextProviderOptions

package/src/utils/auth.ts

@@ -0,0 +1,80 @@
+import type { AwsCredentialIdentityProvider } from '@smithy/types'
+import type * as CredentialProviders from '@aws-sdk/credential-providers'
+
+export type BedrockEndpoint = 'runtime' | 'mantle'
+
+/** SigV4 service name differs per endpoint. */
+export function sigv4Service(endpoint: BedrockEndpoint): string {
+  return endpoint === 'mantle' ? 'bedrock-mantle' : 'bedrock'
+}
+
+export type ResolvedBedrockAuth =
+  | { kind: 'bearer'; token: string }
+  | {
+      kind: 'sigv4'
+      region: string
+      service: string
+      credentials: AwsCredentialIdentityProvider
+    }
+
+const DEFAULT_REGION = 'us-east-1'
+
+function readApiKeyFromEnv(): string | undefined {
+  // Bedrock is server-only (the AWS SDK is Node-only), so the key always comes
+  // from process.env. Read it directly: a property access never throws, so —
+  // unlike the previous try/catch around getApiKeyFromEnv — we no longer swallow
+  // unrelated errors as "key not set". Each var is blank-checked independently
+  // so a present-but-blank BEDROCK_API_KEY falls through to
+  // AWS_BEARER_TOKEN_BEDROCK (and only then to SigV4) rather than masking it.
+  const env = typeof process !== 'undefined' ? process.env : undefined
+  for (const value of [env?.BEDROCK_API_KEY, env?.AWS_BEARER_TOKEN_BEDROCK]) {
+    if (value && value.trim() !== '') return value
+  }
+  return undefined
+}
+
+export interface BedrockAuthConfig {
+  apiKey?: string
+  region?: string
+  auth?: 'apikey' | 'sigv4' | 'auto'
+}
+
+/** apiKey -> BEDROCK_API_KEY -> AWS_BEARER_TOKEN_BEDROCK -> SigV4 (credential chain). */
+export function resolveBedrockAuth(
+  config: BedrockAuthConfig,
+  endpoint: BedrockEndpoint,
+): ResolvedBedrockAuth {
+  const mode = config.auth ?? 'auto'
+  const region = config.region ?? DEFAULT_REGION
+
+  if (mode !== 'sigv4') {
+    const token = config.apiKey ?? readApiKeyFromEnv()
+    if (token) return { kind: 'bearer', token }
+    if (mode === 'apikey') {
+      throw new Error(
+        'No Bedrock API key found. Set BEDROCK_API_KEY (or ' +
+          'AWS_BEARER_TOKEN_BEDROCK), pass `apiKey`, or use auth: "sigv4".',
+      )
+    }
+  }
+
+  return {
+    kind: 'sigv4',
+    region,
+    service: sigv4Service(endpoint),
+    // Lazy credential provider: the AWS SDK is Node/server-only, so we defer the
+    // dynamic import until SigV4 actually needs to resolve credentials. The
+    // specifier is held in a variable (not a string literal) so bundler dep
+    // scanners (e.g. Vite/esbuild optimizeDeps) cannot statically discover the
+    // AWS SDK and try to pre-bundle it for the browser — it would fail on the
+    // SDK's Node-only `fromTokenFile` export chain. `typeof import(...)` is a
+    // type-only reference (erased at emit) so we keep full typing.
+    credentials: async (...args) => {
+      const mod = '@aws-sdk/credential-providers'
+      const { fromNodeProviderChain } = (await import(
+        /* @vite-ignore */ mod
+      )) as typeof CredentialProviders
+      return fromNodeProviderChain()(...args)
+    },
+  }
+}

package/src/utils/client.ts

@@ -0,0 +1,62 @@
+import { resolveBedrockAuth } from './auth'
+import { createSigV4Fetch } from './openai-sigv4-fetch'
+import type { ClientOptions } from 'openai'
+import type { BedrockEndpoint } from './auth'
+
+export type { BedrockEndpoint } from './auth'
+export { resolveBedrockAuth } from './auth'
+export type { ResolvedBedrockAuth } from './auth'
+
+export interface BedrockClientConfig extends Omit<
+  ClientOptions,
+  'apiKey' | 'baseURL'
+> {
+  /** Bedrock API key (bearer). Optional — falls back to env, then SigV4. */
+  apiKey?: string
+  /** Full AWS region (e.g. 'us-east-1'). Default 'us-east-1'. */
+  region?: string
+  /** Chat adapter only; the responses adapter forces 'mantle'. Default 'runtime'. */
+  endpoint?: BedrockEndpoint
+  /** Auth strategy. Default 'auto' (apiKey → env → SigV4). */
+  auth?: 'apikey' | 'sigv4' | 'auto'
+  /** Explicit override; wins over the computed endpoint URL (used by E2E → aimock). */
+  baseURL?: string
+}
+
+const DEFAULT_REGION = 'us-east-1'
+/** OpenAI SDK requires a non-empty apiKey even when a signed fetch overrides Authorization. */
+const SIGV4_PLACEHOLDER_KEY = 'bedrock-sigv4'
+
+function buildBaseURL(region: string, endpoint: BedrockEndpoint): string {
+  return endpoint === 'mantle'
+    ? `https://bedrock-mantle.${region}.api.aws/v1`
+    : `https://bedrock-runtime.${region}.amazonaws.com/openai/v1`
+}
+
+/** Builds OpenAI ClientOptions for the requested endpoint. `forced` pins the endpoint (responses → 'mantle'). */
+export function withBedrockDefaults(
+  config: BedrockClientConfig,
+  forced?: BedrockEndpoint,
+): ClientOptions {
+  const { region, endpoint, auth, apiKey, baseURL, fetch, ...rest } = config
+  const resolvedRegion = region ?? DEFAULT_REGION
+  const resolvedEndpoint = forced ?? endpoint ?? 'runtime'
+  const resolved = resolveBedrockAuth(
+    { apiKey, region: resolvedRegion, auth },
+    resolvedEndpoint,
+  )
+  if (resolved.kind === 'bearer') {
+    return {
+      ...rest,
+      baseURL: baseURL ?? buildBaseURL(resolvedRegion, resolvedEndpoint),
+      apiKey: resolved.token,
+      ...(fetch ? { fetch } : {}),
+    }
+  }
+  return {
+    ...rest,
+    baseURL: baseURL ?? buildBaseURL(resolvedRegion, resolvedEndpoint),
+    apiKey: SIGV4_PLACEHOLDER_KEY,
+    fetch: fetch ?? createSigV4Fetch(resolved),
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export {
+  resolveBedrockAuth,
+  withBedrockDefaults,
+  type BedrockClientConfig,
+  type BedrockEndpoint,
+  type ResolvedBedrockAuth,
+} from './client'