@synapticon/motion-master-client 2.3.0-beta.0 → 6.0.0-alpha.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synapticon GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/api-error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one place that knows how a failed request from the generated client is shaped.
+ *
+ * `swagger-typescript-api`'s client does not throw an `Error`. On a non-2xx it throws its own
+ * `HttpResponse` object, having parsed the response body into that object's `error` property — and
+ * Motion Master's own error body is `{ "error": "<message>" }`. So the message a user should see
+ * sits at `err.error.error`, two levels down, and reading one level yields the string
+ * `"[object Object]"`.
+ *
+ * That is not a shape any caller should have to know, which is the whole reason this lives here: the
+ * wrapping belongs to the generated client, the generated client belongs to this package, so the
+ * unwrapping belongs here too rather than being rediscovered in every page that catches a request.
+ */
+/**
+ * The human-readable reason a request failed.
+ *
+ * Tries, in order: the server's own message (`{ error }`, at either nesting level), the HTTP status,
+ * a thrown `Error`'s message, and finally `fallback`. The server message comes first because it is
+ * the only one that says anything specific — Motion Master's node layer writes these, and they name
+ * the object, the state, or the grammar that was wrong.
+ *
+ * @param err       Whatever was caught.
+ * @param fallback  Returned when nothing usable can be found.
+ */
+export declare function apiErrorMessage(err: unknown, fallback?: string): string;

package/dist/api-error.js

@@ -0,0 +1,52 @@
+/**
+ * The one place that knows how a failed request from the generated client is shaped.
+ *
+ * `swagger-typescript-api`'s client does not throw an `Error`. On a non-2xx it throws its own
+ * `HttpResponse` object, having parsed the response body into that object's `error` property — and
+ * Motion Master's own error body is `{ "error": "<message>" }`. So the message a user should see
+ * sits at `err.error.error`, two levels down, and reading one level yields the string
+ * `"[object Object]"`.
+ *
+ * That is not a shape any caller should have to know, which is the whole reason this lives here: the
+ * wrapping belongs to the generated client, the generated client belongs to this package, so the
+ * unwrapping belongs here too rather than being rediscovered in every page that catches a request.
+ */
+/**
+ * The human-readable reason a request failed.
+ *
+ * Tries, in order: the server's own message (`{ error }`, at either nesting level), the HTTP status,
+ * a thrown `Error`'s message, and finally `fallback`. The server message comes first because it is
+ * the only one that says anything specific — Motion Master's node layer writes these, and they name
+ * the object, the state, or the grammar that was wrong.
+ *
+ * @param err       Whatever was caught.
+ * @param fallback  Returned when nothing usable can be found.
+ */
+export function apiErrorMessage(err, fallback = 'Unknown error') {
+    if (typeof err === 'object' && err !== null) {
+        const candidate = err;
+        // The generated client's HttpResponse: the parsed body sits in `error`.
+        if (typeof candidate.error === 'object' && candidate.error !== null) {
+            const body = candidate.error;
+            if (typeof body.error === 'string' && body.error !== '') {
+                return body.error;
+            }
+        }
+        // A body handed over directly, or an already-unwrapped one.
+        if (typeof candidate.error === 'string' && candidate.error !== '') {
+            return candidate.error;
+        }
+        // No body to read — a network failure, or a response with no JSON. The status is what is left,
+        // and it is still more use than a generic sentence.
+        if (typeof candidate.status === 'number') {
+            const statusText = typeof candidate.statusText === 'string' && candidate.statusText !== ''
+                ? ` ${candidate.statusText}`
+                : '';
+            return `HTTP ${candidate.status}${statusText}`;
+        }
+    }
+    if (err instanceof Error && err.message !== '') {
+        return err.message;
+    }
+    return fallback;
+}

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { Api } from './generated/Api.js';
+import type { ApiConfig } from './generated/http-client.js';
+import { type MmpdFile } from './mmpd.js';
+import { WebSocketConnection, type WebSocketConstructor } from './web-socket-connection.js';
+export interface MotionMasterClientOptions {
+    baseUrl?: string;
+    wsUrl?: string;
+    WebSocket?: WebSocketConstructor;
+    webSocketOptions?: unknown;
+    customFetch?: ApiConfig['customFetch'];
+}
+export declare class MotionMasterClient {
+    readonly api: Api;
+    readonly ws: WebSocketConnection;
+    private readonly httpBaseUrl;
+    private readonly customFetch?;
+    constructor(options?: MotionMasterClientOptions);
+    fetchProcessDataDump(signal?: AbortSignal): Promise<MmpdFile>;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,37 @@
+// The MotionMasterClient facade: a single connection object that composes the generated HTTP API
+// (`client.api.*`, flat — e.g. `client.api.getVersion()`) with the WebSocket connection
+// (`client.ws`). It is a *connection, not a model*: it holds no mutable device/parameter/AL state
+// — the HTTP API and the monitoring stream are the source of truth. Isomorphic: pass `WebSocket`
+// (and `customFetch`) to run under Node; both default to the platform globals in the browser.
+import { Api } from './generated/Api.js';
+import { API_BASE_URL, WS_URL } from './constants.js';
+import { fetchProcessDataDump } from './mmpd.js';
+import { WebSocketConnection } from './web-socket-connection.js';
+export class MotionMasterClient {
+    /// The generated HTTP API client. Flat method surface: `client.api.getVersion()`,
+    /// `client.api.scan()`, `client.api.sdoUpload(...)`, ...
+    api;
+    /// The WebSocket connection: `client.ws.subscribe(topic, cb)`,
+    /// `client.ws.onNotification(cb)`, `client.ws.onProgress(cb)`. Connects lazily.
+    ws;
+    httpBaseUrl;
+    customFetch;
+    constructor(options = {}) {
+        this.httpBaseUrl = options.baseUrl ?? API_BASE_URL;
+        this.customFetch = options.customFetch;
+        this.api = new Api({ baseUrl: this.httpBaseUrl, customFetch: options.customFetch });
+        this.ws = new WebSocketConnection({
+            url: options.wsUrl ?? WS_URL,
+            WebSocket: options.WebSocket,
+            protocolsOrOptions: options.webSocketOptions,
+        });
+    }
+    /// Fetches and parses the live recorder dump (`GET /api/process-data/dump`) as an `MmpdFile`.
+    fetchProcessDataDump(signal) {
+        return fetchProcessDataDump(this.httpBaseUrl, { fetch: this.customFetch, signal });
+    }
+    /// Closes the WebSocket connection (and cancels reconnection). The HTTP API needs no teardown.
+    close() {
+        this.ws.close();
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const API_BASE_URL = "https://local.motion-master.synapticon.com:61447";
+export declare const WS_URL = "wss://local.motion-master.synapticon.com:62281";

package/dist/constants.js

@@ -0,0 +1,8 @@
+// Default endpoints for a Motion Master instance running on the same machine as the client. The
+// bundled Let's Encrypt cert is for `local.motion-master.synapticon.com`, which resolves to
+// 127.0.0.1, so these work out of the box for a localhost install. Override both via
+// `MotionMasterClient` options for a remote/LAN deployment.
+export const API_BASE_URL = 'https://local.motion-master.synapticon.com:61447';
+// The WebSocket connection runs on its own port/loop (separate from the HTTP API) so a slow HTTP
+// request can never stall the monitoring/notification stream.
+export const WS_URL = 'wss://local.motion-master.synapticon.com:62281';

package/dist/eni.d.ts

@@ -0,0 +1,197 @@
+export interface EniExport {
+    xml: string;
+    warnings: number;
+}
+export declare function fetchEni(baseUrl: string, options?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<EniExport>;
+export interface EniBytes {
+    hex: string;
+    bytes: number;
+}
+export interface EniRegisterAnnotation {
+    name: string;
+    description: string;
+    instance?: number;
+    decoded?: Record<string, number | boolean | string>;
+    requestsState?: string;
+    waitsForState?: string;
+}
+export interface EniInitCmd {
+    transitions?: string[];
+    states?: string[];
+    inputOffs?: number;
+    outputOffs?: number;
+    cmd: number;
+    cmdName: string;
+    beforeSlave?: boolean;
+    comment?: string;
+    requires?: string;
+    adp?: number;
+    ado?: number;
+    addr?: number;
+    data?: EniBytes;
+    dataLength?: number;
+    cnt?: number;
+    retries?: number;
+    timeoutMs?: number;
+    validate?: {
+        data: EniBytes;
+        dataMask?: EniBytes;
+        timeoutMs: number;
+    };
+    register?: EniRegisterAnnotation;
+}
+export interface EniCoeCmd {
+    transitions: string[];
+    timeoutMs: number;
+    ccs: number;
+    ccsName: 'download' | 'upload';
+    index: number;
+    subindex: number;
+    comment?: string;
+    data?: EniBytes;
+    disabled?: boolean;
+}
+export interface EniPdoEntry {
+    index: number;
+    subindex: number;
+    bitLen: number;
+    name?: string;
+    dataType?: string;
+    comment?: string;
+}
+export interface EniPdo {
+    index: number;
+    name: string;
+    syncManager?: number;
+    fixed?: boolean;
+    mandatory?: boolean;
+    entries: EniPdoEntry[];
+}
+export interface EniSyncManager {
+    index: number;
+    type: string;
+    startAddress: number;
+    controlByte: number;
+    enable: boolean;
+    minSize?: number;
+    maxSize?: number;
+    defaultSize?: number;
+    watchdog?: number;
+}
+export interface EniMailboxWindow {
+    start: number;
+    length: number;
+    pollTime?: number;
+    statusBitAddr?: number;
+}
+export interface EniSlave {
+    info: {
+        name: string;
+        physAddr: number;
+        autoIncAddr: number;
+        physics: string;
+        vendorId: number;
+        productCode: number;
+        revisionNo: number;
+        serialNo: number;
+    };
+    processData?: {
+        send?: {
+            bitStart: number;
+            bitLength: number;
+        };
+        recv?: {
+            bitStart: number;
+            bitLength: number;
+        };
+        syncManagers: EniSyncManager[];
+        rxPdos?: EniPdo[];
+        txPdos?: EniPdo[];
+    };
+    mailbox?: {
+        send: EniMailboxWindow;
+        recv: EniMailboxWindow;
+        bootstrap?: {
+            send: EniMailboxWindow;
+            recv: EniMailboxWindow;
+        };
+        protocols: string[];
+        coeInitCmds: EniCoeCmd[];
+    };
+    initCmds: EniInitCmd[];
+    previousPorts?: {
+        port: string;
+        selected: boolean;
+        physAddr?: number;
+        deviceId?: number;
+    }[];
+    dc?: {
+        potentialReferenceClock?: boolean;
+        referenceClock?: boolean;
+        cycleTime0Ns?: number;
+        cycleTime1Ns?: number;
+        shiftTimeNs?: number;
+    };
+}
+export interface EniVariable {
+    name: string;
+    bitSize: number;
+    bitOffs: number;
+    comment?: string;
+    dataType?: string;
+}
+export interface EniNetwork {
+    master: {
+        name: string;
+        destination: string;
+        source: string;
+        etherType?: number;
+        mailboxStates?: {
+            startAddr: number;
+            count: number;
+        };
+        eoe?: {
+            maxPorts: number;
+            maxFrames: number;
+            maxMacs: number;
+        };
+        initCmds: EniInitCmd[];
+    };
+    slaves: EniSlave[];
+    cyclic?: {
+        comment?: string;
+        taskId?: string;
+        cycleTimeUs?: number;
+        priority?: number;
+        frames: {
+            comment?: string;
+            cmds: EniInitCmd[];
+        }[];
+    };
+    processImage?: {
+        inputs?: {
+            byteSize: number;
+            variables: EniVariable[];
+        };
+        outputs?: {
+            byteSize: number;
+            variables: EniVariable[];
+        };
+    };
+}
+export interface EniParseResult {
+    network: EniNetwork;
+    warnings: string[];
+    summary: {
+        devices: number;
+        datagrams: number;
+        coeTransfers: number;
+    };
+}
+export declare function parseEni(baseUrl: string, xml: string, options?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<EniParseResult>;

package/dist/eni.js

@@ -0,0 +1,61 @@
+// EtherCAT Network Information (ENI) export.
+//
+// The generated client types `GET /api/eni` as a `File`, which is what swagger-typescript-api makes
+// of a binary response. An ENI is text, and what a caller wants is the document plus the warning
+// count that came with it, so this wraps the call.
+/// Exports the bus as an ENI document (`GET /api/eni`). `baseUrl` is the HTTP API origin (e.g.
+/// `https://host:61447`). Throws on a non-OK response, with the response body's `error` message
+/// when there is one — a bus that has not reached SAFE-OP or OP answers 409, because before that
+/// there is no mapping to describe. Pass `fetch` to inject an implementation (Node, request
+/// logging).
+export async function fetchEni(baseUrl, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const res = await doFetch(`${baseUrl.replace(/\/+$/, '')}/api/eni`, {
+        headers: { Accept: 'application/xml' },
+        signal: options.signal,
+    });
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body?.error) {
+                message = body.error;
+            }
+        }
+        catch {
+            // Non-JSON error body — keep the status message.
+        }
+        throw new Error(message);
+    }
+    const warnings = Number.parseInt(res.headers.get('X-Eni-Warnings') ?? '0', 10);
+    return {
+        xml: await res.text(),
+        warnings: Number.isFinite(warnings) ? warnings : 0,
+    };
+}
+/// Parses an ENI document (`POST /api/eni/parse`). `baseUrl` is the HTTP API origin. The document
+/// need not have come from this server — reading one another tool wrote is the point. Throws on a
+/// non-OK response, with the server's `error` message when there is one.
+export async function parseEni(baseUrl, xml, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const res = await doFetch(`${baseUrl.replace(/\/+$/, '')}/api/eni/parse`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/xml' },
+        body: xml,
+        signal: options.signal,
+    });
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body?.error) {
+                message = body.error;
+            }
+        }
+        catch {
+            // Non-JSON error body — keep the status message.
+        }
+        throw new Error(message);
+    }
+    return (await res.json());
+}