@sixb/azure-ai-foundry 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/transport.ts CHANGED
@@ -31,24 +31,66 @@ const AUDIO_API_VERSION = "2024-10-21"
31
31
  /** The first version with GPT Image; v1 does not route FLUX.1 Kontext edits. */
32
32
  const IMAGE_API_VERSION = "2025-04-01-preview"
33
33
 
34
+ /**
35
+ * The audience every Foundry call accepts: project discovery refuses a token for
36
+ * cognitiveservices.azure.com, which model calls also accept (measured November 2026).
37
+ */
38
+ const ENTRA_SCOPE = "https://ai.azure.com/.default"
39
+
40
+ /**
41
+ * Token renewal follows Azure's own token cycler (`@azure/core-rest-pipeline`): renew in the
42
+ * background from the credential's refresh hint or two minutes before expiry, keep the current
43
+ * token while a renewal fails, and wait only for a missing or expiring one.
44
+ */
45
+ const RENEW_BEFORE_EXPIRY_MS = 2 * 60_000
46
+ const EXPIRING_MS = 1_000
47
+ const RENEW_RETRY_MS = 3_000
48
+ /** Bounds one getToken call, so one that never settles cannot hold every later call. */
49
+ const TOKEN_TIMEOUT_MS = 30_000
50
+
51
+ /** Entra ID sign-in, such as `DefaultAzureCredential` or `ManagedIdentityCredential` from `@azure/identity`. */
52
+ export interface AzureAIFoundryCredential {
53
+ getToken(
54
+ scopes: string | string[],
55
+ options?: { readonly abortSignal?: AbortSignal }
56
+ ): Promise<{
57
+ readonly token: string
58
+ readonly expiresOnTimestamp?: number
59
+ readonly refreshAfterTimestamp?: number
60
+ } | null>
61
+ }
62
+
34
63
  export interface TransportOptions {
35
64
  readonly endpoint: string
36
- readonly apiKey: ValueSource<string | undefined>
65
+ /** The project resource's key, sent as `api-key` (`x-api-key` to Messages). */
66
+ readonly apiKey?: ValueSource<string | undefined>
67
+ /** Entra ID in place of a key: a bearer token for every call, renewed before it expires. */
68
+ readonly credential?: AzureAIFoundryCredential
37
69
  readonly headers?: ValueSource<Readonly<Record<string, string>>>
38
70
  readonly fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>
39
71
  readonly maxRetries?: number
40
72
  readonly maxRetryDelayMs?: number
41
73
  }
42
74
 
75
+ /**
76
+ * The project URL says what is deployed; every model call goes to the resource that owns the
77
+ * project. The project's own inference path answers through another service that trails new
78
+ * models: for gpt-6.2-sol it refused reasoning efforts, ignored tools and reported no input
79
+ * tokens, where the resource answered all three (measured November 2026).
80
+ */
43
81
  export class FoundryTransport {
44
82
  private readonly diagnostics = new WeakMap<Response, RequestDiagnostics>()
45
- readonly baseUrl: string
83
+ /** Deployment discovery: `https://<resource>.services.ai.azure.com/api/projects/<project>`. */
46
84
  readonly projectUrl: string
85
+ /** Every model call: the project URL's origin. */
86
+ readonly resourceUrl: string
47
87
  private readonly options: TransportOptions
88
+ private token?: { readonly value: string; readonly expiresAt: number; readonly renewAt: number }
89
+ private renewal?: Promise<string>
48
90
 
49
- constructor(options: TransportOptions, target: "project" | "resource" = "project") {
91
+ constructor(options: TransportOptions) {
50
92
  if (!URL.canParse(options.endpoint))
51
- throw new TypeError(`${PREFIX} endpoint must be a valid ${target} URL.`)
93
+ throw new TypeError(`${PREFIX} endpoint must be a valid project URL.`)
52
94
  const url = new URL(options.endpoint)
53
95
  if (
54
96
  !["https:", "http:"].includes(url.protocol) ||
@@ -58,25 +100,28 @@ export class FoundryTransport {
58
100
  url.hash
59
101
  ) {
60
102
  throw new TypeError(
61
- `${PREFIX} endpoint must be an HTTP(S) ${target} URL without credentials, query, or fragment.`
103
+ `${PREFIX} endpoint must be an HTTP(S) project URL without credentials, query, or fragment.`
62
104
  )
63
105
  }
64
106
  const path = url.pathname.replace(/\/+$/, "")
65
- if (target === "project" && !/^\/api\/projects\/[^/]+$/.test(path))
107
+ if (!/^\/api\/projects\/[^/]+$/.test(path))
66
108
  throw new TypeError(
67
109
  `${PREFIX} endpoint must be a Foundry project URL: https://<resource>.services.ai.azure.com/api/projects/<project>.`
68
110
  )
69
- if (target === "resource" && path !== "" && path !== "/openai/v1")
70
- throw new TypeError(
71
- `${PREFIX} embeddings.endpoint must be a resource origin or /openai/v1 URL.`
72
- )
73
111
  this.projectUrl = `${url.origin}${path}`
74
- this.baseUrl = target === "project" ? `${this.projectUrl}/openai/v1` : `${url.origin}/openai/v1`
75
- if (
112
+ this.resourceUrl = url.origin
113
+ if (options.credential !== undefined) {
114
+ if (options.apiKey !== undefined)
115
+ throw new TypeError(`${PREFIX} Configure either apiKey or credential, not both.`)
116
+ if (typeof options.credential?.getToken !== "function")
117
+ throw new TypeError(
118
+ `${PREFIX} credential must have a getToken method, such as DefaultAzureCredential from @azure/identity.`
119
+ )
120
+ } else if (
76
121
  typeof options.apiKey !== "function" &&
77
122
  (typeof options.apiKey !== "string" || !options.apiKey.trim())
78
123
  )
79
- throw new TypeError(`${PREFIX} apiKey is required.`)
124
+ throw new TypeError(`${PREFIX} apiKey or credential is required.`)
80
125
  if (
81
126
  options.maxRetries !== undefined &&
82
127
  (!Number.isSafeInteger(options.maxRetries) || options.maxRetries < 0)
@@ -174,38 +219,92 @@ export class FoundryTransport {
174
219
  for (const value of headers.values()) diagnostics.add(value)
175
220
  for (const reserved of ["authorization", "api-key", "x-api-key"])
176
221
  if (headers.has(reserved))
177
- throw new TypeError(`${PREFIX} Use apiKey instead of '${reserved}' headers.`)
222
+ throw new TypeError(`${PREFIX} Use apiKey or credential instead of '${reserved}' headers.`)
223
+ if (this.options.credential) {
224
+ const token = await this.bearerToken(signal)
225
+ diagnostics.add(token)
226
+ headers.set("authorization", `Bearer ${token}`)
227
+ return headers
228
+ }
178
229
  const key = await resolve(this.options.apiKey, signal)
179
230
  if (typeof key !== "string" || !key.trim())
180
- throw new TypeError(`${PREFIX} apiKey must resolve to a nonempty string.`)
231
+ throw new TypeError(
232
+ `${PREFIX} apiKey must resolve to a nonempty string: pass apiKey or credential, or set AZURE_AI_FOUNDRY_API_KEY.`
233
+ )
181
234
  diagnostics.add(key)
182
235
  headers.set(keyHeader, key)
183
236
  return headers
184
237
  }
185
238
 
239
+ /** One token for every call; a call waits only when there is none, or it is about to expire. */
240
+ private bearerToken(signal: AbortSignal): Promise<string> {
241
+ const token = this.token
242
+ const now = Date.now()
243
+ if (!token || now >= token.expiresAt - EXPIRING_MS)
244
+ return abortable(() => this.renewToken(), signal)
245
+ if (now >= token.renewAt)
246
+ this.renewToken().catch(() => {
247
+ // The current token still works; try again shortly, or when it expires.
248
+ if (this.token === token) this.token = { ...token, renewAt: Date.now() + RENEW_RETRY_MS }
249
+ })
250
+ return Promise.resolve(token.value)
251
+ }
252
+
253
+ /** Concurrent callers share one getToken call. */
254
+ private renewToken(): Promise<string> {
255
+ this.renewal ??= (async () => {
256
+ const controller = new AbortController()
257
+ const timer = setTimeout(
258
+ () => controller.abort(new Error(`${PREFIX} credential.getToken timed out.`)),
259
+ TOKEN_TIMEOUT_MS
260
+ )
261
+ try {
262
+ const signal = controller.signal
263
+ const token = await abortable(
264
+ () => this.options.credential!.getToken(ENTRA_SCOPE, { abortSignal: signal }),
265
+ signal
266
+ )
267
+ if (typeof token?.token !== "string" || !token.token.trim())
268
+ throw new TypeError(`${PREFIX} credential returned no token for ${ENTRA_SCOPE}.`)
269
+ // A token without an expiry is not reused: the credential's own cache decides.
270
+ const expiresAt = token.expiresOnTimestamp ?? 0
271
+ this.token = {
272
+ value: token.token,
273
+ expiresAt,
274
+ renewAt: Math.min(
275
+ token.refreshAfterTimestamp ?? expiresAt,
276
+ expiresAt - RENEW_BEFORE_EXPIRY_MS
277
+ ),
278
+ }
279
+ return token.token
280
+ } finally {
281
+ clearTimeout(timer)
282
+ this.renewal = undefined
283
+ }
284
+ })()
285
+ return this.renewal
286
+ }
287
+
186
288
  fetch(url: string, init: RequestInit): Promise<Response> {
187
289
  return (this.options.fetch ?? fetch)(url, init)
188
290
  }
189
291
 
190
292
  url(protocol: FoundryRoute, deployment?: string): string {
191
- if (protocol === "embeddings") return `${this.baseUrl}/embeddings`
192
- // Audio deployments answer on the resource origin, by deployment path.
293
+ const resource = this.resourceUrl
294
+ const path = encodeURIComponent(deployment ?? "")
295
+ // Audio and image deployments answer by deployment path, at the versions noted above.
193
296
  if (protocol === "transcription")
194
- return `${new URL(this.baseUrl).origin}/openai/deployments/${encodeURIComponent(deployment ?? "")}/audio/transcriptions?api-version=${AUDIO_API_VERSION}`
195
- // Decision models answer on the resource origin; the project path does not route them.
196
- if (protocol === "decision")
197
- return `${new URL(this.baseUrl).origin}/providers/microsoft/v1/systemone`
198
- // Image deployments answer on the resource origin, by deployment path.
297
+ return `${resource}/openai/deployments/${path}/audio/transcriptions?api-version=${AUDIO_API_VERSION}`
199
298
  if (protocol === "image" || protocol === "image-edit")
200
- return `${new URL(this.baseUrl).origin}/openai/deployments/${encodeURIComponent(deployment ?? "")}/images/${protocol === "image" ? "generations" : "edits"}?api-version=${IMAGE_API_VERSION}`
201
- // Cohere rerankers answer Cohere's v2 API on the resource origin.
202
- if (protocol === "reranking")
203
- return `${new URL(this.baseUrl).origin}/providers/cohere/v2/rerank`
204
- // Speech answers on the resource's v1 API; the project path does not route it.
205
- if (protocol === "speech") return `${new URL(this.baseUrl).origin}/openai/v1/audio/speech`
206
- if (protocol === "responses") return `${this.baseUrl}/responses`
207
- if (protocol === "chat") return `${this.baseUrl}/chat/completions`
208
- return `${new URL(this.baseUrl).origin}/anthropic/v1/messages`
299
+ return `${resource}/openai/deployments/${path}/images/${protocol === "image" ? "generations" : "edits"}?api-version=${IMAGE_API_VERSION}`
300
+ if (protocol === "decision") return `${resource}/providers/microsoft/v1/systemone`
301
+ // Cohere rerankers answer Cohere's v2 API.
302
+ if (protocol === "reranking") return `${resource}/providers/cohere/v2/rerank`
303
+ if (protocol === "messages") return `${resource}/anthropic/v1/messages`
304
+ if (protocol === "embeddings") return `${resource}/openai/v1/embeddings`
305
+ if (protocol === "speech") return `${resource}/openai/v1/audio/speech`
306
+ if (protocol === "chat") return `${resource}/openai/v1/chat/completions`
307
+ return `${resource}/openai/v1/responses`
209
308
  }
210
309
  }
211
310