merge-gateway-sdk

TypeScript SDK for the Merge Gateway API.

Installation

npm install merge-gateway-sdk

Quick start

import { MergeGateway } from "merge-gateway-sdk";

const client = new MergeGateway({ apiKey: "mg_..." });

Usage

Responses

// Non-streaming
const response = await client.responses.create({
  model: "openai/gpt-4o",
  input: [{ type: "message", role: "user", content: "Tell me a bedtime story about an otter." }],
});
console.log(response.output[0].content[0]);

// Streaming
const stream = await client.responses.create({
  model: "openai/gpt-4o",
  input: [{ type: "message", role: "user", content: "Hello" }],
  stream: true,
});
for await (const event of stream) {
  console.log(event);
}

Models

// List models (with optional pagination)
const models = await client.models.list();
for (const m of models.data) {
  console.log(m.id, m.display_name);
}

// Filter by provider
const openaiModels = await client.models.list({ provider: "openai" });

// Retrieve a specific model
const model = await client.models.retrieve("openai/gpt-4o");

Embeddings

const result = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: "The food was delicious",
  encoding_format: "float",
});
console.log(result.data[0].embedding);

Tags

const tags = await client.tags.list();
for (const tag of tags.data) {
  console.log(tag.tag_key, tag.tag_value);
}

Embedded Routing (customers)

Provision each of your end customers as a Customer with its own routing policies, provider keys, and budget, then scope LLM requests to it with the customer field.

// Provision a customer
const customer = await client.customers.create({ name: "Acme", origin_id: "acme-corp" });

await client.customers.routingPolicies.create(customer.id, {
  name: "workflow-a",
  strategy: "PRIORITY",
  is_default: true,
  priority_order: [
    { model: "openai/gpt-5.5", priority: 1 },
    { model: "anthropic/claude-opus-4-8", priority: 2 },
  ],
});

await client.customers.keys.upsert(customer.id, { vendor: "openai", api_key: "sk-..." });

await client.customers.budgets.create(customer.id, {
  spending_limit: 50,
  reset_period: "MONTHLY",
  spending_limit_type: "HARD",
});

// Scope a request to the customer (omit `model` to route via its default policy)
const response = await client.responses.create({ input: "Hello!", customer: customer.id });

// Per-customer spend report
const usage = await client.customers.usage(customer.id, {
  start: "2026-07-01",
  end: "2026-07-31",
});
console.log(usage.customer_byok_spend, usage.organization_byok_spend, usage.merge_spend);

Error handling

import { MergeGateway, AuthenticationError, RateLimitError } from "merge-gateway-sdk";

try {
  const response = await client.responses.create({ model: "openai/gpt-4o", input: "Hi" });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.log("Check your API key");
  } else if (e instanceof RateLimitError) {
    console.log("Slow down!");
  }
}

Publishing to npm

npm run build
npm publish

Testing locally

npm ci
npm run check:local

check:local runs:

• npm run build
• npm test
• npm pack --dry-run to verify the package contains the built dist entrypoint
• a live SDK smoke test when MERGE_GATEWAY_API_KEY is set
• a best-effort npm registry lookup for merge-gateway-sdk

The live SDK smoke test imports the built package from dist and calls:

• client.models.list()
• client.models.retrieve(...)
• client.tags.list()
• client.responses.create(...)
• client.responses.create({ stream: true, ... })
• client.embeddings.create(...)

To run those same live SDK calls against the currently published npm package:

MERGE_GATEWAY_API_KEY="mg_..." npm run check:published

By default, check:published installs merge-gateway-sdk at the version in this repo's package.json into an isolated temp directory, imports that installed package, and runs the same smoke test calls. To test a different published version:

MERGE_GATEWAY_PUBLISHED_VERSION="0.2.0" MERGE_GATEWAY_API_KEY="mg_..." npm run check:published

To run the live SDK calls locally, set the API key only in your terminal session:

export MERGE_GATEWAY_API_KEY="mg_..."
npm run check:sdk

Or pass it for a single command:

MERGE_GATEWAY_API_KEY="mg_..." npm run check:sdk

Do not put the API key in this repo or commit it in a .env file. The script reads MERGE_GATEWAY_API_KEY from the process environment at runtime.

Useful variants:

# Run everything except the public npm registry lookup
npm run check:local -- --skip-npm

# Only check whether the package name/version is published on npm
npm run check:local -- --npm-only

# Fail if the current local version is not already published
npm run check:local -- --strict-npm

# Run live SDK calls without the streaming response check
npm run check:sdk -- --skip-stream

# Run the published package check without the streaming response check
npm run check:published -- --skip-stream

# Print detailed failure context, including raw SDK responses
npm run check:sdk -- --verbose

# Use a specific model if the script cannot pick one from models.list()
MERGE_GATEWAY_TEST_MODEL="openai/gpt-4o" MERGE_GATEWAY_API_KEY="mg_..." npm run check:sdk

Flags:

• --sdk-only: Build the package and only run live SDK method smoke tests.
• --skip-build: Skip npm run build.
• --skip-tests: Skip npm test.
• --skip-pack: Skip npm pack --dry-run.
• --skip-npm: Skip the public npm registry lookup.
• --skip-sdk: Skip live SDK method smoke tests.
• --skip-stream: Skip the streaming responses.create smoke test.
• --npm-only: Only check whether the package exists on npm.
• --published-only: Install the published package from npm and only run live SDK method smoke tests.
• --published-sdk: Run live SDK method smoke tests against the published package instead of local dist.
• --strict-npm: Fail if the current package version is not published on npm.
• --strict-sdk: Fail instead of skipping when MERGE_GATEWAY_API_KEY is missing.
• --verbose: Print detailed failure context, including raw SDK responses.
• --help: Print all script options.

Optional environment variables:

• MERGE_GATEWAY_BASE_URL
• MERGE_GATEWAY_PUBLISHED_VERSION
• MERGE_GATEWAY_TEST_MODEL
• MERGE_GATEWAY_TEST_EMBEDDING_MODEL
• MERGE_GATEWAY_TEST_TIMEOUT_MS
• MERGE_GATEWAY_DEBUG=1