Ekstra.OS TypeScript SDK (@ekstraai/runtime-sdk)

Node TypeScript SDK for Ekstra.OS runtime IPC.

Scope

This SDK targets Node runtime clients/providers over TCP protocol v1.

Current parity coverage:

1. hello identity handshake
2. request/reply operations
3. subscribe/publish
4. provider registration + heartbeat
5. session start/resume/replay/stop
6. status/policy/metrics/audit operations
7. runtime event stream consumption
8. browser wrapper baseline (MotionBrowserClient) for ws_bridge transport

Install

Published package:

npm install @ekstraai/runtime-sdk

Local package:

cd sdk/ts
npm install
npm run build

Runtime client example

import { MotionRuntimeClient, monotonicSeconds } from "@ekstraai/runtime-sdk";

const client = new MotionRuntimeClient("127.0.0.1", 8765, 2000);
await client.connectWithIdentity({
  role: "client",
  clientName: "ts-app",
  actorId: "actor-1",
  lane: "guest",
});
await client.subscribe("motion.samples");
await client.publish("motion.samples", {
  actor_id: "actor-1",
  part: "hand.right",
  frame: "device:ts",
  timestamp: monotonicSeconds(),
  confidence: 1.0,
});
const event = await client.recvEvent(1000);
console.log(event);
client.close();

Provider SDK example

import { MotionRuntimeClient, ProviderSDK, monotonicSeconds } from "@ekstraai/runtime-sdk";

const runtime = new MotionRuntimeClient("127.0.0.1", 8765, 2000);
const provider = new ProviderSDK(runtime);
await provider.connect({
  providerId: "ts-provider",
  actorId: "actor-1",
  parts: ["hand.right"],
});
provider.startHeartbeat(800);
await provider.publishSample("motion.samples", {
  actor_id: "actor-1",
  part: "hand.right",
  frame: "device:ts-provider",
  timestamp: monotonicSeconds(),
  confidence: 0.95,
});
provider.close();

Browser wrapper baseline

import { MotionBrowserClient } from "@ekstraai/runtime-sdk";

const client = new MotionBrowserClient({ url: "ws://127.0.0.1:8787/ws" });
client.onState((s) => console.log("state", s));
client.onEvent((m) => console.log("event", m.topic, m.event));
await client.connect();

Note:

1. Browser wrapper uses WebSocket bridge transport.
2. Node TCP runtime client remains the primary TypeScript parity path.

Smoke scripts

Requires motiond running on 127.0.0.1:8765.

npm run smoke:client
npm run smoke:provider

Test + typecheck

npm run typecheck
npm run test
npm run smoke:pack

Release

TypeScript release tags:

ts-sdk-vX.Y.Z

The release workflow verifies:

1. npm ci
2. npm run typecheck
3. npm test
4. npm run smoke:pack
5. npm publish --dry-run on branch/manual dry-run
6. npm publish --access public --provenance on release tags