opcjs-client 0.1.13 → 0.1.14

package/dist/index.js

@@ -1,23 +1,87 @@
-import { ChannelFactory, SecureChannel, Configuration, Encoder, BinaryWriter, registerEncoders, Decoder, BinaryReader, registerTypeDecoders, registerBinaryDecoders, UserTokenTypeEnum, AnonymousIdentityToken, UserNameIdentityToken, IssuedIdentityToken, NodeId, SubscriptionAcknowledgement, CreateSubscriptionRequest, PublishRequest, ReadValueId, QualifiedName, MonitoringParameters, ExtensionObject, MonitoredItemCreateRequest, MonitoringModeEnum, CreateMonitoredItemsRequest, TimestampsToReturnEnum, ReadRequest, ApplicationDescription, LocalizedText, ApplicationTypeEnum, CreateSessionRequest, CreateSessionResponse, SignatureData, ActivateSessionRequest, RequestHeader } from 'opcjs-base';
+import { NodeId, StatusCodeToString, initLoggerProvider, getLogger, ServerStateEnum, WebSocketFascade, WebSocketReadableStream, WebSocketWritableStream, SecureChannelContext, TcpMessageInjector, TcpConnectionHandler, TcpMessageDecoupler, SecureChannelMessageEncoder, SecureChannelTypeDecoder, SecureChannelMessageDecoder, SecureChannelTypeEncoder, SecureChannelChunkWriter, SecureChannelChunkReader, SecureChannelFacade, CallMethodRequest, Variant, BrowseDescription, BrowseDirectionEnum, BrowseResultMaskEnum, Configuration, LoggerFactory, Encoder, BinaryWriter, registerEncoders, Decoder, BinaryReader, registerTypeDecoders, registerBinaryDecoders, UserTokenTypeEnum, AnonymousIdentityToken, UserNameIdentityToken, IssuedIdentityToken, TimestampsToReturnEnum, ReadValueId, QualifiedName, ReadRequest, StatusCode, CallRequest, ViewDescription, BrowseRequest, BrowseNextRequest, SubscriptionAcknowledgement, ExpandedNodeId, CreateSubscriptionRequest, PublishRequest, MonitoringParameters, ExtensionObject, MonitoredItemCreateRequest, MonitoringModeEnum, CreateMonitoredItemsRequest, StatusCodeToStringNumber, RequestHeader, ApplicationDescription, LocalizedText, ApplicationTypeEnum, CreateSessionRequest, CreateSessionResponse, SignatureData, ActivateSessionRequest, CancelRequest, CloseSessionRequest } from 'opcjs-base';
 
 // src/client.ts
+var SessionInvalidError = class extends Error {
+  statusCode;
+  constructor(statusCode) {
+    super(`Session is no longer valid: ${StatusCodeToString(statusCode)} (0x${statusCode.toString(16).toUpperCase()})`);
+    this.name = "SessionInvalidError";
+    this.statusCode = statusCode;
+  }
+};
+
+// 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;
     this.secureChannel = secureChannel;
   }
-  createRequestHeader() {
+  /**
+   * Validates the `serviceResult` value from a response header.
+   *
+   * Throws `SessionInvalidError` for session-related status codes so callers
+   * can detect a dropped session and act accordingly (e.g. reconnect).
+   * Throws a generic `Error` for all other non-Good codes.
+   *
+   * @param result  - The `serviceResult` value from the response header.
+   * @param context - Short description used in the error message (e.g. "ReadRequest").
+   */
+  checkServiceResult(result, context) {
+    if (result === void 0 || result === StatusCode.Good) return;
+    if (result === StatusCode.BadSessionIdInvalid || result === StatusCode.BadSessionClosed) {
+      throw new SessionInvalidError(result);
+    }
+    throw new Error(`${context} failed: ${StatusCodeToString(result)} (${StatusCodeToStringNumber(result)})`);
+  }
+  /**
+   * 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 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 = ExtensionObject.newEmpty();
     return requestHeader;
   }
 };
+var CertificateRequiredError = class extends Error {
+  statusCode;
+  constructor(statusCode) {
+    super(
+      `Server requires a client certificate: ${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 {
@@ -25,8 +89,20 @@ var SessionService = class _SessionService extends ServiceBase {
     super(authToken, secureChannel);
     this.configuration = configuration;
   }
-  async createSession() {
-    console.log("Creating session...");
+  logger = 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(clientCertificate = null) {
+    this.logger.debug("Creating session...");
     const clientDescription = new ApplicationDescription();
     clientDescription.applicationUri = this.configuration.applicationUri;
     clientDescription.productUri = this.configuration.productUri;
@@ -42,10 +118,10 @@ 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;
-    console.log("Sending CreateSessionRequest...");
+    this.logger.debug("Sending CreateSessionRequest...");
     const response = await this.secureChannel.issueServiceRequest(request);
     if (!response || !(response instanceof CreateSessionResponse)) {
       throw new Error("Invalid response type for CreateSessionRequest");
@@ -54,24 +130,41 @@ var SessionService = class _SessionService extends ServiceBase {
     if (!castedResponse || !castedResponse.sessionId || !castedResponse.authenticationToken) {
       throw new Error("CreateSessionResponse missing SessionId or AuthenticationToken");
     }
-    const endpoint = "opc." + this.secureChannel.getEndpointUrl();
-    const endpointUrl = new URL(endpoint);
+    const serviceResult = castedResponse.responseHeader?.serviceResult;
+    if (serviceResult !== void 0 && serviceResult !== StatusCode.Good) {
+      if (CERTIFICATE_REQUIRED_STATUS_CODES.has(serviceResult)) {
+        throw new CertificateRequiredError(serviceResult);
+      }
+      throw new Error(`CreateSessionRequest failed: ${StatusCodeToString(serviceResult)}`);
+    }
+    const clientConnectionUrl = new URL("opc." + this.secureChannel.getEndpointUrl());
     const securityMode = this.secureChannel.getSecurityMode();
     const securityPolicyUri = this.secureChannel.getSecurityPolicy();
+    const normalizeEndpointUrl = (serverEndpointUrl) => {
+      const url = new URL(serverEndpointUrl);
+      url.hostname = clientConnectionUrl.hostname;
+      url.port = clientConnectionUrl.port;
+      return url;
+    };
     const serverEndpoint = castedResponse?.serverEndpoints?.find((currentEndpoint) => {
-      const currentEndpointUrl = new URL(currentEndpoint.endpointUrl);
-      return currentEndpointUrl.protocol === endpointUrl.protocol && currentEndpointUrl.pathname === endpointUrl.pathname && currentEndpointUrl.port === endpointUrl.port && currentEndpoint.securityMode === securityMode && currentEndpoint.securityPolicyUri === securityPolicyUri;
+      const normalized = normalizeEndpointUrl(currentEndpoint.endpointUrl);
+      return normalized.protocol === clientConnectionUrl.protocol && normalized.pathname === clientConnectionUrl.pathname && currentEndpoint.securityMode === securityMode && currentEndpoint.securityPolicyUri === securityPolicyUri;
     });
     if (!serverEndpoint) {
-      throw new Error(`Server endpoint ${endpoint} not found in CreateSessionResponse`);
+      throw new Error(`Server endpoint ${clientConnectionUrl.toString()} not found in CreateSessionResponse`);
     }
-    console.log("Session created with id:", castedResponse.sessionId.identifier);
+    serverEndpoint.endpointUrl = normalizeEndpointUrl(serverEndpoint.endpointUrl).toString();
+    this.logger.debug("Session created with id:", castedResponse.sessionId.identifier);
     return {
       sessionId: castedResponse.sessionId.identifier,
       authToken: castedResponse.authenticationToken,
       endpoint: serverEndpoint
     };
   }
+  /**
+   * Activates an existing session using the supplied identity token (OPC UA Part 4, Section 5.7.3).
+   * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
+   */
   async activateSession(identityToken) {
     const signatureData = new SignatureData();
     signatureData.algorithm = this.secureChannel.getSecurityPolicy();
@@ -83,16 +176,65 @@ var SessionService = class _SessionService extends ServiceBase {
     request.localeIds = ["en-US"];
     request.userIdentityToken = ExtensionObject.newBinary(identityToken);
     request.userTokenSignature = signatureData;
-    console.log("Sending ActivateSessionRequest...");
-    await this.secureChannel.issueServiceRequest(request);
-    console.log("Session activated.");
+    this.logger.debug("Sending ActivateSessionRequest...");
+    const activateResponse = await this.secureChannel.issueServiceRequest(request);
+    const activateResult = activateResponse?.responseHeader?.serviceResult;
+    if (activateResult !== void 0 && activateResult !== StatusCode.Good) {
+      throw new Error(`ActivateSessionRequest failed: ${StatusCodeToString(activateResult)}`);
+    }
+    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 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 !== StatusCode.Good) {
+      throw new Error(`CancelRequest failed: ${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
+   *   associated with this Session, freeing their resources immediately.
+   *   Pass false to keep Subscriptions alive for transfer to another Session.
+   */
+  async closeSession(deleteSubscriptions) {
+    this.logger.debug("Sending CloseSessionRequest...");
+    const request = new CloseSessionRequest();
+    request.requestHeader = this.createRequestHeader();
+    request.deleteSubscriptions = deleteSubscriptions;
+    const response = await this.secureChannel.issueServiceRequest(request);
+    const result = response?.responseHeader?.serviceResult;
+    if (result !== void 0 && result !== StatusCode.Good) {
+      throw new Error(`CloseSession failed: ${StatusCodeToString(result)}`);
+    }
+    this.logger.debug("Session closed.");
   }
   recreate(authToken) {
     return new _SessionService(authToken, this.secureChannel, this.configuration);
   }
 };
 
-// src/issuerConfiguration.ts
+// src/configuration/issuerConfiguration.ts
 var IssuerConfiguration = class _IssuerConfiguration {
   constructor(resourceId, authorityUrl, authorityProfileUri, tokenEndpoint, authorizationEndpoint, requestTypes, scopes) {
     this.resourceId = resourceId;
@@ -148,29 +290,159 @@ var Session = class {
   getAuthToken() {
     return this.authToken;
   }
+  getSessionId() {
+    return this.sessionId;
+  }
+  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
+   *   tied to this Session. Defaults to true.
+   */
+  async close(deleteSubscriptions = true) {
+    await this.sessionServices.closeSession(deleteSubscriptions);
+  }
 };
 
 // src/sessions/sessionHandler.ts
 var SessionHandler = class {
+  constructor(secureChannel, configuration) {
+    this.configuration = configuration;
+    this.sessionServices = new SessionService(NodeId.newTwoByte(0), secureChannel, configuration);
+  }
   sessionServices;
+  logger = 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);
+    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;
   }
-  constructor(secureChannel, configuration) {
-    this.sessionServices = new SessionService(NodeId.newTwoByte(0), secureChannel, configuration);
+  /**
+   * Attempts to reactivate an existing OPC UA session on the current (new) SecureChannel
+   * without calling CreateSession first (OPC UA Part 4, Section 5.7.3).
+   *
+   * This is the preferred recovery path when the SecureChannel drops but the server-side
+   * session has not yet timed out: only a new channel is needed, not a new session.
+   *
+   * @returns The reactivated Session if ActivateSession succeeded, or `null` if the server
+   *          rejected the request (e.g. the session had already expired).
+   */
+  async tryActivateExistingSession(existingAuthToken, existingSessionId, existingEndpoint, identity) {
+    const serviceForExistingSession = this.sessionServices.recreate(existingAuthToken);
+    try {
+      const session = new Session(existingSessionId, existingAuthToken, existingEndpoint, serviceForExistingSession);
+      await session.activateSession(identity);
+      return session;
+    } catch (err) {
+      this.logger.debug("ActivateSession for existing session failed:", err);
+      return null;
+    }
+  }
+  /**
+   * Closes the active session on the server (OPC UA Part 4, Section 5.7.4).
+   * @param deleteSubscriptions - Forwarded to CloseSessionRequest. Defaults to true.
+   */
+  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
+   *      client has explicitly restricted which token types it will use.
+   *   2. The token policies advertised by the server endpoint — verifies that the
+   *      server actually supports at least one of the allowed types.
+   *
+   * Throws with a descriptive message if either check fails.
+   */
+  validateUserTokenPolicy(identity, endpoint) {
+    const allowedTypes = this.configuration.securityConfiguration?.allowedUserTokenTypes;
+    if (!allowedTypes) return;
+    const requestedType = identity.getTokenType();
+    if (!allowedTypes.includes(requestedType)) {
+      throw new Error(
+        `User token type '${UserTokenTypeEnum[requestedType]}' is not permitted by the client security configuration. Allowed types: ${allowedTypes.map((t) => UserTokenTypeEnum[t]).join(", ")}.`
+      );
+    }
+    const serverTypes = endpoint.userIdentityTokens?.map((p) => p.tokenType) ?? [];
+    const intersection = allowedTypes.filter((t) => serverTypes.includes(t));
+    if (intersection.length === 0) {
+      throw new Error(
+        `Server endpoint does not offer any user token type from the allowed list: ${allowedTypes.map((t) => UserTokenTypeEnum[t]).join(", ")}. Server offers: ${serverTypes.map((t) => UserTokenTypeEnum[t]).join(", ")}.`
+      );
+    }
   }
 };
 
+// src/securityConfiguration.ts
+var SECURITY_POLICY_NONE_URI = "http://opcfoundation.org/UA/SecurityPolicy#None";
+
 // src/services/attributeServiceAttributes.ts
 var AttrIdValue = 13;
 
 // src/services/attributeService.ts
 var AttributeService = class extends ServiceBase {
-  async ReadValue(nodeIds) {
+  logger = getLogger("services.AttributeService");
+  /**
+   * Reads the Value attribute of one or more Nodes (OPC UA Part 4, Section 5.10.2).
+   * @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.
+   * @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 = TimestampsToReturnEnum.Source, returnDiagnostics = 0, requestHandle) {
     const readValueIds = nodeIds.map((ni) => {
       const readValueId = new ReadValueId();
       readValueId.nodeId = ni;
@@ -180,19 +452,22 @@ var AttributeService = class extends ServiceBase {
       return readValueId;
     });
     const request = new ReadRequest();
-    request.requestHeader = this.createRequestHeader();
-    request.maxAge = 6e4;
-    request.timestampsToReturn = TimestampsToReturnEnum.Source;
+    request.requestHeader = this.createRequestHeader(returnDiagnostics, requestHandle);
+    request.maxAge = maxAge;
+    request.timestampsToReturn = timestampsToReturn;
     request.nodesToRead = readValueIds;
-    console.log("Sending ReadRequest...");
+    this.logger.debug("Sending ReadRequest...");
     const response = await this.secureChannel.issueServiceRequest(request);
+    this.checkServiceResult(response.responseHeader?.serviceResult, "ReadRequest");
     const results = new Array();
-    for (let dataValue of response.results ?? []) {
-      const result = {
-        status: dataValue.statusCode?.toString() ?? "Unknown",
-        value: dataValue.value
-      };
-      results.push(result);
+    const diagInfos = response.diagnosticInfos ?? [];
+    for (let i = 0; i < (response.results ?? []).length; i++) {
+      const dataValue = response.results[i];
+      results.push({
+        statusCode: dataValue.statusCode ?? StatusCode.Good,
+        value: dataValue.value,
+        diagnosticInfo: diagInfos[i]
+      });
     }
     return results;
   }
@@ -203,13 +478,14 @@ var AttributeService = class extends ServiceBase {
 
 // src/readValueResult.ts
 var ReadValueResult = class {
-  constructor(value, status) {
+  constructor(value, statusCode, diagnosticInfo) {
     this.value = value;
-    this.status = status;
+    this.statusCode = statusCode;
+    this.diagnosticInfo = diagnosticInfo;
   }
 };
 
-// src/subscriptionHandlerEntry.ts
+// src/subscription/subscriptionHandlerEntry.ts
 var SubscriptionHandlerEntry = class {
   constructor(subscriptionId, handle, id, callback) {
     this.subscriptionId = subscriptionId;
@@ -219,95 +495,155 @@ var SubscriptionHandlerEntry = class {
   }
 };
 
-// src/subscriptionHandler.ts
+// src/subscription/subscriptionHandler.ts
+var NODE_ID_DATA_CHANGE_NOTIFICATION = 811;
+var NODE_ID_STATUS_CHANGE_NOTIFICATION = 818;
 var SubscriptionHandler = class {
   constructor(subscriptionService, monitoredItemService) {
     this.subscriptionService = subscriptionService;
     this.monitoredItemService = monitoredItemService;
   }
+  logger = getLogger("SubscriptionHandler");
   entries = new Array();
   nextHandle = 0;
-  async subscribe(ids, callback) {
+  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;
+  }
+  async subscribe(ids, callback, options) {
     if (this.entries.length > 0) {
       throw new Error("Subscribing more than once is not implemented");
     }
-    const subscriptionId = await this.subscriptionService.createSubscription();
+    const subscriptionId = await this.subscriptionService.createSubscription(options);
     const items = [];
-    for (let id of ids) {
-      const entry = new SubscriptionHandlerEntry(
-        subscriptionId,
-        this.nextHandle++,
-        id,
-        callback
-      );
+    for (const id of ids) {
+      const entry = new SubscriptionHandlerEntry(subscriptionId, this.nextHandle++, id, callback);
       this.entries.push(entry);
-      const item = {
-        id,
-        handle: entry.handle
-      };
-      items.push(item);
-    }
-    await this.monitoredItemService.createMonitoredItems(subscriptionId, items);
-    this.publish([]);
-  }
-  async publish(acknowledgeSequenceNumbers) {
-    const acknowledgements = [];
-    for (let i = 0; i < acknowledgeSequenceNumbers.length; i++) {
-      const acknowledgement = new SubscriptionAcknowledgement();
-      acknowledgement.subscriptionId = this.entries[i].subscriptionId;
-      acknowledgement.sequenceNumber = acknowledgeSequenceNumbers[i];
-      acknowledgements.push(acknowledgement);
-    }
-    const response = await this.subscriptionService.publish(acknowledgements);
-    const messagesToAcknowledge = response.notificationMessage.sequenceNumber;
-    const notificationDatas = response.notificationMessage.notificationData;
-    for (let notificationData of notificationDatas) {
+      items.push({ id, handle: entry.handle });
+    }
+    await this.monitoredItemService.createMonitoredItems(subscriptionId, items, options);
+    this.isRunning = true;
+    void this.publishLoop([]);
+  }
+  // https://reference.opcfoundation.org/Core/Part4/v105/docs/5.14.5
+  async publishLoop(pendingAcknowledgements) {
+    if (!this.isRunning) return;
+    if (this.publishInFlight) return;
+    this.publishInFlight = true;
+    let response;
+    try {
+      response = await this.subscriptionService.publish(pendingAcknowledgements);
+    } catch (err) {
+      this.logger.error(`Publish failed, stopping publish loop: ${err}`);
+      this.isRunning = false;
+      this.publishInFlight = false;
+      return;
+    }
+    this.publishInFlight = false;
+    const { subscriptionId, availableSequenceNumbers, moreNotifications, notificationMessage } = response;
+    const notificationDatas = notificationMessage?.notificationData ?? [];
+    const seqNumber = notificationMessage?.sequenceNumber;
+    const nextAcknowledgements = [];
+    const isKeepAlive = notificationDatas.length === 0;
+    if (!isKeepAlive && seqNumber !== void 0) {
+      const isAvailable = !availableSequenceNumbers || availableSequenceNumbers.includes(seqNumber);
+      if (isAvailable) {
+        const ack = new SubscriptionAcknowledgement();
+        ack.subscriptionId = subscriptionId;
+        ack.sequenceNumber = seqNumber;
+        nextAcknowledgements.push(ack);
+      }
+    }
+    for (const notificationData of notificationDatas) {
       const decodedData = notificationData.data;
-      const typeNodeId = notificationData.typeId;
-      if (typeNodeId.namespace === 0 && typeNodeId.identifier === 811) {
+      const rawTypeId = notificationData.typeId;
+      const typeNodeId = rawTypeId instanceof ExpandedNodeId ? rawTypeId.nodeId : rawTypeId;
+      if (typeNodeId.namespace === 0 && typeNodeId.identifier === NODE_ID_DATA_CHANGE_NOTIFICATION) {
         const dataChangeNotification = decodedData;
-        for (let item of dataChangeNotification.monitoredItems) {
-          const clientHandle = item.clientHandle;
-          const value = item.value;
-          const entry = this.entries.find((e) => e.handle == clientHandle);
-          entry?.callback([{
-            id: entry.id,
-            value: value.value?.value
-          }]);
+        for (const item of dataChangeNotification.monitoredItems) {
+          const entry = this.entries.find((e) => e.handle === item.clientHandle);
+          entry?.callback([{ id: entry.id, value: item.value.value?.value }]);
         }
+      } else if (typeNodeId.namespace === 0 && typeNodeId.identifier === NODE_ID_STATUS_CHANGE_NOTIFICATION) {
+        const statusChange = decodedData;
+        this.logger.warn(
+          `Subscription ${subscriptionId} status changed: 0x${statusChange.status?.toString(16).toUpperCase()}`
+        );
+        this.isRunning = false;
+        const status = statusChange.status;
+        if (status === StatusCode.BadShutdown || status === StatusCode.BadServerHalted) {
+          this.logger.warn("Server shutdown announced via StatusChangeNotification \u2014 triggering reconnect.");
+          this.onShutdown?.();
+        }
+        return;
       } else {
-        console.log(`The change notification data type ${typeNodeId.namespace}:${typeNodeId.identifier} is not supported.`);
+        this.logger.warn(
+          `Notification data type ${typeNodeId.namespace}:${typeNodeId.identifier} is not supported.`
+        );
       }
     }
-    setTimeout(() => {
-      this.publish([messagesToAcknowledge]);
-    }, 500);
+    if (moreNotifications) {
+      void this.publishLoop(nextAcknowledgements);
+    } else {
+      setTimeout(() => void this.publishLoop(nextAcknowledgements), 0);
+    }
   }
 };
 var SubscriptionService = class extends ServiceBase {
+  logger = getLogger("services.SubscriptionService");
+  /**
+   * Creates a new subscription on the server (OPC UA Part 4, Section 5.14.2).
+   * @param options - Optional subscription parameters; server revises all values.
+   * @returns The server-assigned subscription ID.
+   */
   // https://reference.opcfoundation.org/Core/Part4/v105/docs/5.14.2
-  async createSubscription() {
+  async createSubscription(options) {
     const request = new CreateSubscriptionRequest();
     request.requestHeader = this.createRequestHeader();
-    request.requestedPublishingInterval = 2e3;
-    request.requestedLifetimeCount = 36e4;
-    request.requestedMaxKeepAliveCount = 6e4;
-    request.maxNotificationsPerPublish = 200;
+    request.requestedPublishingInterval = options?.requestedPublishingInterval ?? 2e3;
+    request.requestedLifetimeCount = options?.requestedLifetimeCount ?? 36e4;
+    request.requestedMaxKeepAliveCount = options?.requestedMaxKeepAliveCount ?? 6e4;
+    request.maxNotificationsPerPublish = options?.maxNotificationsPerPublish ?? 200;
     request.publishingEnabled = true;
-    request.priority = 1;
-    console.log("Sending createSubscription...");
+    request.priority = options?.priority ?? 1;
+    this.logger.debug("Sending CreateSubscriptionRequest...");
     const response = await this.secureChannel.issueServiceRequest(request);
-    console.log("Subscription created with id:", response.subscriptionId);
+    const serviceResult = response.responseHeader?.serviceResult;
+    if (serviceResult !== void 0 && serviceResult !== StatusCode.Good) {
+      throw new Error(`CreateSubscriptionRequest failed: ${StatusCodeToString(serviceResult)}`);
+    }
+    this.logger.debug(`Subscription created with id: ${response.subscriptionId}`);
     return response.subscriptionId;
   }
+  /**
+   * Sends a publish request to receive notifications from active subscriptions (OPC UA Part 4, Section 5.14.5).
+   * @param acknowledgements - Sequence numbers to acknowledge from previous publish responses.
+   * @returns The publish response containing notification data.
+   */
   // https://reference.opcfoundation.org/Core/Part4/v105/docs/5.14.5
   async publish(acknowledgements) {
     const request = new PublishRequest();
     request.requestHeader = this.createRequestHeader();
     request.subscriptionAcknowledgements = acknowledgements;
-    console.log("Sending publish...");
+    this.logger.debug("Sending PublishRequest...");
     const response = await this.secureChannel.issueServiceRequest(request);
-    console.log("Received publish response.");
+    const serviceResult = response.responseHeader?.serviceResult;
+    if (serviceResult !== void 0 && serviceResult !== StatusCode.Good) {
+      throw new Error(`PublishRequest failed: ${StatusCodeToString(serviceResult)}`);
+    }
+    this.logger.debug("Received PublishResponse.");
     return response;
   }
   constructor(authToken, secureChannel) {
@@ -315,7 +651,15 @@ var SubscriptionService = class extends ServiceBase {
   }
 };
 var MonitoredItemService = class extends ServiceBase {
-  async createMonitoredItems(subscriptionId, ids) {
+  logger = getLogger("services.MonitoredItemService");
+  /**
+   * Creates monitored items within a subscription (OPC UA Part 4, Section 5.13.2).
+   * @param subscriptionId - ID of the subscription to add monitored items to.
+   * @param ids - Array of NodeIds and client handles identifying the items to monitor.
+   * @param options - Monitoring options (samplingInterval, queueSize).
+   */
+  async createMonitoredItems(subscriptionId, ids, options = {}) {
+    const { samplingInterval = 1e3, queueSize = 100 } = options;
     const items = ids.map((ni) => {
       const readValueId = new ReadValueId();
       readValueId.nodeId = ni.id;
@@ -324,9 +668,9 @@ var MonitoredItemService = class extends ServiceBase {
       readValueId.dataEncoding = new QualifiedName(0, "");
       const monitoringParameters = new MonitoringParameters();
       monitoringParameters.clientHandle = ni.handle;
-      monitoringParameters.samplingInterval = 1e3;
+      monitoringParameters.samplingInterval = samplingInterval;
       monitoringParameters.filter = ExtensionObject.newEmpty();
-      monitoringParameters.queueSize = 100;
+      monitoringParameters.queueSize = queueSize;
       monitoringParameters.discardOldest = true;
       const monitoredItemCreateRequest = new MonitoredItemCreateRequest();
       monitoredItemCreateRequest.itemToMonitor = readValueId;
@@ -339,69 +683,935 @@ var MonitoredItemService = class extends ServiceBase {
     request.subscriptionId = subscriptionId;
     request.timestampsToReturn = TimestampsToReturnEnum.Source;
     request.itemsToCreate = items;
-    console.log("Sending createMonitoredItems...");
-    await this.secureChannel.issueServiceRequest(request);
+    this.logger.debug("Sending CreateMonitoredItemsRequest...");
+    const response = await this.secureChannel.issueServiceRequest(request);
+    const serviceResult = response.responseHeader?.serviceResult;
+    if (serviceResult !== void 0 && serviceResult !== StatusCode.Good) {
+      throw new Error(`CreateMonitoredItemsRequest failed: ${StatusCodeToString(serviceResult)}`);
+    }
+    for (const result of response.results ?? []) {
+      if (result.statusCode !== void 0 && result.statusCode !== StatusCode.Good) {
+        this.logger.warn(`Failed to create monitored item: ${StatusCodeToString(result.statusCode)}`);
+      }
+    }
+  }
+  constructor(authToken, secureChannel) {
+    super(authToken, secureChannel);
+  }
+};
+var MethodService = class extends ServiceBase {
+  logger = getLogger("services.MethodService");
+  /**
+   * 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.
+   * @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, returnDiagnostics = 0, requestHandle) {
+    const request = new CallRequest();
+    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");
+    const diagInfos = response.diagnosticInfos ?? [];
+    return response.results.map((result, i) => ({
+      statusCode: result.statusCode ?? StatusCode.Good,
+      value: result.outputArguments.map((arg) => arg.value),
+      diagnosticInfo: diagInfos[i]
+    }));
   }
   constructor(authToken, secureChannel) {
     super(authToken, secureChannel);
   }
 };
 
+// src/method/callMethodResult.ts
+var CallMethodResult = class {
+  constructor(values, statusCode, diagnosticInfo) {
+    this.values = values;
+    this.statusCode = statusCode;
+    this.diagnosticInfo = diagnosticInfo;
+  }
+};
+var BrowseService = class extends ServiceBase {
+  logger = getLogger("services.BrowseService");
+  /**
+   * 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, returnDiagnostics = 0, requestHandle) {
+    const view = new ViewDescription();
+    view.viewId = NodeId.newNumeric(0, 0);
+    view.timestamp = /* @__PURE__ */ new Date(-116444736e5);
+    view.viewVersion = 0;
+    const request = new BrowseRequest();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics, requestHandle);
+    request.view = view;
+    request.requestedMaxReferencesPerNode = 0;
+    request.nodesToBrowse = nodesToBrowse;
+    this.logger.debug("Sending BrowseRequest...");
+    const response = await this.secureChannel.issueServiceRequest(request);
+    this.checkServiceResult(response.responseHeader?.serviceResult, "BrowseRequest");
+    return response.results ?? [];
+  }
+  /**
+   * 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, returnDiagnostics = 0) {
+    const request = new BrowseNextRequest();
+    request.requestHeader = this.createRequestHeader(returnDiagnostics);
+    request.releaseContinuationPoints = releaseContinuationPoints;
+    request.continuationPoints = continuationPoints;
+    this.logger.debug("Sending BrowseNextRequest...");
+    const response = await this.secureChannel.issueServiceRequest(request);
+    this.checkServiceResult(response.responseHeader?.serviceResult, "BrowseNextRequest");
+    return response.results ?? [];
+  }
+  constructor(authToken, secureChannel) {
+    super(authToken, secureChannel);
+  }
+};
+
+// src/browseNodeResult.ts
+var BrowseNodeResult = class {
+  constructor(referenceTypeId, isForward, nodeId, browseName, displayName, nodeClass, typeDefinition) {
+    this.referenceTypeId = referenceTypeId;
+    this.isForward = isForward;
+    this.nodeId = nodeId;
+    this.browseName = browseName;
+    this.displayName = displayName;
+    this.nodeClass = nodeClass;
+    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 NodeId(newIndex, nodeId.identifier);
+  }
+};
+
 // src/client.ts
+var SERVER_STATUS_NODE_ID = NodeId.newNumeric(0, 2256);
+var NAMESPACE_ARRAY_NODE_ID = NodeId.newNumeric(0, 2255);
+var ESTIMATED_RETURN_TIME_NODE_ID = NodeId.newNumeric(0, 2992);
+var HAS_PROPERTY_REF_TYPE_ID = 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;
     this.identity = identity;
     this.endpointUrl = endpointUrl;
+    initLoggerProvider(configuration.loggerFactory);
+    this.logger = getLogger("Client");
   }
   endpointUrl;
-  channel;
+  attributeService;
+  methodService;
+  browseService;
   session;
   subscriptionHandler;
+  logger;
+  // Stored after connect() so that refreshSession() and disconnect() can use them.
+  secureChannel;
+  secureChannelFacade;
+  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");
     }
     return this.session;
   }
+  /**
+   * (Re-)initialises all session-scoped services from the current `this.session`.
+   * Called both after the initial `connect()` and after a session refresh.
+   */
+  initServices() {
+    const authToken = this.session.getAuthToken();
+    const sc = this.secureChannel;
+    this.attributeService = new AttributeService(authToken, sc);
+    this.methodService = new MethodService(authToken, sc);
+    this.browseService = new BrowseService(authToken, sc);
+    this.subscriptionHandler = new SubscriptionHandler(
+      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
+   * session and retries the operation exactly once.
+   *
+   * This covers the reactive case: a service call reveals that the server has
+   * already dropped the session (e.g. due to timeout). The new session is
+   * established transparently before re-running the original operation.
+   *
+   * For any other error (e.g. transport-level failures when the SecureChannel
+   * drops), this method attempts to reconnect the channel and reactivate the
+   * existing session first — falling back to a brand-new session only when
+   * reactivation fails — before retrying the operation once.
+   */
+  async withSessionRefresh(fn) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof SessionInvalidError) {
+        this.logger.info(`Session invalid (${err.statusCode.toString(16)}), refreshing session...`);
+        this.session = await this.sessionHandler.createNewSession(this.identity);
+        this.initServices();
+        this.logger.info("Session refreshed, retrying operation.");
+        return await fn();
+      }
+      this.logger.info("Service call failed, attempting channel reconnect and session reactivation...");
+      try {
+        await this.reconnectAndReactivate();
+        this.initServices();
+        this.logger.info("Reconnected successfully, retrying operation.");
+      } catch (reconnectErr) {
+        this.logger.warn("Channel reconnect failed:", reconnectErr);
+        throw err;
+      }
+      return await fn();
+    }
+  }
+  /**
+   * 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(() => {
+      if (this.subscriptionHandler?.hasActiveSubscription()) {
+        return;
+      }
+      if (this.attributeService) {
+        void this.attributeService.ReadValue([SERVER_STATUS_NODE_ID]).then((results) => {
+          const statusData = results[0]?.value;
+          if (statusData?.state === ServerStateEnum.Shutdown) {
+            this.handleServerShutdownDetected();
+          }
+        }).catch((err) => {
+          this.logger.warn("Keep-alive read failed:", err);
+        });
+      }
+    }, KEEP_ALIVE_INTERVAL_MS);
+  }
+  stopKeepAlive() {
+    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 channel = ChannelFactory.createChannel(this.endpointUrl);
+    const { ws, sc } = await this.openTransportAndChannel();
+    this.secureChannel = sc;
+    this.secureChannelFacade = sc;
+    this.ws = ws;
+    this.logger.debug("Creating session...");
+    this.sessionHandler = new SessionHandler(sc, this.configuration);
+    this.session = await this.sessionHandler.createNewSession(this.identity);
+    this.logger.debug("Session created.");
+    this.logger.debug("Initializing services...");
+    this.initServices();
+    this.startKeepAlive();
+  }
+  /**
+   * Builds the full WebSocket → TCP → SecureChannel pipeline and returns the
+   * two objects needed to drive it: the raw WebSocket facade (for teardown)
+   * and the SecureChannelFacade (for service requests/session management).
+   *
+   * Extracted from `connect()` so it can be reused by `reconnectAndReactivate()`.
+   */
+  async openTransportAndChannel() {
+    const wsOptions = { endpoint: this.endpointUrl };
+    const ws = new WebSocketFascade(wsOptions);
+    const webSocketReadableStream = new WebSocketReadableStream(ws, 1e3);
+    const webSocketWritableStream = new WebSocketWritableStream(ws);
+    const scContext = new SecureChannelContext(this.endpointUrl);
+    const tcpMessageInjector = new TcpMessageInjector();
+    const tcpConnectionHandler = new TcpConnectionHandler(tcpMessageInjector, scContext);
+    const tcpMessageDecoupler = new TcpMessageDecoupler(tcpConnectionHandler.onTcpMessage.bind(tcpConnectionHandler));
+    const scMessageEncoder = new SecureChannelMessageEncoder(scContext);
+    const scTypeDecoder = new SecureChannelTypeDecoder(
+      this.configuration.decoder
+    );
+    const scMessageDecoder = new SecureChannelMessageDecoder(scContext);
+    const scTypeEncoder = new SecureChannelTypeEncoder(
+      this.configuration.encoder
+    );
+    const scChunkWriter = new SecureChannelChunkWriter(scContext);
+    const scChunkReader = new SecureChannelChunkReader(scContext);
+    webSocketReadableStream.pipeTo(tcpMessageDecoupler.writable);
+    tcpMessageDecoupler.readable.pipeTo(scMessageDecoder.writable);
+    scMessageDecoder.readable.pipeTo(scChunkReader.writable);
+    scChunkReader.readable.pipeTo(scTypeDecoder.writable);
+    scTypeEncoder.readable.pipeTo(scChunkWriter.writable);
+    scChunkWriter.readable.pipeTo(scMessageEncoder.writable);
+    scMessageEncoder.readable.pipeTo(tcpMessageInjector.writable);
+    tcpMessageInjector.readable.pipeTo(webSocketWritableStream);
+    const sc = new SecureChannelFacade(scContext, scTypeDecoder, scTypeEncoder);
     let connected = false;
     while (!connected) {
-      console.log(`Connecting to OPC UA server at ${this.endpointUrl}...`);
-      connected = await channel.connect();
+      this.logger.debug(`Connecting to OPC UA server at ${this.endpointUrl}...`);
+      await ws.connect();
+      this.logger.debug("WebSocket connection established, now establishing TCP connection...");
+      connected = await tcpConnectionHandler.connect(this.endpointUrl);
       if (!connected) {
-        console.log("Connection failed, retrying in 2 seconds...");
+        this.logger.info("Connection failed, retrying in 2 seconds...");
         await new Promise((resolve) => setTimeout(resolve, 2e3));
       }
     }
-    console.log("Connected to OPC UA server.");
-    this.channel = new SecureChannel(channel, this.configuration);
-    await this.channel.openSecureChannelRequest();
-    const sessionHandler = new SessionHandler(this.channel, this.configuration);
-    this.session = await sessionHandler.createNewSession(this.identity);
-    this.subscriptionHandler = new SubscriptionHandler(
-      new SubscriptionService(this.session.getAuthToken(), this.channel),
-      new MonitoredItemService(this.session.getAuthToken(), this.channel)
-    );
+    this.logger.info("Connected to OPC UA server.");
+    this.logger.debug("Opening secure channel...");
+    await sc.openSecureChannel();
+    this.logger.debug("Secure channel established.");
+    this.enforceChannelSecurityConfig(sc);
+    return { ws, sc };
+  }
+  /**
+   * Validates the negotiated channel's security policy and mode against the
+   * client's `SecurityConfiguration` (OPC UA Part 2, Security Administration).
+   *
+   * Throws if:
+   * - `allowSecurityPolicyNone` is `false` and the channel uses SecurityPolicy None.
+   * - `messageSecurityMode` is set and does not match the channel's actual mode.
+   */
+  enforceChannelSecurityConfig(sc) {
+    const config = this.configuration.securityConfiguration;
+    if (!config) return;
+    const negotiatedPolicy = sc.getSecurityPolicy();
+    const negotiatedMode = sc.getSecurityMode();
+    if (config.allowSecurityPolicyNone === false && negotiatedPolicy === SECURITY_POLICY_NONE_URI) {
+      throw new Error(
+        "Connection refused: SecurityPolicy None is disabled by the client security configuration. Only SecurityPolicy None is currently supported by this client implementation."
+      );
+    }
+    if (config.messageSecurityMode !== void 0 && config.messageSecurityMode !== negotiatedMode) {
+      throw new Error(
+        `Connection refused: negotiated MessageSecurityMode ${negotiatedMode} does not match the required mode ${config.messageSecurityMode} from the security configuration.`
+      );
+    }
   }
+  /**
+   * Tears down the current (dead) channel and establishes a fresh one, then
+   * attempts to recover the existing OPC UA session via ActivateSession before
+   * falling back to a full CreateSession + ActivateSession.
+   *
+   * OPC UA Part 4, Section 5.7.1 / Session Client Auto Reconnect conformance unit:
+   * When the SecureChannel drops but the server-side session has not yet timed
+   * out, the client SHOULD reuse the existing session by calling ActivateSession
+   * on the new channel.  Only if that fails should the client create a new session.
+   */
+  async reconnectAndReactivate() {
+    this.logger.info("Tearing down dead channel before reconnect...");
+    try {
+      this.secureChannelFacade?.close();
+    } catch {
+    }
+    try {
+      this.ws?.close();
+    } catch {
+    }
+    this.secureChannelFacade = void 0;
+    this.secureChannel = void 0;
+    this.ws = void 0;
+    const { ws, sc } = await this.openTransportAndChannel();
+    this.secureChannel = sc;
+    this.secureChannelFacade = sc;
+    this.ws = ws;
+    this.sessionHandler = new SessionHandler(sc, this.configuration);
+    if (this.session) {
+      const reactivated = await this.sessionHandler.tryActivateExistingSession(
+        this.session.getAuthToken(),
+        this.session.getSessionId(),
+        this.session.getEndpoint(),
+        this.identity
+      );
+      if (reactivated !== null) {
+        this.session = reactivated;
+        this.logger.info("Existing session successfully reactivated on new channel.");
+        return;
+      }
+      this.logger.info("ActivateSession for existing session failed; creating a fresh session...");
+    }
+    this.session = await this.sessionHandler.createNewSession(this.identity);
+    this.logger.info("Fresh session established on new channel.");
+  }
+  /**
+   * Gracefully disconnects from the OPC UA server.
+   *
+   * Sequence per OPC UA Part 4, Section 5.7.4:
+   * 1. CloseSession (deleteSubscriptions=true) so the server frees all resources.
+   * 2. Close the SecureChannel, which cancels the pending token-renewal timer.
+   * 3. Close the WebSocket transport.
+   *
+   * CloseSession errors are swallowed so transport teardown always completes even
+   * when the session has already expired on the server side.
+   */
   async disconnect() {
-    console.log("Disconnecting from OPC UA server...");
-    if (this.channel) {
-      await this.channel.disconnect();
+    this.logger.info("Disconnecting from OPC UA server...");
+    this.stopKeepAlive();
+    if (this.session && this.sessionHandler) {
+      try {
+        await this.sessionHandler.closeSession(true);
+      } catch (err) {
+        this.logger.warn("CloseSession failed (continuing teardown):", err);
+      }
+      this.session = void 0;
+    }
+    this.secureChannelFacade?.close();
+    this.secureChannelFacade = void 0;
+    this.secureChannel = void 0;
+    this.ws?.close();
+    this.ws = void 0;
+    this.logger.info("Disconnected.");
+  }
+  /**
+   * 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).
+   * @param options - Request options (e.g. `returnDiagnostics`).
+   * @returns A promise resolving to the CallMethodResult, with `requestHandle` available synchronously.
+   */
+  callMethod(objectId, methodId, inputArguments = [], options) {
+    const requestHandle = nextRequestHandle();
+    const promise = this.withSessionRefresh(async () => {
+      const request = new CallMethodRequest();
+      request.objectId = objectId;
+      request.methodId = methodId;
+      request.inputArguments = inputArguments.map((arg) => Variant.newFrom(arg));
+      const responses = await this.methodService.call([request], options?.returnDiagnostics, requestHandle);
+      const response = responses[0];
+      return new CallMethodResult(response.value, response.statusCode, response.diagnosticInfo);
+    });
+    return Object.assign(promise, { requestHandle });
+  }
+  /**
+   * 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, options?.returnDiagnostics ?? 0, requestHandle);
+    });
+    return Object.assign(promise, { requestHandle });
+  }
+  async browseRecursive(nodeId, recursive, visited, returnDiagnostics, requestHandle) {
+    const nodeKey = `${nodeId.namespace}:${nodeId.identifier}`;
+    if (visited.has(nodeKey)) {
+      return [];
+    }
+    visited.add(nodeKey);
+    const description = new BrowseDescription();
+    description.nodeId = nodeId;
+    description.browseDirection = BrowseDirectionEnum.Forward;
+    description.referenceTypeId = NodeId.newNumeric(0, 33);
+    description.includeSubtypes = true;
+    description.nodeClassMask = 0;
+    description.resultMask = BrowseResultMaskEnum.All;
+    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, returnDiagnostics);
+      const nextResult = nextResults[0];
+      allReferences.push(...nextResult.references ?? []);
+      continuationPoint = nextResult.continuationPoint;
+    }
+    const results = allReferences.map(
+      (ref) => new BrowseNodeResult(
+        ref.referenceTypeId,
+        ref.isForward,
+        ref.nodeId,
+        ref.browseName,
+        ref.displayName,
+        ref.nodeClass,
+        ref.typeDefinition
+      )
+    );
+    if (recursive) {
+      for (const ref of allReferences) {
+        const childNodeId = NodeId.newNumeric(
+          ref.nodeId.nodeId.namespace,
+          ref.nodeId.nodeId.identifier
+        );
+        const childResults = await this.browseRecursive(
+          childNodeId,
+          true,
+          visited,
+          returnDiagnostics
+        );
+        results.push(...childResults);
+      }
+    }
+    return results;
+  }
+  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);
   }
-  async read(ids) {
-    const service = new AttributeService(this.getSession().getAuthToken(), this.channel);
-    const result = await service.ReadValue(ids);
-    return result.map((r) => new ReadValueResult(r.value, r.status));
+  /**
+   * 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;
   }
-  async subscribe(ids, callback) {
-    this.subscriptionHandler?.subscribe(ids, callback);
+  /**
+   * 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 BrowseDescription();
+    description.nodeId = nodeId;
+    description.browseDirection = BrowseDirectionEnum.Forward;
+    description.referenceTypeId = HAS_PROPERTY_REF_TYPE_ID;
+    description.includeSubtypes = false;
+    description.nodeClassMask = 0;
+    description.resultMask = 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 Configuration {
-  static getSimple(name, company) {
+  /**
+   * Optional security restrictions applied during `Client.connect()`.
+   * When not set, permissive defaults are used (SecurityPolicy None allowed,
+   * all user-token types accepted).
+   *
+   * @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 LoggerFactory({
+        defaultLevel: "DEBUG",
+        //todo: use enum
+        categoryLevels: {
+          "transport.*": "TRACE",
+          "secureChannel.*": "TRACE"
+        }
+      });
+    }
     const applicationUri = `urn:${company}:${name}`;
     const productUri = `urn:${company}:${name}:product`;
     const encoder = new Encoder();
@@ -415,10 +1625,26 @@ var ConfigurationClient = class _ConfigurationClient extends Configuration {
     });
     registerTypeDecoders(decoder);
     registerBinaryDecoders(decoder);
-    return new _ConfigurationClient(name, applicationUri, name, productUri, encoder, decoder);
+    return new _ConfigurationClient(
+      name,
+      applicationUri,
+      name,
+      productUri,
+      encoder,
+      decoder,
+      loggerFactory
+    );
   }
-  constructor(applicationName, applicationUri, productName, productUri, encoder, decoder) {
-    super(applicationName, applicationUri, productName, productUri, encoder, decoder);
+  constructor(applicationName, applicationUri, productName, productUri, encoder, decoder, loggerFactory) {
+    super(
+      applicationName,
+      applicationUri,
+      productName,
+      productUri,
+      encoder,
+      decoder,
+      loggerFactory
+    );
   }
 };
 var UserIdentity = class _UserIdentity {
@@ -464,6 +1690,36 @@ var UserIdentity = class _UserIdentity {
   }
 };
 
-export { Client, ConfigurationClient, 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
+};
+
+export { BrowseNodeResult, CERTIFICATE_REQUIRED_STATUS_CODES, CallMethodResult, CertificateRequiredError, Client, ConfigurationClient, NamespaceTable, ReturnDiagnosticsMask, SECURITY_POLICY_NONE_URI, SessionInvalidError, UserIdentity };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map