v4.6.1 - Code Quality Improvements

Release Date: 2026-03-22
Type: Patch - Code Quality Improvements

---

Summary

Internal code consolidation: extract shared SDK types and helpers to eliminate duplication between doGenerate/doStream paths, embedding strategies, and V3→V2 adapters. Fix erroneous @internal tag on public type. Strengthen ESLint unused-vars configuration.

Quality: 1117/1117 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.6.1
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.6.1

---

Refactoring

Shared SDK Types

• refactor(types): Extract SDKTokenUsage, SDKCitation, SDKToolCall, SDKDeltaToolCall named interfaces
  • Replace inline type definitions repeated across SDKResponse, StreamCallResponse, StreamTransformerConfig, and orchestration casts
  • Single source of truth prevents silent type divergence

Token Usage Mapping

• refactor(usage): Extract mapTokenUsage() shared helper
  • Deduplicate identical token usage mapping between buildGenerateResult() (doGenerate) and createStreamTransformer flush (doStream)
  • Pairs with existing mapFinishReason() pattern

Embedding Strategy

• refactor(embedding): Lift mergeModelParams() into BaseEmbeddingModelStrategy
  • Identical deepMerge(settings.modelParams, embeddingOptions.modelParams) pattern was duplicated in both concrete strategies

V3→V2 Adapter

• refactor(adapter): Extract withProviderMetadata() helper in convertStreamPartToV2()
  • Replaces 14 identical conditional metadata spread blocks with a single reusable function

Type Safety

• refactor(types): Strengthen SAPToolParameters type with properties and required fields
  • Type now reflects the actual runtime shape returned by buildSAPToolParameters()

---

Bug Fixes

Public API

• fix(types): Remove erroneous @internal tag from DeploymentConfig type
  • DeploymentConfig is exported in both index.ts and index-v2.ts and documented in API_REFERENCE.md

---

Internal

ESLint Configuration

• chore(lint): Configure no-unused-vars to respect _ prefix convention
  • Uses typescript-eslint recommended configuration (argsIgnorePattern, varsIgnorePattern, caughtErrorsIgnorePattern, destructuredArrayIgnorePattern)
  • Removes 7 redundant eslint-disable comments across strategy files

Markdown Linting

• chore(lint): Add .sisyphus/ to markdownlint ignores

---

Dependency Updates

• chore(deps): Update markdownlint-cli2 to ^0.22.0 (#72)
• chore: Lock file maintenance

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors, 0 warnings
• ✅ Tests: 1117/1117 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.6.1 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.6.1 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.6.0...v4.6.1

v4.6.0 - New Features & Improvements

Release Date: 2026-03-21
Type: Minor - New Features & Improvements

---

Summary

Leverages SAP AI SDK v2.9.0 features: source citations in responses, non-image file inputs in messages, token usage details (cached/reasoning tokens), and intermediate failure tracking. Also migrates markdown linting to markdownlint-cli2.

Quality: 1117/1117 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.6.0
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.6.0

---

Features

Source Attribution

• feat(orchestration): Map getCitations() to LanguageModelV3Source content items
  • Citations from Perplexity Sonar models appear as { type: "source", sourceType: "url" } in both doGenerate content array and doStream source events
  • Emitted before finish event in streaming responses

Message Content

• feat(messages): Support non-image file content parts via SAP SDK FileContent type
  • PDF, audio, and other file types mapped to { type: "file", file: { file_data } }
  • Image files continue routing through the existing image_url path
  • Supports base64 data URLs, HTTP URLs, and binary data

Response Metadata

• feat(orchestration): Expose getIntermediateFailures() in providerMetadata
  • Reports errors from fallback retries when using OrchestrationModuleConfigList
  • Conditionally present only when failures occurred

Usage Details

• feat(usage): Map token usage details from SAP SDK to Vercel AI SDK usage fields
  • prompt_tokens_details.cached_tokens → usage.inputTokens.cacheRead
  • completion_tokens_details.reasoning_tokens → usage.outputTokens.reasoning
  • noCache and text adjusted when details are available
  • Works for both orchestration and foundation-models APIs

Type Exports

• feat(types): Re-export 8 new types from @sap-ai-sdk/orchestration
  • ChatMessages, ChatMessageContent, UserChatMessageContent, UserChatMessageContentItem
  • Citation, FileContent, ImageContentUrl
  • OrchestrationError

---

Improvements

Lint Pipeline

• chore(lint): Migrate from markdownlint-cli to markdownlint-cli2
  • Single config file .markdownlint-cli2.jsonc (rules + ignores)
  • Replaces .markdownlintrc and .markdownlintignore

---

Documentation

• Updated API reference with new re-exported types (8 types across 3 new categories)
• Documented intermediateFailures field in providerMetadata tables (doGenerate + doStream)
• Updated convertToSAPMessages() description to include file content support

---

Internal

• chore: Update openspec skills

---

Dependency Updates

• fix(deps): Update @ai-sdk/provider-utils to ^4.0.21 (#59, #68)
• fix(deps): Update @sap-ai-sdk/orchestration to ^2.9.0 (#68)
• fix(deps): Update @sap-ai-sdk/foundation-models to ^2.9.0 (#68)
• chore(deps): Update eslint to ^10.1.0 (#61, #68)
• chore(deps): Update eslint-plugin-perfectionist to ^5.7.0 (#67)
• chore(deps): Update typescript-eslint to ^8.57.1 (#66)
• chore(deps): Update @types/node to ^25.3.5 (#60)
• chore(deps): Update all non-major dependencies (#63, #64)
• chore: Lock file maintenance (#62, #65)

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1117/1117 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.6.0 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.6.0 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.5.0...v4.6.0

v4.5.0 - New Features & Improvements

Release Date: 2026-03-04
Type: Minor - New Features & Improvements

---

Summary

Streaming enhancements with request ID exposure, response headers, and server-provided completion IDs. New orchestration prompt module fallback configuration. Internal refactor to TransformStream pattern for stream transformation. Comprehensive documentation audit and fixes.

Quality: 1103/1103 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.5.0
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.5.0

---

Features

Streaming Enhancements

• feat(streaming): Expose requestId in streaming responses via rawResponse headers
  • Available through providerMetadata on stream results for tracing and debugging
• feat(streaming): Expose response headers in doStream result
  • Headers from the initial SSE connection are now available for debugging and correlation
• feat(streaming): Use server-provided completion ID for response.id
  • Replaces generated UUIDs with actual completion IDs from the SAP AI Core response

Orchestration Configuration

• feat(orchestration): Support prompt module fallback configuration via OrchestrationModuleConfigList
  • Enables fallback model configuration when referencing stored orchestration configs

---

Improvements

Lint Pipeline

• feat(tooling): Add sibling consistency validation to TOC checker
  • Detects missing ToC entries when sibling headings are present
  • Runs as part of npm run lint pipeline

Performance

• perf(lint): Enable caching for ESLint and Prettier
  • Reduces repeated lint/format check times

---

Refactoring

Code Architecture

• refactor(streaming): Replace manual iterator-based stream transformation with standard TransformStream API
  • Cleaner separation of concerns between stream reading and writing
  • Better alignment with Web Streams API standards
• refactor(streaming): Remove unreachable code in Foundation Models stream path

Code Quality

• refactor(comments): Tighten all code comments to describe current state, not change history
• refactor(test): Harmonize test organization across all TOC checker functions with nested describe blocks
• refactor(scripts): Improve prepare-v2-package with generics and cleaner structure

---

Documentation

• Comprehensive documentation audit: fixed 12 issues across 7 files
• Fixed broken anchors, missing ToC entries, and outdated build output lists
• Updated API signatures, documented providerMetadata, and corrected streaming limitation descriptions
• Fixed cross-file anchor links in TROUBLESHOOTING.md
• Harmonized embedding method aliases documentation
• Fixed incorrect processResponse method in architecture template pattern example
• Added missing ToC entries detected by sibling consistency validation
• Improved documentation coherence and added missing error sections

---

Internal

• chore(test): Refine code coverage thresholds

---

Dependency Updates

• chore(deps): Bump @sap-ai-sdk/foundation-models and @sap-ai-sdk/orchestration to 2.8.0
• fix(deps): Update @ai-sdk/provider-utils to ^4.0.17 (#58)
• chore(deps): Update all non-major dependencies (#52, #53, #55, #56)
• chore(deps): Update @types/node to ^25.3.1 (#54)
• chore: Lock file maintenance (#51, #57)

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1103/1103 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.5.0 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.5.0 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.18...v4.5.0

v4.4.18 - Bug Fixes

Release Date: 2026-02-21
Type: Patch - Bug Fixes

---

Summary

Fixed false positive circular reference detection in deepMerge when objects appear in multiple locations.

Quality: 1042/1042 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.18
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.18

---

Bug Fixes

DeepMerge Utility

• fix(deep-merge): Use ancestor tracking to prevent false circular reference detection
  • Changed from WeakSet to Set with proper ancestor tracking pattern
  • Objects are now removed from the tracking set after recursion completes
  • Fixes handling of diamond patterns (same object referenced from multiple paths)
  • Fixes handling of shared configuration objects in target and source

---

Testing

New Test Coverage

• test(deep-merge): Add regression tests for nested cloning (4 tests)
  • Verify deep cloning prevents mutation of target objects during merge
• test(deep-merge): Add regression tests for shared object handling (5 tests)
  • Verify correct behavior for diamond patterns, repeated references, and actual circular reference detection

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1042/1042 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.18 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.18 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.17...v4.4.18

v4.4.17 - Bug Fixes & Improvements

Release Date: 2026-02-21
Type: Patch - Bug Fixes & Improvements

---

Summary

Thread safety and validation improvements for embedding strategies and provider factories.

Quality: 1033/1033 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.17
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.17

---

Bug Fixes

Embedding Strategy

• Thread-safe embedding strategy: Fixed potential race condition in embedding model strategy instantiation
• Fallback defaults in deepMerge: Added safe fallback values when merging undefined sources

DeepMerge Utility

• Circular reference detection: Fixed infinite loop risk when merging objects with circular references

---

Improvements

Validation

• Provider factory validation: Added modelParams validation in createModel() and createEmbeddingModel() for both V3 and V2 providers

Documentation

• JSDoc consistency: Improved existing JSDoc comments consistency across codebase

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1033/1033 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.17 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.17 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.16...v4.4.17

v4.4.16 - Code Quality Improvements

Release Date: 2026-02-21
Type: Patch - Code Quality Improvements

---

Summary

Test suite refactoring with it.each pattern adoption, new tests for complete error class coverage, and comprehensive documentation fixes.

Quality: 1033/1033 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.16
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.16

---

Testing

Test Suite Refactoring

• refactor(test): Apply it.each pattern across all test files for improved readability
  • Reduces test code by ~370 lines while preserving coverage
  • Harmonizes test structure with data-driven approach
  • Applied to: validation, provider, options, embedding, adapters, error, and strategy tests

New Test Coverage

• test: Add missing error class tests for ApiSwitchError, UnsupportedFeatureError, normalizeHeaders
  • Complete coverage for all custom error classes
  • Harmonized terminology across test suites

---

Documentation

Documentation Quality

• docs: Fix documentation quality issues across multiple files
• docs(architecture): Fix inaccuracies and add missing V2 facade files
• docs(readme): Add complete provider methods reference table
• docs(examples): Fix missing import and harmonize output format
• docs(.github): Fix copilot-instructions accuracy, add build:watch command
• docs(.cursor/rules): Fix documentation accuracy issues
• docs(MIGRATION_GUIDE): Fix markdown table formatting

---

Refactoring

Embedding Strategy

• feat(embedding): Add BaseEmbeddingModelStrategy abstract base class
• refactor(embedding): Strategies extend base class (FM + Orchestration)
• style(embedding): Harmonize JSDoc and type alias naming with language model strategies
• fix(embedding): Remove unused getModelId, add FM index sorting

---

Dependencies

• chore(deps): Update ESLint monorepo to v10
• chore(deps): Update AJV to 6.14.0
• chore(deps): Update @types/node to ^25.3.0
• chore(deps): Update eslint and eslint-plugin-jsdoc
• chore: Lock file maintenance

---

Internal

• chore(exports): Add BaseEmbeddingModelStrategy to index
• fix: Apply linter and formatting fixes from code quality review
• chore: Remove .sisyphus/ from git tracking

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1033/1033 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.16 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.16 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.15...v4.4.16

v4.4.15 - Bug Fixes

Release Date: 2026-02-19
Type: Patch - Bug Fixes

---

Summary

Fixes empty assistant messages being sent to SAP AI Core API and improves Mermaid diagram compatibility for GitHub rendering.

Quality: 1011/1011 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.15
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.15

---

Bug Fixes

Empty Assistant Messages

• fix(messages): Filter empty assistant message parts before sending to SAP AI Core API
  • Prevents API errors from empty content in assistant messages
  • Filters out messages with no meaningful content

Mermaid Diagram Compatibility

• fix(docs): Escape special characters in Mermaid diagrams for GitHub rendering
• fix(docs): Simplify SDK labels for GitHub Mermaid compatibility

---

Improvements

Lint Pipeline

• chore(lint): Add mermaid validation to catch diagram issues early
  • New mermaid-validate dependency for CI validation

---

Internal

• refactor(build): Remove outDir from tsup V2 configuration

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1011/1011 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.15 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.15 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.14...v4.4.15

v4.4.14 - Bug Fixes

Release Date: 2026-02-18
Type: Patch - Bug Fixes

---

Summary

Fixes ESM bundle crash in pure ESM contexts ("type": "module") where bundled CJS dependencies call require() on Node.js built-ins.

Quality: 1011/1011 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.14
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.14

---

Bug Fixes

ESM Bundle Compatibility

• fix(build): Polyfill require() for ESM bundles (#47)
  • Injects createRequire polyfill via tsup banner for ESM format
  • Resolves "Dynamic require of 'util' is not supported" crash
  • Bundled CJS dependencies (winston, logform, @colors/colors) now work in pure ESM contexts

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1011/1011 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.14 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.14 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.13...v4.4.14

v4.4.13 - Bug Fixes & Improvements

Release Date: 2026-02-18
Type: Patch - Bug Fixes & Improvements

---

Summary

Fixes V2 package publishing incorrect V3 code by using AI_SDK_VERSION environment variable to branch build paths.

Quality: 1011/1011 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.13
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.13

---

Bug Fixes

V2 Package Publishing

• fix(ci): Fixed V2 package incorrectly publishing V3 code
  • prepublishOnly now branches based on AI_SDK_VERSION env var
  • Removed redundant build steps from publish jobs (prepublishOnly handles it)
  • V2 publish sets AI_SDK_VERSION=v2 to trigger V2 build path

---

Improvements

Workflow Consistency

• CI: Added explicit setup-node step to format-check job for consistency with other jobs

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1011/1011 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.13 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.13 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.12...v4.4.13

v4.4.12 - New Features & Dual Publishing

Release Date: 2026-02-18
Type: Patch - New Features

---

Summary

Introduces dual-package publishing workflow enabling simultaneous release of V3 and V2 packages from a single release tag.

Quality: 1011/1011 tests passing | All quality gates passed

Installation:

• V3: npm install @jerome-benoit/sap-ai-provider@4.4.12
• V2: npm install @jerome-benoit/sap-ai-provider-v2@4.4.12

---

Features

Dual-Package Publishing

• New Publishing Workflow: Added dual-package publishing for V2 and V3 (#49)
  • Single release tag triggers both package publishes
  • V3 package: @jerome-benoit/sap-ai-provider (LanguageModelV3/EmbeddingModelV3)
  • V2 package: @jerome-benoit/sap-ai-provider-v2 (LanguageModelV2/EmbeddingModelV2)
  • Both packages share the same version number

---

Dependency Updates

• Updated typescript-eslint to ^8.56.0 (#48)
• Updated typescript-eslint to ^8.55.0 (#42)
• Updated all non-major dependencies (#43, #44, #45)
• Lock file maintenance (#46)

---

Quality Assurance

• ✅ TypeScript strict mode: 0 errors
• ✅ ESLint: 0 errors
• ✅ Tests: 1011/1011 passing (100%)
• ✅ Build V3: ESM + CJS + DTS verified
• ✅ Build V2: ESM + CJS + DTS verified
• ✅ Node.js + Edge runtime tests passing

---

Installation

# V3 Package (LanguageModelV3/EmbeddingModelV3)
npm install @jerome-benoit/sap-ai-provider@^4.4.12 ai

# V2 Package (LanguageModelV2/EmbeddingModelV2)
npm install @jerome-benoit/sap-ai-provider-v2@^4.4.12 ai

Compatibility: Node.js 20+, AI SDK 5.0+ / 6.0+

---

Full Changelog: v4.4.11...v4.4.12