@jerome-benoit/sap-ai-provider-v2 5.0.1 → 5.0.3

package/README.md

@@ -104,16 +104,17 @@ try {
 
   console.log(result.text);
 } catch (error) {
-  if (error instanceof APICallError) {
-    console.error("SAP AI Core API error:", error.message);
-    console.error("Status:", error.statusCode);
+  process.exitCode = 1;
+  if (APICallError.isInstance(error)) {
+    console.error("SAP AI Core API error:", error.statusCode, error.name);
   } else {
-    console.error("Unexpected error:", error);
+    console.error("Unexpected error:", error instanceof Error ? error.name : "Unknown error");
   }
 }
 ```
 
-> **Note:** Requires `AICORE_SERVICE_KEY` environment variable. See
+> **Note:** For local service-key setup, set `AICORE_SERVICE_KEY`. SAP BTP service
+> bindings and custom destinations are alternatives. See
 > [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
 
 ## Quick Reference
@@ -127,7 +128,7 @@ try {
 | **Streaming**       | `streamText({ model: provider("gpt-4.1"), prompt })`             | [Streaming](#streaming-responses)                             |
 | **Tool Calling**    | `generateText({ tools: { myTool: tool({...}) } })`               | [Tool Calling](#tool-calling)                                 |
 | **Error Handling**  | `if (APICallError.isInstance(error)) { /* handle error */ }`     | [API Reference](./API_REFERENCE.md#error-handling--reference) |
-| **Choose Model**    | See 80+ models (GPT, Claude, Gemini, Llama)                      | [Models](./API_REFERENCE.md#models)                           |
+| **Choose Model**    | Discover models available in your tenant                         | [Models](./API_REFERENCE.md#models)                           |
 | **Embeddings**      | `embed({ model: provider.embedding("text-embedding-3-small") })` | [Embeddings](#embeddings)                                     |
 
 ## Installation
@@ -140,11 +141,15 @@ The published package targets Node.js. Its ESM output uses Node
 The source-level Edge test suite does not establish deployability to pure Edge
 runtimes such as Cloudflare Workers; use a Node.js server runtime for deployment.
 
-| AI SDK | Install                                            | Provider import                     |
-| ------ | -------------------------------------------------- | ----------------------------------- |
-| 7      | `npm install @jerome-benoit/sap-ai-provider ai@^7` | `@jerome-benoit/sap-ai-provider/v4` |
-| 6      | `npm install @jerome-benoit/sap-ai-provider ai@^6` | `@jerome-benoit/sap-ai-provider`    |
-| 5      | `npm install @jerome-benoit/sap-ai-provider ai@^5` | `@jerome-benoit/sap-ai-provider/v2` |
+| AI SDK | Install                                            | Provider import                                                         |
+| ------ | -------------------------------------------------- | ----------------------------------------------------------------------- |
+| 7      | `npm install @jerome-benoit/sap-ai-provider ai@^7` | `@jerome-benoit/sap-ai-provider/v4`                                     |
+| 6      | `npm install @jerome-benoit/sap-ai-provider ai@^6` | `@jerome-benoit/sap-ai-provider` or `@jerome-benoit/sap-ai-provider/v3` |
+| 5      | `npm install @jerome-benoit/sap-ai-provider ai@^5` | `@jerome-benoit/sap-ai-provider/v2`                                     |
+
+`/v3` is an explicit alias for the AI SDK 6 root entrypoint. Both resolve to
+the same runtime modules and TypeScript declarations, including the same `sapai`
+instance within each module format; existing root imports remain valid.
 
 The Quick Start and inline snippets on this page use AI SDK 6 with the root V3
 entrypoint. The runnable files in `examples/` use the repository's installed
@@ -375,11 +380,12 @@ try {
   // streamText returns a result object; its usage property is a promise.
   console.log("\n\nUsage:", await result.usage);
 } catch (error) {
+  process.exitCode = 1;
   if (APICallError.isInstance(error)) {
-    console.error("API Error:", error.message);
-    // See Error Handling section for complete error type reference
+    console.error("API error:", error.statusCode, error.name);
+  } else {
+    console.error("Streaming failed:", error instanceof Error ? error.name : "Unknown error");
   }
-  throw error;
 }
 ```
 
@@ -507,7 +513,7 @@ const result = await generateText({
 
 ⚠️ **Model Limitations:** Some models have tool calling restrictions. See
 [API Reference - Model-Specific Tool Limitations](./API_REFERENCE.md#model-specific-tool-limitations)
-for the complete comparison table.
+for upstream support documentation.
 
 ### Multi-modal Input (Images)
 
@@ -575,7 +581,7 @@ Ground LLM responses in your own documents using vector databases.
 const provider = createSAPAIProvider({
   defaultSettings: {
     grounding: buildDocumentGroundingConfig({
-      filters: [{ id: "vector-store-1", data_repositories: ["*"] }],
+      filters: [{ id: "knowledge-filter", data_repositories: ["*"] }],
       placeholders: { input: ["groundingRequest"], output: "groundingOutput" },
     }),
   },
@@ -675,7 +681,8 @@ authentication, model parameters, data masking, content filtering, and more.
 - `deploymentId`: Specific deployment ID (auto-resolved if not set)
 - `requestConfig`: Custom HTTP request configuration (headers, params, timeout, etc.)
   forwarded to the underlying SAP AI SDK client on every call. Provider-level scope
-  only; use `requestConfig.headers` for SAP-specific headers such as
+  only; per-call `headers` can override individual headers. Use `requestConfig.headers`
+  for SAP-specific headers such as
   `AI-Object-Store-Secret-Name` (feedback service). See
   [API Reference](./API_REFERENCE.md#sapaiprovidersettings) for portability caveats.
 - `modelParams`: Temperature, maxTokens, topP, and other generation parameters
@@ -751,19 +758,19 @@ repository's AI SDK 7 dependency and the local `../src/index-v4` entrypoint.
 In an AI SDK 7 application, import from `@jerome-benoit/sap-ai-provider/v4`.
 See [Installation](#installation) for other AI SDK versions.
 
-| Example                             | Description                 | Key Features                            |
-| ----------------------------------- | --------------------------- | --------------------------------------- |
-| `example-generate-text.ts`          | Basic text generation       | Simple prompts, synchronous generation  |
-| `example-simple-chat-completion.ts` | Simple chat conversation    | System messages, user prompts           |
-| `example-chat-completion-tool.ts`   | Tool calling with functions | Weather API tool, function execution    |
-| `example-streaming-chat.ts`         | Streaming responses         | Real-time text generation, SSE          |
-| `example-image-recognition.ts`      | Multi-modal with images     | Vision models, image analysis           |
-| `example-data-masking.ts`           | Data privacy integration    | DPI masking, anonymization              |
-| `example-content-filtering.ts`      | Content filtering           | Azure Content Safety, orchestration     |
-| `example-document-grounding.ts`     | Document grounding (RAG)    | Vector store, retrieval-augmented gen   |
-| `example-translation.ts`            | Input/output translation    | Multi-language support, SAP translation |
-| `example-embeddings.ts`             | Text embeddings             | Vector generation, semantic similarity  |
-| `example-foundation-models.ts`      | Foundation Models API       | Direct model access, logprobs, seed     |
+| Example                             | Description                 | Key Features                             |
+| ----------------------------------- | --------------------------- | ---------------------------------------- |
+| `example-generate-text.ts`          | Basic text generation       | Simple prompts, non-streaming generation |
+| `example-simple-chat-completion.ts` | Simple chat conversation    | System messages, user prompts            |
+| `example-chat-completion-tool.ts`   | Tool calling with functions | Demo weather tool, function execution    |
+| `example-streaming-chat.ts`         | Streaming responses         | Real-time text generation, SSE           |
+| `example-image-recognition.ts`      | Multi-modal with images     | Vision models, image analysis            |
+| `example-data-masking.ts`           | Data privacy integration    | DPI masking, anonymization               |
+| `example-content-filtering.ts`      | Content filtering           | Azure Content Safety, orchestration      |
+| `example-document-grounding.ts`     | Document grounding (RAG)    | Vector store, retrieval-augmented gen    |
+| `example-translation.ts`            | Input/output translation    | Multi-language support, SAP translation  |
+| `example-embeddings.ts`             | Text embeddings             | Vector generation, semantic similarity   |
+| `example-foundation-models.ts`      | Foundation Models API       | Direct model access, logprobs, seed      |
 
 **Running Examples:**
 
@@ -771,8 +778,8 @@ See [Installation](#installation) for other AI SDK versions.
 npx tsx examples/example-generate-text.ts
 ```
 
-> **Note:** Examples require `AICORE_SERVICE_KEY` environment variable. See
-> [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
+> **Note:** Configure `AICORE_SERVICE_KEY` locally or bind the application to
+> SAP AI Core on SAP BTP. See [Environment Setup](./ENVIRONMENT_SETUP.md).
 
 ## Migration Guides
 

package/dist/{chunk-JRUSQTKB.js → chunk-3H5C5U22.js}

@@ -1,13 +1,14 @@
 import {createRequire as __createRequire} from 'module';var require=__createRequire(import.meta.url);
 import {
   buildEmbeddingResult,
-  prepareEmbeddingCall
-} from "./chunk-AFZC2DH2.js";
+  mergeRequestConfig
+} from "./chunk-4JLNWASF.js";
 import {
   VERSION,
   convertToAISDKError,
-  deepMerge
-} from "./chunk-2KOXKYVT.js";
+  deepMerge,
+  getProviderName
+} from "./chunk-UIBQ5AFS.js";
 
 // src/base-embedding-model-strategy.ts
 import { TooManyEmbeddingValuesForCallError } from "@ai-sdk/provider";
@@ -24,10 +25,16 @@ var BaseEmbeddingModelStrategy = class {
   async doEmbed(config, settings, options, maxEmbeddingsPerCall) {
     const { abortSignal, values } = options;
     try {
-      const { embeddingOptions, providerName } = await prepareEmbeddingCall(
-        { maxEmbeddingsPerCall, modelId: config.modelId, provider: config.provider },
-        options
-      );
+      if (values.length > maxEmbeddingsPerCall) {
+        throw new TooManyEmbeddingValuesForCallError({
+          maxEmbeddingsPerCall,
+          modelId: config.modelId,
+          provider: config.provider,
+          values
+        });
+      }
+      const embeddingOptions = config.parsedProviderOptions;
+      const providerName = getProviderName(config.provider);
       const embeddingType = embeddingOptions?.type ?? settings.type ?? "text";
       const warnings = [];
       this.resolveWarnings(settings, warnings);
@@ -36,8 +43,7 @@ var BaseEmbeddingModelStrategy = class {
         client,
         values,
         embeddingType,
-        abortSignal,
-        config.requestConfig
+        mergeRequestConfig(config.requestConfig, abortSignal, options.headers)
       );
       const embeddings = this.extractEmbeddings(response);
       const totalTokens = this.extractTokenCount(response);
@@ -57,6 +63,8 @@ var BaseEmbeddingModelStrategy = class {
         throw error;
       }
       throw convertToAISDKError(error, {
+        modelId: config.modelId,
+        modelType: "embeddingModel",
         operation: "doEmbed",
         requestBody: { values: values.length },
         url: this.getUrl()
@@ -96,4 +104,4 @@ var BaseEmbeddingModelStrategy = class {
 export {
   BaseEmbeddingModelStrategy
 };
-//# sourceMappingURL=chunk-JRUSQTKB.js.map
+//# sourceMappingURL=chunk-3H5C5U22.js.map

package/dist/chunk-3H5C5U22.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base-embedding-model-strategy.ts"],"sourcesContent":["/** Base class for embedding model strategies using the Template Method pattern. */\nimport type {\n  EmbeddingModelV3CallOptions,\n  EmbeddingModelV3Embedding,\n  EmbeddingModelV3Result,\n  SharedV3Warning,\n} from \"@ai-sdk/provider\";\nimport type { CustomRequestConfig } from \"@sap-ai-sdk/core\";\n\nimport { TooManyEmbeddingValuesForCallError } from \"@ai-sdk/provider\";\n\nimport type { SAPAIEmbeddingSettings } from \"./sap-ai-settings.js\";\nimport type { EmbeddingModelAPIStrategy, EmbeddingModelStrategyConfig } from \"./sap-ai-strategy.js\";\n\nimport { deepMerge } from \"./deep-merge.js\";\nimport { convertToAISDKError } from \"./sap-ai-error.js\";\nimport { getProviderName } from \"./sap-ai-provider-options.js\";\nimport {\n  buildEmbeddingResult,\n  type EmbeddingProviderOptions,\n  type EmbeddingType,\n  mergeRequestConfig,\n  type ResponseMetadata,\n} from \"./strategy-utils.js\";\nimport { VERSION } from \"./version.js\";\n\n/**\n * Abstract base class for embedding model strategies using the Template Method pattern.\n * @template TClient - The SDK client type (e.g., AzureOpenAiEmbeddingClient, OrchestrationEmbeddingClient).\n * @template TResponse - The API response type from the SDK client.\n * @internal\n */\nexport abstract class BaseEmbeddingModelStrategy<\n  TClient,\n  TResponse,\n> implements EmbeddingModelAPIStrategy {\n  /**\n   * Template method implementing the shared embedding algorithm.\n   * @param config - Strategy configuration.\n   * @param settings - Embedding model settings.\n   * @param options - AI SDK call options.\n   * @param maxEmbeddingsPerCall - Maximum embeddings per call.\n   * @returns Complete embedding result for AI SDK.\n   * @internal\n   */\n  async doEmbed(\n    config: EmbeddingModelStrategyConfig,\n    settings: SAPAIEmbeddingSettings,\n    options: EmbeddingModelV3CallOptions,\n    maxEmbeddingsPerCall: number,\n  ): Promise<EmbeddingModelV3Result> {\n    const { abortSignal, values } = options;\n\n    try {\n      if (values.length > maxEmbeddingsPerCall) {\n        throw new TooManyEmbeddingValuesForCallError({\n          maxEmbeddingsPerCall,\n          modelId: config.modelId,\n          provider: config.provider,\n          values,\n        });\n      }\n      const embeddingOptions = config.parsedProviderOptions;\n      const providerName = getProviderName(config.provider);\n\n      const embeddingType = embeddingOptions?.type ?? settings.type ?? \"text\";\n\n      const warnings: SharedV3Warning[] = [];\n      this.resolveWarnings(settings, warnings);\n\n      const client = this.createClient(config, settings, embeddingOptions);\n\n      const response = await this.executeCall(\n        client,\n        values,\n        embeddingType,\n        mergeRequestConfig(config.requestConfig, abortSignal, options.headers),\n      );\n\n      const embeddings = this.extractEmbeddings(response);\n      const totalTokens = this.extractTokenCount(response);\n      const { headers: responseHeaders, requestId } = this.extractResponseMetadata(response);\n\n      return buildEmbeddingResult({\n        embeddings,\n        modelId: config.modelId,\n        providerName,\n        requestId,\n        responseHeaders,\n        totalTokens,\n        version: VERSION,\n        warnings,\n      });\n    } catch (error) {\n      if (error instanceof TooManyEmbeddingValuesForCallError) {\n        throw error;\n      }\n      throw convertToAISDKError(error, {\n        modelId: config.modelId,\n        modelType: \"embeddingModel\",\n        operation: \"doEmbed\",\n        requestBody: { values: values.length },\n        url: this.getUrl(),\n      });\n    }\n  }\n\n  /**\n   * Creates the appropriate SDK client for this API.\n   * @param config - Strategy configuration.\n   * @param settings - Embedding model settings.\n   * @param embeddingOptions - Parsed provider options from the call.\n   * @returns SDK client instance.\n   * @internal\n   */\n  protected abstract createClient(\n    config: EmbeddingModelStrategyConfig,\n    settings: SAPAIEmbeddingSettings,\n    embeddingOptions: EmbeddingProviderOptions | undefined,\n  ): TClient;\n\n  /**\n   * Executes the embedding API call.\n   * @param client - SDK client instance.\n   * @param values - Input strings to embed.\n   * @param embeddingType - Type of embedding (text, query, document).\n   * @param requestConfig - Request configuration with merged headers and abort signal.\n   * @returns SDK response containing embeddings.\n   * @internal\n   */\n  protected abstract executeCall(\n    client: TClient,\n    values: string[],\n    embeddingType: EmbeddingType,\n    requestConfig: CustomRequestConfig | undefined,\n  ): Promise<TResponse>;\n\n  /**\n   * Extracts embeddings from the SDK response.\n   * @param response - SDK response containing embedding data.\n   * @returns Array of normalized embedding vectors.\n   * @internal\n   */\n  protected abstract extractEmbeddings(response: TResponse): EmbeddingModelV3Embedding[];\n\n  /**\n   * Extracts response metadata (request id and HTTP headers) from the SDK response.\n   *\n   * Default returns both fields as `undefined`; subclasses override to extract from the SDK response.\n   * @param _response - SDK response.\n   * @returns Combined `{ headers, requestId }` metadata.\n   * @internal\n   */\n  protected extractResponseMetadata(_response: TResponse): ResponseMetadata {\n    return { headers: undefined, requestId: undefined };\n  }\n\n  /**\n   * Extracts total token count from the SDK response.\n   * @param response - SDK response containing usage data.\n   * @returns Total token count used for the embedding request.\n   * @internal\n   */\n  protected abstract extractTokenCount(response: TResponse): number;\n\n  /**\n   * Returns the URL identifier for this API (used in error messages).\n   * @returns URL string identifier.\n   * @internal\n   */\n  protected abstract getUrl(): string;\n\n  protected mergeModelParams(\n    settings: SAPAIEmbeddingSettings,\n    embeddingOptions: EmbeddingProviderOptions | undefined,\n  ): Record<string, unknown> {\n    return deepMerge(\n      (settings.modelParams as Record<string, unknown> | undefined) ?? {},\n      embeddingOptions?.modelParams ?? {},\n    );\n  }\n\n  /**\n   * Pushes API-specific deprecation or migration warnings into the shared\n   * sink. Default no-op; subclasses override to surface settings-level\n   * warnings (e.g. orchestration's masking_providers deprecation).\n   * @param _settings - Embedding model settings.\n   * @param _warnings - Shared warnings sink for the current call.\n   * @internal\n   */\n  protected resolveWarnings(_settings: SAPAIEmbeddingSettings, _warnings: SharedV3Warning[]): void {\n    return;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AASA,SAAS,0CAA0C;AAuB5C,IAAe,6BAAf,MAGgC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUrC,MAAM,QACJ,QACA,UACA,SACA,sBACiC;AACjC,UAAM,EAAE,aAAa,OAAO,IAAI;AAEhC,QAAI;AACF,UAAI,OAAO,SAAS,sBAAsB;AACxC,cAAM,IAAI,mCAAmC;AAAA,UAC3C;AAAA,UACA,SAAS,OAAO;AAAA,UAChB,UAAU,OAAO;AAAA,UACjB;AAAA,QACF,CAAC;AAAA,MACH;AACA,YAAM,mBAAmB,OAAO;AAChC,YAAM,eAAe,gBAAgB,OAAO,QAAQ;AAEpD,YAAM,gBAAgB,kBAAkB,QAAQ,SAAS,QAAQ;AAEjE,YAAM,WAA8B,CAAC;AACrC,WAAK,gBAAgB,UAAU,QAAQ;AAEvC,YAAM,SAAS,KAAK,aAAa,QAAQ,UAAU,gBAAgB;AAEnE,YAAM,WAAW,MAAM,KAAK;AAAA,QAC1B;AAAA,QACA;AAAA,QACA;AAAA,QACA,mBAAmB,OAAO,eAAe,aAAa,QAAQ,OAAO;AAAA,MACvE;AAEA,YAAM,aAAa,KAAK,kBAAkB,QAAQ;AAClD,YAAM,cAAc,KAAK,kBAAkB,QAAQ;AACnD,YAAM,EAAE,SAAS,iBAAiB,UAAU,IAAI,KAAK,wBAAwB,QAAQ;AAErF,aAAO,qBAAqB;AAAA,QAC1B;AAAA,QACA,SAAS,OAAO;AAAA,QAChB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,SAAS;AAAA,QACT;AAAA,MACF,CAAC;AAAA,IACH,SAAS,OAAO;AACd,UAAI,iBAAiB,oCAAoC;AACvD,cAAM;AAAA,MACR;AACA,YAAM,oBAAoB,OAAO;AAAA,QAC/B,SAAS,OAAO;AAAA,QAChB,WAAW;AAAA,QACX,WAAW;AAAA,QACX,aAAa,EAAE,QAAQ,OAAO,OAAO;AAAA,QACrC,KAAK,KAAK,OAAO;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgDU,wBAAwB,WAAwC;AACxE,WAAO,EAAE,SAAS,QAAW,WAAW,OAAU;AAAA,EACpD;AAAA,EAiBU,iBACR,UACA,kBACyB;AACzB,WAAO;AAAA,MACJ,SAAS,eAAuD,CAAC;AAAA,MAClE,kBAAkB,eAAe,CAAC;AAAA,IACpC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUU,gBAAgB,WAAmC,WAAoC;AAC/F;AAAA,EACF;AACF;","names":[]}