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

package/README.md

@@ -46,6 +46,7 @@ SAP's enterprise-grade AI models through the familiar Vercel AI SDK interface.
 - [Debug Mode](#debug-mode)
 - [Examples](#examples)
 - [Migration Guides](#migration-guides)
+  - [Upgrading from v4.x to v5.x](#upgrading-from-v4x-to-v5x)
   - [Upgrading from v3.x to v4.x](#upgrading-from-v3x-to-v4x)
   - [Upgrading from v2.x to v3.x](#upgrading-from-v2x-to-v3x)
   - [Upgrading from v1.x to v2.x](#upgrading-from-v1x-to-v2x)
@@ -82,7 +83,7 @@ SAP's enterprise-grade AI models through the familiar Vercel AI SDK interface.
 ## Quick Start
 
 ```bash
-npm install @jerome-benoit/sap-ai-provider ai@^6
+npm install @jerome-benoit/sap-ai-provider ai@^6 dotenv
 ```
 
 ```typescript
@@ -125,7 +126,7 @@ try {
 | **Text Generation** | `generateText({ model: provider("gpt-4.1"), prompt })`           | [Basic Usage](#text-generation)                               |
 | **Streaming**       | `streamText({ model: provider("gpt-4.1"), prompt })`             | [Streaming](#streaming-responses)                             |
 | **Tool Calling**    | `generateText({ tools: { myTool: tool({...}) } })`               | [Tool Calling](#tool-calling)                                 |
-| **Error Handling**  | `catch (error instanceof APICallError)`                          | [API Reference](./API_REFERENCE.md#error-handling--reference) |
+| **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)                           |
 | **Embeddings**      | `embed({ model: provider.embedding("text-embedding-3-small") })` | [Embeddings](#embeddings)                                     |
 
@@ -134,6 +135,11 @@ try {
 **Requirements:** Node.js 22.12+. The provider entrypoint must match the installed
 AI SDK major.
 
+The published package targets Node.js. Its ESM output uses Node
+`module.createRequire`, and the SAP SDK dependency chain relies on Node APIs.
+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` |
@@ -269,7 +275,7 @@ The provider is callable and also exposes explicit methods:
 const chatModel = provider("gpt-4.1");
 
 // Explicit method syntax
-const chatModel = provider.chat("gpt-4.1");
+const explicitChatModel = provider.chat("gpt-4.1");
 const embeddingModel = provider.embedding("text-embedding-3-small");
 ```
 
@@ -350,20 +356,26 @@ import { streamText } from "ai";
 import { APICallError } from "@ai-sdk/provider";
 
 try {
+  let streamError: unknown;
   const result = streamText({
     model: provider("gpt-4.1"),
     prompt: "Explain machine learning concepts.",
+    onError({ error }) {
+      streamError = error;
+    },
   });
 
   for await (const delta of result.textStream) {
     process.stdout.write(delta);
   }
 
-  // Await final result to catch any errors that occurred during streaming
-  const finalResult = await result;
-  console.log("\n\nUsage:", finalResult.usage);
+  // textStream does not throw stream errors; preserve the original API error.
+  if (streamError !== undefined) throw streamError;
+
+  // streamText returns a result object; its usage property is a promise.
+  console.log("\n\nUsage:", await result.usage);
 } catch (error) {
-  if (error instanceof APICallError) {
+  if (APICallError.isInstance(error)) {
     console.error("API Error:", error.message);
     // See Error Handling section for complete error type reference
   }
@@ -621,7 +633,10 @@ const model = provider("gpt-4.1");
 ### Provider Options (Per-Call Overrides)
 
 Override constructor settings on a per-call basis using `providerOptions`.
-Options are validated at runtime with Zod schemas.
+Only the documented per-call fields are supported: unknown top-level fields
+are stripped by the Zod schemas, while additional `modelParams` keys pass
+through. Standard AI SDK generation options (for example, `temperature`) take
+precedence over the corresponding `providerOptions` model parameters.
 
 ```typescript
 import { generateText } from "ai";
@@ -654,8 +669,8 @@ authentication, model parameters, data masking, content filtering, and more.
 
 **Common Configuration:**
 
-- `name`: Provider name (default: `'sap-ai'`). Used as key in
-  `providerOptions`/`providerMetadata`.
+- `name`: Provider identifier prefix (default: `'sap-ai'`). The segment before
+  the first dot is used as the key in `providerOptions`/`providerMetadata`.
 - `resourceGroup`: SAP AI Core resource group (default: 'default')
 - `deploymentId`: Specific deployment ID (auto-resolved if not set)
 - `requestConfig`: Custom HTTP request configuration (headers, params, timeout, etc.)
@@ -690,7 +705,9 @@ error handling across providers.
 
 - **Authentication (401)**: Check `AICORE_SERVICE_KEY` or `VCAP_SERVICES`
 - **Model not found (404)**: Confirm tenant/region supports the model ID
-- **Rate limit (429)**: Automatic retry with exponential backoff
+- **Rate limit (429)**: High-level AI SDK calls retry eligible errors with
+  exponential backoff, bounded by `maxRetries`; direct provider calls do not
+  implement retries
 - **Streaming**: Iterate `textStream` correctly; don't mix `generateText` and
   `streamText`
 
@@ -704,10 +721,10 @@ streaming, and tool calling.
 ## Performance
 
 - Prefer streaming (`streamText`) for long outputs to reduce latency and memory.
-- Tune `modelParams` carefully: lower `temperature` for deterministic results;
+- Tune `modelParams` carefully: lower `temperature` for less variable results;
   set `maxTokens` to expected response size.
-- Use `defaultSettings` at provider creation for shared knobs across models to
-  avoid per-call overhead.
+- Use `defaultSettings` at provider creation to share configuration across models;
+  settings are still merged and validated when models and calls are prepared.
 - Avoid unnecessary history: keep `messages` concise to reduce prompt size and
   cost.
 
@@ -759,6 +776,24 @@ npx tsx examples/example-generate-text.ts
 
 ## Migration Guides
 
+### Upgrading from v4.x to v5.x
+
+Version 5.0 adds **AI SDK 7** support through the **V4** facade and requires
+**Node.js 22.12 or newer** for both packages. The root entrypoint remains
+**V3 for AI SDK 6**; upgrading the provider does not require switching SDKs.
+
+**Key changes:**
+
+- **Runtime**: Upgrade local, CI and deployment environments from Node.js 20
+  to Node.js 22.12 or newer.
+- **Entrypoints**: Use `/v4` with SDK 7, the root with SDK 6, or `/v2` with
+  SDK 5. The standalone V2 package remains available for SDK 5/6.
+- **Multimodal inputs**: V4 tagged JPEG/PDF inputs are normalized correctly;
+  unsupported binary objects are rejected instead of silently stringified.
+
+See the [4.x to 5.x migration guide](./MIGRATION_GUIDE.md#version-4x-to-5x-breaking-changes)
+for installation commands, compatibility details and the migration checklist.
+
 ### Upgrading from v3.x to v4.x
 
 Version 4.0 migrates from **LanguageModelV2** to **LanguageModelV3**
@@ -796,7 +831,7 @@ complete upgrade instructions.**
 
 - `SAPAIError` removed → Use `APICallError` from `@ai-sdk/provider`
 - Error properties: `error.code` → `error.statusCode`
-- Automatic retries for rate limits (429) and server errors (5xx)
+- Retryable error classification for the AI SDK's rate-limit/server-error retries
 
 ### Upgrading from v1.x to v2.x
 
@@ -830,7 +865,7 @@ for details.
 ### Documentation
 
 - [Migration Guide](./MIGRATION_GUIDE.md) - Version upgrade instructions (v1.x →
-  v2.x → v3.x → v4.x)
+  v2.x → v3.x → v4.x → v5.x)
 - [API Reference](./API_REFERENCE.md) - Complete API documentation with all
   types and functions
 - [Environment Setup](./ENVIRONMENT_SETUP.md) - Authentication and configuration

package/dist/{chunk-BIBSYTMU.js → chunk-2KOXKYVT.js}

@@ -30642,15 +30642,13 @@ var UnsupportedFeatureError = class extends Error {
   /**
    * Creates a new UnsupportedFeatureError.
    * @param feature - The name of the unsupported feature (e.g., "Content filtering").
-   * @param api - The API being used where the feature will be ignored.
+   * @param api - The API being used that does not support the feature.
    * @param suggestedApi - The API that supports this feature.
    */
   constructor(feature, api, suggestedApi) {
     const apiName = api === "foundation-models" ? "Foundation Models" : "Orchestration";
     const suggestedApiName = suggestedApi === "foundation-models" ? "Foundation Models" : "Orchestration";
-    super(
-      `${feature} is only available with ${suggestedApiName} API and will be ignored by ${apiName} API.`
-    );
+    super(`${feature} is not supported by ${apiName} API. Use ${suggestedApiName} API instead.`);
     this.feature = feature;
     this.api = api;
     this.suggestedApi = suggestedApi;
@@ -30698,7 +30696,7 @@ Request ID: ${requestId}`;
   if (statusCode === HTTP_STATUS.RATE_LIMIT) {
     enhancedMessage += "\n\nRate limit exceeded. Please try again later or contact your SAP administrator.\nSee: https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/rate-limits";
   } else if (statusCode >= HTTP_STATUS.INTERNAL_ERROR) {
-    enhancedMessage += "\n\nSAP AI Core service error. This is typically a temporary issue. The request will be retried automatically.\nSee: https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/troubleshooting";
+    enhancedMessage += "\n\nSAP AI Core service error. This is typically a temporary issue. Retries depend on the caller's retry configuration.\nSee: https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/troubleshooting";
   } else if (location) {
     enhancedMessage += `
 
@@ -31028,7 +31026,7 @@ function tryExtractSAPErrorFromMessage(message) {
 }
 
 // src/version.ts
-var VERSION = true ? "5.0.0" : "0.0.0-test";
+var VERSION = true ? "5.0.1" : "0.0.0-test";
 
 export {
   __toESM,
@@ -31082,4 +31080,4 @@ mime-types/index.js:
 axios/dist/node/axios.cjs:
   (*! Axios v1.20.0 Copyright (c) 2026 Matt Zabriskie and contributors *)
 */
-//# sourceMappingURL=chunk-BIBSYTMU.js.map
+//# sourceMappingURL=chunk-2KOXKYVT.js.map