Meridian

One contract. Every API.

Stripe returns {"error":{"type":"..."}}. OpenAI returns {"error":{"message":"..."}}. Razorpay returns something else entirely. Meridian normalizes all of it — errors, rate limits, pagination, retries — so your application never has to care which provider is behind a call.

npm install meridianjs

TypeScript-first · ESM · Node ≥ 20 · zero required runtime dependencies

The problem

Every third-party API has its own convention for rate-limit headers, pagination cursors, error codes, and retry signals. You end up writing the same glue code for every new provider — and when one goes down, your app goes down with it.

Meridian is a single layer between your app and every provider. You get the same normalized response shape, the same error type, the same retry and failover behavior — no matter which API is behind the call.

Quick start

import { Meridian } from "meridianjs";

const meridian = await Meridian.create({
  localUnsafe: true,
  providers: {
    openai:    { auth: { apiKey: process.env.OPENAI_KEY } },
    anthropic: { auth: { apiKey: process.env.ANTHROPIC_KEY } },
  },
});

// Define a service — your app calls "llm", never "openai" or "anthropic" directly.
const llm = meridian.service("llm", ["openai", "anthropic"]);

// OpenAI goes down at 2am. Meridian fails over to Anthropic in ~27ms.
// Your app doesn't change. Your on-call doesn't wake up.
const { data, meta } = await llm.post("/v1/chat/completions", { body: { ... } });

meta.rateLimit.remaining   // always normalized — same field, every provider
meta.pagination?.hasNext   // same
meta.trace.latency         // ms, always present
meta.trace.retries         // how many retries were needed
meta.trace.circuitBreaker  // CLOSED | OPEN | HALF_OPEN

Errors are always a MeridianError with .category, .retryable, and .retryAfter — no more parsing provider-specific shapes to decide whether to retry.

What Meridian normalizes

| | Raw providers | Through Meridian | |---|---|---| | Errors | Different shape per provider | MeridianError — always category, retryable, retryAfter | | Rate limits | Parse per provider | meta.rateLimit.remaining — always present | | Pagination | cursor / offset / link-header per provider | meta.pagination.hasNext — always present | | Retries | Write per provider | Exponential backoff, idempotency-safe, per-adapter classification | | Circuit breaking | Build yourself | Automatic, per-provider, wraps the retry loop | | Provider outage | Your app breaks | Automatic failover to the next healthy provider | | API drift | Silent breakage | meridian.schema.check() catches it before prod |

Features

Reliability

• Failover — define a service with ordered fallback providers; Meridian routes around outages automatically
• Retries — per-adapter classification of what's retryable; exponential backoff with full idempotency safety
• Rate limiting — token-bucket per provider with adaptive backoff; shared cooldown across all replicas via RedisStateStorage so a 429 on one process backs off the whole fleet
• Circuit breaker — per-provider; wraps the retry loop so 3 retries count as one logical failure, not three
• Transactions — multi-provider sagas with compensating rollbacks

Observability & compliance

• OpenTelemetry — one-line auto-instrumentation; exporter recipes for Datadog, Grafana, Honeycomb, New Relic
• Schema drift detection — snapshot provider contracts and gate CI on breaking changes
• Contract registry — versioned snapshots under .meridian/registry/, designed to be committed to git
• Reliability replay — record outage timelines and re-render them locally for post-mortems
• Policy engine — blockPII, redact, denyCountries, allowedProviders, readOnly run before every request; no network round-trip on block
• India / fintech — 13 Indian payment adapters, UPI helpers, Aadhaar/PAN/VPA redaction, DPDPA compliance mode

Language support

• Polyglot — docker compose up -d starts the gRPC engine; pre-built clients for Go, Rust, and Python get all 47 providers with no Node.js on the host
• CLI — meridian add <provider> --openapi ./spec.json generates a fully-tested adapter from an OpenAPI spec
• Pagination — cursor, offset, and link-header strategies; meta.pagination is always the same shape

Polyglot

One engine, any language — no Node.js required on the host:

cp .env.example .env    # set MERIDIAN_PROXY_TOKEN + provider credentials
docker compose up -d    # gRPC engine on 127.0.0.1:4242

// Go — same normalized shape for all 47 providers
c, _ := meridian.Dial(ctx, "127.0.0.1:4242", meridian.WithToken(token))
resp, _ := c.Get(ctx, "stripe", "/v1/customers")

# Python — including StreamCall for LLM token streaming
async with MeridianGrpcClient("127.0.0.1:4242", auth_token=token) as client:
    async for chunk in client.anthropic.stream_call("/v1/messages", body={...}):
        print(chunk.data, end="")

Go · Rust · Python clients ship in clients/. Generate one for C++, Java, C#, and more straight from proto/meridian.proto. See docs/polyglot.md.

Security

• SSRF protection — every endpoint is validated as a relative path before a request is built; isSafeEndpoint() for untrusted input
• Credential & PII redaction — authorization / token / cookie always scrubbed from logs and error payloads; opt-in PII coverage including Aadhaar, PAN, VPA in India mode
• Webhook verification — timing-safe HMAC checks with timestamp freshness enforcement (matches Stripe's own 5-minute tolerance)
• Zero required runtime dependencies — nothing in your supply chain you didn't ask for

See SECURITY.md for private vulnerability reporting.

Providers

47 adapters, each passing the same 19 contract invariants (1637 contract tests). Verify any one locally: npm run test:contracts stripe.

| Category | Providers | |---|---| | Payments | Stripe · Razorpay · Cashfree · PayU · Juspay · Braintree · Adyen · Klarna · Mollie · PhonePe · Checkout.com · BillDesk · CCAvenue | | 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 · Hunter · S3 | | Mapping | Google Maps · MapMyIndia | | Observability | Sentry · Datadog | | Logistics | Shiprocket · Delhivery | | Other | Cleartax |

India fintech and compliance details: docs/fintech.md.

Contributing

New adapter: npx meridian add <name> --openapi ./spec.json → review GENERATED.md → npm test.

Changelog · License: MIT · npm