meridianjs 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -101,6 +101,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 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

package/README.md

@@ -1,6 +1,22 @@
-# Meridian
 
-A TypeScript SDK that normalizes third-party API interactions through a unified request pipeline, enforcing consistent error handling, rate limiting, and response shapes across providers.
+<div align="center">
+Meridian
+
+**One SDK. Every API. Zero inconsistency.**
+
+A TypeScript-first SDK that enforces a single stable contract across all third-party API providers — normalizing error handling, rate limiting, pagination, and response shapes so your application code never changes when providers do. Deep coverage of the Indian tech ecosystem alongside global providers.
+
+[![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/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Tests](https://img.shields.io/badge/tests-661%20passing-brightgreen)](https://vitest.dev)
+[![Adapters](https://img.shields.io/badge/adapters-31-blueviolet)](#provider-coverage)
+
+[Installation](#installation) · [Quick Start](#quick-start) · [Providers](#provider-coverage) · [Architecture](#architecture) · [API](#public-api) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+
+</div>
 
 ## Problem Statement
 
@@ -8,15 +24,16 @@ Applications integrating multiple third-party APIs face inconsistent response fo
 
 Meridian provides a single abstraction layer that normalizes these differences, allowing applications to interact with any provider through a consistent interface while maintaining type safety and resilience patterns.
 
-## Non-Goals
+```typescript
+// Same interface. Every provider. Always.
+const { data, meta } = await meridian.provider("razorpay").get("/v1/payments/pay_123");
+console.log(meta.rateLimit.remaining); // normalized from any provider
+console.log(meta.provider);            // "razorpay"
+```
 
-- UI components or dashboards
-- API mocking or stubbing frameworks
-- Request recording or replay functionality
-- GraphQL support (v1)
-- Webhook handling (v1)
-- Multi-region routing
-- Built-in caching (applications can layer caching on top)
+If Razorpay changes their error format tomorrow, you don't change a line of your code.
+
+---
 
 ## Installation
 
@@ -24,153 +41,497 @@ Meridian provides a single abstraction layer that normalizes these differences,
 npm install meridianjs
 ```
 
-## Requirements
-
-- **Node.js ≥18.0.0** (required for `fetch`, `Headers`, `AbortController`, `crypto.randomUUID`)
+**Requires Node.js ≥ 18.0.0** (`fetch`, `Headers`, `AbortController`, `crypto.randomUUID` used natively — no polyfills needed).
 
-## Usage
+---
 
-**IMPORTANT**: Meridian requires async initialization. Always use `Meridian.create()`:
+## Quick Start
 
 ```typescript
 import { Meridian } from "meridianjs";
 
-// ✅ CORRECT: Async initialization
 const meridian = await Meridian.create({
+  localUnsafe: true, // for local dev — see State Management for production
+  razorpay: {
+    auth: {
+      username: process.env.RAZORPAY_KEY_ID,
+      password: process.env.RAZORPAY_KEY_SECRET,
+    },
+  },
   github: {
     auth: { token: process.env.GITHUB_TOKEN },
   },
-  localUnsafe: true, // Required for local development without StateStorage
 });
 
-const { data, meta } = await meridian.github.get("/users/octocat");
-console.log(meta.rateLimit.remaining);
+// Payments
+const order = await meridian.provider("razorpay").post("/v1/orders", {
+  body: { amount: 50000, currency: "INR" },
+});
+
+// Paginate automatically — cursors handled for you
+for await (const page of meridian.provider("razorpay").paginate("/v1/payments")) {
+  console.log(page.data.items);
+}
 ```
 
-**❌ NEVER use `new Meridian()`** - the constructor is private and will fail.
+Every response has the same shape, regardless of provider:
 
-### Production Deployment
+```typescript
+{
+  data: T,
+  meta: {
+    provider: string,
+    requestId: string,
+    rateLimit: { limit: number, remaining: number, reset: Date },
+    pagination?: { hasNext: boolean, cursor?: string },
+    warnings: string[],
+  }
+}
+```
 
-For distributed deployments (serverless, multiple instances), you **must** provide a `StateStorage` implementation:
+---
 
-```typescript
-import { Meridian } from "meridianjs";
-import { RedisStateStorage } from "./your-redis-storage.js";
+## Provider Coverage
+
+31 adapters, fully implemented and contract-tested (661 tests).
+
+### Global
+
+| Provider | Category | Auth |
+| --- | --- | --- |
+| **GitHub** | Developer Tools | Bearer token |
+| **Anthropic** | AI / LLM | `x-api-key` header |
+| **OpenAI** | AI / LLM | Bearer token |
+| **Stripe** | Payments | Basic (`key:`) · ✅ webhook |
+| **Twilio** | Communications | Basic (`SID:AuthToken`) · ✅ webhook |
+| **SendGrid** | Communications | Bearer token · ✅ webhook |
+| **Mailgun** | Communications | Basic (`api:key`) · ✅ webhook |
+| **Vonage** | Communications | Query parameter (`api_key:api_secret`) · ✅ webhook |
+| **Adyen** | Payments | Basic (`apiKey:`) · ✅ webhook |
+| **Google Gemini** | AI / LLM | Bearer token / `x-goog-api-key` |
+| **Auth0** | Auth / Identity | Bearer token |
+| **HubSpot** | CRM | Bearer token |
+| **Supabase** | Databases | Bearer token / `apikey` |
+
+### India — Payments
+
+| Provider | Auth | Webhook |
+| --- | --- | --- |
+| **Razorpay** | Basic (`key_id:key_secret`) | ✅ HMAC-SHA256 |
+| **Cashfree** | `x-client-id` + `x-client-secret` | ✅ HMAC-SHA256 |
+| **PayU** | Basic (`key:salt`) | ✅ HMAC-SHA512 |
+| **Juspay** | Basic (`apiKey:`) | ✅ HMAC-SHA256 |
+
+### India — Communications
+
+| Provider | Auth | Key Endpoints |
+| --- | --- | --- |
+| **MSG91** | `authkey` header | SMS, OTP, WhatsApp, Email · ✅ webhook |
+| **Exotel** | Basic (`SID:APIKey`) | Calls, SMS, Virtual Numbers · ✅ webhook |
+| **Gupshup** | `apikey` header | WhatsApp Business, SMS · ✅ webhook |
+
+### India — Banking / Fintech
+
+| Provider | Auth | Key Endpoints |
+| --- | --- | --- |
+| **Setu** | Bearer token | AA consent, UPI, BBPS |
+| **Decentro** | `clientId\|clientSecret\|moduleSecret` | KYC, UPI, Virtual Accounts |
+| **Perfios** | `x-api-key` header | Bank statement analysis, ITR |
+
+### India — Logistics
+
+| Provider | Auth | Key Endpoints |
+| --- | --- | --- |
+| **Shiprocket** | Bearer JWT | Orders, Shipments, Tracking, NDR |
+| **Delhivery** | Bearer token | Waybills, Tracking, COD |
+
+### India — KYC / Identity / eSign
+
+| Provider | Auth | Key Endpoints |
+| --- | --- | --- |
+| **HyperVerge** | `appId\|appKey` headers | Face match, Liveness, OCR |
+| **Digio** | Basic (`clientId:clientSecret`) | eSign, eStamp, Documents |
+| **Karza** | `x-karza-key` header | PAN, GST, Bank verify, ITR |
+| **IDfy** | `api-key` + `account-id` headers | Identity checks, Background verify |
+
+### India — Tax / Compliance / Maps
+
+| Provider | Auth | Key Endpoints |
+| --- | --- | --- |
+| **Cleartax** | `x-cleartax-auth-token` | GST filing, e-invoicing, IRN |
+| **MapMyIndia** | Bearer token | Geocode, Directions, Places |
+
+> **Planned next:** BillDesk, Freshworks, Signzy — see [ROADMAP.md](ROADMAP.md)
+
+---
+
+## Architecture
+
+### Request Flow
+
+```mermaid
+flowchart TD
+    App(["🖥️ Your Application\nmeridian.provider('x').post(...)"])
+
+    subgraph SDK["Meridian SDK"]
+        direction TB
+
+        subgraph Pipeline["Request Pipeline"]
+            direction LR
+            RL["🪣 Rate Limiter\nToken bucket + adaptive backoff"]
+            CB["⚡ Circuit Breaker\nClosed / Open / Half-open"]
+            IK["🔑 Idempotency Resolver\nSAFE / CONDITIONAL / IDEMPOTENT"]
+            RT["🔄 Retry Strategy\nExp. backoff + jitter"]
+            AU["🔐 Auth Strategy\nauthStrategy(config)"]
+            BQ["🔧 Build Request\nbuildRequest(input)"]
+            RL --> CB --> IK --> RT --> AU --> BQ
+        end
+
+        subgraph Adapters["Provider Adapters (22)"]
+            direction LR
+            PAY["💳 Payments\nRazorpay · Cashfree · PayU · Juspay · Stripe"]
+            COM["📱 Communications\nMSG91 · Exotel · Gupshup"]
+            FIN["🏦 Banking / Fintech\nSetu · Decentro · Perfios"]
+            LOG["📦 Logistics\nShiprocket · Delhivery"]
+            KYC["🪪 KYC / Identity\nHyperVerge · Digio · Karza · IDfy"]
+            TAX["🧾 Tax / Maps\nCleartax · MapMyIndia"]
+            GLB["🌐 Global\nGitHub · OpenAI · Anthropic"]
+        end
+
+        OBS["📊 Observability\nlogRequest · logResponse · logError · recordMetric"]
+        STATE[("💾 State Storage\nCircuit breaker · Rate limiter\nRedis / In-memory")]
+    end
+
+    EXT[["🌍 External APIs"]]
+    RES(["✅ NormalizedResponse&lt;T&gt;\n{ data, meta: { provider, rateLimit, pagination } }"])
+    ERR(["❌ MeridianError\n{ category, retryable, status, provider }"])
+
+    App --> RL
+    BQ --> Adapters
+    Adapters -->|fetch| EXT
+    EXT -->|raw response| Adapters
+    Adapters -->|parseResponse| RES
+    Adapters -->|parseError| ERR
+    Pipeline <-->|log + metrics| OBS
+    CB <-->|read/write| STATE
+    RL <-->|read/write| STATE
+```
+
+### Pipeline Stages
+
+```text
+  Your Code
+      │
+      ▼
+  ┌───────────────────────────────────────────────────────────────────┐
+  │                        Request Pipeline                           │
+  │                                                                   │
+  │  ① Rate Limiter          ② Circuit Breaker      ③ Idempotency   │
+  │  ┌─────────────┐         ┌───────────────┐      ┌─────────────┐   │
+  │  │ Token bucket│         │ CLOSED        │      │ Resolve or  │   │
+  │  │ Adaptive    │────────►│ OPEN          │─────►│ generate    │   │
+  │  │ backoff     │         │ HALF_OPEN     │      │ key         │   │
+  │  └─────────────┘         └───────────────┘      └─────────────┘   │
+  │                                                        │          │
+  │  ④ Retry Strategy        ⑤ Auth Strategy    ⑥ Build Request     │
+  │  ┌─────────────┐         ┌───────────────┐  ┌──────────────────┐  │
+  │  │ Exp backoff │         │ authStrategy()│  │ buildRequest()   │  │
+  │  │ + jitter    │◄────────│ → AuthToken   │  │ URL · headers    │  │
+  │  │ retryable?  │         └───────────────┘  │ body · auth      │  │
+  │  └─────────────┘                            └──────────────────┘  │
+  └──────────────────────────────────────────────────┬────────────────┘
+                                                     │
+                                          ┌──────────▼───────────┐
+                                          │   Provider Adapter   │
+                                          │  buildRequest()      │
+                                          │  parseResponse()     │
+                                          │  parseError()        │
+                                          │  rateLimitPolicy()   │
+                                          │  paginationStrategy()│
+                                          └──────────┬───────────┘
+                                                     │ fetch()
+                                                     ▼
+                                               External API
+                                                     │
+                                    ┌────────────────┴────────────────┐
+                                    ▼                                  ▼
+                          NormalizedResponse<T>                 MeridianError
+                          { data, meta: {                       { category,
+                            provider, requestId,                  retryable,
+                            rateLimit, pagination } }              provider, status }
+```
 
+### Multi-Provider Isolation
+
+```text
+┌──────────────────────────────────────────────────────────────────┐
+│                       Meridian Instance                          │
+│                                                                  │
+│  provider("razorpay")   ──► [ CB ] [ RL ] ──► RazorpayAdapter    │
+│  provider("cashfree")   ──► [ CB ] [ RL ] ──► CashfreeAdapter    │
+│  provider("karza")      ──► [ CB ] [ RL ] ──► KarzaAdapter       │
+│  provider("shiprocket") ──► [ CB ] [ RL ] ──► ShiprocketAdapter  │
+│  provider("github")     ──► [ CB ] [ RL ] ──► GitHubAdapter      │
+│                                                                  │
+│  CB = Circuit Breaker (independent per provider)                 │
+│  RL = Rate Limiter    (independent per provider)                 │
+│                                                                  │
+│  One provider tripping its circuit breaker never affects others. │
+└──────────────────────────────────────────────────────────────────┘
+                │                              │
+                ▼                              ▼
+      StateStorage (Redis)            Observability Adapters
+      circuit breaker state           Console / OTel / Prometheus
+      rate limiter state              logs · metrics · traces
+```
+
+---
+
+## Usage Examples
+
+### Cashfree Payment Order
+
+```typescript
 const meridian = await Meridian.create({
-  mode: "distributed",
-  stateStorage: new RedisStateStorage(redisClient), // Required in distributed mode
-  github: {
-    auth: { token: process.env.GITHUB_TOKEN },
+  localUnsafe: true,
+  cashfree: {
+    auth: {
+      custom: {
+        clientId: process.env.CASHFREE_CLIENT_ID,
+        clientSecret: process.env.CASHFREE_CLIENT_SECRET,
+      },
+    },
+  },
+});
+
+const order = await meridian.provider("cashfree").post("/pg/orders", {
+  body: {
+    order_amount: 100.00,
+    order_currency: "INR",
+    customer_details: { customer_id: "user_123", customer_phone: "9999999999" },
   },
+  idempotencyKey: "order-xyz-123",
 });
 ```
 
-**Without `stateStorage` in distributed mode, startup will fail.** This is intentional - in-memory state cannot be shared across instances.
+### Karza PAN Verification
 
-### Local Development
+```typescript
+const result = await meridian.provider("karza").post("/v3/pan/verify", {
+  body: { pan: "ABCDE1234F", consent: "Y" },
+});
+```
 
-For local development, explicitly opt-in to unsafe in-memory state:
+### Webhook Verification
+
+```typescript
+import { CashfreeAdapter, PayuAdapter } from "meridianjs";
+
+// Cashfree — HMAC-SHA256, base64
+const cfAdapter = new CashfreeAdapter();
+const isValid = cfAdapter.verifyWebhook(
+  req.rawBody,
+  req.headers["x-webhook-signature"],
+  process.env.CASHFREE_WEBHOOK_SECRET
+);
+
+// PayU — HMAC-SHA512, hex
+const payuAdapter = new PayuAdapter();
+const isValid = payuAdapter.verifyWebhook(
+  req.rawBody,
+  req.headers["x-verify"],
+  process.env.PAYU_SALT
+);
+```
+
+### Unified Error Handling
+
+```typescript
+import { MeridianError } from "meridianjs";
+
+try {
+  const result = await meridian.provider("razorpay").post("/v1/orders", { body: { ... } });
+} catch (err) {
+  if (err instanceof MeridianError) {
+    switch (err.category) {
+      case "auth":       // bad credentials — do not retry
+        break;
+      case "rate_limit": // check err.retryAfter for when to retry
+        break;
+      case "validation": // bad request — fix the payload
+        break;
+      case "provider":   // upstream 5xx — safe to retry (err.retryable === true)
+        break;
+      case "network":    // connection issue — safe to retry
+        break;
+    }
+  }
+}
+```
+
+---
+
+## State Management
+
+### Local Development
 
 ```typescript
 const meridian = await Meridian.create({
-  mode: "local", // or omit mode
-  localUnsafe: true, // Explicitly acknowledge unsafe state
-  github: {
-    auth: { token: process.env.GITHUB_TOKEN },
-  },
+  localUnsafe: true, // in-memory — fine for dev, never for production
+  razorpay: { auth: { ... } },
 });
 ```
 
-**Warning**: `localUnsafe: true` means circuit breaker and rate limiter state will be lost on process restart. This is acceptable for development but **must not be used in production**.
+### Production (Serverless / Distributed)
 
-## Safety Guarantees
+```typescript
+import { RedisStateStorage } from "./your-redis-storage.js";
 
-Meridian enforces safety by default:
+const meridian = await Meridian.create({
+  mode: "distributed",
+  stateStorage: new RedisStateStorage(redisClient), // required — startup fails without it
+  razorpay: { auth: { ... } },
+});
+```
+
+**Without `stateStorage` in distributed mode, startup will fail.** Circuit breaker and rate limiter state reset on every cold start without it — acceptable for dev, a bug in production.
 
-1. **Fail-Fast Initialization**: SDK cannot be used before initialization completes. All methods throw if called before `Meridian.create()` resolves.
+---
 
-2. **Fail-Closed State Management**: Distributed mode requires `StateStorage`. In-memory state is opt-in only via `localUnsafe: true`.
+## Safety Guarantees
 
-3. **Guaranteed Secret Redaction**: All observability paths (logs, errors, metrics) automatically redact sensitive fields: `authorization`, `cookie`, `token`, `apiKey`, `api_key`, `body`.
+| Guarantee | Behaviour |
+| --- | --- |
+| **Fail-fast init** | All methods throw if called before `Meridian.create()` resolves |
+| **Fail-closed state** | `distributed` mode requires `StateStorage` — startup fails without it |
+| **Secret redaction** | `authorization`, `cookie`, `token`, `apiKey` auto-redacted in all logs, errors, and metrics |
+| **No silent degradation** | Invalid configs fail at startup; adapter validation failures are explicit |
+| **Pagination safety** | Cycle detection + 1000-page hard limit prevent infinite loops |
 
-4. **No Silent Degradation**: Runtime failures are explicit. Invalid configurations fail at startup. Adapter validation failures stop initialization.
+---
 
 ## Public API
 
-### Meridian Class
+### `Meridian.create(config)`
 
-- `static create(config: MeridianConfig, adapters?: Map<string, ProviderAdapter>): Promise<Meridian>` - **Use this to create instances**
-- `getCircuitStatus(provider: string): CircuitBreakerStatus | null`
-- `registerProvider(name: string, adapter: ProviderAdapter, config: ProviderConfig): Promise<void>`
+```typescript
+const meridian = await Meridian.create({
+  razorpay: { auth: { username: "...", password: "..." } },
+  github:   { auth: { token: "..." } },
+
+  defaults: {
+    retry:          { maxRetries: 3, baseDelay: 100, maxDelay: 5000, jitter: true },
+    circuitBreaker: { failureThreshold: 5, timeout: 30000 },
+    rateLimit:      { tokensPerSecond: 10, maxTokens: 100 },
+    timeout:        10000,
+  },
+
+  observability: new ConsoleObservability(),
+  compliance:    { piiRedaction: true, auditLog: true },
+  mode:          "distributed",
+  stateStorage:  new RedisStateStorage(client),
+});
+```
 
 ### Provider Client
 
-Each configured provider exposes a client with:
+```typescript
+const client = meridian.provider("razorpay");
+
+client.get<T>(endpoint, options?)     // GET
+client.post<T>(endpoint, options?)    // POST
+client.put<T>(endpoint, options?)     // PUT
+client.patch<T>(endpoint, options?)   // PATCH
+client.delete<T>(endpoint, options?)  // DELETE
+client.paginate<T>(endpoint, options?) // AsyncGenerator — auto-follows cursors
+```
+
+### `MeridianError`
 
-- `get<T>(endpoint: string, options?: RequestOptions): Promise<NormalizedResponse<T>>`
-- `post<T>(endpoint: string, options?: RequestOptions): Promise<NormalizedResponse<T>>`
-- `put<T>(endpoint: string, options?: RequestOptions): Promise<NormalizedResponse<T>>`
-- `patch<T>(endpoint: string, options?: RequestOptions): Promise<NormalizedResponse<T>>`
-- `delete<T>(endpoint: string, options?: RequestOptions): Promise<NormalizedResponse<T>>`
-- `paginate<T>(endpoint: string, options?: RequestOptions): AsyncGenerator<NormalizedResponse<T>>`
+```typescript
+error.category   // "auth" | "rate_limit" | "network" | "validation" | "provider"
+error.code       // "AUTH_FAILED" | "RATE_LIMITED" | "NOT_FOUND" | "BAD_REQUEST" | "UPSTREAM_5XX" | "NETWORK_ERROR" | "UNKNOWN"
+error.retryable  // boolean
+error.provider   // "razorpay" | "cashfree" | "github" | ...
+error.status     // HTTP status if applicable
+error.retryAfter // Date — present on rate_limit errors
+error.metadata   // sanitized provider context
+```
 
-## Claw Code Integration (Agent Proxy)
+---
 
-Meridian ships a built-in HTTP proxy that lets AI agents (such as [Claw Code](https://github.com/instructkr)) route all outbound API calls through the Meridian pipeline automatically — rate limiting, circuit breaking, and secret redaction apply to every request without any changes to the agent runtime.
+## Agent Proxy
 
-### Start the proxy
+Meridian ships a built-in HTTP proxy for AI agents and LLM runtimes — rate limiting, circuit breaking, and secret redaction apply automatically to every request.
 
 ```bash
-# After installing meridianjs
+export RAZORPAY_KEY_ID="rzp_live_..."  RAZORPAY_KEY_SECRET="..."
 export GITHUB_TOKEN="ghp_..."
-export ANTHROPIC_API_KEY="sk-ant-..."
-export OPENAI_API_KEY="sk-..."
 export STRIPE_SECRET_KEY="sk_live_..."
 
-npx boundary-proxy          # listens on http://127.0.0.1:4242
-npx boundary-proxy 8080     # custom port
-BOUNDARY_PROXY_PORT=9000 npx boundary-proxy
+npx boundary-proxy       # http://127.0.0.1:4242
+npx boundary-proxy 8080  # custom port
 ```
 
-### Route pattern
+Route pattern: `http://localhost:4242/<provider>/<endpoint>`
 
-```
-http://127.0.0.1:4242/<provider>/<endpoint>
+```text
+GET  /github/repos/octocat/Hello-World  →  api.github.com
+POST /razorpay/v1/orders               →  api.razorpay.com
+GET  /anthropic/v1/messages            →  api.anthropic.com
 ```
 
-| Example | Forwards to |
-|---|---|
-| `GET /github/repos/octocat/Hello-World` | `GET https://api.github.com/repos/octocat/Hello-World` |
-| `POST /anthropic/v1/messages` | `POST https://api.anthropic.com/v1/messages` |
-| `GET /openai/v1/models` | `GET https://api.openai.com/v1/models` |
-| `GET /stripe/v1/customers` | `GET https://api.stripe.com/v1/customers` |
+---
 
-Every response is a `NormalizedResponse<T>` with a consistent `{ data, meta }` shape regardless of provider.
+## Project Status
 
-### Embed programmatically
+**v0.1.3** — 22 adapters, 565 tests, zero TypeScript errors. Core pipeline stable. API surface settled — all additions are additive and non-breaking.
 
-```typescript
-import { BoundaryProxyServer } from "meridianjs";
-
-const proxy = new BoundaryProxyServer({
-  port: 4242,
-  providers: {
-    github:    { token:  process.env.GITHUB_TOKEN },
-    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
-    openai:    { apiKey: process.env.OPENAI_API_KEY },
-    stripe:    { apiKey: process.env.STRIPE_SECRET_KEY },
-  },
-});
+| Milestone | Status |
+| --- | --- |
+| Core pipeline (rate limit, circuit breaker, retry, idempotency) | ✅ Stable |
+| 22 provider adapters (global + Indian ecosystem) | ✅ Stable |
+| Contract test coverage for all adapters | ✅ 565 tests |
+| Webhook verification (Cashfree, PayU, Decentro, Shiprocket) | ✅ Partial |
+| Webhook verification on all remaining adapters | 🔄 Next |
+| Twilio + SendGrid | 📋 v0.2 |
+| Streaming support (OpenAI / Anthropic SSE) | 📋 v0.4 |
+| Mock adapter for testing | 📋 v0.4 |
+| India Compliance Mode (DPDPA) | 📋 v0.5 |
+
+See [ROADMAP.md](ROADMAP.md) for the full plan and version targets.
+
+---
 
-await proxy.start();
-// → [Boundary Proxy] Listening on http://127.0.0.1:4242
+## Non-Goals
+
+- UI components or dashboards
+- API mocking / stubbing (planned v0.4)
+- Request recording or replay
+- GraphQL (planned v1)
+- Multi-region routing
+- Built-in caching (layer it on top)
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/Raghaverma/meridianjs
+npm install
+npm test           # 565 tests
+npm run typecheck  # zero errors
+npm run lint
 ```
 
-## Project Status
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter-building guide, error mapping rules, and PR checklist.
 
-**v0.1.0** - Early release. Core functionality is stable and tested. Provider support includes Anthropic, OpenAI, Stripe, and GitHub out of the box. API may evolve based on real-world feedback before v1.0.
+---
 
 ## License
 
-MIT. See [LICENSE.md](LICENSE.md) for details.
+MIT — see [LICENSE.md](LICENSE.md).
+
+---
+
+Built for the Indian and global developer ecosystem · TypeScript-first · Zero runtime dependencies

package/dist/core/adapter-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-validator.d.ts","sourceRoot":"","sources":["../../src/core/adapter-validator.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EAKrB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAGD,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA+R3B;AAGD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAaf;AAGD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAkBtE"}
+{"version":3,"file":"adapter-validator.d.ts","sourceRoot":"","sources":["../../src/core/adapter-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA+Q3B;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAgBtE"}