opcjs-client 0.1.40-alpha → 0.1.41-alpha

package/dist/index.cjs

@@ -13,6 +13,18 @@ var SessionInvalidError = class extends Error {
 };
 
 // src/services/serviceBase.ts
+var requestHandleCounter = 0;
+function nextRequestHandle() {
+  if (requestHandleCounter >= 2147483647) {
+    requestHandleCounter = 1;
+  } else {
+    requestHandleCounter++;
+  }
+  return requestHandleCounter;
+}
+function lastAssignedHandle() {
+  return requestHandleCounter;
+}
 var ServiceBase = class {
   constructor(authToken, secureChannel) {
     this.authToken = authToken;
@@ -35,18 +47,43 @@ var ServiceBase = class {
     }
     throw new Error(`${context} failed: ${opcjsBase.StatusCodeToString(result)} (${opcjsBase.StatusCodeToStringNumber(result)})`);
   }
-  createRequestHeader() {
+  /**
+   * Builds a RequestHeader for an outgoing service request.
+   *
+   * @param returnDiagnostics - Bitmask of diagnostic fields to request from the
+   *   server (OPC UA Part 4, §7.15). Use {@link ReturnDiagnosticsMask} constants
+   *   to compose the value. Default `0` = no diagnostics.
+   */
+  createRequestHeader(returnDiagnostics = 0, preAllocatedHandle) {
     const requestHeader = new opcjsBase.RequestHeader();
     requestHeader.authenticationToken = this.authToken;
     requestHeader.timestamp = /* @__PURE__ */ new Date();
-    requestHeader.requestHandle = 0;
-    requestHeader.returnDiagnostics = 0;
+    requestHeader.requestHandle = preAllocatedHandle ?? nextRequestHandle();
+    requestHeader.returnDiagnostics = returnDiagnostics;
     requestHeader.auditEntryId = "";
     requestHeader.timeoutHint = 6e4;
     requestHeader.additionalHeader = opcjsBase.ExtensionObject.newEmpty();
     return requestHeader;
   }
 };
+var CertificateRequiredError = class extends Error {
+  statusCode;
+  constructor(statusCode) {
+    super(
+      `Server requires a client certificate: ${opcjsBase.StatusCodeToString(statusCode)} (0x${statusCode.toString(16).toUpperCase().padStart(8, "0")})`
+    );
+    this.name = "CertificateRequiredError";
+    this.statusCode = statusCode;
+  }
+};
+var CERTIFICATE_REQUIRED_STATUS_CODES = /* @__PURE__ */ new Set([
+  2148663296,
+  // BadCertificateInvalid
+  2148728832,
+  // BadSecurityChecksFailed
+  2153316352
+  // BadNoValidCertificates
+]);
 
 // src/services/sessionService.ts
 var SessionService = class _SessionService extends ServiceBase {
@@ -57,9 +94,16 @@ var SessionService = class _SessionService extends ServiceBase {
   logger = opcjsBase.getLogger("services.SessionService");
   /**
    * Creates a new session on the server (OPC UA Part 4, Section 5.7.2).
+   *
+   * @param clientCertificate - Optional DER-encoded client certificate to include in
+   *   the request. Pass `null` (default) for SecurityPolicy None without a cert.
+   *   When the server rejects a `null`-cert request with a certificate-related status
+   *   code, the caller should retry with a `Uint8Array` certificate (OPC UA 1.0
+   *   fallback — see `CertificateRequiredError`).
    * @returns The session ID, authentication token, and selected server endpoint.
+   * @throws {CertificateRequiredError} when the server demands a client certificate.
    */
-  async createSession() {
+  async createSession(clientCertificate = null) {
     this.logger.debug("Creating session...");
     const clientDescription = new opcjsBase.ApplicationDescription();
     clientDescription.applicationUri = this.configuration.applicationUri;
@@ -76,7 +120,7 @@ var SessionService = class _SessionService extends ServiceBase {
     request.endpointUrl = this.secureChannel.getEndpointUrl();
     request.sessionName = "";
     request.clientNonce = null;
-    request.clientCertificate = null;
+    request.clientCertificate = clientCertificate ?? null;
     request.requestedSessionTimeout = 6e4;
     request.maxResponseMessageSize = 0;
     this.logger.debug("Sending CreateSessionRequest...");
@@ -90,6 +134,9 @@ var SessionService = class _SessionService extends ServiceBase {
     }
     const serviceResult = castedResponse.responseHeader?.serviceResult;
     if (serviceResult !== void 0 && serviceResult !== opcjsBase.StatusCode.Good) {
+      if (CERTIFICATE_REQUIRED_STATUS_CODES.has(serviceResult)) {
+        throw new CertificateRequiredError(serviceResult);
+      }
       throw new Error(`CreateSessionRequest failed: ${opcjsBase.StatusCodeToString(serviceResult)}`);
     }
     const clientConnectionUrl = new URL("opc." + this.secureChannel.getEndpointUrl());
@@ -139,6 +186,33 @@ var SessionService = class _SessionService extends ServiceBase {
     }
     this.logger.debug("Session activated.");
   }
+  /**
+   * Sends a CancelRequest to the server asking it to abandon the pending
+   * service request identified by `requestHandle` (OPC UA Part 4, Section 5.7.5).
+   *
+   * The server makes a best-effort attempt to cancel matching requests.
+   * Cancelled requests complete with a status of `BadRequestCancelledByClient`.
+   *
+   * @param requestHandle - The `requestHeader.requestHandle` value of the pending
+   *   request to cancel. Pass `0` to attempt to cancel all outstanding requests
+   *   (server behaviour for handle 0 is implementation-specific).
+   * @returns The number of pending requests that were actually cancelled
+   *   (`CancelResponse.cancelCount`).
+   */
+  async cancel(requestHandle) {
+    this.logger.debug(`Sending CancelRequest for requestHandle ${requestHandle}...`);
+    const request = new opcjsBase.CancelRequest();
+    request.requestHeader = this.createRequestHeader();
+    request.requestHandle = requestHandle;
+    const response = await this.secureChannel.issueServiceRequest(request);
+    const result = response?.responseHeader?.serviceResult;
+    if (result !== void 0 && result !== opcjsBase.StatusCode.Good) {
+      throw new Error(`CancelRequest failed: ${opcjsBase.StatusCodeToString(result)}`);
+    }
+    const cancelCount = response?.cancelCount ?? 0;
+    this.logger.debug(`CancelRequest completed; cancelCount = ${cancelCount}.`);
+    return cancelCount;
+  }
   /**
    * Closes the current session on the server (OPC UA Part 4, Section 5.7.4).
    * @param deleteSubscriptions - When true the server deletes all Subscriptions
@@ -224,6 +298,22 @@ var Session = class {
   getEndpoint() {
     return this.endpoint;
   }
+  /**
+   * Switches the active user identity for this session by calling ActivateSession with
+   * a new identity token (OPC UA Part 4, Section 5.7.3 — Session Client Impersonate
+   * conformance unit).
+   *
+   * The server re-evaluates authorisation for the session under the new identity.
+   * All existing Subscriptions and MonitoredItems are preserved; only the security
+   * context changes.
+   *
+   * @param identity - The new user identity to apply to the session.
+   * @throws When the server returns a non-Good ServiceResult (e.g. `BadIdentityTokenRejected`
+   *   or `BadUserAccessDenied`).
+   */
+  async impersonate(identity) {
+    await this.activateSession(identity);
+  }
   /**
    * Closes the session on the server (OPC UA Part 4, Section 5.7.4).
    * @param deleteSubscriptions - When true the server deletes all Subscriptions
@@ -243,10 +333,30 @@ var SessionHandler = class {
   sessionServices;
   logger = opcjsBase.getLogger("sessions.SessionHandler");
   async createNewSession(identity) {
-    const ret = await this.sessionServices.createSession();
-    this.sessionServices = this.sessionServices.recreate(ret.authToken);
-    const session = new Session(ret.sessionId, ret.authToken, ret.endpoint, this.sessionServices);
-    this.validateUserTokenPolicy(identity, ret.endpoint);
+    let sessionResult;
+    try {
+      sessionResult = await this.sessionServices.createSession(null);
+    } catch (err) {
+      if (err instanceof CertificateRequiredError) {
+        const fallbackCert = this.configuration.securityConfiguration?.applicationInstanceCertificate;
+        if (fallbackCert) {
+          this.logger.info(
+            "Server requires a client certificate (OPC UA 1.0 fallback); retrying CreateSession with applicationInstanceCertificate."
+          );
+          sessionResult = await this.sessionServices.createSession(fallbackCert);
+        } else {
+          this.logger.warn(
+            "Server requires a client certificate but no applicationInstanceCertificate is configured in securityConfiguration. Cannot complete the 1.0 fallback."
+          );
+          throw err;
+        }
+      } else {
+        throw err;
+      }
+    }
+    this.sessionServices = this.sessionServices.recreate(sessionResult.authToken);
+    const session = new Session(sessionResult.sessionId, sessionResult.authToken, sessionResult.endpoint, this.sessionServices);
+    this.validateUserTokenPolicy(identity, sessionResult.endpoint);
     await session.activateSession(identity);
     return session;
   }
@@ -278,6 +388,17 @@ var SessionHandler = class {
   async closeSession(deleteSubscriptions = true) {
     await this.sessionServices.closeSession(deleteSubscriptions);
   }
+  /**
+   * Sends a CancelRequest to the server to abandon a pending service call
+   * (OPC UA Part 4, Section 5.7.5).
+   *
+   * @param requestHandle - The `requestHandle` from the `RequestHeader` of the
+   *   pending request to cancel.
+   * @returns The number of requests the server actually cancelled.
+   */
+  async cancel(requestHandle) {
+    return this.sessionServices.cancel(requestHandle);
+  }
   /**
    * Validates the requested user-identity token type against:
    *   1. The `allowedUserTokenTypes` from the client security configuration — the
@@ -320,9 +441,10 @@ var AttributeService = class extends ServiceBase {
    * @param nodeIds - NodeIds of the Nodes to read.
    * @param maxAge - Maximum age of the cached value in milliseconds the server may return. 0 = always current value.
    * @param timestampsToReturn - Which timestamps to include in results. Default: Source.
-   * @returns Array of results containing value and raw status code number, one per requested NodeId.
+   * @param returnDiagnostics - Bitmask of diagnostic fields to request (OPC UA Part 4, §7.15). Default: 0.
+   * @returns Array of results containing value, raw status code, and optional diagnostic info, one per requested NodeId.
    */
-  async ReadValue(nodeIds, maxAge = 0, timestampsToReturn = opcjsBase.TimestampsToReturnEnum.Source) {
+  async ReadValue(nodeIds, maxAge = 0, timestampsToReturn = opcjsBase.TimestampsToReturnEnum.Source, returnDiagnostics = 0, requestHandle) {
     const readValueIds = nodeIds.map((ni) => {
       const readValueId = new opcjsBase.ReadValueId();
       readValueId.nodeId = ni;
@@ -332,7 +454,7 @@ var AttributeService = class extends ServiceBase {
       return readValueId;
     });
     const request = new opcjsBase.ReadRequest();
-    request.requestHeader = this.createRequestHeader();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics, requestHandle);
     request.maxAge = maxAge;
     request.timestampsToReturn = timestampsToReturn;
     request.nodesToRead = readValueIds;
@@ -340,10 +462,13 @@ var AttributeService = class extends ServiceBase {
     const response = await this.secureChannel.issueServiceRequest(request);
     this.checkServiceResult(response.responseHeader?.serviceResult, "ReadRequest");
     const results = new Array();
-    for (const dataValue of response.results ?? []) {
+    const diagInfos = response.diagnosticInfos ?? [];
+    for (let i = 0; i < (response.results ?? []).length; i++) {
+      const dataValue = response.results[i];
       results.push({
         statusCode: dataValue.statusCode ?? opcjsBase.StatusCode.Good,
-        value: dataValue.value
+        value: dataValue.value,
+        diagnosticInfo: diagInfos[i]
       });
     }
     return results;
@@ -355,9 +480,10 @@ var AttributeService = class extends ServiceBase {
 
 // src/readValueResult.ts
 var ReadValueResult = class {
-  constructor(value, statusCode) {
+  constructor(value, statusCode, diagnosticInfo) {
     this.value = value;
     this.statusCode = statusCode;
+    this.diagnosticInfo = diagnosticInfo;
   }
 };
 
@@ -385,6 +511,15 @@ var SubscriptionHandler = class {
   isRunning = false;
   /** Guards against multiple concurrent publish loops. */
   publishInFlight = false;
+  /**
+   * Optional callback invoked when the server announces a shutdown via a
+   * `StatusChangeNotification` with status `BadShutdown` or `BadServerHalted`
+   * (OPC UA Part 4, §5.13.6.2 — Session Client Detect Shutdown).
+   *
+   * Assign this before calling `subscribe()`.  The client sets it automatically
+   * in `initServices()` to trigger a reconnect.
+   */
+  onShutdown;
   /** Returns true when at least one subscription is active and the publish loop is running. */
   hasActiveSubscription() {
     return this.isRunning && this.entries.length > 0;
@@ -449,6 +584,11 @@ var SubscriptionHandler = class {
           `Subscription ${subscriptionId} status changed: 0x${statusChange.status?.toString(16).toUpperCase()}`
         );
         this.isRunning = false;
+        const status = statusChange.status;
+        if (status === opcjsBase.StatusCode.BadShutdown || status === opcjsBase.StatusCode.BadServerHalted) {
+          this.logger.warn("Server shutdown announced via StatusChangeNotification \u2014 triggering reconnect.");
+          this.onShutdown?.();
+        }
         return;
       } else {
         this.logger.warn(
@@ -566,18 +706,22 @@ var MethodService = class extends ServiceBase {
   /**
    * Calls one or more methods on the server (OPC UA Part 4, Section 5.11.2).
    * @param methodsToCall - Array of CallMethodRequest describing each method to invoke.
-   * @returns Array of results containing output argument values and raw status code number, one per requested method.
+   * @param returnDiagnostics - Bitmask of diagnostic fields to request (OPC UA Part 4, §7.15). Default: 0.
+   * @returns Array of results containing output argument values, raw status code, and optional diagnostic info,
+   *   one per requested method.
    */
-  async call(methodsToCall) {
+  async call(methodsToCall, returnDiagnostics = 0, requestHandle) {
     const request = new opcjsBase.CallRequest();
-    request.requestHeader = this.createRequestHeader();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics, requestHandle);
     request.methodsToCall = methodsToCall;
     this.logger.debug("Sending CallRequest...");
     const response = await this.secureChannel.issueServiceRequest(request);
     this.checkServiceResult(response.responseHeader?.serviceResult, "CallRequest");
-    return response.results.map((result) => ({
+    const diagInfos = response.diagnosticInfos ?? [];
+    return response.results.map((result, i) => ({
       statusCode: result.statusCode ?? opcjsBase.StatusCode.Good,
-      value: result.outputArguments.map((arg) => arg.value)
+      value: result.outputArguments.map((arg) => arg.value),
+      diagnosticInfo: diagInfos[i]
     }));
   }
   constructor(authToken, secureChannel) {
@@ -587,9 +731,10 @@ var MethodService = class extends ServiceBase {
 
 // src/method/callMethodResult.ts
 var CallMethodResult = class {
-  constructor(values, statusCode) {
+  constructor(values, statusCode, diagnosticInfo) {
     this.values = values;
     this.statusCode = statusCode;
+    this.diagnosticInfo = diagnosticInfo;
   }
 };
 var BrowseService = class extends ServiceBase {
@@ -597,15 +742,16 @@ var BrowseService = class extends ServiceBase {
   /**
    * Browses one or more Nodes and returns their References (OPC UA Part 4, Section 5.9.2).
    * @param nodesToBrowse - Array of BrowseDescriptions specifying nodes and filter criteria.
+   * @param returnDiagnostics - Bitmask of diagnostic fields to request (OPC UA Part 4, §7.15). Default: 0.
    * @returns Array of BrowseResult, one per requested node.
    */
-  async browse(nodesToBrowse) {
+  async browse(nodesToBrowse, returnDiagnostics = 0, requestHandle) {
     const view = new opcjsBase.ViewDescription();
     view.viewId = opcjsBase.NodeId.newNumeric(0, 0);
     view.timestamp = /* @__PURE__ */ new Date(-116444736e5);
     view.viewVersion = 0;
     const request = new opcjsBase.BrowseRequest();
-    request.requestHeader = this.createRequestHeader();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics, requestHandle);
     request.view = view;
     request.requestedMaxReferencesPerNode = 0;
     request.nodesToBrowse = nodesToBrowse;
@@ -618,11 +764,12 @@ var BrowseService = class extends ServiceBase {
    * Continues a Browse operation using continuation points (OPC UA Part 4, Section 5.9.3).
    * @param continuationPoints - Continuation points returned by a prior Browse or BrowseNext call.
    * @param releaseContinuationPoints - If true, releases the continuation points without returning results.
+   * @param returnDiagnostics - Bitmask of diagnostic fields to request (OPC UA Part 4, §7.15). Default: 0.
    * @returns Array of BrowseResult, one per continuation point.
    */
-  async browseNext(continuationPoints, releaseContinuationPoints) {
+  async browseNext(continuationPoints, releaseContinuationPoints, returnDiagnostics = 0) {
     const request = new opcjsBase.BrowseNextRequest();
-    request.requestHeader = this.createRequestHeader();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics);
     request.releaseContinuationPoints = releaseContinuationPoints;
     request.continuationPoints = continuationPoints;
     this.logger.debug("Sending BrowseNextRequest...");
@@ -647,10 +794,67 @@ var BrowseNodeResult = class {
     this.typeDefinition = typeDefinition;
   }
 };
+var NamespaceTable = class {
+  uris;
+  constructor(uris = []) {
+    this.uris = Object.freeze([...uris]);
+  }
+  /** Returns the namespace URI at the given index, or `undefined` if out of range. */
+  getUri(index) {
+    return this.uris[index];
+  }
+  /** Returns the namespace index for the given URI, or `undefined` if not found. */
+  getIndex(uri) {
+    const idx = this.uris.indexOf(uri);
+    return idx >= 0 ? idx : void 0;
+  }
+  /** Returns the full ordered array of namespace URIs. */
+  getUris() {
+    return this.uris;
+  }
+  /** Returns `true` when both tables contain the same URIs in the same order. */
+  equals(other) {
+    if (this.uris.length !== other.uris.length) return false;
+    return this.uris.every((uri, i) => uri === other.uris[i]);
+  }
+  /**
+   * Remaps the namespace index of `nodeId` from this table to the equivalent
+   * index in `newTable` by matching namespace URIs.
+   *
+   * - Namespace index `0` (OPC UA base namespace) is always returned unchanged.
+   * - Returns the **same** `NodeId` instance when the index has not changed.
+   * - Returns a **new** `NodeId` instance with the updated index when remapping
+   *   is required.
+   *
+   * @throws {Error} When the namespace URI at `nodeId.namespace` is not present
+   *   in this (old) table or when the URI is not present in `newTable`.
+   */
+  remapNodeId(nodeId, newTable) {
+    if (nodeId.namespace === 0) return nodeId;
+    const uri = this.getUri(nodeId.namespace);
+    if (uri === void 0) {
+      throw new Error(
+        `Cannot remap ${nodeId.toString()}: namespace index ${nodeId.namespace} is not present in the old NamespaceTable (length ${this.uris.length}).`
+      );
+    }
+    const newIndex = newTable.getIndex(uri);
+    if (newIndex === void 0) {
+      throw new Error(
+        `Cannot remap ${nodeId.toString()}: namespace URI '${uri}' is not present in the new NamespaceTable.`
+      );
+    }
+    if (newIndex === nodeId.namespace) return nodeId;
+    return new opcjsBase.NodeId(newIndex, nodeId.identifier);
+  }
+};
 
 // src/client.ts
 var SERVER_STATUS_NODE_ID = opcjsBase.NodeId.newNumeric(0, 2256);
+var NAMESPACE_ARRAY_NODE_ID = opcjsBase.NodeId.newNumeric(0, 2255);
+var ESTIMATED_RETURN_TIME_NODE_ID = opcjsBase.NodeId.newNumeric(0, 2992);
+var HAS_PROPERTY_REF_TYPE_ID = opcjsBase.NodeId.newNumeric(0, 46);
 var KEEP_ALIVE_INTERVAL_MS = 25e3;
+var OPC_UA_MIN_DATE_TIME_MS = -116444736e5;
 var Client = class {
   constructor(endpointUrl, configuration, identity) {
     this.configuration = configuration;
@@ -672,6 +876,40 @@ var Client = class {
   ws;
   sessionHandler;
   keepAliveTimer;
+  /** Set to true while a shutdown-triggered reconnect is pending to avoid duplicate attempts. */
+  shutdownReconnectPending = false;
+  /** Most recently read NamespaceArray from the server (Session Client Renew NodeIds). */
+  namespaceTable;
+  /**
+   * Called whenever the server's NamespaceArray changes after a session (re-)establishment
+   * (OPC UA Part 4, Section 5.7.1 — Session Client Renew NodeIds conformance unit).
+   *
+   * Use `oldTable.remapNodeId(nodeId, newTable)` to recalculate cached NodeIds.
+   *
+   * @example
+   * ```ts
+   * client.onNamespaceTableChanged = (oldTable, newTable) => {
+   *   cachedNodeId = oldTable.remapNodeId(cachedNodeId, newTable)
+   * }
+   * ```
+   */
+  onNamespaceTableChanged;
+  /**
+   * Called when the server sends `EstimatedReturnTime = MinDateTime`, indicating it does not
+   * expect to restart (OPC UA Part 5, Section 12.6 — Base Info Client Estimated Return Time
+   * conformance unit).
+   *
+   * When this fires the automatic reconnect is suppressed. The application is responsible for
+   * deciding whether to keep the `Client` instance or dispose it.
+   *
+   * @example
+   * ```ts
+   * client.onPermanentShutdown = () => {
+   *   console.warn('Server will not restart — closing client.')
+   * }
+   * ```
+   */
+  onPermanentShutdown;
   getSession() {
     if (!this.session) {
       throw new Error("No session available");
@@ -692,6 +930,47 @@ var Client = class {
       new SubscriptionService(authToken, sc),
       new MonitoredItemService(authToken, sc)
     );
+    this.subscriptionHandler.onShutdown = () => this.handleServerShutdownDetected();
+    void this.refreshNamespaceTable();
+  }
+  /**
+   * Reads `Server.NamespaceArray` (ns=0, i=2255) and updates the stored
+   * `NamespaceTable`. When the table changes compared to the previous read the
+   * `onNamespaceTableChanged` callback is fired so the application can remap
+   * any cached NodeIds (OPC UA Part 4, Section 5.7.1 — Session Client Renew
+   * NodeIds conformance unit).
+   *
+   * Errors are logged as warnings and do not propagate to the caller.
+   */
+  async refreshNamespaceTable() {
+    if (!this.attributeService) return;
+    try {
+      const results = await this.attributeService.ReadValue([NAMESPACE_ARRAY_NODE_ID]);
+      const variant = results[0]?.value;
+      const uris = variant?.value;
+      if (!Array.isArray(uris)) {
+        this.logger.warn("NamespaceArray read returned an unexpected value; skipping table update.");
+        return;
+      }
+      const newTable = new NamespaceTable(uris);
+      const oldTable = this.namespaceTable;
+      this.namespaceTable = newTable;
+      if (oldTable !== void 0 && !oldTable.equals(newTable)) {
+        this.logger.info("NamespaceArray changed; notifying application to renew NodeIds.");
+        this.onNamespaceTableChanged?.(oldTable, newTable);
+      }
+    } catch (err) {
+      this.logger.warn("NamespaceArray read failed; namespace table not updated:", err);
+    }
+  }
+  /**
+   * Returns the most recently read `NamespaceTable` for this session.
+   *
+   * Available after `connect()` completes (the table is read as part of session
+   * establishment). Returns `undefined` before the first successful read.
+   */
+  getNamespaceTable() {
+    return this.namespaceTable;
   }
   /**
    * Executes `fn` and, if it throws a `SessionInvalidError`, creates a fresh
@@ -733,6 +1012,11 @@ var Client = class {
    * Starts a periodic keep-alive timer that reads Server_ServerStatus when no subscription is
    * active. OPC UA Part 4, Section 5.7.1 requires clients to keep the session alive; when no
    * subscription Publish loop is running this is the only mechanism that does so.
+   *
+   * The keep-alive read also serves as the **Detect Shutdown** mechanism (Session Client Detect
+   * Shutdown conformance unit): when the returned `ServerStatusDataType.state` equals
+   * `ServerStateEnum.Shutdown` the client schedules a reconnect after
+   * `SHUTDOWN_RECONNECT_DELAY_MS` to let the server finish its shutdown sequence.
    */
   startKeepAlive() {
     this.keepAliveTimer = setInterval(() => {
@@ -740,7 +1024,12 @@ var Client = class {
         return;
       }
       if (this.attributeService) {
-        void this.attributeService.ReadValue([SERVER_STATUS_NODE_ID]).catch((err) => {
+        void this.attributeService.ReadValue([SERVER_STATUS_NODE_ID]).then((results) => {
+          const statusData = results[0]?.value;
+          if (statusData?.state === opcjsBase.ServerStateEnum.Shutdown) {
+            this.handleServerShutdownDetected();
+          }
+        }).catch((err) => {
           this.logger.warn("Keep-alive read failed:", err);
         });
       }
@@ -750,6 +1039,87 @@ var Client = class {
     clearInterval(this.keepAliveTimer);
     this.keepAliveTimer = void 0;
   }
+  /**
+   * Called when a server-shutdown announcement is detected — either via the keep-alive read
+   * returning `ServerStateEnum.Shutdown` or via a subscription `StatusChangeNotification`
+   * with status `BadShutdown` / `BadServerHalted`.
+   *
+   * Reads `Server/ServerStatus/EstimatedReturnTime` (ns=0, i=2992) to decide how long to
+   * wait before reconnecting (Base Info Client Estimated Return Time conformance unit).
+   * Falls back to `configuration.shutdownReconnectDelayMs` when the read fails or the
+   * attributed service is not yet available.  Fires `onPermanentShutdown` and suppresses the
+   * reconnect when the server sends `MinDateTime`.
+   *
+   * Only one reconnect attempt is scheduled at a time; a second detection while one is already
+   * pending is silently ignored.
+   */
+  handleServerShutdownDetected() {
+    if (this.shutdownReconnectPending) {
+      return;
+    }
+    this.shutdownReconnectPending = true;
+    this.stopKeepAlive();
+    this.logger.warn("Server shutdown detected; reading EstimatedReturnTime...");
+    void this.computeReconnectDelayMs().then((delayMs) => {
+      if (delayMs === null) {
+        this.logger.warn(
+          "Server indicated it will not restart (MinDateTime). Firing onPermanentShutdown."
+        );
+        this.onPermanentShutdown?.();
+        this.shutdownReconnectPending = false;
+        return;
+      }
+      this.logger.warn(`Scheduling reconnect in ${delayMs} ms...`);
+      setTimeout(() => {
+        void this.reconnectAndReactivate().then(() => {
+          this.initServices();
+          this.startKeepAlive();
+          this.logger.info("Reconnected after server shutdown.");
+        }).catch((err) => {
+          this.logger.warn("Reconnect after server shutdown failed:", err);
+        }).finally(() => {
+          this.shutdownReconnectPending = false;
+        });
+      }, delayMs);
+    });
+  }
+  /**
+   * Reads `Server/ServerStatus/EstimatedReturnTime` (ns=0, i=2992) and returns the reconnect
+   * delay in milliseconds (Base Info Client Estimated Return Time — OPC UA Part 5, §12.6):
+   *
+   * - Valid future `DateTime` → delay = `estimatedReturnTime − now`, clamped to at least
+   *   `MIN_RECONNECT_DELAY_MS`.
+   * - Past `DateTime` (server should already be available) → `MIN_RECONNECT_DELAY_MS`.
+   * - OPC UA `MinDateTime` (server will not restart) → `null`.
+   * - Unreadable / unavailable → falls back to `configuration.shutdownReconnectDelayMs`.
+   */
+  async computeReconnectDelayMs() {
+    if (!this.attributeService) {
+      return this.configuration.shutdownReconnectDelayMs;
+    }
+    try {
+      const results = await this.attributeService.ReadValue([ESTIMATED_RETURN_TIME_NODE_ID]);
+      const variant = results[0]?.value;
+      const estimatedReturnTime = variant?.value;
+      if (estimatedReturnTime instanceof Date && !isNaN(estimatedReturnTime.getTime())) {
+        if (estimatedReturnTime.getTime() <= OPC_UA_MIN_DATE_TIME_MS) {
+          return null;
+        }
+        const delayMs = estimatedReturnTime.getTime() - Date.now();
+        if (delayMs > 0) {
+          this.logger.info(
+            `EstimatedReturnTime: ${estimatedReturnTime.toISOString()} (reconnect in ${delayMs} ms).`
+          );
+          return delayMs;
+        }
+        this.logger.info("EstimatedReturnTime is in the past; reconnecting immediately.");
+        return this.configuration.minReconnectDelayMs;
+      }
+    } catch (err) {
+      this.logger.debug("Failed to read EstimatedReturnTime; using configured delay:", err);
+    }
+    return this.configuration.shutdownReconnectDelayMs;
+  }
   async connect() {
     const { ws, sc } = await this.openTransportAndChannel();
     this.secureChannel = sc;
@@ -914,37 +1284,78 @@ var Client = class {
     this.ws = void 0;
     this.logger.info("Disconnected.");
   }
-  async read(ids) {
-    return this.withSessionRefresh(async () => {
-      const result = await this.attributeService?.ReadValue(ids);
-      return result?.map((r) => new ReadValueResult(r.value, r.statusCode)) ?? [];
+  /**
+   * Reads the Value attribute of one or more Nodes.
+   *
+   * The returned object is a `Promise` that also exposes `requestHandle` — the
+   * OPC UA `requestHandle` assigned to the underlying `ReadRequest`.  The handle
+   * is available synchronously (before `await`) so it can be passed to
+   * `cancel()` to abort the in-flight request.
+   *
+   * @example
+   * ```ts
+   * const req = client.read([nodeId])
+   * await client.cancel(req.requestHandle) // abort before response
+   * const results = await req              // ReadValueResult[]
+   * ```
+   */
+  read(ids, options) {
+    const requestHandle = nextRequestHandle();
+    const promise = this.withSessionRefresh(async () => {
+      const result = await this.attributeService?.ReadValue(ids, 0, void 0, options?.returnDiagnostics, requestHandle);
+      return result?.map((r) => new ReadValueResult(r.value, r.statusCode, r.diagnosticInfo)) ?? [];
     });
+    return Object.assign(promise, { requestHandle });
   }
   /**
    * Method for calling a single method on the server.
+   *
+   * The returned object is a `Promise` that also exposes `requestHandle` — the
+   * OPC UA `requestHandle` assigned to the underlying `CallRequest`. The handle
+   * is available synchronously (before `await`) so it can be passed to
+   * `cancel()` to abort the in-flight request.
+   *
    * @param objectId - NodeId of the Object that owns the method.
    * @param methodId - NodeId of the Method to invoke.
    * @param inputArguments - Input argument Variants (default: empty).
-   * @returns The CallMethodResult for the invoked method.
+   * @param options - Request options (e.g. `returnDiagnostics`).
+   * @returns A promise resolving to the CallMethodResult, with `requestHandle` available synchronously.
    */
-  async callMethod(objectId, methodId, inputArguments = []) {
-    return this.withSessionRefresh(async () => {
+  callMethod(objectId, methodId, inputArguments = [], options) {
+    const requestHandle = nextRequestHandle();
+    const promise = this.withSessionRefresh(async () => {
       const request = new opcjsBase.CallMethodRequest();
       request.objectId = objectId;
       request.methodId = methodId;
       request.inputArguments = inputArguments.map((arg) => opcjsBase.Variant.newFrom(arg));
-      const responses = await this.methodService.call([request]);
+      const responses = await this.methodService.call([request], options?.returnDiagnostics, requestHandle);
       const response = responses[0];
-      return new CallMethodResult(response.value, response.statusCode);
+      return new CallMethodResult(response.value, response.statusCode, response.diagnosticInfo);
     });
+    return Object.assign(promise, { requestHandle });
   }
-  async browse(nodeId, recursive = false) {
-    return this.withSessionRefresh(() => {
+  /**
+   * Browses the Address Space starting from `nodeId`.
+   *
+   * The returned object is a `Promise` that also exposes `requestHandle` — the
+   * OPC UA `requestHandle` assigned to the initial `BrowseRequest`. The handle
+   * is available synchronously (before `await`) so it can be passed to
+   * `cancel()` to abort the in-flight request.
+   *
+   * @param nodeId - Starting node.
+   * @param recursive - When true, recursively follows HierarchicalReferences.
+   * @param options - Request options (e.g. `returnDiagnostics`).
+   * @returns A promise resolving to the list of referenced nodes, with `requestHandle` available synchronously.
+   */
+  browse(nodeId, recursive = false, options) {
+    const requestHandle = nextRequestHandle();
+    const promise = this.withSessionRefresh(() => {
       const visited = /* @__PURE__ */ new Set();
-      return this.browseRecursive(nodeId, recursive, visited);
+      return this.browseRecursive(nodeId, recursive, visited, options?.returnDiagnostics ?? 0, requestHandle);
     });
+    return Object.assign(promise, { requestHandle });
   }
-  async browseRecursive(nodeId, recursive, visited) {
+  async browseRecursive(nodeId, recursive, visited, returnDiagnostics, requestHandle) {
     const nodeKey = `${nodeId.namespace}:${nodeId.identifier}`;
     if (visited.has(nodeKey)) {
       return [];
@@ -957,12 +1368,12 @@ var Client = class {
     description.includeSubtypes = true;
     description.nodeClassMask = 0;
     description.resultMask = opcjsBase.BrowseResultMaskEnum.All;
-    const browseResults = await this.browseService.browse([description]);
+    const browseResults = await this.browseService.browse([description], returnDiagnostics, requestHandle);
     const browseResult = browseResults[0];
     const allReferences = [...browseResult.references ?? []];
     let continuationPoint = browseResult.continuationPoint;
     while (continuationPoint && continuationPoint.byteLength > 0) {
-      const nextResults = await this.browseService.browseNext([continuationPoint], false);
+      const nextResults = await this.browseService.browseNext([continuationPoint], false, returnDiagnostics);
       const nextResult = nextResults[0];
       allReferences.push(...nextResult.references ?? []);
       continuationPoint = nextResult.continuationPoint;
@@ -987,7 +1398,8 @@ var Client = class {
         const childResults = await this.browseRecursive(
           childNodeId,
           true,
-          visited
+          visited,
+          returnDiagnostics
         );
         results.push(...childResults);
       }
@@ -997,6 +1409,170 @@ var Client = class {
   async subscribe(ids, callback, options) {
     this.subscriptionHandler?.subscribe(ids, callback, options);
   }
+  /**
+   * Asks the server to cancel a pending service request
+   * (OPC UA Part 4, Section 5.7.5 — Session Client Cancel conformance unit).
+   *
+   * The `requestHandle` uniquely identifies the pending request. It is the value
+   * assigned to `RequestHeader.requestHandle` when the request was initially sent.
+   * Service calls made through this client automatically assign monotonically
+   * increasing handles, so the caller can capture the handle before or after issuing
+   * Each method (`read`, `browse`, `callMethod`) returns a `Promise` with a
+   * `requestHandle` property that is available synchronously.  Pass that handle
+   * here to abort the corresponding in-flight request.
+   *
+   * The server makes a best-effort attempt to cancel the matching request. Cancelled
+   * requests complete with status `BadRequestCancelledByClient`. Not all servers
+   * guarantee that a request in flight can be cancelled.
+   *
+   * @param requestHandle - Handle of the pending request to cancel.
+   * @returns The number of pending requests the server actually cancelled.
+   * @throws If no session is active or the server returns a non-Good status.
+   *
+   * @example
+   * ```ts
+   * // Issue a potentially slow operation and immediately cancel it.
+   * const req = client.read([nodeId])
+   * const cancelled = await client.cancel(req.requestHandle)
+   * console.log(`Cancelled ${cancelled} request(s)`)
+   * const results = await req  // resolves with BadRequestCancelledByClient
+   * ```
+   */
+  async cancel(requestHandle) {
+    if (!this.sessionHandler) {
+      throw new Error("Not connected: call connect() before cancel()");
+    }
+    return this.sessionHandler.cancel(requestHandle);
+  }
+  /**
+   * Switches the active user identity for the current session by calling ActivateSession
+   * with a new identity token (OPC UA Part 4, Section 5.7.3 — Session Client Impersonate
+   * conformance unit).
+   *
+   * The server re-evaluates authorisation under the new identity while keeping all existing
+   * Subscriptions and MonitoredItems intact. The new identity is also stored so that any
+   * subsequent auto-reconnect or session refresh uses it instead of the original identity.
+   *
+   * @param identity - The new user identity to apply to the session.
+   * @throws {Error} When not connected (call `connect()` first).
+   * @throws {Error} When the server rejects the identity (e.g. `BadIdentityTokenRejected`
+   *   or `BadUserAccessDenied`).
+   *
+   * @example
+   * ```ts
+   * await client.connect()
+   * // ... work as the original user ...
+   * await client.impersonate(UserIdentity.newWithUserName('admin', 'secret'))
+   * // ... subsequent calls run under the admin identity ...
+   * ```
+   */
+  async impersonate(identity) {
+    if (!this.session) {
+      throw new Error("Not connected: call connect() before impersonate()");
+    }
+    await this.session.impersonate(identity);
+    this.identity = identity;
+  }
+  /**
+   * Reads the `SelectionListType` metadata for a Variable
+   * (OPC UA Part 5, §7.18 — Base Info Client Selection List conformance unit).
+   *
+   * The client browses the node's `HasProperty` references for `Selections`,
+   * `SelectionDescriptions`, and `RestrictToList`, then reads their values in a
+   * single batch Read request.
+   *
+   * Works transparently for instances of `SelectionListType` (ns=0; i=19726) and
+   * any of its subtypes, because all subtypes inherit the `Selections` mandatory
+   * property.
+   *
+   * @param nodeId - NodeId of the Variable to inspect.
+   * @returns `SelectionList` when the node has a `Selections` property, `null` otherwise.
+   * @throws When not connected or if the server returns a non-Good service status.
+   *
+   * @example
+   * ```ts
+   * const list = await client.getSelectionList(nodeId)
+   * if (list) {
+   *   list.selectionDescriptions.forEach((desc, i) =>
+   *     console.log(`[${i}] ${desc.text}:`, list.selections[i])
+   *   )
+   * }
+   * ```
+   */
+  getSelectionList(nodeId) {
+    return this.withSessionRefresh(() => this.fetchSelectionList(nodeId));
+  }
+  /**
+   * Internal implementation of `getSelectionList`. Browses the node's
+   * HasProperty references to locate Selections/SelectionDescriptions/RestrictToList,
+   * then batch-reads their values.
+   */
+  async fetchSelectionList(nodeId) {
+    if (!this.browseService || !this.attributeService) {
+      throw new Error("Not connected: call connect() before getSelectionList()");
+    }
+    const description = new opcjsBase.BrowseDescription();
+    description.nodeId = nodeId;
+    description.browseDirection = opcjsBase.BrowseDirectionEnum.Forward;
+    description.referenceTypeId = HAS_PROPERTY_REF_TYPE_ID;
+    description.includeSubtypes = false;
+    description.nodeClassMask = 0;
+    description.resultMask = opcjsBase.BrowseResultMaskEnum.All;
+    const browseResults = await this.browseService.browse([description]);
+    const refs = browseResults[0]?.references ?? [];
+    let selectionsNodeId;
+    let selectionsDescNodeId;
+    let restrictToListNodeId;
+    for (const ref of refs) {
+      const name = ref.browseName?.name;
+      if (name === "Selections") {
+        selectionsNodeId = ref.nodeId.nodeId;
+      } else if (name === "SelectionDescriptions") {
+        selectionsDescNodeId = ref.nodeId.nodeId;
+      } else if (name === "RestrictToList") {
+        restrictToListNodeId = ref.nodeId.nodeId;
+      }
+    }
+    if (!selectionsNodeId) {
+      return null;
+    }
+    const nodeIdsToRead = [selectionsNodeId];
+    if (selectionsDescNodeId) nodeIdsToRead.push(selectionsDescNodeId);
+    if (restrictToListNodeId) nodeIdsToRead.push(restrictToListNodeId);
+    const readResults = await this.attributeService.ReadValue(nodeIdsToRead);
+    const selectionsVariant = readResults[0]?.value;
+    const selections = Array.isArray(selectionsVariant?.value) ? selectionsVariant.value : [];
+    let selectionDescriptions = [];
+    let descReadIdx = 1;
+    if (selectionsDescNodeId) {
+      const descVariant = readResults[descReadIdx]?.value;
+      if (Array.isArray(descVariant?.value)) {
+        selectionDescriptions = descVariant.value;
+      }
+      descReadIdx++;
+    }
+    let restrictToList = false;
+    if (restrictToListNodeId) {
+      const rtlVariant = readResults[descReadIdx]?.value;
+      if (typeof rtlVariant?.value === "boolean") {
+        restrictToList = rtlVariant.value;
+      }
+    }
+    return { nodeId, selections, selectionDescriptions, restrictToList };
+  }
+  /**
+   * The `requestHandle` value that was assigned to the most recently issued
+   * service request in this session.
+   *
+   * @deprecated Prefer accessing `requestHandle` directly on the promise returned
+   *   by `read()`, `browse()`, or `callMethod()`, which is available synchronously
+   *   before `await` and avoids relying on shared module state.
+   *
+   * Returns `0` before any request has been sent.
+   */
+  get lastRequestHandle() {
+    return lastAssignedHandle();
+  }
 };
 var ConfigurationClient = class _ConfigurationClient extends opcjsBase.Configuration {
   /**
@@ -1007,6 +1583,26 @@ var ConfigurationClient = class _ConfigurationClient extends opcjsBase.Configura
    * @see SecurityConfiguration
    */
   securityConfiguration;
+  /**
+   * How long to wait (ms) before attempting a reconnect after a server-shutdown
+   * is detected via `ServerStatus/State = Shutdown` or a subscription
+   * `StatusChangeNotification` with `BadShutdown` / `BadServerHalted`.
+   *
+   * Gives the server process time to exit fully before the client tries to
+   * re-connect.  Defaults to 5 000 ms.
+   */
+  shutdownReconnectDelayMs = 5e3;
+  /**
+   * Minimum reconnect delay in milliseconds used when
+   * `Server/ServerStatus/EstimatedReturnTime` is already in the past (the server
+   * should already be available again).
+   *
+   * Also acts as the lower bound for the ERT-derived delay, ensuring the client
+   * always waits at least this long before retrying.
+   *
+   * Defaults to 1 000 ms.
+   */
+  minReconnectDelayMs = 1e3;
   static getSimple(name, company, loggerFactory) {
     if (!loggerFactory) {
       loggerFactory = new opcjsBase.LoggerFactory({
@@ -1096,10 +1692,44 @@ var UserIdentity = class _UserIdentity {
   }
 };
 
+// src/requestOptions.ts
+var ReturnDiagnosticsMask = {
+  /** All service-level diagnostic fields. */
+  ServiceLevel: 31,
+  /** All operation-level diagnostic fields. */
+  OperationLevel: 992,
+  /** All diagnostic fields (service level + operation level). */
+  All: 1023,
+  /** Service-level: index to SymbolicId in the server string table. */
+  ServiceSymbolicId: 1,
+  /** Service-level: index to LocalizedText in the server string table. */
+  ServiceLocalizedText: 2,
+  /** Service-level: additional info string. */
+  ServiceAdditionalInfo: 4,
+  /** Service-level: inner status code. */
+  ServiceInnerStatusCode: 8,
+  /** Service-level: inner diagnostic info. */
+  ServiceInnerDiagnostics: 16,
+  /** Operation-level: index to SymbolicId in the server string table. */
+  OperationSymbolicId: 32,
+  /** Operation-level: index to LocalizedText in the server string table. */
+  OperationLocalizedText: 64,
+  /** Operation-level: additional info string. */
+  OperationAdditionalInfo: 128,
+  /** Operation-level: inner status code. */
+  OperationInnerStatusCode: 256,
+  /** Operation-level: inner diagnostic info. */
+  OperationInnerDiagnostics: 512
+};
+
 exports.BrowseNodeResult = BrowseNodeResult;
+exports.CERTIFICATE_REQUIRED_STATUS_CODES = CERTIFICATE_REQUIRED_STATUS_CODES;
 exports.CallMethodResult = CallMethodResult;
+exports.CertificateRequiredError = CertificateRequiredError;
 exports.Client = Client;
 exports.ConfigurationClient = ConfigurationClient;
+exports.NamespaceTable = NamespaceTable;
+exports.ReturnDiagnosticsMask = ReturnDiagnosticsMask;
 exports.SECURITY_POLICY_NONE_URI = SECURITY_POLICY_NONE_URI;
 exports.SessionInvalidError = SessionInvalidError;
 exports.UserIdentity = UserIdentity;