@objectstack/embedder-openai 7.8.0 → 8.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/embedder-openai@7.8.0 build /home/runner/work/framework/framework/packages/plugins/embedder-openai
+> @objectstack/embedder-openai@8.0.0 build /home/runner/work/framework/framework/packages/plugins/embedder-openai
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     4.27 KB
-CJS dist/index.js.map 9.70 KB
-CJS ⚡️ Build success in 52ms
-ESM dist/index.mjs     3.16 KB
-ESM dist/index.mjs.map 9.64 KB
-ESM ⚡️ Build success in 53ms
+ESM dist/index.mjs     3.25 KB
+ESM dist/index.mjs.map 9.77 KB
+ESM ⚡️ Build success in 48ms
+CJS dist/index.js     4.38 KB
+CJS dist/index.js.map 9.82 KB
+CJS ⚡️ Build success in 48ms
 DTS Build start
-DTS ⚡️ Build success in 4410ms
+DTS ⚡️ Build success in 5103ms
 DTS dist/index.d.mts 4.86 KB
 DTS dist/index.d.ts  4.86 KB

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @objectstack/embedder-openai
 
+## 8.0.0
+
+### Patch Changes
+
+- d5a8161: feat(spec): resilientFetch — timeout + backoff for outbound HTTP (P1-1)
+
+  Outbound calls in the connectors/embedder were naked `fetch` with no timeout or
+  retry, so a slow or rate-limited external API could hang an agent turn with no
+  recovery.
+
+  New shared `resilientFetch` (`@objectstack/spec/shared`):
+
+  - per-attempt timeout via `AbortController` (default 30s);
+  - exponential backoff with jitter, up to 3 attempts, on network errors / 429 / 5xx;
+  - honours a `Retry-After` header on 429;
+  - never retries a caller-initiated abort (intentional cancellation).
+
+  Wired into `connector-rest`, `connector-slack`, and `embedder-openai`.
+  `connector-mcp` talks through the MCP SDK transport, so it gets a 30s per-request
+  `timeout` on `callTool` / `listTools` instead.
+
+  A stateful per-host **circuit breaker** is deliberately left as a follow-up:
+  timeout + backoff already removes the hang/no-recovery risk.
+
+- Updated dependencies [a46c017]
+- Updated dependencies [b990b89]
+- Updated dependencies [99111ec]
+- Updated dependencies [d5a8161]
+- Updated dependencies [5cf1f1b]
+- Updated dependencies [9ef89d4]
+- Updated dependencies [3306d2f]
+- Updated dependencies [bc44195]
+- Updated dependencies [9e2e229]
+  - @objectstack/spec@8.0.0
+
+## 7.9.0
+
+### Patch Changes
+
+- @objectstack/spec@7.9.0
+
 ## 7.8.0
 
 ### Patch Changes

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+var import_shared = require("@objectstack/spec/shared");
 var KNOWN_DIMENSIONS = {
   // OpenAI
   "text-embedding-3-small": 1536,
@@ -74,7 +75,7 @@ var OpenAIEmbedder = class {
     if (texts.length === 0) return [];
     const body = { model: this.model, input: texts };
     if (this.requestedDims) body.dimensions = this.requestedDims;
-    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+    const res = await (0, import_shared.resilientFetch)(`${this.baseUrl}/embeddings`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -82,7 +83,7 @@ var OpenAIEmbedder = class {
         ...this.extraHeaders
       },
       body: JSON.stringify(body)
-    });
+    }, { fetchImpl: this.fetchImpl });
     if (!res.ok) {
       const text = await res.text().catch(() => "");
       throw new Error(

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+DA,IAAM,mBAA2C;AAAA;AAAA,EAE/C,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA;AAAA,EAE1B,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,qBAAqB;AAAA;AAAA,EAErB,eAAe;AAAA,EACf,eAAe;AAAA;AAAA,EAEf,eAAe;AAAA,EACf,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,yBAAyB;AAAA,EACzB,0BAA0B;AAAA,EAC1B,UAAU;AAAA;AAAA,EAEV,sCAAsC;AAAA,EACtC,gCAAgC;AAAA;AAAA,EAEhC,oBAAoB;AAAA;AAAA,EAEpB,WAAW;AACb;AAmCO,IAAM,iBAAN,MAA0C;AAAA,EAU/C,YAAY,MAA6B;AACvC,QAAI,CAAC,KAAK,OAAQ,OAAM,IAAI,MAAM,iCAAiC;AACnE,SAAK,SAAS,KAAK;AACnB,SAAK,KAAK,KAAK,MAAM;AACrB,SAAK,QAAQ,KAAK,SAAS;AAC3B,SAAK,WAAW,KAAK,WAAW,6BAA6B,QAAQ,QAAQ,EAAE;AAC/E,SAAK,YAAY,KAAK,SAAU,WAAW;AAC3C,SAAK,gBAAgB,KAAK;AAC1B,SAAK,eAAe,KAAK,WAAW,CAAC;AACrC,SAAK,aACH,KAAK,cAAc,iBAAiB,KAAK,KAAK,KAAK;AACrD,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,OAAsC;AAChD,QAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAChC,UAAM,OAAgC,EAAE,OAAO,KAAK,OAAO,OAAO,MAAM;AACxE,QAAI,KAAK,cAAe,MAAK,aAAa,KAAK;AAC/C,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,OAAO,eAAe;AAAA,MAC7D,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,GAAG,KAAK;AAAA,MACV;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,YAAM,IAAI;AAAA,QACR,mBAAmB,KAAK,OAAO,YAAO,IAAI,MAAM,IAAI,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE;AAAA,MAC5G;AAAA,IACF;AACA,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,UAAM,OAAO,KAAK,QAAQ,CAAC;AAC3B,QAAI,KAAK,WAAW,MAAM,QAAQ;AAChC,YAAM,IAAI;AAAA,QACR,4BAA4B,MAAM,MAAM,iBAAiB,KAAK,MAAM;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS;AAAA,EACpC;AACF;AAMO,IAAM,4BAA4B;AAAA,EACvC,QAAQ;AAAA,EACR,OAAO;AAAA;AAAA,EACP,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AACV;AAmBO,SAAS,qBAAqB,MAA6C;AAChF,QAAM,UACJ,KAAK,YACJ,KAAK,SAAS,0BAA0B,KAAK,MAAM,IAAI;AAC1D,SAAO,IAAI,eAAe,EAAE,GAAG,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,UAAU,SAAS,CAAC;AACxF;AAEA,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await resilientFetch(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    }, { fetchImpl: this.fetchImpl });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/index.ts
+import { resilientFetch } from "@objectstack/spec/shared";
 var KNOWN_DIMENSIONS = {
   // OpenAI
   "text-embedding-3-small": 1536,
@@ -47,7 +48,7 @@ var OpenAIEmbedder = class {
     if (texts.length === 0) return [];
     const body = { model: this.model, input: texts };
     if (this.requestedDims) body.dimensions = this.requestedDims;
-    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+    const res = await resilientFetch(`${this.baseUrl}/embeddings`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -55,7 +56,7 @@ var OpenAIEmbedder = class {
         ...this.extraHeaders
       },
       body: JSON.stringify(body)
-    });
+    }, { fetchImpl: this.fetchImpl });
     if (!res.ok) {
       const text = await res.text().catch(() => "");
       throw new Error(

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":";AA+DA,IAAM,mBAA2C;AAAA;AAAA,EAE/C,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA;AAAA,EAE1B,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,qBAAqB;AAAA;AAAA,EAErB,eAAe;AAAA,EACf,eAAe;AAAA;AAAA,EAEf,eAAe;AAAA,EACf,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,yBAAyB;AAAA,EACzB,0BAA0B;AAAA,EAC1B,UAAU;AAAA;AAAA,EAEV,sCAAsC;AAAA,EACtC,gCAAgC;AAAA;AAAA,EAEhC,oBAAoB;AAAA;AAAA,EAEpB,WAAW;AACb;AAmCO,IAAM,iBAAN,MAA0C;AAAA,EAU/C,YAAY,MAA6B;AACvC,QAAI,CAAC,KAAK,OAAQ,OAAM,IAAI,MAAM,iCAAiC;AACnE,SAAK,SAAS,KAAK;AACnB,SAAK,KAAK,KAAK,MAAM;AACrB,SAAK,QAAQ,KAAK,SAAS;AAC3B,SAAK,WAAW,KAAK,WAAW,6BAA6B,QAAQ,QAAQ,EAAE;AAC/E,SAAK,YAAY,KAAK,SAAU,WAAW;AAC3C,SAAK,gBAAgB,KAAK;AAC1B,SAAK,eAAe,KAAK,WAAW,CAAC;AACrC,SAAK,aACH,KAAK,cAAc,iBAAiB,KAAK,KAAK,KAAK;AACrD,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,OAAsC;AAChD,QAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAChC,UAAM,OAAgC,EAAE,OAAO,KAAK,OAAO,OAAO,MAAM;AACxE,QAAI,KAAK,cAAe,MAAK,aAAa,KAAK;AAC/C,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,OAAO,eAAe;AAAA,MAC7D,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,GAAG,KAAK;AAAA,MACV;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,YAAM,IAAI;AAAA,QACR,mBAAmB,KAAK,OAAO,YAAO,IAAI,MAAM,IAAI,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE;AAAA,MAC5G;AAAA,IACF;AACA,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,UAAM,OAAO,KAAK,QAAQ,CAAC;AAC3B,QAAI,KAAK,WAAW,MAAM,QAAQ;AAChC,YAAM,IAAI;AAAA,QACR,4BAA4B,MAAM,MAAM,iBAAiB,KAAK,MAAM;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS;AAAA,EACpC;AACF;AAMO,IAAM,4BAA4B;AAAA,EACvC,QAAQ;AAAA,EACR,OAAO;AAAA;AAAA,EACP,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AACV;AAmBO,SAAS,qBAAqB,MAA6C;AAChF,QAAM,UACJ,KAAK,YACJ,KAAK,SAAS,0BAA0B,KAAK,MAAM,IAAI;AAC1D,SAAO,IAAI,eAAe,EAAE,GAAG,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,UAAU,SAAS,CAAC;AACxF;AAEA,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await resilientFetch(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    }, { fetchImpl: this.fetchImpl });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":";AAsBA,SAAS,sBAAsB;AA0C/B,IAAM,mBAA2C;AAAA;AAAA,EAE/C,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA;AAAA,EAE1B,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,qBAAqB;AAAA;AAAA,EAErB,eAAe;AAAA,EACf,eAAe;AAAA;AAAA,EAEf,eAAe;AAAA,EACf,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,yBAAyB;AAAA,EACzB,0BAA0B;AAAA,EAC1B,UAAU;AAAA;AAAA,EAEV,sCAAsC;AAAA,EACtC,gCAAgC;AAAA;AAAA,EAEhC,oBAAoB;AAAA;AAAA,EAEpB,WAAW;AACb;AAmCO,IAAM,iBAAN,MAA0C;AAAA,EAU/C,YAAY,MAA6B;AACvC,QAAI,CAAC,KAAK,OAAQ,OAAM,IAAI,MAAM,iCAAiC;AACnE,SAAK,SAAS,KAAK;AACnB,SAAK,KAAK,KAAK,MAAM;AACrB,SAAK,QAAQ,KAAK,SAAS;AAC3B,SAAK,WAAW,KAAK,WAAW,6BAA6B,QAAQ,QAAQ,EAAE;AAC/E,SAAK,YAAY,KAAK,SAAU,WAAW;AAC3C,SAAK,gBAAgB,KAAK;AAC1B,SAAK,eAAe,KAAK,WAAW,CAAC;AACrC,SAAK,aACH,KAAK,cAAc,iBAAiB,KAAK,KAAK,KAAK;AACrD,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,OAAsC;AAChD,QAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAChC,UAAM,OAAgC,EAAE,OAAO,KAAK,OAAO,OAAO,MAAM;AACxE,QAAI,KAAK,cAAe,MAAK,aAAa,KAAK;AAC/C,UAAM,MAAM,MAAM,eAAe,GAAG,KAAK,OAAO,eAAe;AAAA,MAC7D,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,GAAG,KAAK;AAAA,MACV;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,GAAG,EAAE,WAAW,KAAK,UAAU,CAAC;AAChC,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,YAAM,IAAI;AAAA,QACR,mBAAmB,KAAK,OAAO,YAAO,IAAI,MAAM,IAAI,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE;AAAA,MAC5G;AAAA,IACF;AACA,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,UAAM,OAAO,KAAK,QAAQ,CAAC;AAC3B,QAAI,KAAK,WAAW,MAAM,QAAQ;AAChC,YAAM,IAAI;AAAA,QACR,4BAA4B,MAAM,MAAM,iBAAiB,KAAK,MAAM;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS;AAAA,EACpC;AACF;AAMO,IAAM,4BAA4B;AAAA,EACvC,QAAQ;AAAA,EACR,OAAO;AAAA;AAAA,EACP,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AACV;AAmBO,SAAS,qBAAqB,MAA6C;AAChF,QAAM,UACJ,KAAK,YACJ,KAAK,SAAS,0BAA0B,KAAK,MAAM,IAAI;AAC1D,SAAO,IAAI,eAAe,EAAE,GAAG,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,UAAU,SAAS,CAAC;AACxF;AAEA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/embedder-openai",
-  "version": "7.8.0",
+  "version": "8.0.0",
   "license": "Apache-2.0",
   "description": "OpenAI-compatible embedder for ObjectStack — works against OpenAI, 阿里通义 DashScope, 智谱 BigModel, 硅基流动 SiliconFlow, 火山引擎 Doubao, MiniMax, Ollama, and any drop-in OpenAI-shape endpoint.",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "7.8.0"
+    "@objectstack/spec": "8.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/src/index.ts

@@ -20,6 +20,7 @@
  */
 
 import type { IEmbedder } from '@objectstack/spec/contracts';
+import { resilientFetch } from '@objectstack/spec/shared';
 
 export interface OpenAIEmbedderOptions {
   /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */
@@ -154,7 +155,7 @@ export class OpenAIEmbedder implements IEmbedder {
     if (texts.length === 0) return [];
     const body: Record<string, unknown> = { model: this.model, input: texts };
     if (this.requestedDims) body.dimensions = this.requestedDims;
-    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+    const res = await resilientFetch(`${this.baseUrl}/embeddings`, {
       method: 'POST',
       headers: {
         'content-type': 'application/json',
@@ -162,7 +163,7 @@ export class OpenAIEmbedder implements IEmbedder {
         ...this.extraHeaders,
       },
       body: JSON.stringify(body),
-    });
+    }, { fetchImpl: this.fetchImpl });
     if (!res.ok) {
       const text = await res.text().catch(() => '');
       throw new Error(

package/vitest.config.ts

@@ -11,6 +11,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@objectstack/spec/contracts': path.resolve(__dirname, '../../spec/src/contracts/index.ts'),
+      '@objectstack/spec/shared': path.resolve(__dirname, '../../spec/src/shared/index.ts'),
       '@objectstack/spec': path.resolve(__dirname, '../../spec/src/index.ts'),
     },
   },