TypeScript SDK

@alive/sdk 0.1.0 builds to native ESM JavaScript and declaration files. It is private and not published to npm yet. Install a supplied tarball with pnpm add ./alive-sdk-0.1.0.tgz. No workspace checkout, Python engine or customer Supabase setup is included in that install.

import { createAliveClient, unwrap, AliveApiError, idempotencyKey } from "@alive/sdk";

const alive = createAliveClient({
  baseUrl: "http://127.0.0.1:8000",
  getToken: () => process.env.ALIVE_TOKEN,
});

const catalog = unwrap(await alive.GET("/v1/models"));
const projectKey = idempotencyKey(); // persist before sending if retries need to resume
const project = unwrap(await alive.POST("/v1/projects", {
  headers: { "Idempotency-Key": projectKey },
  body: { title: "Navigator capacity experiment", org_id: process.env.ALIVE_ORG_ID },
}));

Use GET, POST and DELETE with paths/bodies generated from the actual OpenAPI. Public catalog/schema/prompt/validation calls need no token. Other operations enforce scopes, tenant membership and required role/budget. A reachable hosted API is separate from the public site. No client call implicitly approves processing, chooses a budget or runs a world.

Run and inspect deliberately

Validate a reviewed WorldSpec with POST /v1/world-specs/validate, save with POST /v1/projects/{project_id}/worlds, and estimate with POST /v1/runs/estimate. Inspect runnable, issues, reserved_credits and available_credits. After the user authorizes the budget, call POST /v1/runs with world_revision_id, budget_limit_credits and a retained Idempotency-Key. Poll GET /v1/runs/{run_id} explicitly; read results after succeeded/timed_out.

POST /v1/experiments/compare reads existing pairs from one run with body: {run_id}. Event queries use limit/offset and return next_offset/events_included. Export returns a signed link; download it with a separate request without your API bearer header. No SDK download helper or implicit polling is included.

Typed failures

openapi-fetch returns {data, error, response}. unwrap returns success data or throws AliveApiError, whose status and body preserve code, message, details and request_id. Network failures remain fetch exceptions. Inspect failures rather than treating them as results.

try {
  const result = unwrap(await alive.POST("/v1/experiments/compare", { body: { run_id: "run_…" } }));
  console.log(result.metrics);
} catch (error) {
  if (error instanceof AliveApiError) console.error(error.status, error.body.code, error.body.request_id);
  else throw error;
}

Retry an ambiguous idempotent create using the same body and key. Saving another world revision changes the run body; preserve the original revision and run id. World/plan saves do not currently accept keys. unwrapAs<T> casts free-form success responses to a caller-supplied shape; it does not validate that shape or supply missing server guarantees.

Bundled resources

The tarball includes dist/resources/manifest.json, focused Markdown guides, current JSON schemas, the public model catalog/OpenAPI and four sample worlds. In Node, use import.meta.resolve("@alive/sdk/resources/manifest.json") to locate them, or the corresponding @alive/sdk/resources/worlds/rural-clinic.json path. Read JSON/files through your filesystem tools; browser applications can copy public assets into their own build when needed. The SDK has no browser filesystem shim or auto-installed agent skill. See the agent guide and HTTP reference for exact workflows and limits.