meridianjs 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,174 +1,121 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to Meridian are documented here.
 
-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).
+---
 
-## [0.2.3] - 2026-06-01
+## [0.2.5] — Adoption Sprint
 
 ### Added
-- **Core stabilization**: Integrated 741 contract tests (19 invariants × 39 adapters) verifying error handling, rate limiting, retries, timeouts, pagination, and request/response normalization across every provider adapter via the shared `runProviderContract` harness.
-- **Contract test suite & CLI runner**: Run tests with `npm run test:contracts` or per-provider via `npm run test:contracts stripe`.
-- **CI pipeline integration**: Added contract validation to the GitHub Actions test runner.
-- **Provider status matrix**: Published a complete compatibility checklist in the README.
-- **Comprehensive developer documentation**: Added 8 core manuals under the `docs/` folder.
 
-## [2.0.2] - 2025-01-XX
+**Service Routing — Weighted & Geo**
+- `strategy: "weighted"` — probabilistic load distribution across providers using a `weights` map (e.g. `{ stripe: 70, razorpay: 30 }`)
+- `strategy: "geo"` — region-aware routing via `MERIDIAN_REGION` env var or `defaultRegion`; `regions` maps region names to ordered provider lists
+- Both strategies select a primary provider via `selectIndex()` and failover through remaining providers on retryable errors
 
-### Changed
-- **Public API lockdown**: Package now exports from `src/public.ts` as the single public entry point. This restricts consumer access to only documented, stable APIs.
-- **Error contract enhancement**: `MeridianError` now exposes a `code` getter returning a frozen public `MeridianErrorCode` (e.g. `AUTH_FAILED`, `RATE_LIMITED`, `UPSTREAM_5XX`), derived from `category` and HTTP status. This provides a stable, documented error contract independent of the internal category.
-
-### Internal
-- Fixed incomplete code from prior refactoring in error message formatting
-- Corrected timeout error construction to use proper `MeridianError` class instantiation
-- Improved code consistency across error handling paths
-
-## [2.0.1] - 2025-01-14
-
-### Fixed
-- Fix incorrect internal package version. SDK_VERSION now correctly reads from package.json as single source of truth, eliminating version mismatches.
+**Policy Engine — Three New Built-ins**
+- `redact(fields, providers?)` — redacts dot-notation field paths (e.g. `"user.ssn"`) from the request body before it reaches the provider; does not block the request
+- `requireFields(fields, providers?)` — blocks requests missing required body fields; returns `MeridianError` with `category: "validation"`
+- `denyCountries(codes, field?)` — blocks requests where `body.country`, `body.country_code`, or `body.countryCode` matches a denied ISO 3166-1 alpha-2 code
 
-## [2.0.0] - 2025-01-09
+**Schema Monitor — Three New Methods**
+- `meridian.schema.diff(provider, endpoint, data)` — returns drift between current data and stored schema baseline
+- `meridian.schema.report(provider)` — returns structured `SchemaReport` with all snapshotted endpoints, field counts, and schemas
+- `meridian.schema.alert(provider, endpoint, data, callback)` — runs drift check and invokes callback with drifts if any are detected; returns the drifts array
 
-**This release establishes the long-term safety contract of the SDK.** All breaking changes are intentional and enforce safety by default.
+**Documentation**
+- `docs/payments/` — Stripe/Razorpay/Cashfree unified interface, failover, analytics
+- `docs/llms/` — OpenAI→Anthropic→Gemini failover, production chat endpoints
+- `docs/communications/` — Twilio→MSG91 SMS fallback, email fallback patterns
+- `docs/failover/` — all 7 routing strategies with runnable examples
+- `docs/policies/` — all policy built-ins with fintech compliance example
+- `docs/schema-drift/` — full snapshot→diff→report→alert workflow
+- `docs/transactions/` — saga pattern with multi-step rollback example
 
-**⚠️ BREAKING: This is a major version release with breaking changes. See migration guide below.**
+**Cost Intelligence**
+- `MeridianConfig.providerCosts` — declare per-request cost for each provider (e.g. `{ openai: 0.03, anthropic: 0.01 }`)
+- `meridian.cost(currency?)` — returns `CostReport` with per-provider request counts, cost-per-request, estimated spend, and a total; resets with `analytics.reset()`
+- `CostReport`, `CostEntry` exported from `meridianjs`
 
-### Breaking Changes
+**Examples**
+- `examples/nextjs-openai-failover/` — Next.js 14 App Router LLM endpoint with failover
+- `examples/express-stripe/` — Express server with pagination, idempotency, health endpoint
+- `examples/nestjs-payments/` — NestJS module with DI, weighted routing, saga transaction
+- `examples/fastify-webhooks/` — Fastify webhook verification with raw body parsing
+- `examples/multi-provider-llm/` — Node.js script demonstrating failover, cheapest routing, drift detection, analytics
 
-- **Constructor removed**: `new Meridian(config)` no longer works. Use `await Meridian.create(config)` instead. This enforces async initialization and prevents use before initialization.
+---
 
-- **Mandatory initialization**: All SDK methods throw if called before `Meridian.create()` completes. This prevents undefined behavior from uninitialized state.
+## [0.2.4] — Operational Intelligence
 
-- **StateStorage enforcement**: 
-  - `mode: "distributed"` **requires** a `StateStorage` implementation. Startup fails without it.
-  - Configurations without `stateStorage` require explicit `localUnsafe: true` to acknowledge the limitation.
-  - This prevents accidental use of in-memory state in production deployments.
-
-- **Node.js version requirement**: SDK now explicitly requires Node.js ≥18.0.0 (was implicit before). This is enforced via `engines` field in `package.json`.
-
-- **Typed request options**: `ProviderClient` methods now use strict `RequestOptions` types instead of `any`. Invalid options are caught at compile time.
+This release transforms Meridian from an API normalisation SDK into an operational layer for third-party integrations. Every feature below works with zero configuration beyond what you already have.
 
 ### Added
 
-- **Safety guarantees**:
-  - Fail-fast initialization enforcement
-  - Fail-closed state management
-  - Guaranteed secret redaction in all observability paths
-  - No silent degradation - all failures are explicit
-
-- **Pagination safety**: Cycle detection and max page limit (1000 pages) prevent infinite loops from malformed adapters.
-
-- **Adapter validation safety**: Validation uses fake test tokens to prevent side effects during adapter checks.
-
-- **Instance-scoped adapter cache**: Prevents config sharing across Meridian instances.
+**Service Abstraction & Failover**
+- `meridian.service("name")` — logical service client that routes across multiple providers
+- `MeridianConfig.services` — configure provider groups with a routing strategy
+- Routing strategies: `"failover"`, `"round-robin"`, `"lowest-latency"`, `"cheapest"`, `"highest-success-rate"`
+- `"lowest-latency"` self-calibrates via EWMA over `meta.trace.latency`
+- `"highest-success-rate"` routes dynamically using live analytics data
+- `"cheapest"` accepts a `costs` map and fails over in ascending cost order
+
+**Request Trace**
+- `result.meta.trace` — always present: `retries`, `latency`, `circuitBreaker`, `rateLimitRemaining`
+- `ResponseContext.trace` — trace data now visible to all observability adapters
+
+**Analytics & Health**
+- `meridian.analytics()` — per-provider: `requests`, `errors`, `errorRate`, `successRate`, `avgLatency`, `p95Latency`
+- `meridian.health()` — per-provider status (`healthy`/`degraded`/`down`) combining analytics + circuit breaker
+- `AnalyticsCollector` always active, zero configuration required
+
+**Debug Recording & Replay**
+- `meridian.debug.enable()` / `.disable()` / `.clear()`
+- `meridian.debug.recordings()` — full log with trace data and original request options
+- `meridian.replay(requestId)` — re-execute any recorded request with identical options
+
+**Policy Engine**
+- `MeridianConfig.policies` — evaluate before every request, block or allow
+- Built-ins: `blockPII()`, `allowedProviders()`, `blockedProviders()`, `readOnly()`, `customPolicy()`
+- PII detection covers: credit cards, SSNs, emails, phone numbers, Aadhaar, PAN
+- Blocked requests throw `MeridianError` with `category: "validation"` — no network round-trip wasted
+
+**Multi-Provider Transactions**
+- `meridian.transaction(steps)` — saga pattern across multiple providers
+- Per-step `rollback` function; executed in reverse order on failure
+- `TransactionError` carries `failed`, `succeeded`, `rolledBack`, `rollbackErrors`, `results`
+
+**Schema Drift Detection (enhanced)**
+- `meridian.schema.snapshot(provider, endpoint, data)` — baseline any live response
+- `meridian.schema.check(provider, endpoint, data)` — detect field removals, type changes, required changes
+- `DriftDetector` now recurses into nested object and array schemas
+
+**Provider Capability Registry**
+- `meridian.providers()` — all configured providers with capability arrays
+- `meridian.findProviders({ capability })` — filter by capability string
+- 39 providers mapped: chat, embeddings, streaming, payments, kyc, upi, shipping, maps, and more
+
+**Adapter Generator**
+- `npx meridian generate --provider <name> [--openapi spec.json]`
+- Parses OpenAPI 3.x JSON: extracts base URL, auth type, endpoint list
+- Generates `adapter.ts`, `adapter.test.ts` (8 passing tests out of the box), `pagination.ts`, `index.ts`
 
 ### Changed
 
-- All examples and documentation updated to use `Meridian.create()` pattern.
-- Enhanced header sanitization to handle variations (e.g., "X-API-Key" matches "apikey").
-- Improved error messages for state management failures.
-
-### Fixed
-
-- Secrets no longer leak through observability (logs, errors, metrics).
-- Adapter cache properly scoped per instance.
-- Pagination cannot infinite-loop.
-
-### Migration from 1.x
-
-**Required changes:**
-
-1. **Replace constructor with factory method:**
-   ```typescript
-   // ❌ OLD (1.x)
-   const meridian = new Meridian({ ... });
-   
-   // ✅ NEW (2.0.0)
-   const meridian = await Meridian.create({ ... });
-   ```
-
-2. **Add state management configuration:**
-   ```typescript
-   // For local development
-   const meridian = await Meridian.create({
-     ...config,
-     localUnsafe: true, // Required for local dev
-   });
-   
-   // For production/distributed
-   const meridian = await Meridian.create({
-     ...config,
-     mode: "distributed",
-     stateStorage: new YourStateStorage(), // Required
-   });
-   ```
-
-3. **Ensure Node.js ≥18.0.0** (now enforced via `engines` field)
+- `DriftDetector.detect()` now recursively compares nested schemas (previously top-level only)
+- `ResponseContext` gains optional `trace?: RequestTrace` for observability adapter use
 
-4. **Update TypeScript types:** `ProviderClient` methods now use strict `RequestOptions` instead of `any`
-
-## [0.1.3] - 2026-05-31
-
-### Added
-- **Razorpay adapter** (`src/providers/razorpay/`) — full `ProviderAdapter` implementation for India's largest payment gateway
-  - Basic auth with `key_id:key_secret` (supports `username`/`password` or `apiKey`/`custom.keySecret`)
-  - `X-Idempotency-Key` header support on write operations
-  - Error mapping: 400/422→validation, 401/403→auth, 404→validation, 429→rate_limit, 5xx→provider (retryable)
-  - Offset-based pagination via Razorpay's `items[]`/`count`/`skip` list format
-  - Idempotency config for orders, payments, refunds, transfers, payouts, subscriptions, invoices
-  - 31 contract tests covering all adapter methods
-- Registered 17 additional Indian provider adapters in the built-in registry (Cashfree, PayU, Juspay, MSG91, Exotel, Gupshup, Setu, Decentro, Shiprocket, Delhivery, HyperVerge, Digio, Karza, IDfy, Cleartax, MapMyIndia, Perfios) — implementations pending
-- `ROADMAP.md` — comprehensive future plan covering Indian and international provider coverage, SDK capabilities (webhook verification, streaming, mock adapter, batch operations, India compliance mode, UPI helpers), and version targets through v1.0
-
-## [Unreleased]
-
-### Added
-- Auto-registration of built-in provider adapters
-- Configuration validation for rate limit, retry, circuit breaker, and timeout settings
-- Fallback error handling when adapter `parseError()` throws unexpectedly
-
-### Fixed
-- Removed circular self-dependency in package.json that caused installation failures
-- Fetch timeout now properly cancels requests using `AbortController` (prevents resource leaks)
-- GitHub 403 errors now correctly distinguished between rate limit and permission denied
-- Adapter validation now runs in production (logs warning instead of throwing)
-
-### Changed
-- Improved type safety: `authToken` parameter now uses `AuthToken` type instead of `any`
-
-## [1.0.2] - 2024-01-XX
-
-### Fixed
-- Constructor now supports both nested and flat provider config structures
-- GitHub adapter auto-registers when provider is configured
-
-## [1.0.1] - 2024-01-XX
-
-### Fixed
-- TypeScript strict mode compatibility issues
-- Optional property handling in exactOptionalPropertyTypes mode
-
-## [1.0.0] - 2024-01-XX
-
-### Added
-- Core request pipeline with unified response normalization
-- Circuit breaker implementation with state machine
-- Rate limiting with token bucket and adaptive backoff
-- Retry strategy with exponential backoff and idempotency awareness
-- Idempotency resolver with SAFE/IDEMPOTENT/CONDITIONAL/UNSAFE levels
-- Schema validation with pluggable storage and drift detection
-- Observability adapter pattern with console and no-op implementations
-- GitHub provider adapter with OAuth support
-- Pagination normalization for cursor and offset-based strategies
-- Error normalization with unified error contract
-- TypeScript strict mode with full type safety
-
-[Unreleased]: https://github.com/Raghaverma/Meridian/compare/v1.0.2...HEAD
-[1.0.2]: https://github.com/Raghaverma/Meridian/compare/v1.0.1...v1.0.2
-[1.0.1]: https://github.com/Raghaverma/Meridian/compare/v1.0.0...v1.0.1
-[1.0.0]: https://github.com/Raghaverma/Meridian/releases/tag/v1.0.0
+---
 
+## [0.2.3] — SDK Prototype
 
+- 39 provider adapters with unified contract
+- Normalized responses, errors, pagination, rate limits
+- Circuit breaker, retry, rate limiting
+- Webhook verification
+- Contract testing suite (19 invariants per adapter)
+- Streaming (SSE) for OpenAI, Anthropic, Gemini, Mistral, Cohere
+- Batch requests with concurrency control
+- India compliance mode (DPDPA PII redaction)
+- Proxy server (`boundary-proxy`)
+- Observability adapters: Console, NoOp, OpenTelemetry, Prometheus