@krizaka/orazaka-client
One Orazaka client for the TypeScript products: start a run, read its status and outputs, typed errors, a time limit and a circuit breaker.
Install
npm install @krizaka/orazaka-clientOne client of Orazaka's edge for every Krizaka TypeScript product, instead of one copy per product (Yomizaka, Orochia, soon Akinaza): start a Studio run, read its status and its outputs, wait for it. The base URL, the key and the clock are parameters — this package reads no environment and no wall clock.
import { createOrazakaClient, outputOf } from "@krizaka/orazaka-client";
const orazaka = createOrazakaClient({ baseUrl: "https://api.orazaka.com", apiKey: env.AI_API_KEY, clock: { now: () => new Date() } });
const { run } = await orazaka.startRun("compliance-check", { document: text }, { idempotencyKey: `doc-${documentId}-v${version}` });
const done = await orazaka.waitForRun(run.id); // or poll `getRun` yourself
if (done.status === "SUCCEEDED") use(outputOf(done, "report"));- Safe to retry.
startRunwith anidempotencyKeyanswers the run already started for the same key and inputs (replayed: true) instead of paying for a second one; the same key for other inputs isORAZAKA_KEY_REUSED. - Typed errors. Every failure is an
OrazakaErrorwith a stablecode(ORAZAKA_KEY,ORAZAKA_CREDITS,ORAZAKA_LOCKED,ORAZAKA_INPUT,ORAZAKA_NOT_FOUND,ORAZAKA_BUSYwithretryAfterSeconds,ORAZAKA_UNAVAILABLE,ORAZAKA_TIMEOUT,ORAZAKA_SHAPE,ORAZAKA_CIRCUIT_OPEN…) and thestatusa product answers its own caller with. A product translates the codes; none is a sentence. A failed run is not an error:waitForRungives it back with itserrorMessage. - A time limit and a circuit breaker, as options:
timeoutMs(20 s by default) on every call; five failures in a row (no answer, timeout, 5xx) open the circuit for 30 s — it refuses at once, then lets one call probe. A refusal (401, 402, 404, 429…) is an answer and never opens it.circuit: falseturns it off. - Contract-tested against the edge's answers kept as fixtures (
test/fixtures): when the edge changes a shape, the fixture changes first.
Run events as a stream (Server-Sent Events, GET /api/v1/studios/runs/{id}/events) come in a later minor; waitForRun polls until then.
Exports
The 21 names the package exports, read from its types.
| Name | Kind | What it is |
|---|---|---|
Circuit | type | |
CircuitOptions | type | |
Clock | type | |
createCircuit | function | A circuit breaker over a dependency that may be down: after failureThreshold failures in a row it refuses at once (no waiting on a timeout, no load on a st… |
createOrazakaClient | function | Orazaka's edge, for every TypeScript product: one client instead of one copy per product. |
isTerminal | function | The run is over, green or not: nothing more will change. |
ORAZAKA_CODE | constant | The stable codes of a refusal or a failure of Orazaka's edge — a product translates them; none is a sentence. |
OrazakaClient | type | |
OrazakaClientOptions | type | |
OrazakaCode | type | |
OrazakaError | class | |
orazakaRefusal | function | What the edge's status means for a product that answers its own caller: the status to send back and the code. |
OrazakaRun | type | A run, as the edge answers it (GET /api/v1/studios/runs/\{id\}). |
outputOf | function | The value of one output, or null when the run did not produce it (yet). |
parseInstallations | function | The Studios an account installed: GET /api/v1/studios/installations. |
parseRun | function | Reads a run from the edge's JSON; anything else is ORAZAKA_SHAPE. |
RUN_STATUS | constant | Where a run sits (orazaka-studio RunStatus). |
RunOutput | type | One output of a run (orazaka-studio RunArtefactResponse): type is a rendering hint (TEXT, IMAGE, VIDEO…). |
StartedRun | type | |
StartRunOptions | type | |
WaitOptions | type |
Package
| Version on npm | Not on npm yet |
| Licence | Apache-2.0 |
| Node.js | >=22 |
| Dependencies | date-fns ^4.4.0 |
| Source | orazaka-client |
Changelog
0.1.0
Minor changes
- New:
@krizaka/orazaka-client, the one Orazaka client for the TypeScript products (#33). Start a Studio run (idempotency key), read its status and outputs, wait for it; typed errors with stable codes, a time limit and a circuit breaker as options; base URL, key and clock as parameters; a fixture-based contract test.