@wago/plcprog-wss-client

@wago/plcprog-wss-client is a Node.js client for the public plcprog WSS server.

Install

npm install @wago/plcprog-wss-client

Usage

import { PlcprogWssClient } from "@wago/plcprog-wss-client";

const accessToken = "paste-generated-token-here";
const client = await new PlcprogWssClient({
  url: process.env.PLCPROG_WSS_URL,
  accessToken,
}).connect();
client.onDataUpdate((message) => console.log(message.topic, message.body));
client.onInstanceUpdate((message) => console.log(message.topic, message.body));
await client.dataRegisterValue("Virtual.store.energy");
await client.instanceSubscribe();
await client.workspaceInstall("scripts", ["python"], true);
await client.instanceUnsubscribe();
client.close();

The client uses the runtime's native WebSocket implementation when one is available and otherwise falls back automatically to its packaged ws dependency. This keeps the same client setup working on Node.js releases that do not expose globalThis.WebSocket, including the Node.js 18 runtime used on PLC targets. Pass webSocketImpl only when a custom implementation is needed.

Contracts

contracts/asyncapi.json is the formal AsyncAPI 3.1 contract for the WebSocket channel, authentication, messages, payloads, replies, errors, and server-pushed updates. contracts/wss-messages.json is the compact scenario index used by the focused examples. Both are intentionally static snapshots and are checked together for drift.

Coverage

• ping → pong (base)
• InstanceListRequest → InstanceListResponse (instance)
• InstanceDetailRequest → InstanceDetailResponse (instance)
• InstanceSaveRequest → InstanceSaveResponse (instance)
• InstanceDeleteRequest → InstanceDeleteResponse (instance)
• InstanceRefreshRequest → InstanceRefreshResponse (instance)
• InstanceStartRequest → InstanceStartResponse (instance)
• InstanceStopRequest → InstanceStopResponse (instance)
• InstanceRestartRequest → InstanceRestartResponse (instance)
• InstanceSubscribeRequest → InstanceSubscribeResponse (instance)
• InstanceUnsubscribeRequest → InstanceUnsubscribeResponse (instance)
• InstanceUpdate (instance)
• DataGetSchemaRequest → DataGetSchemaResponse (data)
• DataSetSchemaRequest → DataSetSchemaResponse (data)
• DataRenameSchemaRequest → DataRenameSchemaResponse (data)
• DataDeleteSchemaRequest → DataDeleteSchemaResponse (data)
• DataGetValueRequest → DataGetValueResponse (data)
• DataSetValueRequest → DataSetValueResponse (data)
• DataRegisterValueRequest → DataRegisterValueResponse (data)
• DataUnregisterValueRequest → DataUnregisterValueResponse (data)
• DataUpdate (data)
• ScriptBrowseRequest → ScriptBrowseResponse (workspace)
• ScriptSaveRequest → ScriptSaveResponse (workspace)
• ScriptDeleteRequest → ScriptDeleteResponse (workspace)
• ScriptUploadRequest → ScriptUploadResponse (workspace)
• ScriptDownloadRequest → ScriptDownloadResponse (workspace, single path or selection)
• ScriptInstallRequest → ScriptInstallResponse (workspace)
• ScriptGetContentRequest → ScriptGetContentResponse (workspace)
• ScriptSetContentRequest → ScriptSetContentResponse (workspace)
• ScriptMoveRequest → ScriptMoveResponse (workspace)
• ScriptCopyRequest → ScriptCopyResponse (workspace)
• error (base)

Focused Examples

The examples/ tree contains exactly one runnable example for each of the 32 contract message scenarios. Every focused file is deliberately self-contained: it repeats imports, URL and authentication configuration, client construction, WebSocket connection, the direct message call or push listener, output and error handling, and guaranteed disconnect. No focused example imports a shared example runner. Scenarios use the same ids and groups in every language. The combined quick-start example remains available.

The npm package includes the complete examples/ tree and its contract manifest.

Run one example from the repository root:

node examples/base/ping.js

Configuration, resource selectors, and safety switches are documented in Environment Variables.

Verify that every contract item has exactly one file:

python3 examples/check_manifest.py

Environment Variables

Each example defines an accessToken string beside client construction. Paste a generated token into that string for protected messages; the client library never reads the token from an environment variable. The remaining variables are read by the examples at runtime. Safety-gate variables protect against accidental changes but do not replace server authorization.

| Variable | When required | Default | Description | | --- | --- | --- | --- | | PLCPROG_WSS_URL | No | ws://127.0.0.1:8081/ws | URL of the plcprog WebSocket endpoint. Use wss:// when TLS is enabled. | | PLCPROG_ALLOW_MUTATION | Mutating examples | Not set | Local safety gate. Set exactly to 1 before an example may change instances, data schemas/values, or workspace content. It is not sent to the server. | | PLCPROG_ALLOW_INSTALL | Install example | Not set | Additional local safety gate for ScriptInstallRequest. Set exactly to 1; PLCPROG_ALLOW_MUTATION=1 is also required. | | PLCPROG_INSTANCE_UUID | Instance-specific examples | Not set | UUID of the runtime instance to inspect, delete, start, stop, or restart. | | PLCPROG_DATA_PATH | No | Scenario-specific | Overrides the data path. Read, registration, and update examples default to Virtual.store or Virtual.store.energy; schema/value writes use Virtual.store.clientExamples.node. | | PLCPROG_WORKSPACE_PATH | No | Scenario-specific | Overrides the workspace path used by focused messages. Defaults are the root, examples, or an isolated examples/node-wss-client.txt file depending on the scenario. | | PLCPROG_WORKSPACE_PATHS | No | examples | Non-empty comma-separated workspace paths included by the selection download-message example. | | PLCPROG_WORKSPACE_FILE | No | examples/node-wss-client.txt | Workspace file used only by the combined quick-start example. Focused examples use PLCPROG_WORKSPACE_PATH. |

Authentication

Pass a session or managed API token as the constructor's accessToken string. The client treats it as opaque configuration and automatically adds jwt.<token> alongside the plcprog WebSocket subprotocol. Omit it or use an empty string for public messages. The token authorizes protected messages when they are sent. If it later expires or is revoked, the connection and existing subscriptions remain active and continue receiving updates, while later protected messages are rejected.

Error Handling

API clients raise language-specific exceptions for non-2xx responses. WSS clients raise language-specific exceptions for {"type":"error"} envelopes and keep the server code and message available.

Timeouts

Normal runtime, instance, data, and workspace requests use a 22 second timeout. ScriptInstallRequest and /workspace/install use 900 seconds because they may run Composer, npm, Python, or Cargo installers. Large workspace content is represented as JSON string content and follows the server's /workspace/get-content and /workspace/set-content contracts.

Live Smoke Test

Set PLCPROG_WSS_URL to a running server and run either the quick-start example or any focused example under examples/. Unit tests and manifest checks are mocked/static by default and do not require a live plcprog runtime.