@fluentcommerce/fc-connect-sdk 0.1.52 → 0.1.53

package/CHANGELOG.md

@@ -1,506 +1,514 @@
-# Changelog
-
-All notable changes to the Fluent Commerce Connect SDK will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-_No unreleased changes_
-
-## [0.1.52] - 2026-02-15
-
-### Added - Event API Log Query (REST GET Endpoints)
-- Added `getEvents(params)` to `FluentClient` and `FluentVersoriClient` for `GET /api/v4.1/event`
-  - Search/query events with comprehensive filtering (entity type, status, date range, etc.)
-  - Supports pagination with `start`/`count` parameters (max 5000 per page)
-  - Full documentation with JSDoc examples for common use cases
-- Added `getEventById(eventId)` to `FluentClient` and `FluentVersoriClient` for `GET /api/v4.1/event/{eventId}`
-  - Retrieve complete event details by unique identifier
-  - Returns event metadata, context, attributes, and source event IDs
-  - Useful for event tracing and debugging workflows
-- Added typed Event Log models: `FluentEventQueryParams`, `FluentEventLogResponse`, `FluentEventLogItem`, `FluentEventLogContext`, and `FluentEventLogAttribute`
-- Added typed Event constants for query safety: `FluentEventType`, `FluentEventStatus`, `FluentEventCategory`, `FluentEventRootEntityType`, and `FluentEventEntityType`
-- Added unit test coverage for query-string building, empty-filter handling, success parsing, and error paths
-- Updated API docs with `getEvents()` and `getEventById()` usage examples
-
-### Added - Security & Compliance
-- **Security Audit Infrastructure** - Comprehensive security audit tools and scripts
-  - `security-audit/security-audit.cjs` - Automated vulnerability scanning
-  - `security-audit/safe-fix.cjs` - Safe vulnerability fixing with automatic testing
-  - `security-audit/snyk-setup.cjs` - Snyk integration for advanced scanning
-  - GitHub Actions workflow for automated security scans
-  - Dependabot configuration for automated dependency updates
-- **Security Documentation** - Complete security and compliance guides
-  - SOC 2 Compliance Guide
-  - Vulnerability Checking Guide
-  - Safe Fixing Guide
-  - Advanced Scanning Guide (Snyk)
-  - Security audit quick start
-- **Security Scripts** - NPM scripts for security management
-  - `npm run security:check` - Comprehensive security audit
-  - `npm run security:fix` - Safe vulnerability fixing
-  - `npm run security:snyk` - Advanced Snyk scanning
-  - `npm run security:full` - Full security check (npm audit + Snyk)
-
-### Fixed - Security Vulnerabilities
-- **js-yaml vulnerabilities** (MODERATE) - Updated to secure versions (3.14.2, 4.1.1)
-- **@versori/run** - Updated from 0.4.4 to 0.4.11 (includes security fixes)
-- **markdownlint-cli** (HIGH) - Updated from 0.45.0 to 0.46.0 (fixes glob command injection)
-- **Removed unused dependency** - Removed unused `jose@5.10.0` package
-- **Security Status:** Reduced vulnerabilities from 12 to 3 (75% reduction)
-  - Fixed: 2 Critical, 3 High, 4 Moderate, 1 Low
-  - Remaining: 3 Moderate (transitive dependencies, no fix available)
-
-## [0.1.51] - 2025-01-12
-
-### Added
-
-**GraphQL Partial Response Support**
-- **New error handling mode**: Added `errorHandling: 'partial'` option for `FluentClient.graphql()` and `ExtractionOrchestrator`
-  - Allows returning both `data` AND `errors` when GraphQL returns partial responses (GraphQL spec compliant)
-  - Default behavior unchanged: `'throw'` mode throws `GraphQLExecutionError` on any errors (backward compatible)
-  - Opt-in feature for scenarios where partial data is acceptable (batch operations, analytics, etc.)
-- **Response extensions**: Added `hasPartialData` flag to `GraphQLResponse` interface
-  - Set to `true` when response contains both data and errors
-  - Only present when `errorHandling: 'partial'` is used and errors occurred
-- **Error accumulation across pagination**: Partial mode accumulates errors from all pages
-  - All GraphQL errors collected in `response.errors` array for paginated queries
-  - ExtractionOrchestrator includes errors in `stats.partialErrors` field
-- **Null data handling**: ExtractionOrchestrator gracefully handles `data: null` with errors in partial mode
-  - Returns empty array `[]` instead of throwing
-  - Stops pagination when no data available (cannot determine if more pages exist)
-  - Errors still accumulated in `stats.partialErrors`
-  - Preserves backward compatibility: throw mode still throws original error messages
-
-**Use Cases:**
-- Batch mutations where some items may fail independently
-- Analytics/reporting where partial data is better than no data
-- Extraction workflows where some records may be inaccessible
-- Resilient data pipelines that continue despite errors
-
-**Usage Example:**
-```typescript
-// Partial mode: get both successful and failed results
-const result = await client.graphql({
-  query: batchMutation,
-  errorHandling: 'partial'  // Opt-in
-});
-
-if (result.hasPartialData) {
-  // Process successful items
-  processSuccessful(result.data);
-
-  // Log or retry failed items
-  for (const error of result.errors || []) {
-    logger.warn('Failed item:', error.path, error.message);
-  }
-}
-
-// Default mode (throw): fail fast on any error
-const criticalResult = await client.graphql({
-  query: singleMutation
-  // errorHandling: 'throw' is default
-});
-```
-
-**Documentation:**
-- Complete guide: `docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-partial-responses.md`
-- Best practices, migration guide, and edge case handling included
-- Integration examples with FluentClient, FluentVersoriClient, and ExtractionOrchestrator
-
-**Test Coverage:**
-- 9+ test scenarios in `tests/unit/fluent-client-partial-response.test.ts`
-- 5+ test scenarios in `tests/unit/services/extraction/extraction-orchestrator.test.ts` (including null data edge cases)
-- Edge cases: null data, empty errors array, error extensions, pagination, pagination stop on null data
-
-**Backward Compatibility:**
-- No breaking changes
-- Default behavior unchanged ('throw' mode)
-- Existing code continues to work without modifications
-
-## [0.1.48] - 2025-11-19
-
-### ⚠️ IMPORTANT - Share in Slack
-
-**Breaking Change in v0.1.47**: If you're using `httpStatus` from EventResponse, you must migrate to `statusCode`.
-
-```typescript
-// ❌ OLD (no longer works)
-const status = response.httpStatus;
-
-// ✅ NEW (v0.1.47+)
-const status = response.statusCode;
-```
-
-See v0.1.47 changelog below for full details.
-
-### Added
-- **FluentVersoriClient connection validation enhancements** - Improved error handling and connection validation for Versori platform
-- **Event API template documentation** - 8 new templates for S3/SFTP ingestion with CSV, XML, JSON, Parquet formats
-- **Connection validation pattern guide** - New documentation for Versori connection validation patterns
-- **README error classification documentation** - Added comprehensive code examples for `classifyError` and `classifyErrors` functions
-
-### Changed
-- **README updates** - Updated template count from 15+ to 23+, added Error Classification section to Core Services table
-- **Smart Error Handling documentation** - Added note about consistent `statusCode` field across success and error responses
-- **Error handling documentation improvements** - Added links to comprehensive error handling guide and quick reference
-
-### Fixed
-- **FluentVersoriClient improvements** - 206 lines of enhancements for better error handling and connection management
-
-## [0.1.47] - 2025-11-19
-
-### Changed
-- **BREAKING: EventResponse interface standardized on `statusCode`**
-  - Removed `httpStatus` field from EventResponse interface
-  - HTTP status code is now consistently available as `statusCode` in both success and error responses
-  - Success: `response.statusCode` (200, 201, 202)
-  - Error: `error.statusCode` (400, 401, 404, 500, etc.)
-  - Migration: Replace all `response.httpStatus` with `response.statusCode`
-
-### Fixed
-- **Auth retry tests** - Updated expected error type from FluentAPIError to AuthenticationError after exhausting retries
-- **Test timeouts** - Added proper timeout for retry delay tests
-
-## [0.1.46] - 2025-11-18
-
-### Changed
-- Documentation consolidation for error handling
-- Removed duplicate module files in error-handling docs
-- Added SDK automatic retry behavior clarification
-
-## [0.1.45] - 2025-11-17
-
-### Added
-- **XML Helper Exports** (2025-11-17)
-  - `getXmlAttribute` - Extract XML attributes from multiple parser formats (Versori $, SDK @, xml2js)
-  - `getXmlTextContent` - Extract XML text content from multiple formats (_, #text, value)
-  - `normalizeEmpty` - Normalize empty values (null, undefined, '', whitespace)
-  - All three helpers now exported from `@fluentcommerce/fc-connect-sdk`
-  - Comprehensive unit tests (19 tests) and inline JSDoc documentation
-
-### Changed
-- **Resolver Helper Improvements** (2025-11-17)
-  - SDK resolvers now use `helpers.getXmlTextContent` for XML text extraction
-  - Replaces manual format checking (`attr._ || attr['#text'] || attr.value`)
-  - Improves consistency across XML parser formats
-
-### Notes
-- These helpers were previously internal-only and are now part of the public API
-- No breaking changes - existing code continues to work
-- Maintains backward compatibility with all existing resolver implementations
-
-## [0.1.43] - 2025-01-14
-
-### Added
-
-**GraphQL Error Classification Service** (2025-01-14)
-- **New error classification utilities**: Added `classifyError()` and `classifyErrors()` functions to classify Fluent Commerce GraphQL errors
-- **Retry guidance**: Automatically determines if errors are retryable based on error codes (C/S/T prefix)
-- **User-friendly messages**: Provides actionable error messages and recommended actions
-- **Error code support**: Handles Fluent Commerce error codes (C0121E, S0002E, etc.) with proper classification
-- **Export location**: Available via `import { classifyError, classifyErrors, type ErrorClassification } from '@fluentcommerce/fc-connect-sdk'`
-
-**Usage Example:**
-```typescript
-import { classifyErrors } from '@fluentcommerce/fc-connect-sdk';
-
-if (response.errors) {
-  const classification = classifyErrors(response.errors);
-  if (classification.retryable) {
-    // Retry with delay
-    await delay(classification.retryDelaySeconds * 1000);
-  } else {
-    // Show error to user
-    console.error(classification.userMessage);
-  }
-}
-```
-
-**Error Classification Features:**
-- Categorizes errors as CLIENT_ERROR, SERVER_ERROR, THIRD_PARTY_ERROR, or UNKNOWN
-- Provides retryability guidance (retryable: true/false)
-- Includes recommended action (FIX_AND_RETRY, RETRY_LATER, CONTACT_SUPPORT, VERIFY_PAYLOAD)
-- Suggests retry delay in seconds for retryable errors
-- Extracts error codes from multiple locations (extensions.code, message parsing)
-
-## [0.1.41] - 2025-11-13
-
-### Improved
-
-**GraphQLMutationMapper API Consistency** (2025-11-13)
-- **Auto-generates GraphQL query**: `mapWithNodes()` now includes `query` property in result (consistent with `map()` method)
-- **Explicit variables property**: Added `MapWithNodesResult.variables` for direct GraphQL execution
-  - `variables` is auto-wrapped in `{ input: ... }` when using fields pattern
-  - `data` remains unwrapped for direct field access (`result.data.orderRef`)
-- **Improved constructor options**: Added `MappingOptions` interface
-  - `customResolvers` - Pass resolvers via constructor instead of every method call
-  - `customTransforms` - Pass custom transforms via constructor
-  - Method-level resolvers still supported (takes precedence over constructor resolvers)
-- **Optional resolvers parameter**: `mapWithNodes(sourceData)` - resolvers now optional
-- **Consistent error handling**: Returns structured error result (not throw) with `success: false`
-
-**Before (old pattern - removed):**
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, client, logger);
-const result = await mapper.mapWithNodes(sourceData, customResolvers);
-const query = buildMutationQuery(mappingConfig); // Manual step
-await client.graphql({ query, variables: result.data });
-```
-
-**After (new pattern - consistent with UniversalMapper):**
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, {
-  customResolvers,
-  fluentClient: client  // Pass client via options
-});
-const result = await mapper.mapWithNodes(sourceData);
-await client.graphql({
-  query: result.query,        // Auto-generated
-  variables: result.variables  // Auto-wrapped if fields pattern
-});
-```
-
-**Backward Compatibility:**
-- Existing code using `result.data` continues to work
-- Optional parameters maintain compatibility with existing code
-
-### Fixed
-
-**GraphQLMutationMapper Bug Fixes** (2025-11-13)
-- **Empty `arguments: {}` detection**: Fixed `buildMutationQuery()` to treat empty `arguments: {}` as fields pattern
-  - Previously, empty `arguments: {}` would not trigger `{ input: ... }` wrapping
-  - Now correctly detects and wraps variables when using fields pattern
-- **Type safety**: Updated `MapWithNodesResult` interface with complete type definitions
-- **CRITICAL**: Fixed incorrect Versori credential access pattern in templates
-  - Templates incorrectly used `connections.credentials().getAccessToken()` or `ctx.connections.credentials().getAccessToken()`
-  - Correct pattern is `ctx.credentials().getAccessToken()`
-  - This error caused runtime failures: `Cannot read properties of undefined (reading 'credentials')`
-  - Fixed 7 template files across batch-api, graphql-mutations, and extraction workflows
-  - Updated inline documentation comments to reflect correct pattern
-  - Removed unnecessary `connections` destructuring from context objects
-
-### Removed - OAuth2 Server Functionality
-
-**WebhookAuthService OAuth2 Server Methods Removed** (2025-11-06)
-- **BREAKING**: Removed OAuth2 server functionality from `WebhookAuthService`
-  - Removed `issueToken()` method - OAuth2 token issuance no longer supported
-  - Removed `validateToken()` method - OAuth2 token validation no longer supported
-  - Removed `refreshToken()` method - OAuth2 token refresh no longer supported
-  - Removed `revokeToken()` method - OAuth2 token revocation no longer supported
-  - Removed `WebhookAuthServiceConfig` interface - constructor now only requires logger
-  - Removed `jose` dependency - no longer needed for JWT token handling
-- **API Key Authentication**: `WebhookAuthService` now supports API key authentication only
-  - `generateApiKey()` - Generate secure API keys
-  - `generateApiKeyWithPrefix()` - Generate prefixed API keys
-  - `hashApiKey()` - Hash API keys for secure storage
-  - `validateApiKey()` - Validate API keys with lookup function
-- **Migration**: Users of OAuth2 server methods should migrate to API key authentication
-- **Note**: OAuth2 **client** authentication (FluentClient authenticating with Fluent Commerce) remains unchanged
-
-## [0.1.39] - 2025-01-14
-
-### Changed
-- **Production Ready Release**: Comprehensive documentation and feature completion
-  - Fixed missing bin file (analyze-source-structure.js)
-  - Fixed 449 documentation links (97% success rate)
-  - Created 52 README files for improved navigation
-  - Added 33 module files for complete feature coverage
-  - All 7 CLI tools now functional
-  - PDF documentation generated
-  - Published to npm registry
-
-### Documentation
-- Comprehensive documentation updates across all modules
-- Improved navigation with README files in all directories
-- Complete API reference documentation
-- Updated template examples and guides
-- CLI tool documentation
-
-### Features (Stable)
-- TypeScript SDK for Fluent Commerce integration
-- Multi-runtime support (Node.js ≥18.0.0, Deno, Versori platform)
-- Complete API client with OAuth2 authentication
-- Data sources: S3, SFTP with connection pooling
-- Parsers: CSV, XML, JSON, Parquet
-- Mappers: UniversalMapper, GraphQLMutationMapper
-- Comprehensive test suite (97%+ coverage)
-
-## [0.1.31] - 2025-01-14
-
-### Code Changes
-- None
-
-### Documentation
-- Fixed 32 critical documentation issues across 10 core guide sections
-- Corrected method names, type definitions, and configuration parameters
-- Updated 35+ documentation files with accurate examples
-- Improved overall documentation accuracy to 95%+
-
-## Previous Releases
-
-### Added - Security Enhancements
-
-**WebhookAuthService Security Features** (2025-01-XX)
-- **Token Revocation**: Added `revokeToken()` method with optional `revocationStore` configuration
-  - Tokens can be revoked before expiry using JTI (JWT ID) blacklist
-  - Automatic revocation check in `validateToken()` when revocation store is configured
-  - Supports automatic cleanup via TTL (expiresAt)
-- **Rate Limiting**: Added sliding window rate limiting for `issueToken()` endpoint
-  - Optional `rateLimitStore` configuration for persistent rate limiting
-  - Configurable limits (default: 10 attempts per 60 seconds)
-  - Per-username rate limiting to prevent brute force attacks
-  - Fail-open behavior on rate limit errors (allows requests if check fails)
-- **Constant-Time Comparison**: Added `constantTimeEqualHex()` function for API key validation
-  - Prevents timing attacks on API key validation
-  - Automatic timing attack protection in `validateApiKey()` when `useConstantTimeComparison` is enabled
-- **Refresh Token Rotation**: Automatic refresh token rotation on each refresh
-  - Old refresh tokens are automatically revoked when new tokens are issued
-  - Requires `revocationStore` to be configured for rotation
-- **Token Type Consistency**: Added `type: 'access'` field to access tokens
-  - Access tokens now include `type: 'access'` claim
-  - Refresh tokens include `type: 'refresh'` claim
-  - Improves token type validation and security
-
-### Changed - Security Enhancements
-
-**WebhookAuthService API Changes** (2025-01-XX)
-- `validateApiKey()` now accepts optional `options` parameter:
-  - `useConstantTimeComparison?: boolean` - Enable timing attack protection (default: true)
-  - `compareHashed?: boolean` - If true, keyLookup expects hashed key
-- `WebhookAuthServiceConfig` now supports optional security features:
-  - `revocationStore?: { get, set }` - Optional token revocation store
-  - `rateLimitStore?: { get, set }` - Optional rate limiting store
-  - `rateLimitConfig?: { maxAttempts, windowSeconds }` - Rate limiting configuration
-
-### Testing
-
-**Security Test Coverage** (2025-01-XX)
-- Added comprehensive security test suite (500+ lines)
-  - Token revocation tests (3 tests)
-  - Rate limiting tests (4 tests)
-  - Malformed token handling tests (5 tests)
-  - Expired token handling tests (2 tests)
-  - Token type validation tests (2 tests)
-  - API key security tests (2 tests)
-  - Refresh token rotation tests (2 tests)
-- Total test coverage: 20+ new security-specific tests
-
-### Documentation
-
-**Security Documentation** (2025-01-XX)
-- Added `docs/04-REFERENCE/platforms/versori/webhook-auth-security-considerations.md` - Security best practices guide
-- Updated `README.md` with security features
-- Updated service documentation with security configuration examples
-
-## [0.1.28] - 2025-10-30
-
-### Documentation
-
-**README Critical Fixes** (2025-10-30)
-- Fixed missing FluentBatchManager (FBM) in Mermaid architecture diagram
-  - Added FBM node to Service Layer subgraph (line 63)
-  - Added FBM styling to match other services (line 138)
-  - Restored 9 connections referencing FBM
-  - **Impact:** Architecture diagram now renders correctly with all services visible
-- Fixed 2 broken links to mapper comparison guide
-  - Updated paths from `docs/00-START-HERE/MAPPER-COMPARISON-GUIDE.md` to correct location
-  - Correct path: `docs/02-CORE-GUIDES/mapping/mapper-comparison-guide.md`
-  - **Impact:** Users can now access critical mapper selection guide
-- Fixed SDK philosophy filename case sensitivity issue
-  - Changed from `SDK-PHILOSOPHY.md` (uppercase) to `sdk-philosophy.md` (lowercase)
-  - **Impact:** Link now works on case-sensitive filesystems (Linux, macOS)
-- Verified all 24 documentation paths in README
-  - All links validated and working
-  - Cross-platform compatibility ensured
-
-**Previous README Improvements** (2025-10-30)
-- Added Table of Contents for improved navigation
-- Restructured to show Architecture/Services upfront before Quickstart
-- Fixed 2 hallucinated service names throughout README:
-  - `BatchAPIClient` → `FluentBatchManager` (correct SDK service name)
-  - `IngestionOrchestrator` → `IngestionService` (correct SDK service name)
-- Clarified logging approach: Function-based utilities (`createConsoleLogger`, `toStructuredLogger`) for standalone environments
-- Fixed 6 broken documentation links to match new 5-folder structure
-- Added complete S3 CSV → Batch API workflow example with real SDK methods
-- Added complete SFTP XML → Batch API workflow example with real SDK methods
-- Added Universal Mapping section with XML/JSON transformation examples
-- Fixed architecture diagram with correct service names and relationships
-- Added "Learn More" sections linking to relevant documentation guides
-- Updated code examples to match actual SDK APIs (all examples now verified)
-- Improved "When to Use This SDK" decision table
-- Enhanced authentication section with OAuth2 token refresh details
-- Added Common Pitfalls section with quick fixes
-
-**Impact:** All README code examples now verified against SDK source. Documentation is now fully synchronized with actual SDK implementation. All critical documentation links fixed and verified.
-
-## [0.1.27] - 2025-10-30
-
-### Initial Release
-
-A TypeScript SDK for Fluent Commerce API integration with support for Node.js, Deno, and Versori platform.
-
-### Features
-
-**Authentication & Security**
-- OAuth2 authentication with automatic token refresh
-- Refresh token support (`grant_type=refresh_token` when available)
-- Automatic 401 retry with exponential backoff (up to 3 attempts)
-- Thread-safe token refresh (prevents duplicate refresh requests)
-- Handles clock skew, server-side revocation, and multi-process conflicts
-- 60-second expiry buffer prevents mid-flight token expiry
-- Webhook signature validation with RSA cryptography
-
-**Data Ingestion**
-- Batch API with Batch Pre-Processing (BPP) for change detection
-- Event API for real-time updates
-- GraphQL mutations with automatic mapping
-- Support for CSV, XML, JSON, and Parquet formats
-- Universal field mapping with built-in resolvers
-
-**Data Extraction**
-- GraphQL queries with automatic cursor-based pagination
-- ExtractionOrchestrator for high-level extraction workflows
-- Path-based extraction for specific data nodes
-- Support for reverse pagination (most recent first)
-
-**Data Sources**
-- S3DataSource with streaming and retry logic
-- SftpDataSource with connection pooling and retry logic
-- Automatic archiving and error handling
-
-**Parsers**
-- CSVParserService with validation
-- XMLParserService with path resolution
-- JSONParserService with streaming
-- ParquetParserService for columnar data
-
-**Service Layer**
-- BatchAPIClient for batch operations
-- UniversalMapper for field transformations
-- StateService for distributed state management
-- JobTracker for job lifecycle tracking
-- PartialBatchRecovery for handling partial failures
-- PreflightValidator for pre-execution validation
-
-**Cross-Runtime Support**
-- Node.js ≥18.0.0
-- Deno runtime
-- Versori platform with native integration
-- Triple module system (CommonJS, ESM, TypeScript definitions)
-
-**Documentation**
-- 15+ production-ready templates (Versori + standalone)
-- Progressive learning guides (ingestion, extraction, mapping)
-- Reusable patterns (error handling, orchestrators)
-- Complete API reference
-- Architecture documentation
-
-### Notes
-
-- **Zero Breaking Changes**: Maintains API stability
-- **Optional Features**: Refresh tokens depend on Fluent account configuration
-- **Versori Integration**: VersoriConnectionAdapter has native refresh token support
-- **Platform Detection**: Automatic environment detection (Node.js, Deno, Versori)
+# Changelog
+
+All notable changes to the Fluent Commerce Connect SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+_No unreleased changes_
+
+## [0.1.53] - 2026-02-15
+
+### Fixed - Event API GET Documentation and Typing Alignment
+- Corrected README `getEvents()` documentation for `retailerId` behavior to clarify there is no automatic fallback to client config for query filters.
+- Added explicit README guidance showing quoted dot-notation keys (for example, `'context.rootEntityType'`) when passing Event API GET context filters in JavaScript/TypeScript.
+- Updated `FluentEventLogAttribute.value` type from `string` to `unknown` to match real Event API responses that can include non-string values (for example, numeric timers and nested objects).
+- No runtime behavior changes to existing API methods; this patch aligns published docs/types with current SDK behavior.
+
+## [0.1.52] - 2026-02-15
+
+### Added - Event API Log Query (REST GET Endpoints)
+- Added `getEvents(params)` to `FluentClient` and `FluentVersoriClient` for `GET /api/v4.1/event`
+  - Search/query events with comprehensive filtering (entity type, status, date range, etc.)
+  - Supports pagination with `start`/`count` parameters (max 5000 per page)
+  - Full documentation with JSDoc examples for common use cases
+- Added `getEventById(eventId)` to `FluentClient` and `FluentVersoriClient` for `GET /api/v4.1/event/{eventId}`
+  - Retrieve complete event details by unique identifier
+  - Returns event metadata, context, attributes, and source event IDs
+  - Useful for event tracing and debugging workflows
+- Added typed Event Log models: `FluentEventQueryParams`, `FluentEventLogResponse`, `FluentEventLogItem`, `FluentEventLogContext`, and `FluentEventLogAttribute`
+- Added typed Event constants for query safety: `FluentEventType`, `FluentEventStatus`, `FluentEventCategory`, `FluentEventRootEntityType`, and `FluentEventEntityType`
+- Added unit test coverage for query-string building, empty-filter handling, success parsing, and error paths
+- Updated API docs with `getEvents()` and `getEventById()` usage examples
+
+### Added - Security & Compliance
+- **Security Audit Infrastructure** - Comprehensive security audit tools and scripts
+  - `security-audit/security-audit.cjs` - Automated vulnerability scanning
+  - `security-audit/safe-fix.cjs` - Safe vulnerability fixing with automatic testing
+  - `security-audit/snyk-setup.cjs` - Snyk integration for advanced scanning
+  - GitHub Actions workflow for automated security scans
+  - Dependabot configuration for automated dependency updates
+- **Security Documentation** - Complete security and compliance guides
+  - SOC 2 Compliance Guide
+  - Vulnerability Checking Guide
+  - Safe Fixing Guide
+  - Advanced Scanning Guide (Snyk)
+  - Security audit quick start
+- **Security Scripts** - NPM scripts for security management
+  - `npm run security:check` - Comprehensive security audit
+  - `npm run security:fix` - Safe vulnerability fixing
+  - `npm run security:snyk` - Advanced Snyk scanning
+  - `npm run security:full` - Full security check (npm audit + Snyk)
+
+### Fixed - Security Vulnerabilities
+- **js-yaml vulnerabilities** (MODERATE) - Updated to secure versions (3.14.2, 4.1.1)
+- **@versori/run** - Updated from 0.4.4 to 0.4.11 (includes security fixes)
+- **markdownlint-cli** (HIGH) - Updated from 0.45.0 to 0.46.0 (fixes glob command injection)
+- **Removed unused dependency** - Removed unused `jose@5.10.0` package
+- **Security Status:** Reduced vulnerabilities from 12 to 3 (75% reduction)
+  - Fixed: 2 Critical, 3 High, 4 Moderate, 1 Low
+  - Remaining: 3 Moderate (transitive dependencies, no fix available)
+
+## [0.1.51] - 2025-01-12
+
+### Added
+
+**GraphQL Partial Response Support**
+- **New error handling mode**: Added `errorHandling: 'partial'` option for `FluentClient.graphql()` and `ExtractionOrchestrator`
+  - Allows returning both `data` AND `errors` when GraphQL returns partial responses (GraphQL spec compliant)
+  - Default behavior unchanged: `'throw'` mode throws `GraphQLExecutionError` on any errors (backward compatible)
+  - Opt-in feature for scenarios where partial data is acceptable (batch operations, analytics, etc.)
+- **Response extensions**: Added `hasPartialData` flag to `GraphQLResponse` interface
+  - Set to `true` when response contains both data and errors
+  - Only present when `errorHandling: 'partial'` is used and errors occurred
+- **Error accumulation across pagination**: Partial mode accumulates errors from all pages
+  - All GraphQL errors collected in `response.errors` array for paginated queries
+  - ExtractionOrchestrator includes errors in `stats.partialErrors` field
+- **Null data handling**: ExtractionOrchestrator gracefully handles `data: null` with errors in partial mode
+  - Returns empty array `[]` instead of throwing
+  - Stops pagination when no data available (cannot determine if more pages exist)
+  - Errors still accumulated in `stats.partialErrors`
+  - Preserves backward compatibility: throw mode still throws original error messages
+
+**Use Cases:**
+- Batch mutations where some items may fail independently
+- Analytics/reporting where partial data is better than no data
+- Extraction workflows where some records may be inaccessible
+- Resilient data pipelines that continue despite errors
+
+**Usage Example:**
+```typescript
+// Partial mode: get both successful and failed results
+const result = await client.graphql({
+  query: batchMutation,
+  errorHandling: 'partial'  // Opt-in
+});
+
+if (result.hasPartialData) {
+  // Process successful items
+  processSuccessful(result.data);
+
+  // Log or retry failed items
+  for (const error of result.errors || []) {
+    logger.warn('Failed item:', error.path, error.message);
+  }
+}
+
+// Default mode (throw): fail fast on any error
+const criticalResult = await client.graphql({
+  query: singleMutation
+  // errorHandling: 'throw' is default
+});
+```
+
+**Documentation:**
+- Complete guide: `docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-partial-responses.md`
+- Best practices, migration guide, and edge case handling included
+- Integration examples with FluentClient, FluentVersoriClient, and ExtractionOrchestrator
+
+**Test Coverage:**
+- 9+ test scenarios in `tests/unit/fluent-client-partial-response.test.ts`
+- 5+ test scenarios in `tests/unit/services/extraction/extraction-orchestrator.test.ts` (including null data edge cases)
+- Edge cases: null data, empty errors array, error extensions, pagination, pagination stop on null data
+
+**Backward Compatibility:**
+- No breaking changes
+- Default behavior unchanged ('throw' mode)
+- Existing code continues to work without modifications
+
+## [0.1.48] - 2025-11-19
+
+### ⚠️ IMPORTANT - Share in Slack
+
+**Breaking Change in v0.1.47**: If you're using `httpStatus` from EventResponse, you must migrate to `statusCode`.
+
+```typescript
+// ❌ OLD (no longer works)
+const status = response.httpStatus;
+
+// ✅ NEW (v0.1.47+)
+const status = response.statusCode;
+```
+
+See v0.1.47 changelog below for full details.
+
+### Added
+- **FluentVersoriClient connection validation enhancements** - Improved error handling and connection validation for Versori platform
+- **Event API template documentation** - 8 new templates for S3/SFTP ingestion with CSV, XML, JSON, Parquet formats
+- **Connection validation pattern guide** - New documentation for Versori connection validation patterns
+- **README error classification documentation** - Added comprehensive code examples for `classifyError` and `classifyErrors` functions
+
+### Changed
+- **README updates** - Updated template count from 15+ to 23+, added Error Classification section to Core Services table
+- **Smart Error Handling documentation** - Added note about consistent `statusCode` field across success and error responses
+- **Error handling documentation improvements** - Added links to comprehensive error handling guide and quick reference
+
+### Fixed
+- **FluentVersoriClient improvements** - 206 lines of enhancements for better error handling and connection management
+
+## [0.1.47] - 2025-11-19
+
+### Changed
+- **BREAKING: EventResponse interface standardized on `statusCode`**
+  - Removed `httpStatus` field from EventResponse interface
+  - HTTP status code is now consistently available as `statusCode` in both success and error responses
+  - Success: `response.statusCode` (200, 201, 202)
+  - Error: `error.statusCode` (400, 401, 404, 500, etc.)
+  - Migration: Replace all `response.httpStatus` with `response.statusCode`
+
+### Fixed
+- **Auth retry tests** - Updated expected error type from FluentAPIError to AuthenticationError after exhausting retries
+- **Test timeouts** - Added proper timeout for retry delay tests
+
+## [0.1.46] - 2025-11-18
+
+### Changed
+- Documentation consolidation for error handling
+- Removed duplicate module files in error-handling docs
+- Added SDK automatic retry behavior clarification
+
+## [0.1.45] - 2025-11-17
+
+### Added
+- **XML Helper Exports** (2025-11-17)
+  - `getXmlAttribute` - Extract XML attributes from multiple parser formats (Versori $, SDK @, xml2js)
+  - `getXmlTextContent` - Extract XML text content from multiple formats (_, #text, value)
+  - `normalizeEmpty` - Normalize empty values (null, undefined, '', whitespace)
+  - All three helpers now exported from `@fluentcommerce/fc-connect-sdk`
+  - Comprehensive unit tests (19 tests) and inline JSDoc documentation
+
+### Changed
+- **Resolver Helper Improvements** (2025-11-17)
+  - SDK resolvers now use `helpers.getXmlTextContent` for XML text extraction
+  - Replaces manual format checking (`attr._ || attr['#text'] || attr.value`)
+  - Improves consistency across XML parser formats
+
+### Notes
+- These helpers were previously internal-only and are now part of the public API
+- No breaking changes - existing code continues to work
+- Maintains backward compatibility with all existing resolver implementations
+
+## [0.1.43] - 2025-01-14
+
+### Added
+
+**GraphQL Error Classification Service** (2025-01-14)
+- **New error classification utilities**: Added `classifyError()` and `classifyErrors()` functions to classify Fluent Commerce GraphQL errors
+- **Retry guidance**: Automatically determines if errors are retryable based on error codes (C/S/T prefix)
+- **User-friendly messages**: Provides actionable error messages and recommended actions
+- **Error code support**: Handles Fluent Commerce error codes (C0121E, S0002E, etc.) with proper classification
+- **Export location**: Available via `import { classifyError, classifyErrors, type ErrorClassification } from '@fluentcommerce/fc-connect-sdk'`
+
+**Usage Example:**
+```typescript
+import { classifyErrors } from '@fluentcommerce/fc-connect-sdk';
+
+if (response.errors) {
+  const classification = classifyErrors(response.errors);
+  if (classification.retryable) {
+    // Retry with delay
+    await delay(classification.retryDelaySeconds * 1000);
+  } else {
+    // Show error to user
+    console.error(classification.userMessage);
+  }
+}
+```
+
+**Error Classification Features:**
+- Categorizes errors as CLIENT_ERROR, SERVER_ERROR, THIRD_PARTY_ERROR, or UNKNOWN
+- Provides retryability guidance (retryable: true/false)
+- Includes recommended action (FIX_AND_RETRY, RETRY_LATER, CONTACT_SUPPORT, VERIFY_PAYLOAD)
+- Suggests retry delay in seconds for retryable errors
+- Extracts error codes from multiple locations (extensions.code, message parsing)
+
+## [0.1.41] - 2025-11-13
+
+### Improved
+
+**GraphQLMutationMapper API Consistency** (2025-11-13)
+- **Auto-generates GraphQL query**: `mapWithNodes()` now includes `query` property in result (consistent with `map()` method)
+- **Explicit variables property**: Added `MapWithNodesResult.variables` for direct GraphQL execution
+  - `variables` is auto-wrapped in `{ input: ... }` when using fields pattern
+  - `data` remains unwrapped for direct field access (`result.data.orderRef`)
+- **Improved constructor options**: Added `MappingOptions` interface
+  - `customResolvers` - Pass resolvers via constructor instead of every method call
+  - `customTransforms` - Pass custom transforms via constructor
+  - Method-level resolvers still supported (takes precedence over constructor resolvers)
+- **Optional resolvers parameter**: `mapWithNodes(sourceData)` - resolvers now optional
+- **Consistent error handling**: Returns structured error result (not throw) with `success: false`
+
+**Before (old pattern - removed):**
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, client, logger);
+const result = await mapper.mapWithNodes(sourceData, customResolvers);
+const query = buildMutationQuery(mappingConfig); // Manual step
+await client.graphql({ query, variables: result.data });
+```
+
+**After (new pattern - consistent with UniversalMapper):**
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, {
+  customResolvers,
+  fluentClient: client  // Pass client via options
+});
+const result = await mapper.mapWithNodes(sourceData);
+await client.graphql({
+  query: result.query,        // Auto-generated
+  variables: result.variables  // Auto-wrapped if fields pattern
+});
+```
+
+**Backward Compatibility:**
+- Existing code using `result.data` continues to work
+- Optional parameters maintain compatibility with existing code
+
+### Fixed
+
+**GraphQLMutationMapper Bug Fixes** (2025-11-13)
+- **Empty `arguments: {}` detection**: Fixed `buildMutationQuery()` to treat empty `arguments: {}` as fields pattern
+  - Previously, empty `arguments: {}` would not trigger `{ input: ... }` wrapping
+  - Now correctly detects and wraps variables when using fields pattern
+- **Type safety**: Updated `MapWithNodesResult` interface with complete type definitions
+- **CRITICAL**: Fixed incorrect Versori credential access pattern in templates
+  - Templates incorrectly used `connections.credentials().getAccessToken()` or `ctx.connections.credentials().getAccessToken()`
+  - Correct pattern is `ctx.credentials().getAccessToken()`
+  - This error caused runtime failures: `Cannot read properties of undefined (reading 'credentials')`
+  - Fixed 7 template files across batch-api, graphql-mutations, and extraction workflows
+  - Updated inline documentation comments to reflect correct pattern
+  - Removed unnecessary `connections` destructuring from context objects
+
+### Removed - OAuth2 Server Functionality
+
+**WebhookAuthService OAuth2 Server Methods Removed** (2025-11-06)
+- **BREAKING**: Removed OAuth2 server functionality from `WebhookAuthService`
+  - Removed `issueToken()` method - OAuth2 token issuance no longer supported
+  - Removed `validateToken()` method - OAuth2 token validation no longer supported
+  - Removed `refreshToken()` method - OAuth2 token refresh no longer supported
+  - Removed `revokeToken()` method - OAuth2 token revocation no longer supported
+  - Removed `WebhookAuthServiceConfig` interface - constructor now only requires logger
+  - Removed `jose` dependency - no longer needed for JWT token handling
+- **API Key Authentication**: `WebhookAuthService` now supports API key authentication only
+  - `generateApiKey()` - Generate secure API keys
+  - `generateApiKeyWithPrefix()` - Generate prefixed API keys
+  - `hashApiKey()` - Hash API keys for secure storage
+  - `validateApiKey()` - Validate API keys with lookup function
+- **Migration**: Users of OAuth2 server methods should migrate to API key authentication
+- **Note**: OAuth2 **client** authentication (FluentClient authenticating with Fluent Commerce) remains unchanged
+
+## [0.1.39] - 2025-01-14
+
+### Changed
+- **Production Ready Release**: Comprehensive documentation and feature completion
+  - Fixed missing bin file (analyze-source-structure.js)
+  - Fixed 449 documentation links (97% success rate)
+  - Created 52 README files for improved navigation
+  - Added 33 module files for complete feature coverage
+  - All 7 CLI tools now functional
+  - PDF documentation generated
+  - Published to npm registry
+
+### Documentation
+- Comprehensive documentation updates across all modules
+- Improved navigation with README files in all directories
+- Complete API reference documentation
+- Updated template examples and guides
+- CLI tool documentation
+
+### Features (Stable)
+- TypeScript SDK for Fluent Commerce integration
+- Multi-runtime support (Node.js ≥18.0.0, Deno, Versori platform)
+- Complete API client with OAuth2 authentication
+- Data sources: S3, SFTP with connection pooling
+- Parsers: CSV, XML, JSON, Parquet
+- Mappers: UniversalMapper, GraphQLMutationMapper
+- Comprehensive test suite (97%+ coverage)
+
+## [0.1.31] - 2025-01-14
+
+### Code Changes
+- None
+
+### Documentation
+- Fixed 32 critical documentation issues across 10 core guide sections
+- Corrected method names, type definitions, and configuration parameters
+- Updated 35+ documentation files with accurate examples
+- Improved overall documentation accuracy to 95%+
+
+## Previous Releases
+
+### Added - Security Enhancements
+
+**WebhookAuthService Security Features** (2025-01-XX)
+- **Token Revocation**: Added `revokeToken()` method with optional `revocationStore` configuration
+  - Tokens can be revoked before expiry using JTI (JWT ID) blacklist
+  - Automatic revocation check in `validateToken()` when revocation store is configured
+  - Supports automatic cleanup via TTL (expiresAt)
+- **Rate Limiting**: Added sliding window rate limiting for `issueToken()` endpoint
+  - Optional `rateLimitStore` configuration for persistent rate limiting
+  - Configurable limits (default: 10 attempts per 60 seconds)
+  - Per-username rate limiting to prevent brute force attacks
+  - Fail-open behavior on rate limit errors (allows requests if check fails)
+- **Constant-Time Comparison**: Added `constantTimeEqualHex()` function for API key validation
+  - Prevents timing attacks on API key validation
+  - Automatic timing attack protection in `validateApiKey()` when `useConstantTimeComparison` is enabled
+- **Refresh Token Rotation**: Automatic refresh token rotation on each refresh
+  - Old refresh tokens are automatically revoked when new tokens are issued
+  - Requires `revocationStore` to be configured for rotation
+- **Token Type Consistency**: Added `type: 'access'` field to access tokens
+  - Access tokens now include `type: 'access'` claim
+  - Refresh tokens include `type: 'refresh'` claim
+  - Improves token type validation and security
+
+### Changed - Security Enhancements
+
+**WebhookAuthService API Changes** (2025-01-XX)
+- `validateApiKey()` now accepts optional `options` parameter:
+  - `useConstantTimeComparison?: boolean` - Enable timing attack protection (default: true)
+  - `compareHashed?: boolean` - If true, keyLookup expects hashed key
+- `WebhookAuthServiceConfig` now supports optional security features:
+  - `revocationStore?: { get, set }` - Optional token revocation store
+  - `rateLimitStore?: { get, set }` - Optional rate limiting store
+  - `rateLimitConfig?: { maxAttempts, windowSeconds }` - Rate limiting configuration
+
+### Testing
+
+**Security Test Coverage** (2025-01-XX)
+- Added comprehensive security test suite (500+ lines)
+  - Token revocation tests (3 tests)
+  - Rate limiting tests (4 tests)
+  - Malformed token handling tests (5 tests)
+  - Expired token handling tests (2 tests)
+  - Token type validation tests (2 tests)
+  - API key security tests (2 tests)
+  - Refresh token rotation tests (2 tests)
+- Total test coverage: 20+ new security-specific tests
+
+### Documentation
+
+**Security Documentation** (2025-01-XX)
+- Added `docs/04-REFERENCE/platforms/versori/webhook-auth-security-considerations.md` - Security best practices guide
+- Updated `README.md` with security features
+- Updated service documentation with security configuration examples
+
+## [0.1.28] - 2025-10-30
+
+### Documentation
+
+**README Critical Fixes** (2025-10-30)
+- Fixed missing FluentBatchManager (FBM) in Mermaid architecture diagram
+  - Added FBM node to Service Layer subgraph (line 63)
+  - Added FBM styling to match other services (line 138)
+  - Restored 9 connections referencing FBM
+  - **Impact:** Architecture diagram now renders correctly with all services visible
+- Fixed 2 broken links to mapper comparison guide
+  - Updated paths from `docs/00-START-HERE/MAPPER-COMPARISON-GUIDE.md` to correct location
+  - Correct path: `docs/02-CORE-GUIDES/mapping/mapper-comparison-guide.md`
+  - **Impact:** Users can now access critical mapper selection guide
+- Fixed SDK philosophy filename case sensitivity issue
+  - Changed from `SDK-PHILOSOPHY.md` (uppercase) to `sdk-philosophy.md` (lowercase)
+  - **Impact:** Link now works on case-sensitive filesystems (Linux, macOS)
+- Verified all 24 documentation paths in README
+  - All links validated and working
+  - Cross-platform compatibility ensured
+
+**Previous README Improvements** (2025-10-30)
+- Added Table of Contents for improved navigation
+- Restructured to show Architecture/Services upfront before Quickstart
+- Fixed 2 hallucinated service names throughout README:
+  - `BatchAPIClient` → `FluentBatchManager` (correct SDK service name)
+  - `IngestionOrchestrator` → `IngestionService` (correct SDK service name)
+- Clarified logging approach: Function-based utilities (`createConsoleLogger`, `toStructuredLogger`) for standalone environments
+- Fixed 6 broken documentation links to match new 5-folder structure
+- Added complete S3 CSV → Batch API workflow example with real SDK methods
+- Added complete SFTP XML → Batch API workflow example with real SDK methods
+- Added Universal Mapping section with XML/JSON transformation examples
+- Fixed architecture diagram with correct service names and relationships
+- Added "Learn More" sections linking to relevant documentation guides
+- Updated code examples to match actual SDK APIs (all examples now verified)
+- Improved "When to Use This SDK" decision table
+- Enhanced authentication section with OAuth2 token refresh details
+- Added Common Pitfalls section with quick fixes
+
+**Impact:** All README code examples now verified against SDK source. Documentation is now fully synchronized with actual SDK implementation. All critical documentation links fixed and verified.
+
+## [0.1.27] - 2025-10-30
+
+### Initial Release
+
+A TypeScript SDK for Fluent Commerce API integration with support for Node.js, Deno, and Versori platform.
+
+### Features
+
+**Authentication & Security**
+- OAuth2 authentication with automatic token refresh
+- Refresh token support (`grant_type=refresh_token` when available)
+- Automatic 401 retry with exponential backoff (up to 3 attempts)
+- Thread-safe token refresh (prevents duplicate refresh requests)
+- Handles clock skew, server-side revocation, and multi-process conflicts
+- 60-second expiry buffer prevents mid-flight token expiry
+- Webhook signature validation with RSA cryptography
+
+**Data Ingestion**
+- Batch API with Batch Pre-Processing (BPP) for change detection
+- Event API for real-time updates
+- GraphQL mutations with automatic mapping
+- Support for CSV, XML, JSON, and Parquet formats
+- Universal field mapping with built-in resolvers
+
+**Data Extraction**
+- GraphQL queries with automatic cursor-based pagination
+- ExtractionOrchestrator for high-level extraction workflows
+- Path-based extraction for specific data nodes
+- Support for reverse pagination (most recent first)
+
+**Data Sources**
+- S3DataSource with streaming and retry logic
+- SftpDataSource with connection pooling and retry logic
+- Automatic archiving and error handling
+
+**Parsers**
+- CSVParserService with validation
+- XMLParserService with path resolution
+- JSONParserService with streaming
+- ParquetParserService for columnar data
+
+**Service Layer**
+- BatchAPIClient for batch operations
+- UniversalMapper for field transformations
+- StateService for distributed state management
+- JobTracker for job lifecycle tracking
+- PartialBatchRecovery for handling partial failures
+- PreflightValidator for pre-execution validation
+
+**Cross-Runtime Support**
+- Node.js ≥18.0.0
+- Deno runtime
+- Versori platform with native integration
+- Triple module system (CommonJS, ESM, TypeScript definitions)
+
+**Documentation**
+- 15+ production-ready templates (Versori + standalone)
+- Progressive learning guides (ingestion, extraction, mapping)
+- Reusable patterns (error handling, orchestrators)
+- Complete API reference
+- Architecture documentation
+
+### Notes
+
+- **Zero Breaking Changes**: Maintains API stability
+- **Optional Features**: Refresh tokens depend on Fluent account configuration
+- **Versori Integration**: VersoriConnectionAdapter has native refresh token support
+- **Platform Detection**: Automatic environment detection (Node.js, Deno, Versori)