SDKs

Edgaze maintains official SDKs for the v1 REST API. Each SDK is generated against the OpenAPI document and tested against the live API. Use an SDK for retries, pagination, streaming, and webhook verification instead of writing them yourself.

TypeScript#

The TypeScript SDK runs on Node 18 and later, Deno, and other runtimes that provide fetch and Web Crypto. It has no runtime dependencies.

npm install @edgaze/sdk

Create a key in Developer → API keys and set it as EDGAZE_API_KEY. Keep the key on your server: the SDK refuses to run in a browser, where every visitor could read it.

Run a workflow#

import Edgaze from "@edgaze/sdk";

const client = new Edgaze(); // reads EDGAZE_API_KEY

const run = await client.runs.createAndWait({
  workflow: "550e8400-e29b-41d4-a716-446655440000",
  inputs: { topic: "Tides" },
});

if (run.status === "completed") {
  for (const output of run.outputs) console.log(output.name, output.value);
} else {
  console.error(run.status, run.reason);
}

Key inputs by each field's nodeId from Get Workflow. createAndWait returns failed and cancelled runs rather than throwing, so check status.

Stream progress live#

const { run } = await client.runs.create({ workflow: workflowId, inputs });

for await (const message of client.runs.stream(run.id)) {
  if (message.kind === "event" && message.event.type === "node.output.delta") {
    process.stdout.write(message.event.data?.text ?? "");
  }
}

The stream replays what already happened, then follows new events. It reconnects with Last-Event-ID after the server's five-minute roll-over, a dropped connection, or a connection that goes silent, so no event is lost or repeated. It ends once the run is finished. See Streaming & Real-time for the frames it reads.

Pagination#

List methods can be iterated directly. The SDK fetches the next page when it needs it, and run listings use the cursor, so runs created while you page are never repeated or skipped:

for await (const run of client.runs.list({ status: "failed" })) {
  console.log(run.id, run.startedAt);
}

Await a list method instead to get one page, with hasNextPage() and getNextPage().

Retries and idempotency#

The SDK retries connection errors, timeouts, and responses with status 408, 425, 429, and 5xx. It makes two retries by default, with exponential backoff that honours Retry-After. Every runs.create call sends an Idempotency-Key, so a retry returns the original run instead of starting a second one. Pass your own key to make retries safe across process restarts:

await client.runs.create(
  { workflow: workflowId, inputs },
  { idempotencyKey: `invoice-${invoice.id}` },
);

Errors#

Every error from the API is an APIError subclass with the HTTP status, the error code, and the requestId:

import { APIError, NotFoundError } from "@edgaze/sdk";

try {
  await client.runs.retrieve(runId);
} catch (err) {
  if (err instanceof NotFoundError) {
    // the run does not exist or is not visible to this key
  } else if (err instanceof APIError) {
    console.error(err.status, err.code, err.requestId);
  } else {
    throw err;
  }
}

Branch on code, not on the message. New codes can appear without notice (see Versioning & Deprecation), so handle an unrecognized code by its status. Quote requestId when you contact support. The codes are listed in Errors.

Webhooks#

unwrapWebhook verifies the edgaze-signature header against the raw body and rejects deliveries signed more than five minutes ago:

import { unwrapWebhook, WebhookVerificationError } from "@edgaze/sdk";

export async function POST(request: Request) {
  try {
    const { event, deliveryId } = await unwrapWebhook({
      payload: await request.text(),
      headers: request.headers,
      secret: process.env.EDGAZE_WEBHOOK_SECRET!,
    });
    // Store event keyed by deliveryId, then do the work asynchronously.
    return new Response(null, { status: 200 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response(null, { status: 400 });
    throw err;
  }
}

Pass the body exactly as received. Parsing and re-serializing the JSON changes the bytes, and the signature no longer matches. See Webhooks for the payloads and retry behavior.

Updates#

The SDK follows semver. Because v1 only gains additions, upgrading within a major version is safe. When the OpenAPI document changes, the SDK repository picks it up automatically, and its tests fail until the SDK covers any new endpoint or parameter. The changelog lists every release.