v2.1.0

🚀 v2.1.0 ^{Enterprise Banking Security & Distributed Tracing}

XYO Financial Node.js SDK v2.1.0 delivers Tier-1 institutional security hardening, full W3C distributed tracing compliance, enhanced rate limiting resilience, zero-trust fail-closed SSRF defenses, PCI-DSS PII log redaction, dynamic secret rotation, and strict OpenAPI code isolation.

🌟 Highlights

• W3C Distributed Tracing: Full end-to-end tracing support via correlationId (UUID v4) and standard traceparent (W3C Trace Context RFC) headers across all single and batch financial transaction enrichment operations.
• Rate Limiting: Dedicated XyoRateLimitError class providing structured access to Retry-After, RateLimit-Reset, RateLimit-Limit, and RateLimit-Remaining response headers with automatic ISO date and epoch timestamp parsing.
• PCI-DSS PII Redaction: Elimination of raw response body preview strings in error diagnostics (preventing CWE-209 log leaks) and strict CRLF header injection protection (CWE-113) on xApiUser headers.
• Pure OpenAPI Isolation: Architectural decoupling of ergonomic wrapper logic (src/index.ts) from auto-generated OpenAPI bindings (src/generated/), ensuring zero manual modifications to generated client code.
• Fail-Closed SSRF Defense: Zero-trust domain validation restricting archive downloads strictly to configured API host endpoints or verified AWS S3 (*.amazonaws.com) domains with scheme validation rejecting non-HTTP protocols (file://, ftp://, gopher://).
• Secret Rotation: NIST SP 800-57 compliant support for dynamic API keys and OAuth tokens via async tokenSupplier / apiKeySupplier callbacks.

---

📝 What's Changed / Detailed Commit Log

• 66a930f chore(release): bump version to 2.1.0 (#28)
• 1875e82 Automated SDK Update (#27)
• f5debd8 ci: use SDK_DISPATCH_TOKEN for automated PR creation in generate workflow (#25)
• f050ca9 fix(docs): use absolute raw github URL for mascot in README (#23)
• 1c4038a docs(readme): add NestJS, Express, and Serverless integration recipes (#22)
• a006957 style(readme): standardize header structure with mascot, title, and description (#21)
• a047c0e docs(readme): refine headings to omit 'Enterprise' and simplify 'Executive Summary' to 'Summary' (#20)
• 5f3a8ad docs(security): add Node.js runtime LTS schedule SVG and 3-month proactive sunset policy
• 754cae6 docs: standardize section heading emojis across markdown documentation (#19)
• 2d993b8 docs: add standard Keep a Changelog CHANGELOG.md (#18)
• 04a5f3c ci: remove npm whoami from release pipeline (#17)
• ebe2046 feat(sdk): enforce zero trust domain validation and strongly-typed async body iteration (#16)
• 8459703 feat(sdk): universal async body iteration, SSRF preview mitigation, and tar parser bounds (#15)
• 1a297e5 feat(sdk): ISO 3166-1 alpha-2 validation and xApiUser CRLF injection protection (CWE-113) (#14)
• b08bc62 feat(sdk): enterprise banking resilience, dynamic key rotation, and tar bomb protections (#13)
• 0258a78 docs(license): align LICENSE with exact standard Apache 2.0 text for licensecheck compliance

Full Diff Statistics: 34 files changed, 2762 insertions(+), 1404 deletions(-)
Full Changelog: v2.0.0...v2.1.0

---

📦 Installation & Usage Quickstart

Installation

npm install @xyo-financial/sdk-node@2.1.0

Quickstart Example

import { XYOClient, XyoRateLimitError } from '@xyo-financial/sdk-node';

// Initialize client with W3C Distributed Tracing and dynamic key rotation
const client = new XYOClient({
  apiKeySupplier: async () => process.env.XYO_API_KEY!,
  correlationId: '123e4567-e89b-12d3-a456-426614174000',
  traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
});

try {
  const enrichment = await client.enrichTransaction({
    raw_transaction: '0x1234567890abcdef...',
    country_code: 'US',
  });
  console.log('Transaction enriched successfully:', enrichment);
} catch (error) {
  if (error instanceof XyoRateLimitError) {
    console.error(`Rate limited! Retry after ${error.retryAfterSeconds}s (Reset: ${error.resetAt})`);
  } else {
    console.error('API Error:', error);
  }
}

v2.0.0

Release v2.0.0 (Major Release)

Version 2.0.0 represents a complete architectural overhaul of the XYO Financial Node.js SDK, transitioning to an automated OpenAPI Generator foundation while providing a high-level XYOClient wrapper with native bulk .tar.gz decompression and strict RFC 7807 Problem Details error handling.

---

💥 Breaking Changes

• New Error Class Hierarchy: Replaced legacy ClientError with OpenAPI runtime exception classes:
  • ResponseError: Thrown for HTTP 4xx/5xx responses containing raw Response and parsed RFC 7807 ErrorResponse payloads.
  • FetchError: Thrown on network/transport-level connection failures.
  • RequiredError: Thrown when required parameter validations fail before network transmission.
• Method Renaming & Signature Alignment:
  • enrichTransactionCollection is now enrichTransactions (or client.enrichment.enrichTransactions).
  • enrichTransactionCollectionStatus is now getEnrichmentStatus (or client.enrichment.getEnrichmentStatus).
• Client Class Standardization: Primary client is now XYOClient (with Client exported as a backward-compatible alias).

---

🚀 Key Features & Enhancements

1. OpenAPI-Generated Core (src/generated)

• Generated strictly typed API client models and endpoints (EnrichmentApi, EnrichmentRequest, EnrichmentResponse, ErrorResponse, APIError).
• Added openapitools.json and a dedicated GitHub Action workflow (.github/workflows/generate.yml) for continuous spec synchronization.

2. High-Level XYOClient Wrapper (src/index.ts)

• Provides intuitive synchronous and asynchronous enrichment methods:
  • enrichTransaction(request): Real-time single transaction enrichment.
  • enrichTransactions(transactions): Asynchronous bulk batch submission.
  • getEnrichmentStatus(id): Bulk job status polling (READY, PENDING, FAILED).
  • downloadEnrichmentCollection(downloadUrl): Built-in native gzip streaming decompression and POSIX/ustar tar archive parser that unpacks .tar.gz batch results directly into typed EnrichmentResponse[] records without third-party runtime dependencies.

3. Middleware & Lifecycle Interceptors

• Exposes Configuration and Middleware hooks (pre, post, onError) for custom request mutation, logging, metrics, and telemetry injection.

4. Comprehensive RFC 7807 Problem Details Support

• Native parsing and model mapping for RFC 7807 Problem Details payloads (ErrorResponseFromJSON), handling multi-error responses with granular type, title, status, detail, and instance attributes.

---

🧪 Testing & CI/CD Hardening

• Expanded Test Suite: Replaced legacy tests with a comprehensive 1,600+ line test suite (src/index.test.ts) covering constructor options, request construction, RFC 7807 parsing, middleware execution, mock fetch transport errors, and bulk .tar.gz decompression.
• Dockerfile Security Audit: Updated deploy/Dockerfile security gate to run npm audit --omit=dev --audit-level=low, ensuring audits focus on runtime production dependencies.

---

📚 Documentation, Governance & Security

• Enterprise Documentation: Overhauled README.md with complete integration guides, architectural principles, polling patterns, and error resolution matrices.
• Security Policy: Added SECURITY.md outlining vulnerability disclosure guidelines.
• License: Relicensed to Apache-2.0.

---

📊 Summary of Diff (v1.2.3...v2.0.0)

• Commits: 2
• Files Changed: 43
• Additions: +4,901
• Deletions: -1,721

v1.2.3

🔄 Repository URL Migration

• GitHub Organization & Repo Update: Updated all GitHub repository references across package.json metadata (repository, bugs, homepage) and README.md (mascot image assets and CI workflow badges) from syniol/xyo-sdk-node to the official xyo-financial/sdk-node organization.

📦 Maintenance & Versioning

• Patch Release: Incremented package version from 1.2.2 to 1.2.3.
• Lockfile Synchronization: Synchronised package-lock.json and example/package-lock.json lockfiles.

Full Changelog: v1.2.2...v1.2.3

v1.2.2

🚀 XYO Node.js SDK v1.2.2 Release Notes

Tag: v1.2.2
Previous Tag: v1.2.1
Release Date: 20th July 2026

---

⚖️ Licensing Update

• Adopted BSD 3-Clause License: Changed package licensing from Apache-2.0 / legacy references to the standard BSD 3-Clause License.
• License File Synchronization: Replaced content in LICENSE with official BSD 3-Clause License text.
• Package Metadata: Updated the "license" field in package.json to "BSD-3-Clause".
• Documentation Alignment: Updated the License section and copyright headers in README.md to reflect the BSD 3-Clause License and Copyright © 2026 Syniol Limited.

---

📦 Version Bump

• SDK Version: Incremented from 1.2.1 to 1.2.2 across package.json, package-lock.json, and example/package-lock.json.
• Runtime Version Consistency: Automatically updated SDK_VERSION export in src/client/version.ts.

---

📊 Summary of Modified Files

File	Changes
LICENSE	Updated to BSD 3-Clause License text
README.md	Updated license section to BSD 3-Clause and copyright to 2026
package.json	Incremented version to 1.2.2 & set "license": "BSD-3-Clause"
package-lock.json	Synchronised lockfile with package version and license
example/package-lock.json	Synchronised example application dependency lockfile

Diff Stats: 5 files changed, 38 additions(+), 26 deletions(-)

v1.2.1

Release v1.2.1

📖 Documentation Overhaul (Enterprise Grade)

• Elite README.md Rewrite: Completely overhauled the primary documentation to target Principal Engineers and Lead Architects at Tier-1 financial institutions.
  • Introduced Enterprise Architectural Principles (Type-Safety, Resiliency, Statelessness).
  • Added detailed integration patterns differentiating between Real-Time Enrichment (Synchronous) and Batch Processing (Asynchronous Bulk).
  • Added a Robust Error Handling matrix detailing enterprise mitigation strategies (e.g., DLQ routing, Circuit Breakers, Exponential Backoff).
  • Added Security & Compliance assertions highlighting zero third-party runtime dependencies and TLS enforcement.
• British English Standardisation: Audited and converted all documentation (README.md, CONTRIBUTING.md, mascot_generation_instructions.md) to adhere strictly to British English spelling (e.g., Initialise, Unauthorised, maximise, colours).

🎨 Branding & Assets

• New SDK Mascot: Updated docs/mascot.png from the legacy turtle concept to a sleek, neon cybernetic hexagon to match the unified Syniol SDK aesthetics.
• Mascot Instructions: Added docs/mascot_generation_instructions.md outlining the prompt and reference images used to generate the new mascot.

⚖️ Licensing & Maintenance

• License Audit: Streamlined and cleaned up the LICENSE file.
• Readme Badges: Updated CI/CD workflow and compatibility badges in the README.
• Version Increment: Incremented the minor version in package.json and synchronised package-lock.json.

Full Changelog: v1.2.0...v1.2.1

v1.2.0

Release v1.2.0

🚀 Features & Enhancements

• AI-Guided Refactoring: Addressed comprehensive code reviews by multiple AI models (Gemini 3.5 Flash, Claude Sonnet 4.6, and Opus 4.7) resulting in a significantly more robust codebase.
• Client Hardening: Major enhancements to src/client/client.ts, including improved type guards, payload validations, and enhanced network error handling.
• Enrichment Module Restructure: Streamlined the enrichment implementation by consolidating service.ts and service.test.ts directly into enrichment.ts.
• Enhanced Error Handling: Overhauled src/client/error.ts to provide more granular, typed error classes for better SDK debugging and integration.
• Testing Expansion: Added massive coverage improvements to the test suite (client.test.ts with over 800 insertions).

🛠 Fixes & CI/CD

• NPM Publish Pipeline: Completely revamped and unified the release pipeline in .github/workflows/release.yml. Deprecated the separate npm_publish.yml workflow and fixed authentication/provenance issues with the npm registry.
• Security Hardening: Integrated npm audit --audit-level=low directly into the CI/CD and Docker builds (deploy/Dockerfile) to ensure zero-tolerance for vulnerabilities.
• Publish Packaging: Removed the deprecated .npmignore file, opting for a deterministic files array pattern inside package.json for cleaner published tarballs.

📝 Documentation & Examples

• Documentation: Updated CONTRIBUTING.md (Syniol-only policies and release processes) and README.md to reflect the latest changes.
• Example Implementation: Refactored example/index.js and example/package.json to seamlessly link and demonstrate the locally built SDK without module resolution errors.

📊 Diff Stats

• Commits: 4
• Files Changed: 23
• Additions: 1,838
• Deletions: 728

1.1.0

• Added a new field for an enrichment response location
• Added a new field for an enrichment response address
• Updated Unit Tests

v1.0.2

Stable release until the next iteration

v1.0.0

Initial stable version 1.0.0 release for node.js

v0.2.1

Tested release for minor x.2.x version.