@wago/plcprog-api-client

@wago/plcprog-api-client is a Node.js client for the public plcprog API server.

Install

npm install @wago/plcprog-api-client

Usage

import { PlcprogApiClient } from "@wago/plcprog-api-client";

const accessToken = "paste-generated-token-here";
const client = new PlcprogApiClient({
  baseUrl: process.env.PLCPROG_API_URL,
  accessToken,
});
await client.instances.list();
await client.data.getValue("Virtual.store.energy");
await client.workspace.setContent("examples/run.py", "print(1)");

Contracts

Public contract summaries are stored in contracts/. They are intentionally static and do not include local checkout paths or generated update helpers.

Coverage

• GET / - Swagger UI redirect
• GET /index.html - Swagger UI index
• GET /openapi.json - OpenAPI 3.1 document
• GET /health - API server health
• GET /runtime/info - Loaded API server runtime metadata
• GET /instances - List runtime instances
• POST /instances - Create runtime instance
• GET /instances/script-interpreters - Supported script interpreter metadata
• POST /instances/script-command-preview - Preview a script instance command
• GET /instances/{uuid} - Read runtime instance
• PUT /instances/{uuid} - Update runtime instance
• DELETE /instances/{uuid} - Delete runtime instance
• POST /instances/{uuid}/start - Start runtime instance
• POST /instances/{uuid}/stop - Stop runtime instance
• POST /instances/{uuid}/restart - Restart runtime instance
• GET /instances/{uuid}/logs - Read runtime instance logs
• GET /data/get-schema - Read data schema
• POST /data/set-schema - Write data schema
• POST /data/rename-schema - Rename data schema path
• DELETE /data/delete-schema - Delete data schema
• GET /data/get-value - Read data value
• POST /data/set-value - Write data value
• GET /workspace/browse - Browse workspace entry tree
• POST /workspace/save - Save workspace entry
• DELETE /workspace/delete - Delete workspace entry
• POST /workspace/upload - Upload workspace file content
• GET /workspace/download - Download a workspace folder as a zip payload
• POST /workspace/download - Download selected workspace entries as one zip payload
• POST /workspace/install - Install workspace dependencies
• GET /workspace/get-content - Read workspace file content
• POST /workspace/set-content - Write workspace file content
• POST /workspace/move - Move workspace entry
• POST /workspace/copy - Copy workspace entry
• GET /registry/packages/search - Search public package registries
• GET /registry/packages/versions - List public package versions

Focused Examples

The examples/ tree contains exactly one runnable example for each of the 35 contract operations. Every focused file is deliberately self-contained: it repeats imports, URL and authentication configuration, client construction, the direct operation call, output and error handling, and the HTTP cleanup semantics. 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.

Run one example from the repository root:

node examples/runtime/get-health.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 endpoints; 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_API_URL | No | http://127.0.0.1:8080 | Base URL of the plcprog HTTP API. Reverse-proxy path prefixes and an optional trailing slash are supported. | | PLCPROG_ALLOW_MUTATION | Mutating examples | Not set | Local safety gate. Set exactly to 1 before an example may create, update, start, stop, restart, move, copy, or delete data. It is not sent to the server. | | PLCPROG_ALLOW_INSTALL | Install example | Not set | Additional local safety gate for the workspace dependency installer. 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 read, update, delete, start, stop, restart, or inspect for logs. | | PLCPROG_DATA_PATH | No | Scenario-specific | Overrides the data path. Read examples default to Virtual.store or Virtual.store.energy; write examples use the isolated Virtual.store.clientExamples.node namespace. | | PLCPROG_WORKSPACE_PATH | No | Scenario-specific | Overrides the workspace path used by focused examples. Defaults are the root, examples, or an isolated examples/node-client.txt file depending on the operation. | | PLCPROG_WORKSPACE_PATHS | No | examples | Non-empty comma-separated workspace paths included by the selection-download example. | | PLCPROG_WORKSPACE_FILE | No | examples/node-client.txt | Workspace file used only by the combined quick-start example. Focused examples use PLCPROG_WORKSPACE_PATH. | | PLCPROG_PROJECT_TYPE | No | npm | Registry ecosystem supplied to package search and version examples. | | PLCPROG_PACKAGE_QUERY | No | typescript | Search text used by the registry package-search example. | | PLCPROG_PACKAGE_NAME | No | typescript | Exact package name used by the registry package-versions example. |

Authentication

Pass a session or managed API token as the constructor's accessToken string. The client treats it as opaque configuration and automatically sends Authorization: Bearer <token> with every request. Omit it or use an empty string for public endpoints. A token authorizes protected operations when they are requested; expiring or revoking it does not stop a script instance that was already started, while later protected requests 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_API_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.