@rulvar/openai 1.14.0 → 1.16.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import OpenAI, { ClientOptions } from "openai";
 import { CanonicalId, ChatEvent, ChatRequest, Effort, ModelCaps, PriceTable, ProviderAdapter, Usage, WireError } from "@rulvar/core";
 
 //#region src/caps.d.ts
@@ -47,11 +48,31 @@ interface OpenAiClientLike {
     };
   };
 }
+/**
+* Official SDK construction options forwarded verbatim to
+* `new OpenAI(...)`, minus `maxRetries`: Rulvar owns retries and
+* wall-clock, so SDK autoretries stay disabled no matter what is passed
+* here. This is the production surface for auth beyond a plain API key,
+* `workloadIdentity` federation included, plus `fetch`, `timeout`, and
+* `defaultHeaders`. The SDK's own rules still apply inside it, e.g.
+* `sdkOptions.apiKey` and `sdkOptions.workloadIdentity` are mutually
+* exclusive and rejected typed at construction.
+*/
+type OpenAiSdkOptions = Omit<ClientOptions, "maxRetries">;
 interface OpenAiAdapterOptions {
+  /** Shorthand for `sdkOptions.apiKey`; setting both is a ConfigError. */
   apiKey?: string;
+  /** Shorthand for `sdkOptions.baseURL`; setting both is a ConfigError. */
   baseURL?: string;
-  /** Test seam: a preconstructed client; production uses the openai SDK. */
-  client?: OpenAiClientLike;
+  /** Official SDK construction options; see `OpenAiSdkOptions`. */
+  sdkOptions?: OpenAiSdkOptions;
+  /**
+  * A preconstructed client instead of the construction options above
+  * (combining them is a ConfigError): the official `OpenAI` instance
+  * (production; it must be constructed with `maxRetries: 0`) or a
+  * structural `OpenAiClientLike` mock (tests).
+  */
+  client?: OpenAI | OpenAiClientLike;
 }
 /** Creates the first-class OpenAI adapter (id 'openai'); maxRetries 0. */
 declare function openai(options?: OpenAiAdapterOptions): ProviderAdapter;
@@ -145,4 +166,4 @@ declare function buildChatCompletionsParams(req: ChatRequest, ids: OpenAiIdMap):
 */
 declare function mapChatCompletionsStream(stream: AsyncIterable<Record<string, unknown>>, ids: OpenAiIdMap): AsyncGenerator<ChatEvent, void>;
 //#endregion
-export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, type OpenAiAdapterOptions, type OpenAiClientLike, type OpenAiCompatibleConfig, OpenAiIdMap, type OpenAiModelInfo, type ResponsesStreamEvent, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };
+export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OPENAI_PRICING, type OpenAiAdapterOptions, type OpenAiClientLike, type OpenAiCompatibleConfig, OpenAiIdMap, type OpenAiModelInfo, type OpenAiSdkOptions, type ResponsesStreamEvent, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };

package/dist/index.js

@@ -623,13 +623,27 @@ async function* mapChatCompletionsStream(stream, ids) {
 * Docs: https://docs.rulvar.com/guide/providers
 * The openaiCompatible factory ships in M3.
 */
-/** Creates the first-class OpenAI adapter (id 'openai'); maxRetries 0. */
-function openai(options = {}) {
-	const client = options.client ?? new OpenAI({
+function resolveOpenAiClient(options) {
+	if (options.client !== void 0) {
+		if (options.apiKey !== void 0 || options.baseURL !== void 0 || options.sdkOptions !== void 0) throw new ConfigError("openai(): 'client' is mutually exclusive with 'apiKey', 'baseURL', and 'sdkOptions'; configure the preconstructed client directly");
+		const maxRetries = options.client.maxRetries;
+		if (typeof maxRetries === "number" && maxRetries !== 0) throw new ConfigError(`openai(): the injected client has SDK autoretries enabled (maxRetries ${String(maxRetries)}); construct it with maxRetries: 0, Rulvar owns retries and wall-clock`);
+		return options.client;
+	}
+	const sdkOptions = options.sdkOptions ?? {};
+	if (options.apiKey !== void 0 && sdkOptions.apiKey !== void 0) throw new ConfigError("openai(): 'apiKey' and 'sdkOptions.apiKey' are both set; pick one place");
+	if (options.apiKey !== void 0 && sdkOptions.workloadIdentity !== void 0) throw new ConfigError("openai(): 'apiKey' and 'sdkOptions.workloadIdentity' are mutually exclusive auth modes");
+	if (options.baseURL !== void 0 && sdkOptions.baseURL !== void 0) throw new ConfigError("openai(): 'baseURL' and 'sdkOptions.baseURL' are both set; pick one place");
+	return new OpenAI({
+		...sdkOptions,
 		...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
 		...options.baseURL === void 0 ? {} : { baseURL: options.baseURL },
 		maxRetries: 0
 	});
+}
+/** Creates the first-class OpenAI adapter (id 'openai'); maxRetries 0. */
+function openai(options = {}) {
+	const client = resolveOpenAiClient(options);
 	const ids = new OpenAiIdMap(createCanonicalIdMinter());
 	return {
 		id: "openai",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/openai",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Rulvar first-class provider adapter for the OpenAI Responses API, plus the openaiCompatible factory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,13 +23,13 @@
   },
   "dependencies": {
     "openai": "^6.45.0",
-    "@rulvar/core": "1.14.0"
+    "@rulvar/core": "1.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.14.0"
+    "@rulvar/testing": "1.16.0"
   },
   "repository": {
     "type": "git",