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 install hayonixInference goes through the official openai package; install it next to the SDK if you call models:
npm install openaiConfigure
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.
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.
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.
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:
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.
// 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);
}// 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).
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.
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:
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.
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.
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);