@fystash/sdk

TypeScript SDK for the Fystash public API. Catalog operations are generated from spec/operations/catalog.json. Ergonomic handles (Revision, Branch, Plan, Run, Evidence) live in a handwritten layer above that transport (ADR-0091). This package is not a second CLI.

Install

npm install @fystash/sdk

Configure

Set environment variables, or pass them explicitly. The SDK does not read ~/.fystash/credentials.json unless you call Fystash.fromCliContext().

FYSTASH_API_URL       default https://api.fystash.ai/v1
FYSTASH_ACCESS_TOKEN
FYSTASH_PROJECT_ID

import { Fystash } from "@fystash/sdk";

const fystash = Fystash.fromEnv();
// or: Fystash.connect({ apiUrl, accessToken, projectId })

Quickstart

const fystash = Fystash.fromEnv();

const revision =
  await fystash.environments.compileFile("environment.yaml");

const branch =
  await fystash.branches.create({
    revision: revision.id,
    name: "dev"
  });

const plan =
  await fystash.runs.plan({
    revision: revision.id,
    branch: branch.id
  });

const run = await plan.apply();

await run.waitReady();
await run.exec(["npm", "test"]);
const evidence = await run.evidence.list();
await run.stop();

plan.apply() submits the digest stored on that Plan object. Retrying apply() on the same handle reuses one idempotency key; constructing a new Plan starts a new intent.

run.exec(argv) maps to catalog execProcess with component=workspace and actor=agent unless overridden. It never invokes a local shell.

Errors

Transport failures keep the canonical envelope code. Convenience classes (AuthenticationError, PermissionError, CapabilityUnavailableError, ApprovalRequiredError, ConflictError, TimeoutError) wrap that envelope.

License

Apache-2.0