TypeScript SDK

The SDK covers calls (one endpoint or a routed capability) and the live log. It runs anywhere with fetch and web streams on the server: Node 20+, Bun, Deno and Workers. Never ship an API key to a browser.

Create a clientCopy Anchor Link

import { createGrid } from "@relaygrid/sdk";

const grid = createGrid({ apiKey: process.env.GRID_API_KEY! });

Run a capabilityCopy Anchor Link

run lets GridRouter route: it tries the vendors for a capability in route order and stops at the first hit. The body is the run request.

const result = await grid.run("people.email.find", {
  input: { first_name: "Ada", last_name: "Lovelace", domain: "stripe.com" },
  options: { cost: { max_cost_micro: 50_000 } },
});
console.log(result.provider, result.data);

Call one endpointCopy Anchor Link

call pins a vendor endpoint. Async endpoints return a Job to poll instead of a result.

const res = await grid.call("hunter/email.find", {
  input: { first_name: "Ada", last_name: "Lovelace", domain: "stripe.com" },
  include_raw: true,
});

Stream the live logCopy Anchor Link

const tail = grid.logs.tail(
  {
    filter: { kinds: "call", capability: "people.email.find", status: "failed" },
    onControl: (frame) => console.error(frame.kind),
    onError: (err) => console.error(err),
  },
  (event) => {
    if (event.kind === "call") console.log(event.row.call_id, event.row.outcome);
  },
);

// later
tail.close();
await tail.done;
console.log(`dropped ${tail.dropped} events`);

filter takes the same keys as the live tail. tail streams over SSE, reconnects with backoff from 0.5 s to 10 s, asks for replay=100 on reconnect and skips events it has already delivered. It stops on a 4xx other than 429 and reports it to onError. Pass signal to stop with an AbortSignal, or reconnect: false to stop at the first disconnect.

Read recent eventsCopy Anchor Link

const { items } = await grid.logs.recent({ kinds: "call", limit: 20 });

items is newest last, up to 1,000 (default 50).

ErrorsCopy Anchor Link

Failed requests throw GridApiError, which carries the error envelope's code, message and HTTP status.