@openrois/sdk 0.0.1-stage → 0.1.0-alpha.1

package/dist/transport-kMEIcw5y.d.ts

@@ -0,0 +1,383 @@
+/// <reference lib="esnext.disposable" />
+import { z } from 'zod';
+
+/**
+ * A small typed event emitter for RoISClient and WebSocketTransport.
+ *
+ * Node's EventEmitter would need the `events` package in browsers, its types need
+ * @types/node, and it throws on an "error" event with no listener, so one bad message
+ * from a server would end the process. Here a fault is an event that nothing can turn
+ * into a throw: it goes to the "error" listeners, or to the console if there are none.
+ */
+/** The events of an emitter: each name maps to its listener's arguments. */
+type EmitterEvents<Events> = Record<keyof Events, unknown[]> & {
+    error: [error: Error];
+};
+/** Base class of whatever emits events. Only the class itself can emit. */
+declare class TypedEmitter<Events extends EmitterEvents<Events>> {
+    private readonly listeners;
+    /** Add a listener. It stays until off() removes it. */
+    on<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): this;
+    /** Remove a listener added with on(). */
+    off<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): this;
+    /**
+     * Call the listeners of an event. A listener that throws, or an async listener that
+     * rejects, is reported as a fault, because the caller is the reader of a socket and
+     * must carry on with the next message.
+     */
+    protected emit<E extends keyof Events>(event: E, ...args: Events[E]): void;
+    /** Pass on what a listener threw. An "error" listener that throws can only be logged. */
+    private reportFault;
+}
+
+/**
+ * JSON-RPC 2.0 envelopes for the OpenRoIS SDK.
+ *
+ * Defines the four message types exchanged with an engine over WebSocket:
+ *
+ *   JsonRpcRequest      - A call that expects a reply (has `id`)
+ *   JsonRpcResponse     - A successful reply to a request
+ *   JsonRpcError        - A failed reply to a request
+ *   JsonRpcNotification - A push with no reply expected (no `id`)
+ *
+ * This module knows nothing about RoIS. The method names, the params and result
+ * of each method, the notifications and the JSON-RPC error codes come from the
+ * method catalog in @openrois/interfaces (RoISMethods, RoISMethodSchemas,
+ * RoISNotifications, JsonRpcErrorCode). Section 17 of docs/rois-reference.md
+ * describes the binding.
+ *
+ * A RoIS failure is a normal JsonRpcResponse whose result has a return_code
+ * other than OK. A JsonRpcError only reports a protocol fault: unparseable
+ * JSON, an invalid request, an unknown method, params that fail validation, or
+ * an internal error.
+ *
+ * Source: JSON-RPC 2.0 Specification (https://www.jsonrpc.org/specification)
+ */
+
+/**
+ * The error object carried inside a JsonRpcError message.
+ *
+ * Maps to the Error Object defined in section 5.1 of the JSON-RPC 2.0 spec.
+ * The standard codes are in JsonRpcErrorCode. Codes from -32000 to -32099 are
+ * left to the engine.
+ */
+declare const JsonRpcErrorObjectSchema: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+type JsonRpcErrorObject = z.infer<typeof JsonRpcErrorObjectSchema>;
+/**
+ * A JSON-RPC 2.0 Notification: a push from the engine with no `id`, so the
+ * client never replies. The `params` are the catalog's params model for the
+ * notification.
+ *
+ * Example:
+ *   {
+ *     "jsonrpc": "2.0",
+ *     "method": "rois.command.completed",
+ *     "params": { "command_id": "3f2a9c1e-5b7d-4e2a-9f10-6c8d2b4a7e01", "status": "OK" }
+ *   }
+ */
+declare const JsonRpcNotificationSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodUnknown>]>>;
+}, z.core.$strict>;
+type JsonRpcNotification = z.infer<typeof JsonRpcNotificationSchema>;
+
+/**
+ * WebSocket transport layer for the OpenRoIS SDK.
+ *
+ * Carries the JSON-RPC messages between RoISClient and an engine.
+ * Responsibilities:
+ *
+ *   - Establish and manage a WebSocket connection (browser or Node.js).
+ *   - Serialize outgoing JSON-RPC requests and deserialize incoming messages.
+ *   - Correlate responses to pending requests by matching the `id` field.
+ *   - Route server-push notifications to listeners.
+ *   - Handle connection errors, timeouts, and unexpected disconnects.
+ *
+ * The transport does NOT validate the inner payload of `params` or `result`.
+ * RoISClient does that with the catalog schemas from @openrois/interfaces
+ * (RoISMethodSchemas and RoISNotificationSchemas).
+ *
+ * Usage (both Node.js and Browser):
+ *   const transport = new WebSocketTransport();
+ *   await transport.connect("ws://localhost:8765");
+ *   const result = await transport.send("rois.command.search", { condition: "" });
+ *   transport.close();
+ *
+ * The transport uses the global WebSocket, which browsers and Node.js 22 both
+ * have. TransportOptions.webSocketFactory replaces it, for example to pass
+ * headers with the `ws` package.
+ *
+ * Architecture: docs/architecture.md section 5 (Client & Service Application SDK)
+ */
+
+/**
+ * Minimal WebSocket interface satisfied by the global WebSocket of browsers and
+ * Node.js, and by the `ws` package.
+ *
+ * We use the property-based event handler style (onopen, onmessage, etc.)
+ * because all of them support it identically. The transport assigns these
+ * handlers after creating the socket.
+ */
+interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    onopen: ((event: {
+        type: string;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+        type: string;
+    }) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+        type: string;
+    }) => void) | null;
+    onerror: ((event: {
+        error?: unknown;
+        message?: string;
+        type: string;
+    }) => void) | null;
+}
+/**
+ * Connection lifecycle states for the transport.
+ *
+ * State transitions:
+ *   DISCONNECTED -> CONNECTING -> CONNECTED -> CLOSING -> DISCONNECTED
+ *                                           -> DISCONNECTED (unexpected close)
+ */
+declare enum TransportState {
+    /** No active connection. Initial state and state after close. */
+    DISCONNECTED = "DISCONNECTED",
+    /** connect() has been called, and the WebSocket has not opened yet. */
+    CONNECTING = "CONNECTING",
+    /** WebSocket is open and ready to send/receive messages. */
+    CONNECTED = "CONNECTED",
+    /** close() has been called, and the WebSocket has not finished closing yet. */
+    CLOSING = "CLOSING"
+}
+/**
+ * Options for configuring the WebSocket transport.
+ */
+interface TransportOptions {
+    /**
+     * Maximum time in milliseconds to wait for a response to a request.
+     * If the gateway does not reply within this window, the Promise returned
+     * by send() rejects with a RequestTimeoutError. Default: 30000 (30s).
+     */
+    requestTimeout?: number;
+    /**
+     * Maximum time in milliseconds to wait for the WebSocket connection to
+     * open during connect(). Default: 10000 (10s).
+     */
+    connectTimeout?: number;
+    /**
+     * Optional factory function that creates a WebSocket instance for a given URL.
+     *
+     * By default, the transport uses the global WebSocket. Override this if you
+     * need custom WebSocket configuration (headers, protocols, proxy settings,
+     * etc.) or run somewhere that has no global WebSocket.
+     *
+     * Example (Node.js, `ws` package):
+     *   webSocketFactory: (url) =>
+     *     new WebSocket(url, { perMessageDeflate: false }) as unknown as WebSocketLike
+     */
+    webSocketFactory?: (url: string) => WebSocketLike;
+}
+/**
+ * Base error for all transport-level failures.
+ *
+ * Callers can catch TransportError to handle any transport problem, or catch
+ * a specific subclass for finer control.
+ */
+declare class TransportError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when the WebSocket connection cannot be established or is lost
+ * unexpectedly.
+ */
+declare class ConnectionError extends TransportError {
+    /** The URL that the transport tried to connect to, if available. */
+    readonly url: string;
+    constructor(message: string, url?: string);
+}
+/**
+ * Raised when a send() call does not receive a response within the
+ * configured timeout window.
+ */
+declare class RequestTimeoutError extends TransportError {
+    /** The JSON-RPC method that timed out. */
+    readonly method: string;
+    /** The request id that timed out. */
+    readonly requestId: string;
+    constructor(method: string, requestId: string, timeoutMs: number);
+}
+/**
+ * Raised when the engine responds with a JSON-RPC error object.
+ *
+ * This reports a protocol fault: unparseable JSON, an invalid request, an
+ * unknown method, params that fail validation, or an internal error. A RoIS
+ * failure is not an RpcError: it is a normal result with a return_code other
+ * than OK, which RoISClient raises as a RoISError.
+ */
+declare class RpcError extends TransportError {
+    /** The numeric JSON-RPC error code (e.g. -32601 for MethodNotFound). */
+    readonly code: number;
+    /** Optional additional error data from the gateway. */
+    readonly data: unknown;
+    constructor(errorObject: JsonRpcErrorObject);
+}
+/**
+ * The events of WebSocketTransport, with their listener arguments.
+ *
+ *   "open"          - The WebSocket connection opened successfully.
+ *   "notification"  - A JSON-RPC notification arrived from the gateway, with any
+ *                     method, in or outside the catalog.
+ *   "close"         - The WebSocket connection closed.
+ *   "error"         - A message from the gateway could not be used.
+ */
+type TransportEvents = {
+    open: [];
+    notification: [notification: JsonRpcNotification];
+    close: [code: number, reason: string];
+    error: [error: Error];
+};
+/**
+ * Manages a single WebSocket connection to the OpenRoIS gateway.
+ *
+ * The transport handles the JSON-RPC 2.0 wire protocol: serialization,
+ * deserialization, request/response correlation, notification routing,
+ * and error handling. RoISClient calls transport.send() and listens to the
+ * transport events.
+ *
+ * One transport instance manages one connection. To reconnect, close the
+ * existing connection and call connect() again.
+ */
+declare class WebSocketTransport extends TypedEmitter<TransportEvents> {
+    /** Current connection state. */
+    private _state;
+    /** The underlying WebSocket instance, or null when disconnected. */
+    private ws;
+    /** Map of request id -> pending request awaiting a response. */
+    private pending;
+    /** Counter for generating unique request ids within this connection. */
+    private nextId;
+    /** Resolved configuration with defaults applied. */
+    private options;
+    /** The URL this transport is connected (or connecting) to. */
+    private url;
+    /** Ends the connect() that is in progress, or null when none is. */
+    private abortConnect;
+    constructor(options?: TransportOptions);
+    /** The current connection state. */
+    get state(): TransportState;
+    /**
+     * Open a WebSocket connection to the gateway.
+     *
+     * Resolves when the connection is established and ready for messages.
+     * Rejects with ConnectionError if the connection fails or times out, or if
+     * close() runs first.
+     *
+     * @param url - The WebSocket URL, e.g. "ws://localhost:8765" or
+     *              "wss://gateway.example.com".
+     */
+    connect(url: string): Promise<void>;
+    /**
+     * Send a JSON-RPC request to the gateway and wait for the response.
+     *
+     * Returns a Promise that resolves with the `result` field from the
+     * success response, or rejects with:
+     *   - RpcError: the gateway sent a JSON-RPC error response.
+     *   - RequestTimeoutError: no response within the timeout window.
+     *   - ConnectionError: the connection dropped while waiting.
+     *   - TransportError: the transport is not connected.
+     *
+     * The caller is responsible for validating the returned result with the
+     * catalog schema for the method:
+     *   const result = await transport.send("rois.command.search", { condition: "" });
+     *   const parsed = RoISMethodSchemas["rois.command.search"].result.parse(result);
+     *
+     * @param method - The JSON-RPC method name, e.g. "rois.command.search".
+     * @param params - Optional named parameters for the method.
+     * @returns The `result` field from the gateway's success response.
+     */
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Close the WebSocket connection.
+     *
+     * Any pending requests are rejected with a ConnectionError.
+     * Safe to call when already disconnected (no-op).
+     *
+     * During connect(), this ends the attempt instead: connect() rejects with a
+     * ConnectionError and no "close" event fires, because no connection opened.
+     *
+     * @param code   - WebSocket close code (default: 1000 for normal closure): 1000, or
+     *                 3000 to 4999, which is what the WebSocket API lets a client send.
+     * @param reason - Human-readable close reason, at most 123 bytes of UTF-8.
+     * @throws TransportError for any other code or reason, in every state, and a
+     *         connection stays open.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Process a raw message string from the WebSocket.
+     *
+     * Parses the JSON, classifies the message type, and dispatches to the
+     * appropriate handler (response correlation or notification routing).
+     */
+    private handleMessage;
+    /**
+     * Handle a success response by resolving the matching pending request.
+     */
+    private handleResponse;
+    /**
+     * Handle an error response by rejecting the matching pending request.
+     */
+    private handleErrorResponse;
+    /**
+     * Handle a notification by emitting it as an event. It goes out only as
+     * "notification", never under its method name, because a server could then
+     * fake the "close" event by naming a notification after it.
+     */
+    private handleNotification;
+    /**
+     * Handle WebSocket close after the connection was established.
+     *
+     * If the close was not initiated by the client (i.e. the state is still
+     * CONNECTED), this is an unexpected disconnect. All pending requests are
+     * rejected.
+     */
+    private handleClose;
+    /**
+     * Reject all pending requests with the given error.
+     *
+     * Called on disconnect (expected or unexpected) so no Promise is left
+     * hanging forever.
+     */
+    private rejectAllPending;
+    /**
+     * Null out the WebSocket reference and remove event handlers.
+     *
+     * Prevents stale handlers from firing after the transport considers
+     * itself disconnected. The error handler stays as a no-op, because the `ws`
+     * package throws a late socket error that has no handler, and it raises one
+     * when a socket closes before its handshake ends.
+     */
+    private cleanupSocket;
+    /**
+     * Generate a unique request id.
+     *
+     * Uses a simple incrementing counter prefixed with "req-". Ids are unique
+     * within a single transport instance. The counter resets if you create a
+     * new transport.
+     */
+    private generateId;
+}
+
+export { ConnectionError as C, RequestTimeoutError as R, type TransportOptions as T, WebSocketTransport as W, TypedEmitter as a, RpcError as b, TransportError as c, type TransportEvents as d, TransportState as e, type WebSocketLike as f };

package/dist/transport.d.ts

@@ -0,0 +1,3 @@
+/// <reference lib="esnext.disposable" />
+export { C as ConnectionError, R as RequestTimeoutError, b as RpcError, c as TransportError, d as TransportEvents, T as TransportOptions, e as TransportState, f as WebSocketLike, W as WebSocketTransport } from './transport-kMEIcw5y.js';
+import 'zod';

package/dist/transport.js

@@ -0,0 +1,17 @@
+import {
+  ConnectionError,
+  RequestTimeoutError,
+  RpcError,
+  TransportError,
+  TransportState,
+  WebSocketTransport
+} from "./chunk-AEO3U7Y7.js";
+export {
+  ConnectionError,
+  RequestTimeoutError,
+  RpcError,
+  TransportError,
+  TransportState,
+  WebSocketTransport
+};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,13 +1,81 @@
 {
   "name": "@openrois/sdk",
-  "version": "0.0.1-stage",
-  "description": "Placeholder for the OpenRoIS client SDK",
-  "main": "index.js",
+  "version": "0.1.0-alpha.1",
+  "description": "JavaScript client SDK for the OpenRoIS middleware",
+  "license": "Apache-2.0",
+  "author": "OpenRoIS Community",
+  "type": "module",
+  "main": "./dist/rois-client.js",
+  "types": "./dist/rois-client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/rois-client.d.ts",
+      "default": "./dist/rois-client.js"
+    },
+    "./transport": {
+      "types": "./dist/transport.d.ts",
+      "default": "./dist/transport.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "sideEffects": false,
+  "directories": {
+    "test": "tests"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "test:consumer": "npm run build && node tests/consumer/run.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ tests/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@openrois/interfaces": "^0.1.0-alpha.6",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/browser-playwright": "^4.1.9",
+    "eslint": "^10.5.0",
+    "jiti": "^2.7.0",
+    "playwright": "1.58.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.9",
+    "ws": "^8.21.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openrois/openrois",
+    "directory": "sdk/javascript"
+  },
+  "homepage": "https://openrois.org/",
+  "bugs": {
+    "url": "https://github.com/openrois/openrois/issues"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "keywords": [
+    "rois",
+    "omg",
+    "robotics",
+    "hri",
+    "middleware",
+    "sdk",
+    "json-rpc",
+    "websocket"
+  ]
 }