Skip to content
Hayonix

SDKs and CLI

TypeScript SDK

Install and configure the hayonix package, handle errors, tune retries and timeouts, paginate, stream, upload and download files, wait for resources and work with money.

The TypeScript SDK has a method for every operation in the API reference, grouped by area: client.pods.create, client.serverless.submitJob, client.fineTuning.listEvents. Each reference page shows its call. Responses are typed plain objects in the API's own snake_case field names.

Install

npm
npm install hayonix

Inference goes through the official openai package; install it next to the SDK if you call models:

npm
npm install openai

Configure

new Client() reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL from the environment. Pass any of them as options instead (apiKey, baseUrl, inferenceBaseUrl), along with timeout, maxRetries, maxRetryWaitMs, defaultHeaders or your own fetch.

TypeScript
import { Client } from 'hayonix';

// API_KEY, API_BASE_URL and INFERENCE_BASE_URL come from the environment by default.
const client = new Client({
  timeout: 30_000, // per attempt, in milliseconds (default 60 000)
  maxRetries: 3, // retries of a retryable failure (default 2)
});

const me = await client.caller(); // the key's org, project and permissions
console.log('project:', me.project_id);

Path parameters are positional and everything else goes in one params object: client.pods.exec(podId, { command }). Organization-level calls fill in the key's organization, so client.billing.getBalance() needs no arguments.

Errors

Every API error is an ApiError subclass chosen by the error's type; see Errors and retries for the full list.

TypeScript
import { ApiError, NotFoundError, RateLimitError } from 'hayonix';

try {
  await client.pods.get('pod_00000000000000000000000000');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('not found:', err.message);
  } else if (err instanceof RateLimitError) {
    console.log('slow down; retry after', err.retryAfterSeconds, 's');
  } else if (err instanceof ApiError) {
    console.log(err.status, err.type, err.code, err.param, 'request', err.requestId);
  } else {
    throw err;
  }
}

Retries, timeouts and cancellation

The last argument of every method takes per-call options: timeout (milliseconds per attempt), maxRetries, signal (an AbortSignal that cancels the call and its retries), idempotencyKey and extra headers.

TypeScript
const controller = new AbortController();
const secrets = await client.secrets.list(
  { limit: 10 },
  { timeout: 5_000, maxRetries: 0, signal: controller.signal },
);
console.log('secrets on the first page:', secrets.data.length);

What is retried, and when, is described in Errors and retries. Creating calls carry an Idempotency-Key the SDK generates and keeps across its retries; pass idempotencyKey to make a retry from another process safe too:

TypeScript
import { randomUUID } from 'node:crypto';
import { Client, IdempotencyError } from 'hayonix';

const client = new Client();

const key = randomUUID(); // store it with the work item, so a restarted job reuses it
const first = await client.secrets.create(
  { name, value: 'example-value' },
  { idempotencyKey: key },
);
const again = await client.secrets.create(
  { name, value: 'example-value' },
  { idempotencyKey: key },
);
console.log('same secret:', first.id === again.id);

Pagination

List methods return a page that you can await (data, nextCursor, nextPage()) or iterate with for await over every item.

TypeScript
// Every item, fetching further pages as the loop reaches them:
for await (const secret of client.secrets.list({ limit: 2 })) {
  console.log('secret:', secret.name);
}
TypeScript
// One page at a time: `data` and `nextCursor`, or `nextPage()` until it returns null.
let page = await client.secrets.list({ limit: 2 });
for (let n = 1; ; n++) {
  console.log(
    `page ${n}: ${page.data.length} item(s), next cursor: ${page.nextCursor ?? 'none'}`,
  );
  const next = await page.nextPage();
  if (!next) break;
  page = next;
}

Uploads and downloads

A file field accepts a Blob, a File, bytes, a string, or { name, data }. In Node, fileFromPath from hayonix/node streams a file from disk. Downloads return a BinaryResponse: read it once with text(), bytes(), body (a web stream) or saveTo(path).

TypeScript
import { fileFromPath } from 'hayonix/node';

// Upload from disk (streamed, not read into memory), wait for validation, download again.
const uploaded = await client.files.upload({ file: await fileFromPath(path), purpose: 'batch' });
const checked = await client.waitFor.file(uploaded.id);
console.log('file', checked.id, checked.status, checked.bytes, 'bytes');

const content = await client.files.getContent(uploaded.id);
await content.saveTo(join(dir, 'copy.jsonl'));

Waiting

client.waitFor polls a resource until it reaches the state you want, with a default timeout per kind: pod (until running, or another state you pass), job, fineTune, batch, file, dedicatedEndpoint, sandbox and cluster (until every member runs). Each throws WaitTimeoutError when time runs out and UnexpectedStateError when the resource reaches a state it cannot leave for the one you asked for. onUpdate sees every observation.

TypeScript
const done = await client.waitFor.batch(batch.id, {
  onUpdate: (b) => {
    console.log('status:', b.status);
  },
});

Streaming

Inference streams come from the OpenAI client. Serverless job output and fine-tuning events are followed with client.follow, as async iterables that end when the job does:

TypeScript
const job = await client.serverless.submitJob(endpoint.id, {
  input: { text: 'hello from a worker' },
});
for await (const chunk of client.follow.jobStream(job.id)) {
  console.log('chunk:', JSON.stringify(chunk.data));
}
const done = await client.waitFor.job(job.id);
console.log('state:', done.state, 'output:', JSON.stringify(done.output));

Pod logs are a server-sent event stream: client.pods.streamLogs(podId, { follow: 'true' }) resolves to an iterable of events.

Money

Amounts are nano-USD decimal strings. Keep them as strings or bigints; the helpers format and parse them without floating point.

TypeScript
import { formatCost, formatUsd, parseUsd } from 'hayonix';

const balance = await client.billing.getBalance(); // the key's org is filled in for you
console.log('available:', formatUsd(balance.available)); // e.g. "$25.00"
console.log('exact:', formatUsd(balance.available, { maxDecimals: 9 }));
console.log('a tiny charge:', formatCost('184331')); // "<$0.01"
console.log('$5 in nano-USD:', parseUsd('5')); // "5000000000"

The OpenAI client

await client.openai() returns the official OpenAI client pointed at the inference base URL with your key. Everything the inference API offers is used through it unchanged.

TypeScript
import { Client } from 'hayonix';

const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct';

const client = new Client(); // reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL
const openai = await client.openai();

const completion = await openai.chat.completions.create({
  model,
  messages: [{ role: 'user', content: 'Name three uses for a GPU in one sentence.' }],
  max_completion_tokens: 64,
});
console.log('reply:', completion.choices[0]?.message.content?.trim() ?? '');
console.log('tokens:', completion.usage?.total_tokens);