meridianjs 0.2.4 → 0.2.7

package/README.md

@@ -4,47 +4,58 @@
 
 **Integration Reliability SDK**
 
-*One interface. Every provider. Built for production.*
+[![npm](https://img.shields.io/npm/v/meridianjs?color=0070f3)](https://www.npmjs.com/package/meridianjs)
+[![version](https://img.shields.io/badge/version-0.2.5-blue)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-1602%20passing-brightgreen)](https://vitest.dev)
+[![adapters](https://img.shields.io/badge/adapters-39-blueviolet)](#providers)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
 
-[![npm version](https://img.shields.io/npm/v/meridianjs?color=0070f3&label=npm)](https://www.npmjs.com/package/meridianjs)
-[![npm downloads](https://img.shields.io/npm/dm/meridianjs?color=0070f3)](https://www.npmjs.com/package/meridianjs)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Version](https://img.shields.io/badge/version-0.2.4-blue)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-1568%20passing-brightgreen)](https://vitest.dev)
-[![Adapters](https://img.shields.io/badge/adapters-39-blueviolet)](#provider-status-matrix)
+One interface for 39 APIs. Automatic failover. Built-in observability. Zero runtime dependencies.
 
 </div>
 
+```bash
+npm install meridianjs
+```
+
 ---
 
-Your application integrates with Stripe, OpenAI, Razorpay, Twilio — and a dozen more.
+## Why Meridian Exists
 
-Each one fails differently. Each one changes silently. Each one has a different error shape, pagination strategy, and rate limit header.
+Every integration team rewrites the same things.
 
-**Meridian sits between your application and every provider.**
+Retries. Pagination. Rate limit parsing. Error normalization. Failover logic.
 
-It normalizes the differences, absorbs the failures, and makes providers swappable without touching your application code.
+They write it once for Stripe. Then again for Razorpay. Then again for OpenAI. The code is never shared because every provider has a different shape.
 
-```
-Your Application
-       │
-       ▼
-   Meridian
-  ┌────┼─────┐
-  ▼    ▼     ▼
-Stripe OpenAI Razorpay  ···  39 providers
-```
+Meridian provides a single reliability layer between your application and third-party APIs. Write your integration once. Every provider gets the same retry behavior, the same error format, the same pagination interface, the same circuit breaker, the same trace data.
+
+The two features that make it more than a wrapper:
 
-When OpenAI goes down, Meridian routes to Anthropic. When Stripe rate-limits you, Meridian backs off and retries. When a provider silently renames a field, Meridian tells you before it breaks production.
+**Service abstraction** — your application calls `service("payments")`, not `provider("stripe")`. Meridian decides which provider handles the request. Your application is never coupled to a specific vendor.
 
-Zero runtime dependencies. Node.js 18+.
+**Schema drift detection** — providers silently change their API responses. Meridian detects the change before it reaches production.
 
 ---
 
-## The Killer Feature: Providers Become Replaceable
+## Architecture
+
+```mermaid
+graph TD
+    App[Your Application] --> M[Meridian]
+    M --> P[Policy Engine]
+    P --> CB[Circuit Breaker]
+    CB --> RL[Rate Limiter]
+    RL --> RT[Retry]
+    RT --> S[Stripe]
+    RT --> O[OpenAI]
+    RT --> R[Razorpay]
+    RT --> More[···36 more]
+```
+
+---
 
-Your application stops naming vendors. Meridian routes, fails over, and recovers — automatically.
+## Quick Start
 
 ```typescript
 import { Meridian } from "meridianjs";
@@ -52,604 +63,218 @@ import { Meridian } from "meridianjs";
 const meridian = await Meridian.create({
   localUnsafe: true,
   providers: {
-    openai:    { auth: { apiKey: process.env.OPENAI_API_KEY } },
-    anthropic: { auth: { apiKey: process.env.ANTHROPIC_API_KEY } },
-    gemini:    { auth: { apiKey: process.env.GEMINI_API_KEY } },
-  },
-  services: {
-    // Your app calls "llm". It never touches "openai" or "anthropic".
-    llm: {
-      providers: ["openai", "anthropic", "gemini"],
-      strategy: "failover",
-    },
+    stripe: { auth: { apiKey: process.env.STRIPE_KEY } },
+    openai: { auth: { apiKey: process.env.OPENAI_KEY } },
   },
 });
 
-// OpenAI outage? Anthropic takes over. No code change. No redeployment.
-const result = await meridian.service("llm")!.post("/v1/chat/completions", {
-  body: { messages: [{ role: "user", content: "Hello" }] },
-});
+const { data, meta } = await meridian.provider("stripe")!.get("/v1/customers");
 
-console.log(result.meta.provider);        // "openai" or "anthropic" — whoever answered
-console.log(result.meta.trace.retries);   // 0, 1, 2 — what it took to get a response
-console.log(result.meta.trace.latency);   // ms end-to-end
+meta.rateLimit.remaining  // always normalized
+meta.pagination?.hasNext  // always normalized
+meta.trace.latency        // ms, always present
+meta.trace.retries        // how many retries
+meta.trace.circuitBreaker // CLOSED | OPEN | HALF_OPEN
 ```
 
-This works across payments, messaging, KYC, logistics — any category where multiple providers exist.
-
 ---
 
-## Install
-
-```bash
-npm install meridianjs
-```
-
----
+## What Meridian Does
 
-## What Meridian Owns
-
-| Problem | Without Meridian | With Meridian |
+| | Without | With |
 |---|---|---|
-| Error handling | Different shape per provider | `MeridianError` — always `category`, `retryable`, `retryAfter` |
-| Rate limits | Parse headers manually per provider | `meta.rateLimit` — always normalized |
-| Pagination | Different cursor/offset/link per provider | `meta.pagination` — always normalized |
-| Retries | Roll your own | Exponential backoff with jitter, idempotency-safe |
-| Circuit breaking | Roll your own | Automatic, per-provider |
-| Provider outage | Your app breaks | Automatic failover to next provider |
-| Request tracing | Nothing | `meta.trace` — latency, retries, circuit state |
-| API drift | Silent production breaks | `meridian.schema.check()` — detect before it breaks |
+| Errors | Different shape per provider | `MeridianError` — always `category`, `retryable`, `retryAfter` |
+| Rate limits | Parse per provider | `meta.rateLimit` — normalized |
+| Pagination | cursor / offset / link per provider | `meta.pagination` — normalized |
+| Retries | Manual | Exponential backoff, idempotency-safe |
+| Circuit breaking | Manual | Automatic, per-provider |
+| Provider outage | App breaks | Automatic failover |
+| API drift | Silent breakage | `meridian.schema.check()` |
 
 ---
 
-## Service Abstraction & Failover
+## Provider Failover
 
-Your application stops knowing which vendor it uses. If OpenAI goes down, Anthropic takes over. No code changes, no deployment.
+Your app calls `"llm"`. It never touches `"openai"` or `"anthropic"` directly.
 
 ```typescript
 const meridian = await Meridian.create({
   localUnsafe: true,
   providers: {
-    openai:    { auth: { apiKey: process.env.OPENAI_API_KEY } },
-    anthropic: { auth: { apiKey: process.env.ANTHROPIC_API_KEY } },
-    gemini:    { auth: { apiKey: process.env.GEMINI_API_KEY } },
+    openai:    { auth: { apiKey: "..." } },
+    anthropic: { auth: { apiKey: "..." } },
+    gemini:    { auth: { apiKey: "..." } },
   },
   services: {
-    llm: {
-      providers: ["openai", "anthropic", "gemini"],
-      strategy: "failover",  // try in order, advance on network/rate/provider errors
-    },
-    payments: {
-      providers: ["stripe", "razorpay"],
-      strategy: "highest-success-rate",  // always routes to healthiest provider
-    },
-    cheapLlm: {
-      providers: ["openai", "anthropic", "gemini"],
-      strategy: "cheapest",
-      costs: { openai: 0.03, anthropic: 0.01, gemini: 0.02 }, // per 1K tokens
-    },
+    llm: { providers: ["openai", "anthropic", "gemini"], strategy: "failover" },
   },
 });
 
-// Your application never touches provider names again
-const result = await meridian.service("llm")!.post("/v1/chat/completions", {
-  body: { model: "gpt-4o", messages: [{ role: "user", content: "Hello" }] },
-});
+await meridian.service("llm")!.post("/v1/chat/completions", { body: { ... } });
 ```
 
-**Routing strategies:**
-
-| Strategy | Behaviour |
-|---|---|
-| `"failover"` | Try providers in order. Advance on `rate_limit`, `network`, or `provider` errors. |
-| `"round-robin"` | Distribute requests evenly across all providers. |
-| `"lowest-latency"` | Route to the fastest provider. Self-calibrates using EWMA over `meta.trace.latency`. |
-| `"cheapest"` | Route to the cheapest provider. Fails over in ascending cost order. |
-| `"highest-success-rate"` | Route to the provider with the best live success rate from `meridian.analytics()`. |
-
----
-
-## Request Trace
-
-Every response carries operational telemetry — no configuration needed:
-
-```typescript
-const result = await meridian.provider("stripe").get("/v1/customers");
-
-console.log(result.meta.trace);
-// {
-//   retries: 2,
-//   latency: 341,          // ms end-to-end including retries
-//   circuitBreaker: "CLOSED",
-//   rateLimitRemaining: 91
-// }
+```mermaid
+sequenceDiagram
+    App->>Meridian: service("llm").post(...)
+    Meridian->>OpenAI: attempt
+    OpenAI-->>Meridian: 503 outage
+    Meridian->>Anthropic: failover
+    Anthropic-->>Meridian: 200 OK
+    Meridian-->>App: result (meta.provider = "anthropic")
 ```
 
----
-
-## Analytics & Health
+**Routing strategies:** `failover` · `round-robin` · `lowest-latency` · `cheapest` · `highest-success-rate` · `weighted` · `geo`
 
 ```typescript
-// After some traffic has flowed through:
-console.log(meridian.analytics());
-// {
-//   stripe:   { requests: 12431, errors: 37, errorRate: "0.3%", avgLatency: 240, p95Latency: 480 },
-//   razorpay: { requests: 8111,  errors: 146, errorRate: "1.8%", avgLatency: 410, p95Latency: 820 },
-//   openai:   { requests: 4200,  errors: 50,  errorRate: "1.2%", avgLatency: 780, p95Latency: 1500 }
-// }
-
-console.log(meridian.health());
-// {
-//   stripe:   { status: "healthy",  successRate: "99.7%", avgLatency: 240, circuitBreaker: "CLOSED" },
-//   razorpay: { status: "degraded", successRate: "98.2%", avgLatency: 410, circuitBreaker: "CLOSED" },
-//   openai:   { status: "down",     successRate: "88.1%", avgLatency: 780, circuitBreaker: "OPEN"   }
-// }
-```
+// weighted: 70% Stripe, 30% Razorpay
+payments: { providers: ["stripe", "razorpay"], strategy: "weighted", weights: { stripe: 70, razorpay: 30 } }
 
-Health thresholds: `>= 99%` → healthy, `>= 95%` → degraded, `< 95%` → down. Circuit breaker state overrides: `OPEN` → down, `HALF_OPEN` → at least degraded.
+// geo: route by region (MERIDIAN_REGION env var)
+payments: { providers: ["razorpay", "stripe"], strategy: "geo", regions: { "ap-south-1": ["razorpay"], "us-east-1": ["stripe"] } }
+```
 
 ---
 
-## Debug Recording & Replay
+## Observability
 
-Record production requests. Replay failures locally.
+Every response includes a trace. No configuration needed.
 
 ```typescript
-meridian.debug.enable();
+result.meta.trace
+// { retries: 2, latency: 341, circuitBreaker: "CLOSED", rateLimitRemaining: 91 }
 
-// Run your application...
-
-const recordings = meridian.debug.recordings();
-// [
-//   {
-//     requestId: "abc-123",
-//     provider: "stripe",
-//     endpoint: "/v1/charges",
-//     method: "POST",
-//     statusCode: 200,
-//     duration: 241,
-//     trace: { retries: 0, latency: 241, circuitBreaker: "CLOSED", rateLimitRemaining: 99 },
-//     options: { method: "POST", body: { amount: 1000, currency: "usd" } }
-//   }
-// ]
-
-// Replay a specific request with identical options:
-const fresh = await meridian.replay("abc-123");
-
-meridian.debug.disable();
-meridian.debug.clear();
+meridian.analytics()
+// { stripe: { requests: 12431, errorRate: "0.3%", avgLatency: 240, p95Latency: 480 } }
+
+meridian.health()
+// { stripe: { status: "healthy", successRate: "99.7%", circuitBreaker: "CLOSED" } }
+
+meridian.cost()
+// { providers: { openai: { requests: 1243, costPerRequest: 0.03, estimatedSpend: 37.29 } },
+//   total: { requests: 1243, estimatedSpend: 37.29 }, since: "2026-06-05T...", currency: "USD" }
 ```
 
 ---
 
 ## Policy Engine
 
-Block requests before they leave your application. Enforce compliance rules at the SDK layer.
+Runs before every request. No network round-trip on block.
 
 ```typescript
-import { Meridian, blockPII, allowedProviders, readOnly, customPolicy } from "meridianjs";
-
-const meridian = await Meridian.create({
-  localUnsafe: true,
-  providers: { openai: { auth: { apiKey: "..." } } },
-  policies: [
-    // Block PII (credit cards, SSNs, emails, Aadhaar, PAN) from reaching OpenAI
-    blockPII(["openai"]),
-
-    // Only allow these providers to be used
-    allowedProviders(["openai", "stripe"]),
-
-    // No write operations to GitHub in this service
-    readOnly(["github"]),
-
-    // Custom policy with your own logic
-    customPolicy("require-tenant-id", (ctx) =>
-      ctx.body && typeof ctx.body === "object" && "tenantId" in ctx.body
-        ? { allow: true }
-        : { allow: false, reason: "tenantId is required in all requests" }
-    ),
-  ],
-});
+import { blockPII, redact, requireFields, denyCountries, allowedProviders, readOnly, customPolicy } from "meridianjs";
+
+policies: [
+  blockPII(["openai"]),                    // blocks credit cards, SSNs, emails, Aadhaar, PAN
+  redact(["user.ssn", "card.number"]),     // redacts fields in-place — request still goes through
+  requireFields(["tenantId"]),             // blocks if required fields missing
+  denyCountries(["KP", "IR"]),            // blocks by ISO 3166-1 country code
+  allowedProviders(["openai", "stripe"]),  // provider whitelist
+  readOnly(["github"]),                    // no writes
+  customPolicy("require-tenant", (ctx) =>
+    "tenantId" in (ctx.body as object)
+      ? { allow: true }
+      : { allow: false, reason: "tenantId required" }
+  ),
+]
 ```
 
-A blocked request throws `MeridianError` with `category: "validation"` containing the policy name and reason. Policies run before the request leaves the process — no network round-trip wasted.
-
-**Built-in policies:**
-
-| Function | Description |
-|---|---|
-| `blockPII(providers?)` | Detects and blocks credit cards, SSNs, emails, phone numbers, Aadhaar, PAN |
-| `allowedProviders(list)` | Only allow requests to the specified providers |
-| `blockedProviders(list)` | Block requests to the specified providers entirely |
-| `readOnly(providers?)` | Block POST, PUT, PATCH, DELETE |
-| `customPolicy(name, fn)` | Define any rule as a function |
-
 ---
 
-## Multi-Provider Transactions
+## Transactions
 
-Coordinate operations across multiple providers. If any step fails, compensating rollbacks run automatically in reverse order.
+Saga pattern. Failed steps trigger compensating rollbacks in reverse order.
 
 ```typescript
-import { Meridian } from "meridianjs";
-
-const stripe  = meridian.provider("stripe")!;
-const sendgrid = meridian.provider("sendgrid")!;
-const hubspot  = meridian.provider("hubspot")!;
-
-const result = await meridian.transaction([
+await meridian.transaction([
   {
     name: "charge",
-    execute: async () =>
-      stripe.post("/v1/charges", { body: { amount: 2000, currency: "usd", source: "tok_visa" } }),
-    rollback: async (r) =>
-      stripe.post(`/v1/charges/${(r.data as any).id}/refund`),
+    execute:  () => stripe.post("/v1/charges", { body: { amount: 2000 } }),
+    rollback: (r) => stripe.post(`/v1/charges/${r.data.id}/refund`),
   },
   {
     name: "email",
-    execute: async () =>
-      sendgrid.post("/v3/mail/send", { body: { to: "user@example.com", subject: "Receipt" } }),
-    // no rollback — can't unsend an email
-  },
-  {
-    name: "crm",
-    execute: async () =>
-      hubspot.post("/crm/v3/objects/contacts", { body: { properties: { email: "user@example.com" } } }),
-    rollback: async (r) =>
-      hubspot.delete(`/crm/v3/objects/contacts/${(r.data as any).id}`),
+    execute: () => sendgrid.post("/v3/mail/send", { body: { ... } }),
   },
 ]);
-
-// { succeeded: ["charge", "email", "crm"], rolledBack: [], results: {...} }
-```
-
-If `crm` fails: charge is refunded, `email` has no rollback (skipped), and `TransactionError` is thrown with `failed`, `succeeded`, `rolledBack`, `rollbackErrors`, and partial `results`.
-
----
-
-## Schema Drift Detection
-
-Snapshot API response schemas and get alerted when providers silently rename or remove fields.
-
-```typescript
-// Baseline today's response:
-const customers = await meridian.provider("stripe")!.get("/v1/customers");
-await meridian.schema.snapshot("stripe", "/v1/customers", customers.data);
-
-// Run again tomorrow (or in CI):
-const latest = await meridian.provider("stripe")!.get("/v1/customers");
-const drifts = await meridian.schema.check("stripe", "/v1/customers", latest.data);
-
-if (drifts.length > 0) {
-  console.error("Stripe API drift detected:");
-  for (const d of drifts) {
-    console.error(`  ${d.severity} ${d.type}: field "${d.field}" changed from ${d.oldValue} → ${d.newValue}`);
-  }
-}
-// ERROR FIELD_REMOVED: field "customer_name" changed from "string" → undefined
-// WARNING REQUIRED_REMOVED: field "name" changed from true → false
 ```
 
-Schemas are stored by default in `.meridian/schemas/` (file system). Configure a custom `SchemaStorage` for cloud storage or databases.
-
----
-
-## Provider Capability Registry
-
-Discover what each provider supports. Build capability-driven routing.
-
-```typescript
-meridian.providers();
-// [
-//   { name: "openai",    capabilities: ["chat", "completions", "embeddings", "streaming", "vision", ...] },
-//   { name: "stripe",    capabilities: ["payments", "subscriptions", "refunds", "invoices", ...] },
-//   { name: "razorpay",  capabilities: ["payments", "upi", "subscriptions", "refunds", ...] },
-// ]
-
-meridian.findProviders({ capability: "streaming" });
-// [{ name: "openai", ... }, { name: "anthropic", ... }, { name: "gemini", ... }, { name: "mistral", ... }]
-
-meridian.findProviders({ capability: "kyc" });
-// [{ name: "hyperverge", ... }, { name: "digio", ... }, { name: "karza", ... }, { name: "idfy", ... }]
-
-meridian.findProviders({ capability: "upi" });
-// [{ name: "razorpay", ... }, { name: "phonepe", ... }, { name: "cashfree", ... }, { name: "setu", ... }]
+```mermaid
+flowchart LR
+    A[charge ✓] --> B[email ✗]
+    B -- failure --> C[rollback: charge]
+    C --> D[TransactionError]
 ```
 
-Custom adapters can declare additional capabilities via the optional `capabilities(): string[]` method.
-
 ---
 
-## Adapter Generator
-
-Scaffold a new provider adapter in under a minute.
-
-```bash
-# From a description:
-npx meridian generate --provider acme --base-url https://api.acme.com --auth bearer
-
-# From an OpenAPI 3.x spec:
-npx meridian generate --provider acme --openapi ./acme-openapi.json
-```
-
-Generates four files in `src/providers/acme/`:
-
-| File | Contents |
-|---|---|
-| `adapter.ts` | Full working adapter with auth, error mapping, rate-limit header parsing |
-| `adapter.test.ts` | 8 tests that pass immediately |
-| `pagination.ts` | Cursor pagination stub with TODO comments |
-| `index.ts` | Barrel export |
-
-**Options:**
-
-| Flag | Description | Default |
-|---|---|---|
-| `--provider` | Provider name (required) | — |
-| `--openapi` | Path to OpenAPI 3.x JSON file | — |
-| `--base-url` | API base URL | `https://api.<name>.com` |
-| `--auth` | Auth type: `apiKey`, `bearer`, `basic`, `oauth2` | `apiKey` |
-| `--output` | Output directory | `src/providers/<name>/` |
-
----
-
-## Error Handling
-
-Every provider error has the same shape — no more per-provider archaeology:
-
-```typescript
-try {
-  const result = await meridian.provider("stripe")!.post("/v1/charges", { body });
-} catch (err) {
-  if (err instanceof MeridianError) {
-    err.category;   // "auth" | "rate_limit" | "validation" | "network" | "provider"
-    err.code;       // "AUTH_FAILED" | "RATE_LIMITED" | "BAD_REQUEST" | "UPSTREAM_5XX" | ...
-    err.retryable;  // boolean — safe to retry?
-    err.retryAfter; // Date | undefined — when to retry
-    err.provider;   // "stripe"
-    err.requestId;  // for support tickets
-  }
-}
-```
-
----
-
-## Circuit Breaker
-
-Each provider has its own circuit breaker. Opens after repeated failures, probes with a single request after a timeout, closes on success.
-
-```typescript
-const status = meridian.getCircuitStatus("stripe");
-// {
-//   state: "CLOSED",    // "CLOSED" | "OPEN" | "HALF_OPEN"
-//   failures: 0,
-//   successes: 12,
-//   lastFailure: null,
-//   nextAttempt: null
-// }
-```
-
----
-
-## Pagination
-
-```typescript
-for await (const page of meridian.provider("stripe")!.paginate("/v1/customers")) {
-  console.log(page.meta.pagination);
-  // { hasNext: true, cursor: "cu_next123", total: 4200 }
-  for (const customer of page.data as Customer[]) {
-    process(customer);
-  }
-}
-```
-
-Works identically for cursor, offset, and link-header pagination — the adapter handles the translation.
-
----
-
-## Streaming
-
-```typescript
-for await (const chunk of meridian.provider("openai")!.stream("/v1/chat/completions", {
-  body: { model: "gpt-4o", messages: [{ role: "user", content: "Hello" }], stream: true },
-})) {
-  process.stdout.write(chunk.data as string);
-}
-```
-
-Supported: OpenAI, Anthropic, Gemini, Mistral, Cohere.
-
----
+## Schema Drift Detection
 
-## Batch Requests
+Snapshot a response. Check later. Get alerted when the provider changes their API silently.
 
 ```typescript
-const results = await meridian.provider("stripe")!.batch([
-  { method: "GET", endpoint: "/v1/customers/cu_1" },
-  { method: "GET", endpoint: "/v1/customers/cu_2" },
-  { method: "GET", endpoint: "/v1/customers/cu_3" },
-], 5); // max 5 concurrent
-
-// Results always in input order. Errors are MeridianError, never thrown.
-```
+await meridian.schema.snapshot("stripe", "/v1/customers", response.data);
 
----
+const drifts = await meridian.schema.check("stripe", "/v1/customers", laterResponse.data);
+// [{ type: "FIELD_REMOVED", field: "customer_name", severity: "ERROR" }]
 
-## Webhook Verification
+await meridian.schema.alert("stripe", "/v1/customers", newData, (drifts, provider, endpoint) => {
+  pagerDuty.trigger(`Schema drift on ${provider}${endpoint}`);
+});
 
-```typescript
-import { StripeAdapter } from "meridianjs";
-
-const adapter = new StripeAdapter();
-const valid = adapter.verifyWebhook(
-  req.rawBody,
-  req.headers["stripe-signature"],
-  process.env.STRIPE_WEBHOOK_SECRET,
-);
+const report = await meridian.schema.report("stripe");
+// { provider: "stripe", endpoints: [{ endpoint: "/v1/customers", fieldCount: 12, version: "..." }] }
 ```
 
-Timing-safe HMAC verification available on Stripe, Razorpay, Cashfree, Braintree, Twilio, Adyen, and more.
-
 ---
 
-## Configuration Reference
+## More Features
 
 ```typescript
-const meridian = await Meridian.create({
-  // Required: either localUnsafe:true or stateStorage
-  localUnsafe: true,                     // dev only — warns on startup
-
-  // Per-provider configuration
-  providers: {
-    stripe: {
-      auth: { apiKey: "sk_live_..." },   // or token, username/password, clientId/Secret
-      baseUrl: "https://api.stripe.com", // override base URL
-      retry: { maxRetries: 3, baseDelay: 1000, maxDelay: 30000, jitter: true },
-      circuitBreaker: { failureThreshold: 5, timeout: 60000, errorThresholdPercentage: 50 },
-      rateLimit: { tokensPerSecond: 10, maxTokens: 100, adaptiveBackoff: true },
-    },
-  },
-
-  // Service abstraction — group providers behind a logical name
-  services: {
-    llm: { providers: ["openai", "anthropic"], strategy: "failover" },
-  },
-
-  // Default settings applied to all providers
-  defaults: {
-    timeout: 30000,
-    retry: { maxRetries: 2 },
-    circuitBreaker: { failureThreshold: 5 },
-  },
-
-  // Policy engine
-  policies: [blockPII(["openai"]), readOnly(["github"])],
-
-  // Observability (any number of adapters)
-  observability: [new ConsoleObservability(), new PrometheusObservability()],
-
-  // Distributed state (required for multi-instance deployments)
-  mode: "distributed",
-  stateStorage: new RedisStateStorage(redisClient),
-
-  // Schema validation & drift detection
-  schemaValidation: {
-    enabled: true,
-    storage: new FileSystemSchemaStorage(".meridian/schemas"),
-    onDrift: (drifts) => alerting.notify(drifts),
-  },
+// Debug & replay
+meridian.debug.enable();
+await meridian.replay(requestId); // re-runs with exact original options
 
-  // Compliance
-  compliance: {
-    piiRedaction: true,   // redacts Aadhaar, PAN, bank accounts from logs
-    indiaMode: true,      // DPDPA-compliant redaction
-    auditLog: true,
-  },
+// Capability registry
+meridian.findProviders({ capability: "streaming" });
+// [{ name: "openai" }, { name: "anthropic" }, { name: "gemini" }, ...]
 
-  // Idempotency
-  idempotency: {
-    defaultLevel: IdempotencyLevel.SAFE,
-    autoGenerateKeys: true,
-  },
-});
-```
+// Adapter generator
+// npx meridian generate --provider acme --openapi ./acme.json
+// → adapter.ts  adapter.test.ts  pagination.ts  index.ts (8 tests pass immediately)
 
----
+// Pagination
+for await (const page of meridian.provider("stripe")!.paginate("/v1/customers")) { ... }
 
-## Provider Status Matrix
+// Streaming (OpenAI, Anthropic, Gemini, Mistral, Cohere)
+for await (const chunk of meridian.provider("openai")!.stream("/v1/chat/completions", { body })) { ... }
 
-Every adapter passes a 19-invariant contract test suite before being listed. Run the suite yourself:
+// Batch
+await meridian.provider("stripe")!.batch([{ method: "GET", endpoint: "/v1/customers/1" }, ...], 5);
 
-```bash
-npm run test:contracts          # all 39 adapters
-npm run test:contracts stripe   # single provider
+// Webhook verification
+new StripeAdapter().verifyWebhook(req.rawBody, req.headers["stripe-signature"], secret);
 ```
 
-| Provider | Category | Contract | Status |
-|:---|:---|:---:|:---:|
-| **Adyen** | Payments | 19/19 | ✅ |
-| **Anthropic** | AI / LLM | 19/19 | ✅ |
-| **Apollo.io** | CRM / Sales | 19/19 | ✅ |
-| **Auth0** | Auth / Identity | 19/19 | ✅ |
-| **Braintree** | Payments | 19/19 | ✅ |
-| **Cashfree** | Payments | 19/19 | ✅ |
-| **Checkout.com** | Payments | 19/19 | ✅ |
-| **Cleartax** | Tax / Compliance | 19/19 | ✅ |
-| **Cohere** | AI / LLM | 19/19 | ✅ |
-| **Decentro** | Banking / Fintech | 19/19 | ✅ |
-| **Delhivery** | Logistics | 19/19 | ✅ |
-| **Digio** | eSign / KYC | 19/19 | ✅ |
-| **Exotel** | Communications | 19/19 | ✅ |
-| **Google Gemini** | AI / LLM | 19/19 | ✅ |
-| **GitHub** | Developer Tools | 19/19 | ✅ |
-| **Gupshup** | Communications | 19/19 | ✅ |
-| **HubSpot** | CRM | 19/19 | ✅ |
-| **HyperVerge** | KYC / Identity | 19/19 | ✅ |
-| **IDfy** | KYC / Identity | 19/19 | ✅ |
-| **Juspay** | Payments | 19/19 | ✅ |
-| **Karza** | KYC / Verification | 19/19 | ✅ |
-| **Klarna** | Payments | 19/19 | ✅ |
-| **Mailgun** | Communications | 19/19 | ✅ |
-| **MapMyIndia** | Maps / Geo | 19/19 | ✅ |
-| **Mistral** | AI / LLM | 19/19 | ✅ |
-| **Mollie** | Payments | 19/19 | ✅ |
-| **MSG91** | Communications | 19/19 | ✅ |
-| **OpenAI** | AI / LLM | 19/19 | ✅ |
-| **PayU** | Payments | 19/19 | ✅ |
-| **Perfios** | Financial Data | 19/19 | ✅ |
-| **PhonePe** | Payments | 19/19 | ✅ |
-| **Razorpay** | Payments | 19/19 | ✅ |
-| **SendGrid** | Communications | 19/19 | ✅ |
-| **Setu** | Banking / UPI | 19/19 | ✅ |
-| **Shiprocket** | Logistics | 19/19 | ✅ |
-| **Stripe** | Payments | 19/19 | ✅ |
-| **Supabase** | Database / Auth | 19/19 | ✅ |
-| **Twilio** | Communications | 19/19 | ✅ |
-| **Vonage** | Communications | 19/19 | ✅ |
-
 ---
 
-## Adding a Provider
+## Providers
 
-Fastest path: use the generator.
+39 adapters, each passing 19 contract invariants. `npm run test:contracts stripe`
 
-```bash
-npx meridian generate --provider myprovider --openapi ./myprovider-openapi.json
-```
-
-Manual path: implement `ProviderAdapter` and register it:
-
-```typescript
-import type { ProviderAdapter } from "meridianjs";
-
-class MyAdapter implements ProviderAdapter {
-  buildRequest(input) { ... }
-  parseResponse(raw)  { ... }
-  parseError(raw)     { ... }
-  authStrategy(cfg)   { ... }
-  rateLimitPolicy(h)  { ... }
-  paginationStrategy(){ ... }
-  getIdempotencyConfig() { ... }
-}
-
-await meridian.registerProvider("myprovider", new MyAdapter(), {
-  auth: { apiKey: process.env.MY_API_KEY },
-});
-```
+| Category | Providers |
+|---|---|
+| **Payments** | Stripe · Razorpay · Cashfree · PayU · Juspay · Braintree · Adyen · Klarna · Mollie · PhonePe · Checkout.com |
+| **AI / LLM** | OpenAI · Anthropic · Gemini · Cohere · Mistral |
+| **Communications** | Twilio · SendGrid · Mailgun · Vonage · MSG91 · Exotel · Gupshup |
+| **KYC / Identity** | HyperVerge · Digio · Karza · IDfy · Setu · Decentro · Perfios |
+| **Tools & Infra** | GitHub · HubSpot · Supabase · Auth0 · Apollo |
+| **Logistics** | Shiprocket · Delhivery |
+| **Other** | MapMyIndia · Cleartax |
 
 ---
 
 ## Contributing
 
-1. Fork → feature branch → PR
-2. Every new adapter requires: `adapter.ts`, `adapter.test.ts`, `pagination.ts`, `index.ts`
-3. All existing contract tests must continue to pass: `npm test`
-4. The adapter generator produces a correct starting point: `npx meridian generate --provider yourprovider`
-
----
-
-## Links
+New adapter: `npx meridian generate --provider name --openapi ./spec.json` → implement TODOs → `npm test`.
 
-- [Changelog](CHANGELOG.md)
-- [License: MIT](LICENSE.md)
-- [npm](https://www.npmjs.com/package/meridianjs)
+[Changelog](CHANGELOG.md) · [License: MIT](LICENSE.md) · [npm](https://www.npmjs.com/package/meridianjs)