Skip to content

API client ​

The contract ​

The contract is ratavyr's REST API v1, specified in ratavyr/docs/rest-api.md and documented at ratavyr.bzy-logics.com.

  • src/types/api.ts mirrors it type-for-type.
  • src/api/ implements it.

When the contract changes, update src/types/api.ts first. npm run typecheck then shows every place that needs attention.

src/api/ ​

FileResponsibility
client.tsTyped REST client for /health, /info, /session, /status, /config, /plugins, /commands/{name}, /ws-tickets, /firmware/*. Parses the error envelope {"error":{"code","message"}} into ApiError
ws.ts/api/ws client for engine, telemetry and log messages. Fetches a fresh single-use ticket before every connect; reconnects with backoff
backoff.tsExponential backoff with jitter: 500 ms doubling to 10 s, ±20 %
auth.tsToken storage: sessionStorage by default, localStorage when remembered (key motioncore.api_token)
index.tsPublic exports, including the API types
ts
import { api, ApiError } from './api'

try {
  await api.command('jog', { axis: 'j1', delta: 5 })   // params are typed per command name
  const jobs = await api.firmware.jobs()
} catch (e) {
  if (e instanceof ApiError && e.code === 'not_homed') { /* … */ }
}

ApiError carries code, message and the HTTP status. A response without the error envelope becomes code http_<status>. Branch on code, never on the message. The codes are listed in ratavyr: error codes.

src/hooks/ ​

Hook / moduleResponsibility
liveStore.tsOne shared live store: engine connection, latest telemetry, a 30 s position history, the last 500 log lines, and a health poll every 5 s
useEngine / useTelemetry / useAuthReact access to the live store
status.tsDerived status: stale after 1.5 s without telemetry, E-stop confirmation window (2 s), permissions from /api/session
usePollingFetches on mount and then at an interval, with data / error / loading / refresh; for data not on the event stream (e.g. firmware jobs)
useCommandSends a command; failures surface as toasts ("Jog failed: not_homed"); resolves true on success

Rules the client follows ​

  • Never synthesise robot state. Display only what telemetry and configuration report.
  • A command response is acceptance, not completion. Wait for telemetry.
  • Tolerate unknown enum values. A newer 1.x engine may send "unknown", and "unspecified" is possible.
  • Treat nulls as "not set". Optional fields are always present, as null when unset.
  • Permissions are a hint. If /api/session is unavailable (ratavyr < 0.3), all permissions are treated as unknown/allowed and the server decides.

Compatibility with older servers ​

ServerBehaviour
ratavyr ≥ 0.3Full: session, roles, WebSocket tickets
ratavyr < 0.3Works. No /api/session, so permissions are unknown; no /api/ws-tickets, so the WebSocket falls back to ?access_token=

Part of MotionCore. The on-screen E-STOP is a software stop — it never replaces a hardware E-stop circuit.