@acentric-cloud/client

Create and drive Acentric Cloud sessions from Node 20+ or a browser. Install with npm install @acentric-cloud/client. The package has no runtime dependencies.

import { Client } from '@acentric-cloud/client';
const client = new Client({ baseUrl: 'https://api.cloud.acentric.dev', token });
const created = await client.createSession({ agent_id: agentId, configuration: {} });
if ('accepted' in created.response) {
  const receipt = await client.sendInput(
    created.session_id,
    { kind: 'message', payload: { text: 'hello' } },
    { inputId: 'message-1' },
  );
  console.log(receipt.response);
}

Create waits for init's answer. Input and configuration changes wait for their step's answer, and upgrade waits for migrate. Each returns a receipt with response: { accepted: true } | { rejected: Json } | { failed: Json }. The client resends queued responses with the identical body and identity. timeoutSeconds sets each server wait from 0 through 60, default 30; signal ends the HTTP wait without cancelling the submitted operation. Inputs and configuration changes that failed may be delivered again after an operator resumes or upgrades the session. Create and upgrade failures are final.

sendInput generates one UUID or uses inputId. updateConfiguration takes { id, config } and posts to /configuration. Keep these identities to recover after a lost response; changing a body under the same identity is refused. upgradeSession accepts toRelease, toVersion, idempotencyKey and answer options. With no target it uses the deployment. A successful upgrade clears a fault and delivers migrated first.

suspendSession stops work while inputs and config changes remain queued. resumeSession reopens a suspended or faulted gate. closeSession ends the session permanently and cancels its effects. These controls return Session, including its code version. A user stop should be an input defined by the agent. getSession, listSessions, deleteSession, getStatus, getState, getConfiguration, listConfigurations and getUsage cover other session reads.

getInput reads an inbox entry with queued or answered status and its latest answer. listInputs filters statuses and kinds with paging. listEffects lists open effects by default; request settled statuses and includeArgs explicitly when needed. Timers appear as @timer effects. listJournal({ after?, limit? }) returns { entries, next_after? }.

listLog(sessionId, { after?, before?, kinds?, limit?, cursor? }) returns { entries, cursor? } oldest first. Log positions and at milliseconds are numbers. An explicit empty kinds or statuses array is encoded as an empty filter; omit it for all kinds or the default effect statuses. streamLog(sessionId, { after?, kinds?, signal?, onLive? }) yields entries, consumes heartbeats and reconnects after its last delivered seq. Use after: 0 to replay the whole log. An omitted after pins the current head once before connecting.

getView returns the stored view plus an HTTP etag. No view is null; a conditional read with ifNoneMatch returns undefined when unchanged. listConsole, listAgentConsole and streamConsole read bounded diagnostics with an org credential. Console positions, session counters and revisions remain decimal strings, so compare those with BigInt. Console paging uses afterSeq, beforeSeq, minLevel, limit, cursor and order.

The constructor takes baseUrl, token (a string or async credential function), optional login org, custom fetch and retry attempts. Credential functions run before every request and stream reconnect. AcentricError exposes status, code, message, field, retryable, retryAfter and cause. Network errors and retryable API errors retry repeatable requests, retaining their identities and honoring Retry-After. A malformed response is a nonretryable protocol error. Token minting is sent once, and a delete retry can accept not_found after a lost reply.

Mint a session token on your server with mintSessionToken. A writable token may send inputs and suspend or resume; session tokens may read the session and its journal, log, inbox, effects, state, view and configuration. The console, creation, configuration writes, upgrades, close, deletion and minting tokens require an org credential. Give browsers a session token. getPricing() reads the public rate book without credentials or org headers. All generated wire types are exported unchanged.