node-opcua-client-browser 2.177.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-2024  Sterfive SAS - 833264583 RCS ORLEANS - France (https://www.sterfive.com)
+
+Copyright (c) 2014-2022 Etienne Rossignon
+
+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/README.md

@@ -0,0 +1,42 @@
+# node-opcua-client-browser
+
+OPC UA client SDK for modern browsers, using the **WebSocket transport mapping**
+defined in OPC UA Part 6, §7.5.
+
+> **Status — scaffold only.**
+> This initial drop establishes the package layout, build toolchain, and
+> Playwright E2E harness. The WebSocket transport, the `createBrowserClient`
+> helper, and the prebuilt browser bundle arrive in follow-up PRs. Consult
+> `openspec/changes/add-browser-client-wsopcua/` for the canonical scope and
+> roadmap.
+
+## Planned scope (upcoming PRs)
+
+- Endpoint URL schemes: `opc.ws://`, `opc.wss://`, `ws://`, `wss://`
+- Security policies: `None`, `Basic256Sha256` (SignAndEncrypt)
+- User identity tokens: Anonymous, UserName/Password (password encrypted under
+  `Basic256Sha256` when applicable)
+- Services: Read / Write / CreateSubscription / CreateMonitoredItems / Publish
+
+## What is in this scaffold PR
+
+- Package skeleton (`package.json`, `tsconfig*.json`).
+- An empty `source/index.ts` that just exports a `VERSION` string; subsequent
+  PRs add the actual transport implementation.
+- A Playwright test harness that builds a minimal test page with esbuild,
+  serves it over a local HTTP server, and loads it headless in Chromium.
+- One smoke spec (`test/e2e/smoke.spec.ts`) that asserts the test page loads
+  and the `node-opcua-client-browser` module evaluates. Later PRs replace
+  this with full OPC UA Read / Write / Subscribe flows over `opc.ws` and
+  `opc.wss` against a demo server.
+
+## Running the smoke test
+
+```bash
+pnpm exec playwright install chromium   # first time only
+pnpm test:e2e                           # runs the smoke spec headless
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client_ws_transport.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module node-opcua-client-browser
+ *
+ * `ClientWS_transport` — OPC UA WebSocket client transport (Part 6 §7.5).
+ *
+ * Subclasses `ClientTCP_transport` and reuses its HEL/ACK + chunk-reassembly
+ * machinery unchanged. The only swap is the socket-creation step: instead of
+ * opening a TCP connection, we open a `WebSocket` and hand a
+ * {@link WsSocketAdapter} to `TCP_transport._install_socket`.
+ *
+ * OPC UA WebSocket framing:
+ *   - One UACP chunk per outgoing binary WebSocket frame (handled naturally —
+ *     each `write(chunk)` call invokes `ws.send(chunk)` once).
+ *   - Incoming bytes are fed into `TCP_transport`'s packet-assembler, which
+ *     re-combines split chunks.
+ *   - Subprotocol `opcua+uacp` is requested on the handshake. If the server
+ *     echoes it back we record that; if not (common with a `websockify`
+ *     bridge) we continue without failing — browsers still accept the
+ *     connection provided the server's bytes are valid UACP.
+ */
+import type { ErrorCallback } from "node-opcua-status-code";
+import { ClientTransportBase, type IClientTransportFactory, type TransportSettingsOptions } from "node-opcua-transport";
+import { type WebSocketLike } from "./ws_socket_adapter";
+/** WebSocket subprotocol name defined by OPC UA Part 6 §7.5 */
+export declare const OPCUA_UACP_SUBPROTOCOL = "opcua+uacp";
+/**
+ * A tiny WebSocket-constructor type. In the browser this is `globalThis.WebSocket`;
+ * in Node-side unit tests this is the `ws` package's `default` export. Either works.
+ */
+export type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/** Options specific to the browser WebSocket transport. */
+export interface ClientWSTransportOptions extends TransportSettingsOptions {
+    /**
+     * The WebSocket constructor to use. Defaults to `globalThis.WebSocket`.
+     * Override this from Node-side unit tests to inject the `ws` package.
+     */
+    webSocketCtor?: WebSocketConstructor;
+    /**
+     * When `true`, `connect()` fails if the peer does not echo back the
+     * `opcua+uacp` subprotocol on the WebSocket opening handshake. Defaults to
+     * `false` because `websockify` bridges do not negotiate subprotocols; the
+     * OPC UA bytes that follow will fail the HEL/ACK step anyway if the peer
+     * isn't actually speaking UACP.
+     */
+    strictSubprotocol?: boolean;
+}
+/**
+ * Parsed endpoint URL, normalised for the browser `WebSocket` constructor.
+ */
+export interface ParsedWsEndpoint {
+    /** The URL to pass to `new WebSocket(url, …)` — always starts with `ws://` or `wss://`. */
+    wsUrl: string;
+    /** `true` if the original URL used `opc.wss://` or `wss://`. */
+    secure: boolean;
+}
+/**
+ * Parse and normalise an OPC UA WebSocket endpoint URL. Accepts all four
+ * forms: `opc.ws://`, `opc.wss://`, `ws://`, `wss://`. Anything else throws.
+ *
+ * @throws {Error} if the scheme is not one of the four accepted forms.
+ */
+export declare function parseWsEndpointUrl(endpointUrl: string): ParsedWsEndpoint;
+/**
+ * WebSocket-backed client transport. A sibling of `ClientTCP_transport`: both extend
+ * {@link ClientTransportBase} and reuse its UACP HEL/ACK machinery; the only
+ * difference is the socket flavour (`WebSocket` here, `net.Socket` in TCP).
+ */
+export declare class ClientWS_transport extends ClientTransportBase {
+    private readonly _webSocketCtor;
+    private readonly _strictSubprotocol;
+    constructor(options?: ClientWSTransportOptions);
+    /**
+     * Opens a WebSocket to `endpointUrl`, adapts it to `ISocketLike`, and
+     * drives the inherited HEL/ACK transaction from `ClientTransportBase`.
+     */
+    connect(endpointUrl: string, callback: ErrorCallback): void;
+    dispose(): void;
+}
+/**
+ * A factory that produces {@link ClientWS_transport} instances. Pass to
+ * `ClientSecureChannelLayerOptions.transportFactory` to route all channel
+ * traffic through a WebSocket.
+ *
+ * @example
+ *   const ws = browserWsTransportFactory.create({});
+ *   // or, on Node:
+ *   import WebSocket from "ws";
+ *   const factory: IClientTransportFactory = {
+ *       create(s) { return new ClientWS_transport({ ...s, webSocketCtor: WebSocket as any }); }
+ *   };
+ */
+export declare const browserWsTransportFactory: IClientTransportFactory;

package/dist/client_ws_transport.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * @module node-opcua-client-browser
+ *
+ * `ClientWS_transport` — OPC UA WebSocket client transport (Part 6 §7.5).
+ *
+ * Subclasses `ClientTCP_transport` and reuses its HEL/ACK + chunk-reassembly
+ * machinery unchanged. The only swap is the socket-creation step: instead of
+ * opening a TCP connection, we open a `WebSocket` and hand a
+ * {@link WsSocketAdapter} to `TCP_transport._install_socket`.
+ *
+ * OPC UA WebSocket framing:
+ *   - One UACP chunk per outgoing binary WebSocket frame (handled naturally —
+ *     each `write(chunk)` call invokes `ws.send(chunk)` once).
+ *   - Incoming bytes are fed into `TCP_transport`'s packet-assembler, which
+ *     re-combines split chunks.
+ *   - Subprotocol `opcua+uacp` is requested on the handshake. If the server
+ *     echoes it back we record that; if not (common with a `websockify`
+ *     bridge) we continue without failing — browsers still accept the
+ *     connection provided the server's bytes are valid UACP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserWsTransportFactory = exports.ClientWS_transport = exports.OPCUA_UACP_SUBPROTOCOL = void 0;
+exports.parseWsEndpointUrl = parseWsEndpointUrl;
+/* global WebSocket */
+const node_opcua_assert_1 = require("node-opcua-assert");
+const node_opcua_debug_1 = require("node-opcua-debug");
+const node_opcua_transport_1 = require("node-opcua-transport");
+const ws_socket_adapter_1 = require("./ws_socket_adapter");
+const debugLog = (0, node_opcua_debug_1.make_debugLog)("ClientWS_transport");
+const warningLog = (0, node_opcua_debug_1.make_warningLog)("ClientWS_transport");
+const doDebug = (0, node_opcua_debug_1.checkDebugFlag)("ClientWS_transport");
+/** WebSocket subprotocol name defined by OPC UA Part 6 §7.5 */
+exports.OPCUA_UACP_SUBPROTOCOL = "opcua+uacp";
+/**
+ * Parse and normalise an OPC UA WebSocket endpoint URL. Accepts all four
+ * forms: `opc.ws://`, `opc.wss://`, `ws://`, `wss://`. Anything else throws.
+ *
+ * @throws {Error} if the scheme is not one of the four accepted forms.
+ */
+function parseWsEndpointUrl(endpointUrl) {
+    const m = /^(opc\.ws|opc\.wss|ws|wss):\/\/(.+)$/i.exec(endpointUrl);
+    if (!m) {
+        throw new Error(`[node-opcua-client-browser] unsupported endpoint URL scheme for WebSocket transport: ${endpointUrl} ` +
+            `(expected one of opc.ws://, opc.wss://, ws://, wss://)`);
+    }
+    const scheme = m[1].toLowerCase();
+    const secure = scheme === "opc.wss" || scheme === "wss";
+    const wsUrl = `${secure ? "wss" : "ws"}://${m[2]}`;
+    return { wsUrl, secure };
+}
+/**
+ * WebSocket-backed client transport. A sibling of `ClientTCP_transport`: both extend
+ * {@link ClientTransportBase} and reuse its UACP HEL/ACK machinery; the only
+ * difference is the socket flavour (`WebSocket` here, `net.Socket` in TCP).
+ */
+class ClientWS_transport extends node_opcua_transport_1.ClientTransportBase {
+    _webSocketCtor;
+    _strictSubprotocol;
+    constructor(options) {
+        super(options);
+        const resolvedCtor = options?.webSocketCtor ??
+            (typeof globalThis !== "undefined" ? globalThis.WebSocket : undefined);
+        if (!resolvedCtor) {
+            throw new Error("[ClientWS_transport] no WebSocket constructor available: pass `webSocketCtor` explicitly or run in a browser / Node 22+");
+        }
+        this._webSocketCtor = resolvedCtor;
+        this._strictSubprotocol = !!options?.strictSubprotocol;
+    }
+    /**
+     * Opens a WebSocket to `endpointUrl`, adapts it to `ISocketLike`, and
+     * drives the inherited HEL/ACK transaction from `ClientTransportBase`.
+     */
+    connect(endpointUrl, callback) {
+        this.endpointUrl = endpointUrl;
+        /* c8 ignore next */
+        doDebug && debugLog(`ClientWS_transport#connect(endpointUrl = ${endpointUrl})`);
+        let parsed;
+        try {
+            parsed = parseWsEndpointUrl(endpointUrl);
+        }
+        catch (err) {
+            callback(err);
+            return;
+        }
+        let ws;
+        try {
+            ws = new this._webSocketCtor(parsed.wsUrl, exports.OPCUA_UACP_SUBPROTOCOL);
+        }
+        catch (err) {
+            /* c8 ignore next */
+            doDebug && debugLog("WebSocket construction failed", err.message);
+            callback(err);
+            return;
+        }
+        const socket = new ws_socket_adapter_1.WsSocketAdapter(ws, parsed.wsUrl);
+        const onEarlyError = (err) => {
+            callback(err);
+        };
+        socket.once("error", onEarlyError);
+        socket.once("connect", () => {
+            socket.removeListener("error", onEarlyError);
+            // Subprotocol negotiation check. Browser WS exposes `protocol` on the
+            // instance; `ws` package exposes it too. When the peer doesn't
+            // negotiate (e.g. a websockify bridge), `protocol` is an empty
+            // string. Only fail in strict mode.
+            const negotiated = ws.protocol;
+            if (negotiated && negotiated !== exports.OPCUA_UACP_SUBPROTOCOL) {
+                const msg = `unexpected WebSocket subprotocol negotiated: "${negotiated}" (expected "${exports.OPCUA_UACP_SUBPROTOCOL}")`;
+                if (this._strictSubprotocol) {
+                    callback(new Error(`[ClientWS_transport] ${msg}`));
+                    socket.destroy();
+                    return;
+                }
+                warningLog(msg);
+            }
+            else if (!negotiated) {
+                /* c8 ignore next */
+                doDebug &&
+                    debugLog(`peer did not echo the "${exports.OPCUA_UACP_SUBPROTOCOL}" subprotocol; continuing ` +
+                        `(set strictSubprotocol=true to reject this)`);
+            }
+            // Install the WebSocket-backed socket adapter into the inherited TCP_transport machinery.
+            (0, node_opcua_assert_1.assert)(!this._socket, "transport should not have a socket yet");
+            this._install_socket(socket);
+            this._perform_HEL_ACK_transaction((err) => {
+                if (!err) {
+                    /* c8 ignore next */
+                    if (!this._socket) {
+                        return callback(new Error("Abandoned"));
+                    }
+                    this._install_post_connect_error_handler(endpointUrl);
+                    this.emit("connect");
+                }
+                else {
+                    debugLog("_perform_HEL_ACK_transaction has failed with err=", err.message);
+                }
+                callback(err);
+            });
+        });
+    }
+    dispose() {
+        /* c8 ignore next */
+        doDebug && debugLog(" ClientWS_transport disposed");
+        super.dispose();
+    }
+}
+exports.ClientWS_transport = ClientWS_transport;
+/**
+ * A factory that produces {@link ClientWS_transport} instances. Pass to
+ * `ClientSecureChannelLayerOptions.transportFactory` to route all channel
+ * traffic through a WebSocket.
+ *
+ * @example
+ *   const ws = browserWsTransportFactory.create({});
+ *   // or, on Node:
+ *   import WebSocket from "ws";
+ *   const factory: IClientTransportFactory = {
+ *       create(s) { return new ClientWS_transport({ ...s, webSocketCtor: WebSocket as any }); }
+ *   };
+ */
+exports.browserWsTransportFactory = {
+    create(settings) {
+        return new ClientWS_transport(settings);
+    }
+};
+//# sourceMappingURL=client_ws_transport.js.map

package/dist/client_ws_transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client_ws_transport.js","sourceRoot":"","sources":["../source/client_ws_transport.ts"],"names":[],"mappings":"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"}

package/dist/create_browser_client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @module node-opcua-client-browser
+ *
+ * Thin helper that constructs an `OPCUAClient` (from `node-opcua-client`)
+ * pre-wired with the browser WebSocket transport factory and, when no
+ * credentials are supplied, an in-memory certificate/key pair provider so
+ * no disk paths are touched.
+ *
+ * All other `OPCUAClient` configuration passes through unchanged — callers
+ * configure session timeouts, reconnection strategies, security policies,
+ * etc. exactly as they would for the Node client.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserClient, AttributeIds, MessageSecurityMode, SecurityPolicy } from "node-opcua-client-browser";
+ *
+ * const client = createBrowserClient({
+ *     endpointMustExist: false,
+ *     securityMode: MessageSecurityMode.None,
+ *     securityPolicy: SecurityPolicy.None,
+ * });
+ * await client.connect("opc.ws://localhost:4840");
+ * const session = await client.createSession();
+ * const dv = await session.read({ nodeId: "ns=1;s=Counter", attributeId: AttributeIds.Value });
+ * await session.close();
+ * await client.disconnect();
+ * ```
+ */
+import { OPCUAClient, type OPCUAClientOptions } from "node-opcua-client";
+import type { Certificate, PrivateKey } from "node-opcua-crypto/web";
+/**
+ * Options accepted by {@link createBrowserClient}. Superset of
+ * {@link OPCUAClientOptions}; the browser-specific defaults described above
+ * apply unless the caller overrides them.
+ */
+export interface CreateBrowserClientOptions extends OPCUAClientOptions {
+    /**
+     * Pre-built client certificate chain (DER). When combined with
+     * `clientPrivateKey`, it is loaded into an
+     * `InMemoryCertificateKeyPairProvider` so the owning `OPCUAClient`
+     * needs no disk cert files.
+     *
+     * If you already pass `certificateKeyPairProvider`, this option is
+     * ignored.
+     */
+    clientCertificate?: Certificate | Certificate[];
+    /**
+     * Pre-built client private key. Paired with `clientCertificate` to
+     * populate the in-memory provider.
+     *
+     * If you already pass `certificateKeyPairProvider`, this option is
+     * ignored.
+     */
+    clientPrivateKey?: PrivateKey;
+}
+/**
+ * Construct an `OPCUAClient` with browser-appropriate defaults.
+ *
+ * - `transportFactory` defaults to `browserWsTransportFactory` so the
+ *   underlying secure channel opens a WebSocket. Callers can override by
+ *   passing a different `transportFactory`.
+ * - `certificateKeyPairProvider` defaults to an
+ *   `InMemoryCertificateKeyPairProvider`, populated with
+ *   `clientCertificate` / `clientPrivateKey` when those are supplied.
+ *   When they are NOT supplied, the provider is constructed empty —
+ *   callers are expected to await `ensureCertificateExists(...)` on the
+ *   returned client's credentials before connecting with a non-None
+ *   security policy.
+ * - `clientCertificateManager` defaults to an `InMemoryCertificateStore`
+ *   (auto-accept unknown peer certs). Callers can override by passing
+ *   their own `clientCertificateManager` (e.g. one backed by IndexedDB
+ *   or OPFS).
+ */
+export declare function createBrowserClient(options?: CreateBrowserClientOptions): OPCUAClient;

package/dist/create_browser_client.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * @module node-opcua-client-browser
+ *
+ * Thin helper that constructs an `OPCUAClient` (from `node-opcua-client`)
+ * pre-wired with the browser WebSocket transport factory and, when no
+ * credentials are supplied, an in-memory certificate/key pair provider so
+ * no disk paths are touched.
+ *
+ * All other `OPCUAClient` configuration passes through unchanged — callers
+ * configure session timeouts, reconnection strategies, security policies,
+ * etc. exactly as they would for the Node client.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserClient, AttributeIds, MessageSecurityMode, SecurityPolicy } from "node-opcua-client-browser";
+ *
+ * const client = createBrowserClient({
+ *     endpointMustExist: false,
+ *     securityMode: MessageSecurityMode.None,
+ *     securityPolicy: SecurityPolicy.None,
+ * });
+ * await client.connect("opc.ws://localhost:4840");
+ * const session = await client.createSession();
+ * const dv = await session.read({ nodeId: "ns=1;s=Counter", attributeId: AttributeIds.Value });
+ * await session.close();
+ * await client.disconnect();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserClient = createBrowserClient;
+const node_opcua_common_1 = require("node-opcua-common");
+const node_opcua_client_1 = require("node-opcua-client");
+const client_ws_transport_1 = require("./client_ws_transport");
+/**
+ * Construct an `OPCUAClient` with browser-appropriate defaults.
+ *
+ * - `transportFactory` defaults to `browserWsTransportFactory` so the
+ *   underlying secure channel opens a WebSocket. Callers can override by
+ *   passing a different `transportFactory`.
+ * - `certificateKeyPairProvider` defaults to an
+ *   `InMemoryCertificateKeyPairProvider`, populated with
+ *   `clientCertificate` / `clientPrivateKey` when those are supplied.
+ *   When they are NOT supplied, the provider is constructed empty —
+ *   callers are expected to await `ensureCertificateExists(...)` on the
+ *   returned client's credentials before connecting with a non-None
+ *   security policy.
+ * - `clientCertificateManager` defaults to an `InMemoryCertificateStore`
+ *   (auto-accept unknown peer certs). Callers can override by passing
+ *   their own `clientCertificateManager` (e.g. one backed by IndexedDB
+ *   or OPFS).
+ */
+function createBrowserClient(options = {}) {
+    const { clientCertificate, clientPrivateKey, ...clientOptions } = options;
+    // Default to the browser WS transport factory unless the caller supplies one.
+    if (!clientOptions.transportFactory) {
+        clientOptions.transportFactory = client_ws_transport_1.browserWsTransportFactory;
+    }
+    // Default to an in-memory cert/key provider unless the caller supplies one.
+    // If the caller provided a client cert + private key, pre-populate the
+    // provider so the owning client can reach them without further async setup.
+    if (!clientOptions.certificateKeyPairProvider) {
+        const chain = clientCertificate
+            ? (Array.isArray(clientCertificate) ? clientCertificate : [clientCertificate])
+            : undefined;
+        clientOptions.certificateKeyPairProvider = new node_opcua_common_1.InMemoryCertificateKeyPairProvider(chain, clientPrivateKey);
+    }
+    // Default to an in-memory trust store unless the caller supplies one.
+    if (!clientOptions.clientCertificateManager) {
+        clientOptions.clientCertificateManager = new node_opcua_common_1.InMemoryCertificateStore({ autoAcceptUnknown: true });
+    }
+    return node_opcua_client_1.OPCUAClient.create(clientOptions);
+}
+//# sourceMappingURL=create_browser_client.js.map

package/dist/create_browser_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_browser_client.js","sourceRoot":"","sources":["../source/create_browser_client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;AAqDH,kDAwBC;AA3ED,yDAAiG;AACjG,yDAAyE;AAGzE,+DAAkE;AA6BlE;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,mBAAmB,CAAC,UAAsC,EAAgC;IACtG,MAAM,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAE1E,8EAA8E;IAC9E,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,CAAC;QAClC,aAAa,CAAC,gBAAgB,GAAG,+CAAyB,CAAC;IAC/D,CAAC;IAED,4EAA4E;IAC5E,uEAAuE;IACvE,4EAA4E;IAC5E,IAAI,CAAC,aAAa,CAAC,0BAA0B,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,iBAAiB;YAC3B,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;YAC9E,CAAC,CAAC,SAAS,CAAC;QAChB,aAAa,CAAC,0BAA0B,GAAG,IAAI,sDAAkC,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IAC/G,CAAC;IAED,sEAAsE;IACtE,IAAI,CAAC,aAAa,CAAC,wBAAwB,EAAE,CAAC;QAC1C,aAAa,CAAC,wBAAwB,GAAG,IAAI,4CAAwB,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IACvG,CAAC;IAED,OAAO,+BAAW,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/*!
+ * The MIT License (MIT)
+ * Copyright (c) 2022-2025  Sterfive SAS - 833264583 RCS ORLEANS - France (https://www.sterfive.com)
+ *
+ * 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.
+ */
+/**
+ * @module node-opcua-client-browser
+ *
+ * Browser entry point for `node-opcua-client`. Exposes the OPC UA WebSocket
+ * transport (`ClientWS_transport`, `browserWsTransportFactory`,
+ * `parseWsEndpointUrl`).
+ *
+ * Target environments: modern evergreen browsers (Chromium, Firefox, WebKit).
+ * The transport uses the OPC UA WebSocket mapping per Part 6 §7.5
+ * (`opcua+uacp` subprotocol, one UACP chunk per binary frame).
+ *
+ * NOTE: `createBrowserClient` is temporarily NOT re-exported from this
+ * barrel. Its `OPCUAClient` import drags in `node-opcua-client`, which
+ * still transitively pulls Node-only modules (`node:crypto`, `node:fs`,
+ * `node:dns`, `@ster5/global-mutex`, `multicast-dns`, …) at bundle
+ * time. The full plan to make those packages browser-safe lives at
+ * `C:\Users\etien\.claude\plans\run-pnpm-filter-node-opcua-client-browse-vivid-sparkle.md`.
+ * The Node-side helper itself is still built and unit-tested — its 8
+ * mocha cases in `test/unit/test_create_browser_client.ts` import it
+ * directly from `../../dist`. Re-export will be restored in Step 5 of
+ * the plan once Steps 1–4 land.
+ */
+export * from "./client_ws_transport";
+export * as uacp from "./uacp";
+export { type WebSocketLike, WsSocketAdapter } from "./ws_socket_adapter";
+export declare const VERSION = "2.172.0";

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/*!
+ * The MIT License (MIT)
+ * Copyright (c) 2022-2025  Sterfive SAS - 833264583 RCS ORLEANS - France (https://www.sterfive.com)
+ *
+ * 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.
+ */
+/**
+ * @module node-opcua-client-browser
+ *
+ * Browser entry point for `node-opcua-client`. Exposes the OPC UA WebSocket
+ * transport (`ClientWS_transport`, `browserWsTransportFactory`,
+ * `parseWsEndpointUrl`).
+ *
+ * Target environments: modern evergreen browsers (Chromium, Firefox, WebKit).
+ * The transport uses the OPC UA WebSocket mapping per Part 6 §7.5
+ * (`opcua+uacp` subprotocol, one UACP chunk per binary frame).
+ *
+ * NOTE: `createBrowserClient` is temporarily NOT re-exported from this
+ * barrel. Its `OPCUAClient` import drags in `node-opcua-client`, which
+ * still transitively pulls Node-only modules (`node:crypto`, `node:fs`,
+ * `node:dns`, `@ster5/global-mutex`, `multicast-dns`, …) at bundle
+ * time. The full plan to make those packages browser-safe lives at
+ * `C:\Users\etien\.claude\plans\run-pnpm-filter-node-opcua-client-browse-vivid-sparkle.md`.
+ * The Node-side helper itself is still built and unit-tested — its 8
+ * mocha cases in `test/unit/test_create_browser_client.ts` import it
+ * directly from `../../dist`. Re-export will be restored in Step 5 of
+ * the plan once Steps 1–4 land.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.WsSocketAdapter = exports.uacp = void 0;
+__exportStar(require("./client_ws_transport"), exports);
+exports.uacp = __importStar(require("./uacp"));
+var ws_socket_adapter_1 = require("./ws_socket_adapter");
+Object.defineProperty(exports, "WsSocketAdapter", { enumerable: true, get: function () { return ws_socket_adapter_1.WsSocketAdapter; } });
+exports.VERSION = "2.172.0";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,+CAA+B;AAC/B,yDAA0E;AAA7C,oHAAA,eAAe,OAAA;AAE/B,QAAA,OAAO,GAAG,SAAS,CAAC"}

package/dist/uacp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module node-opcua-client-browser
+ * @internal
+ *
+ * UACP primitives usable in the browser.
+ *
+ * These are thin re-exports of the byte-level encoders/decoders from
+ * `node-opcua-transport`. Those modules are pure-JS (only `node:events` is
+ * pulled in, which Vite polyfills automatically) and are therefore safe to
+ * bundle for the browser. Consolidating them here gives us a single point of
+ * audit if a future release of `node-opcua-transport` introduces a Node-only
+ * import.
+ */
+export { AcknowledgeMessage, HelloMessage, TCPErrorMessage, packTcpMessage, readRawMessageHeader, type TransportSettingsOptions } from "node-opcua-transport";