meridianjs 0.2.3 → 0.2.5

package/README.md

@@ -2,28 +2,56 @@
 
 # Meridian
 
-**One SDK. Every API. Zero inconsistency.**
+**Integration Reliability SDK**
 
-[![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/)
-[![Tests](https://img.shields.io/badge/tests-1489%20passing-brightgreen)](https://vitest.dev)
-[![Adapters](https://img.shields.io/badge/adapters-39-blueviolet)](#provider-status-matrix)
+[![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)
 
-A TypeScript-first SDK that gives every third-party API the same interface — normalized errors, rate limits, pagination, and response shapes, regardless of provider.
+One interface for 39 APIs. Automatic failover. Built-in observability. Zero runtime dependencies.
 
 </div>
 
----
-
-## Install
-
 ```bash
 npm install meridianjs
 ```
 
-Requires **Node.js ≥ 18**. Zero runtime dependencies.
+---
+
+## Why Meridian Exists
+
+Every integration team rewrites the same things.
+
+Retries. Pagination. Rate limit parsing. Error normalization. Failover logic.
+
+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.
+
+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:
+
+**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.
+
+**Schema drift detection** — providers silently change their API responses. Meridian detects the change before it reaches production.
+
+---
+
+## 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]
+```
 
 ---
 
@@ -33,156 +61,220 @@ Requires **Node.js ≥ 18**. Zero runtime dependencies.
 import { Meridian } from "meridianjs";
 
 const meridian = await Meridian.create({
+  localUnsafe: true,
   providers: {
-    stripe: { auth: { apiKey: process.env.STRIPE_SECRET_KEY } },
-    razorpay: {
-      auth: {
-        username: process.env.RAZORPAY_KEY_ID,
-        password: process.env.RAZORPAY_KEY_SECRET,
-      },
-    },
+    stripe: { auth: { apiKey: process.env.STRIPE_KEY } },
+    openai: { auth: { apiKey: process.env.OPENAI_KEY } },
   },
 });
 
-// Same API for every provider
-const { data, meta } = await meridian.provider("stripe").get("/v1/customers");
+const { data, meta } = await meridian.provider("stripe")!.get("/v1/customers");
 
-console.log(meta.provider);            // "stripe"
-console.log(meta.rateLimit.remaining); // always normalized
-console.log(meta.pagination.hasNext);  // always normalized
+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
 ```
 
-Switch providers — your app code doesn't change.
-
 ---
 
-## What It Does
+## What Meridian Does
 
-| Feature | Description |
-|---|---|
-| **Normalized responses** | Every provider returns `{ data, meta }` with consistent shape |
-| **Typed errors** | `MeridianError` with `category`, `retryable`, `retryAfter` — always |
-| **Auto-retry** | Exponential backoff with jitter on 429s and 5xx errors |
-| **Circuit breaker** | Opens automatically on repeated failures, closes after cooldown |
-| **Rate limit awareness** | Tracks limits from response headers, delays before hitting 429 |
-| **Pagination** | Unified `meta.pagination` across cursor, offset, and link-based strategies |
-| **Webhook verification** | Timing-safe HMAC verification on every payment/comms adapter |
-| **Streaming** | SSE streaming for OpenAI, Anthropic, Mistral, Cohere |
-| **Batch requests** | Fan-out with concurrency control via `.batch()` |
-| **India Compliance** | DPDPA-compliant PII redaction (Aadhaar, PAN, UPI VPA, bank accounts) |
+| | Without | With |
+|---|---|---|
+| 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()` |
 
 ---
 
-## Provider Status Matrix
+## Provider Failover
 
-Every adapter in Meridian is held to the **same** contract — adapters are just data sources, so the guarantees Meridian makes (error normalization, retry semantics, rate-limit parsing, pagination, request shaping) must hold identically across all of them. A single, provider-agnostic suite (`runProviderContract`) runs **19 invariants against every registered adapter** in CI, so a provider is only listed here if it upholds the full contract.
+Your app calls `"llm"`. It never touches `"openai"` or `"anthropic"` directly.
 
-```bash
-npm run test:contracts          # run the contract against all 39 adapters
-npm run test:contracts stripe   # focus a single provider
+```typescript
+const meridian = await Meridian.create({
+  localUnsafe: true,
+  providers: {
+    openai:    { auth: { apiKey: "..." } },
+    anthropic: { auth: { apiKey: "..." } },
+    gemini:    { auth: { apiKey: "..." } },
+  },
+  services: {
+    llm: { providers: ["openai", "anthropic", "gemini"], strategy: "failover" },
+  },
+});
+
+await meridian.service("llm")!.post("/v1/chat/completions", { body: { ... } });
 ```
 
-| Provider | Category | Contract Tests | Status |
-|:---|:---|:---:|:---:|
-| **Adyen** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Anthropic** | AI / LLM | 19/19 Passed | ✅ Production-Ready |
-| **Apollo.io** | CRM / Sales | 19/19 Passed | ✅ Production-Ready |
-| **Auth0** | Auth / Identity | 19/19 Passed | ✅ Production-Ready |
-| **Braintree** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Cashfree** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Checkout.com** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Cleartax** | Tax / Compliance | 19/19 Passed | ✅ Production-Ready |
-| **Cohere** | AI / LLM | 19/19 Passed | ✅ Production-Ready |
-| **Decentro** | Banking / Fintech | 19/19 Passed | ✅ Production-Ready |
-| **Delhivery** | Logistics | 19/19 Passed | ✅ Production-Ready |
-| **Digio** | eSign / KYC | 19/19 Passed | ✅ Production-Ready |
-| **Exotel** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **Google Gemini** | AI / LLM | 19/19 Passed | ✅ Production-Ready |
-| **Gupshup** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **GitHub** | Developer Tools | 19/19 Passed | ✅ Production-Ready |
-| **HubSpot** | CRM | 19/19 Passed | ✅ Production-Ready |
-| **HyperVerge** | KYC / Identity | 19/19 Passed | ✅ Production-Ready |
-| **IDfy** | KYC / Identity | 19/19 Passed | ✅ Production-Ready |
-| **Juspay** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Karza** | KYC / Verification | 19/19 Passed | ✅ Production-Ready |
-| **Klarna** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Mailgun** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **MapMyIndia** | Maps / Geo | 19/19 Passed | ✅ Production-Ready |
-| **Mistral** | AI / LLM | 19/19 Passed | ✅ Production-Ready |
-| **Mollie** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **MSG91** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **OpenAI** | AI / LLM | 19/19 Passed | ✅ Production-Ready |
-| **PayU** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Perfios** | Financial Data | 19/19 Passed | ✅ Production-Ready |
-| **PhonePe** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Razorpay** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **SendGrid** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **Setu** | Banking / UPI | 19/19 Passed | ✅ Production-Ready |
-| **Shiprocket** | Logistics | 19/19 Passed | ✅ Production-Ready |
-| **Stripe** | Payments | 19/19 Passed | ✅ Production-Ready |
-| **Supabase** | Database / Auth | 19/19 Passed | ✅ Production-Ready |
-| **Twilio** | Communications | 19/19 Passed | ✅ Production-Ready |
-| **Vonage** | Communications | 19/19 Passed | ✅ Production-Ready |
+```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")
+```
+
+**Routing strategies:** `failover` · `round-robin` · `lowest-latency` · `cheapest` · `highest-success-rate` · `weighted` · `geo`
+
+```typescript
+// weighted: 70% Stripe, 30% Razorpay
+payments: { providers: ["stripe", "razorpay"], strategy: "weighted", weights: { stripe: 70, razorpay: 30 } }
+
+// geo: route by region (MERIDIAN_REGION env var)
+payments: { providers: ["razorpay", "stripe"], strategy: "geo", regions: { "ap-south-1": ["razorpay"], "us-east-1": ["stripe"] } }
+```
 
 ---
 
-## Error Handling
+## Observability
 
-Every error has the same shape — no more `try/catch` archaeology per provider:
+Every response includes a trace. No configuration needed.
 
 ```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.retryable;  // boolean
-    err.retryAfter; // Date | undefined
-    err.provider;   // "stripe"
-  }
-}
+result.meta.trace
+// { retries: 2, latency: 341, circuitBreaker: "CLOSED", rateLimitRemaining: 91 }
+
+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" }
 ```
 
 ---
 
-## Webhook Verification
+## Policy Engine
+
+Runs before every request. No network round-trip on block.
 
 ```typescript
-import { StripeAdapter } from "meridianjs";
-
-const adapter = new StripeAdapter();
-const valid = adapter.verifyWebhook(
-  req.rawBody,
-  req.headers["stripe-signature"],
-  process.env.STRIPE_WEBHOOK_SECRET,
-);
+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" }
+  ),
+]
 ```
 
-Works identically for Razorpay, Cashfree, Braintree, Twilio, Adyen, and more.
+---
+
+## Transactions
+
+Saga pattern. Failed steps trigger compensating rollbacks in reverse order.
+
+```typescript
+await meridian.transaction([
+  {
+    name: "charge",
+    execute:  () => stripe.post("/v1/charges", { body: { amount: 2000 } }),
+    rollback: (r) => stripe.post(`/v1/charges/${r.data.id}/refund`),
+  },
+  {
+    name: "email",
+    execute: () => sendgrid.post("/v3/mail/send", { body: { ... } }),
+  },
+]);
+```
+
+```mermaid
+flowchart LR
+    A[charge ✓] --> B[email ✗]
+    B -- failure --> C[rollback: charge]
+    C --> D[TransactionError]
+```
 
 ---
 
-## Batch Requests
+## Schema Drift Detection
+
+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
+await meridian.schema.snapshot("stripe", "/v1/customers", response.data);
 
-// Results are always in input order; errors are MeridianError, never thrown
+const drifts = await meridian.schema.check("stripe", "/v1/customers", laterResponse.data);
+// [{ type: "FIELD_REMOVED", field: "customer_name", severity: "ERROR" }]
+
+await meridian.schema.alert("stripe", "/v1/customers", newData, (drifts, provider, endpoint) => {
+  pagerDuty.trigger(`Schema drift on ${provider}${endpoint}`);
+});
+
+const report = await meridian.schema.report("stripe");
+// { provider: "stripe", endpoints: [{ endpoint: "/v1/customers", fieldCount: 12, version: "..." }] }
 ```
 
-## Support & Contact
+---
 
-If you encounter any issues or have questions, please reach out directly at [raghav.verma.work@gmail.com](mailto:raghav.verma.work@gmail.com).
+## More Features
+
+```typescript
+// Debug & replay
+meridian.debug.enable();
+await meridian.replay(requestId); // re-runs with exact original options
+
+// Capability registry
+meridian.findProviders({ capability: "streaming" });
+// [{ name: "openai" }, { name: "anthropic" }, { name: "gemini" }, ...]
+
+// 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")) { ... }
+
+// Streaming (OpenAI, Anthropic, Gemini, Mistral, Cohere)
+for await (const chunk of meridian.provider("openai")!.stream("/v1/chat/completions", { body })) { ... }
+
+// Batch
+await meridian.provider("stripe")!.batch([{ method: "GET", endpoint: "/v1/customers/1" }, ...], 5);
+
+// Webhook verification
+new StripeAdapter().verifyWebhook(req.rawBody, req.headers["stripe-signature"], secret);
+```
+
+---
+
+## Providers
+
+39 adapters, each passing 19 contract invariants. `npm run test:contracts stripe`
+
+| 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 |
 
 ---
 
-## Links
+## Contributing
+
+New adapter: `npx meridian generate --provider name --openapi ./spec.json` → implement TODOs → `npm test`.
 
-- [GitHub](https://github.com/Raghaverma/Meridianjs)
-- [Changelog](CHANGELOG.md)
-- [Roadmap](ROADMAP.md)
-- [License: MIT](LICENSE.md)
+[Changelog](CHANGELOG.md) · [License: MIT](LICENSE.md) · [npm](https://www.npmjs.com/package/meridianjs)

package/dist/analytics/collector.d.ts

@@ -0,0 +1,44 @@
+import type { ErrorContext, Metric, ObservabilityAdapter, RequestContext, ResponseContext } from "../core/types.js";
+export interface ProviderStats {
+    requests: number;
+    errors: number;
+    errorRate: string;
+    successRate: string;
+    avgLatency: number;
+    p95Latency: number;
+}
+export interface HealthEntry {
+    status: "healthy" | "degraded" | "down";
+    successRate: string;
+    avgLatency: number;
+}
+export interface CostEntry {
+    requests: number;
+    costPerRequest: number;
+    estimatedSpend: number;
+}
+export interface CostReport {
+    providers: Record<string, CostEntry>;
+    total: {
+        requests: number;
+        estimatedSpend: number;
+    };
+    since: string;
+    currency: string;
+}
+export declare class AnalyticsCollector implements ObservabilityAdapter {
+    private buckets;
+    private startedAt;
+    logRequest(_ctx: RequestContext): void;
+    logResponse(ctx: ResponseContext): void;
+    logError(ctx: ErrorContext): void;
+    logWarning(): void;
+    recordMetric(_metric: Metric): void;
+    private record;
+    get(): Record<string, ProviderStats>;
+    getHealth(): Record<string, HealthEntry>;
+    private computeStats;
+    getCost(costs: Record<string, number>, currency?: string): CostReport;
+    reset(): void;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/analytics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/analytics/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,oBAAoB,EACpB,cAAc,EACd,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,kBAAmB,YAAW,oBAAoB;IAC7D,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAA4B;IAE7C,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAEtC,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAIvC,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAIjC,UAAU,IAAI,IAAI;IAElB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAEnC,OAAO,CAAC,MAAM;IAWd,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAQpC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAcxC,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,SAAQ,GAAG,UAAU;IAqBpE,KAAK,IAAI,IAAI;CAId"}

package/dist/analytics/collector.js

@@ -0,0 +1,82 @@
+export class AnalyticsCollector {
+    buckets = new Map();
+    startedAt = new Date().toISOString();
+    logRequest(_ctx) { }
+    logResponse(ctx) {
+        this.record(ctx.provider, true, ctx.duration);
+    }
+    logError(ctx) {
+        this.record(ctx.provider, false, ctx.duration);
+    }
+    logWarning() { }
+    recordMetric(_metric) { }
+    record(provider, success, latency) {
+        if (!this.buckets.has(provider)) {
+            this.buckets.set(provider, { requests: 0, errors: 0, latencies: [] });
+        }
+        const b = this.buckets.get(provider);
+        b.requests++;
+        if (!success)
+            b.errors++;
+        b.latencies.push(latency);
+        if (b.latencies.length > 1000)
+            b.latencies.shift();
+    }
+    get() {
+        const out = {};
+        for (const [provider, b] of this.buckets) {
+            out[provider] = this.computeStats(b);
+        }
+        return out;
+    }
+    getHealth() {
+        const out = {};
+        for (const [provider, b] of this.buckets) {
+            const stats = this.computeStats(b);
+            const successPct = Number.parseFloat(stats.successRate);
+            out[provider] = {
+                status: successPct >= 99 ? "healthy" : successPct >= 95 ? "degraded" : "down",
+                successRate: stats.successRate,
+                avgLatency: stats.avgLatency,
+            };
+        }
+        return out;
+    }
+    computeStats(b) {
+        const sorted = [...b.latencies].sort((a, c) => a - c);
+        const avg = sorted.length > 0 ? sorted.reduce((a, c) => a + c, 0) / sorted.length : 0;
+        const p95 = sorted.length > 0 ? (sorted[Math.floor(sorted.length * 0.95)] ?? 0) : 0;
+        const errorRate = b.requests > 0 ? (b.errors / b.requests) * 100 : 0;
+        return {
+            requests: b.requests,
+            errors: b.errors,
+            errorRate: `${errorRate.toFixed(1)}%`,
+            successRate: `${(100 - errorRate).toFixed(1)}%`,
+            avgLatency: Math.round(avg),
+            p95Latency: Math.round(p95),
+        };
+    }
+    getCost(costs, currency = "USD") {
+        const providers = {};
+        let totalRequests = 0;
+        let totalSpend = 0;
+        for (const [provider, b] of this.buckets) {
+            const costPerRequest = costs[provider] ?? 0;
+            const estimatedSpend = b.requests * costPerRequest;
+            providers[provider] = { requests: b.requests, costPerRequest, estimatedSpend };
+            totalRequests += b.requests;
+            totalSpend += estimatedSpend;
+        }
+        return {
+            providers,
+            total: { requests: totalRequests, estimatedSpend: totalSpend },
+            since: this.startedAt,
+            currency,
+        };
+    }
+    reset() {
+        this.buckets.clear();
+        this.startedAt = new Date().toISOString();
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/analytics/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/analytics/collector.ts"],"names":[],"mappings":"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"}

package/dist/analytics/index.d.ts

@@ -0,0 +1,3 @@
+export { AnalyticsCollector } from "./collector.js";
+export type { ProviderStats, HealthEntry } from "./collector.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/analytics/index.js

@@ -0,0 +1,2 @@
+export { AnalyticsCollector } from "./collector.js";
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,3 @@
+export { PROVIDER_CAPABILITIES } from "./registry.js";
+export type { ProviderInfo } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/capabilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/capabilities/index.js

@@ -0,0 +1,2 @@
+export { PROVIDER_CAPABILITIES } from "./registry.js";
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/capabilities/registry.d.ts

@@ -0,0 +1,6 @@
+export declare const PROVIDER_CAPABILITIES: Record<string, string[]>;
+export interface ProviderInfo {
+    name: string;
+    capabilities: string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/capabilities/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/capabilities/registry.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAqE1D,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB"}