opcjs-client 0.1.40-alpha → 0.1.41-alpha

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, MessageSecurityModeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive, XmlElement, ExtensionObject, DataValue, DiagnosticInfo } from 'opcjs-base';
+import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, DiagnosticInfo, MessageSecurityModeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive, XmlElement, ExtensionObject, DataValue } from 'opcjs-base';
 
 declare abstract class ServiceBase {
     private authToken;
@@ -14,7 +14,14 @@ declare abstract class ServiceBase {
      * @param context - Short description used in the error message (e.g. "ReadRequest").
      */
     protected checkServiceResult(result: number | undefined, context: string): void;
-    protected createRequestHeader(): RequestHeader;
+    /**
+     * 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.
+     */
+    protected createRequestHeader(returnDiagnostics?: number, preAllocatedHandle?: number): RequestHeader;
     constructor(authToken: NodeId, secureChannel: ISecureChannel);
 }
 
@@ -23,9 +30,16 @@ declare class SessionService extends ServiceBase {
     private logger;
     /**
      * 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.
      */
-    createSession(): Promise<{
+    createSession(clientCertificate?: Uint8Array | null): Promise<{
         sessionId: number;
         authToken: NodeId;
         endpoint: EndpointDescription;
@@ -35,6 +49,20 @@ declare class SessionService extends ServiceBase {
      * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
      */
     activateSession(identityToken: UserIdentityToken): Promise<void>;
+    /**
+     * 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`).
+     */
+    cancel(requestHandle: number): Promise<number>;
     /**
      * Closes the current session on the server (OPC UA Part 4, Section 5.7.4).
      * @param deleteSubscriptions - When true the server deletes all Subscriptions
@@ -93,6 +121,20 @@ declare class Session {
     getAuthToken(): NodeId;
     getSessionId(): number;
     getEndpoint(): EndpointDescription;
+    /**
+     * 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`).
+     */
+    impersonate(identity: UserIdentity): Promise<void>;
     /**
      * Closes the session on the server (OPC UA Part 4, Section 5.7.4).
      * @param deleteSubscriptions - When true the server deletes all Subscriptions
@@ -105,7 +147,11 @@ declare class Session {
 declare class ReadValueResult {
     value: unknown;
     statusCode: number;
-    constructor(value: unknown, statusCode: number);
+    /** Diagnostic info returned by the server when `returnDiagnostics` was set in the request options. */
+    diagnosticInfo?: DiagnosticInfo | undefined;
+    constructor(value: unknown, statusCode: number, 
+    /** Diagnostic info returned by the server when `returnDiagnostics` was set in the request options. */
+    diagnosticInfo?: DiagnosticInfo | undefined);
 }
 
 /** Options for creating a subscription. All fields are optional; server will revise requested values. */
@@ -209,6 +255,20 @@ type SecurityConfiguration = {
      *       implemented alongside non-None security policies.
      */
     unknownCertificatePolicy?: UnknownCertificatePolicy;
+    /**
+     * DER-encoded X.509 ApplicationInstanceCertificate for this client.
+     *
+     * When set, this certificate is used in a OPC UA 1.0 compatibility fallback:
+     * if `CreateSession` with no client certificate is rejected by the server with
+     * a certificate-related status code (`BadCertificateInvalid`,
+     * `BadSecurityChecksFailed`, or `BadNoValidCertificates`), the `CreateSession`
+     * is automatically retried with this certificate in the `clientCertificate`
+     * field (OPC UA Part 4, SecurityPolicy None – CreateSession/ActivateSession 1.0
+     * optional conformance unit).
+     *
+     * Without this field the fallback is disabled and the error propagates as-is.
+     */
+    applicationInstanceCertificate?: Uint8Array;
 };
 
 declare class ConfigurationClient extends Configuration {
@@ -220,6 +280,26 @@ declare class ConfigurationClient extends Configuration {
      * @see SecurityConfiguration
      */
     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: number;
+    /**
+     * 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: number;
     static getSimple(name: string, company: string, loggerFactory?: ILoggerFactory): ConfigurationClient;
     constructor(applicationName: string, applicationUri: string, productName: string, productUri: string, encoder: Encoder, decoder: Decoder, loggerFactory: ILoggerFactory);
 }
@@ -227,7 +307,11 @@ declare class ConfigurationClient extends Configuration {
 declare class CallMethodResult {
     values: unknown[];
     statusCode: number;
-    constructor(values: unknown[], statusCode: number);
+    /** Diagnostic info returned by the server when `returnDiagnostics` was set in the request options. */
+    diagnosticInfo?: DiagnosticInfo | undefined;
+    constructor(values: unknown[], statusCode: number, 
+    /** Diagnostic info returned by the server when `returnDiagnostics` was set in the request options. */
+    diagnosticInfo?: DiagnosticInfo | undefined);
 }
 
 declare class BrowseNodeResult {
@@ -259,6 +343,165 @@ type ScalarCallMethodArgument = UaPrimitive | NodeId | ExpandedNodeId | Qualifie
  */
 type CallMethodArgument = ScalarCallMethodArgument | ScalarCallMethodArgument[];
 
+/**
+ * Bitmask constants for the `returnDiagnostics` field in the OPC UA RequestHeader
+ * (OPC UA Part 4, §7.15 — DiagnosticsMask).
+ *
+ * Combine values with bitwise OR to request multiple diagnostic fields.
+ *
+ * @example
+ * ```ts
+ * import { ReturnDiagnosticsMask, RequestOptions } from 'opcjs-client'
+ *
+ * const options: RequestOptions = {
+ *   returnDiagnostics: ReturnDiagnosticsMask.ServiceLevel | ReturnDiagnosticsMask.OperationLevel,
+ * }
+ * ```
+ */
+declare const ReturnDiagnosticsMask: {
+    /** All service-level diagnostic fields. */
+    readonly ServiceLevel: 31;
+    /** All operation-level diagnostic fields. */
+    readonly OperationLevel: 992;
+    /** All diagnostic fields (service level + operation level). */
+    readonly All: 1023;
+    /** Service-level: index to SymbolicId in the server string table. */
+    readonly ServiceSymbolicId: 1;
+    /** Service-level: index to LocalizedText in the server string table. */
+    readonly ServiceLocalizedText: 2;
+    /** Service-level: additional info string. */
+    readonly ServiceAdditionalInfo: 4;
+    /** Service-level: inner status code. */
+    readonly ServiceInnerStatusCode: 8;
+    /** Service-level: inner diagnostic info. */
+    readonly ServiceInnerDiagnostics: 16;
+    /** Operation-level: index to SymbolicId in the server string table. */
+    readonly OperationSymbolicId: 32;
+    /** Operation-level: index to LocalizedText in the server string table. */
+    readonly OperationLocalizedText: 64;
+    /** Operation-level: additional info string. */
+    readonly OperationAdditionalInfo: 128;
+    /** Operation-level: inner status code. */
+    readonly OperationInnerStatusCode: 256;
+    /** Operation-level: inner diagnostic info. */
+    readonly OperationInnerDiagnostics: 512;
+};
+/**
+ * Options accepted by all `Client` service calls.
+ *
+ * Each field is optional; omitting it keeps the existing default behaviour.
+ */
+type RequestOptions = {
+    /**
+     * Bitmask specifying which diagnostic fields the server should populate in
+     * the `diagnosticInfo` fields of the response (OPC UA Part 4, §7.15).
+     *
+     * Use {@link ReturnDiagnosticsMask} constants to compose the value:
+     * ```ts
+     * returnDiagnostics: ReturnDiagnosticsMask.All
+     * ```
+     *
+     * Default: `0` — no diagnostics returned.
+     */
+    returnDiagnostics?: number;
+};
+
+/**
+ * Tracks the OPC UA NamespaceArray for a session (OPC UA Part 4, Section 5.7.1 —
+ * Session Client Renew NodeIds conformance unit).
+ *
+ * The NamespaceArray maps namespace indices (used inside NodeIds) to stable namespace
+ * URIs. Because the server may assign different indices to the same URI across
+ * sessions (e.g. after a server restart), clients that cache NodeIds must remap
+ * the namespace index whenever the table changes.
+ *
+ * Namespace index `0` is always the OPC UA base namespace
+ * (`http://opcfoundation.org/UA/`) and is guaranteed never to change by the spec.
+ *
+ * @example
+ * ```ts
+ * const oldTable = new NamespaceTable(['http://opcfoundation.org/UA/', 'urn:my-server:model'])
+ * // After reconnect the server puts the model namespace at index 2:
+ * const newTable = new NamespaceTable(['http://opcfoundation.org/UA/', 'urn:unrelated', 'urn:my-server:model'])
+ * const remapped = oldTable.remapNodeId(NodeId.newNumeric(1, 1001), newTable)
+ * // remapped === NodeId(2, 1001)
+ * ```
+ */
+declare class NamespaceTable {
+    private readonly uris;
+    constructor(uris?: string[]);
+    /** Returns the namespace URI at the given index, or `undefined` if out of range. */
+    getUri(index: number): string | undefined;
+    /** Returns the namespace index for the given URI, or `undefined` if not found. */
+    getIndex(uri: string): number | undefined;
+    /** Returns the full ordered array of namespace URIs. */
+    getUris(): readonly string[];
+    /** Returns `true` when both tables contain the same URIs in the same order. */
+    equals(other: NamespaceTable): boolean;
+    /**
+     * 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: NodeId, newTable: NamespaceTable): NodeId;
+}
+
+/**
+ * Result of reading a SelectionListType variable's metadata
+ * (OPC UA Part 5, §7.18 — Base Info Selection List conformance unit).
+ *
+ * Represents the set of permitted values and their human-readable descriptions
+ * that the server exposes for a variable with a `SelectionListType` TypeDefinition.
+ *
+ * @example
+ * ```ts
+ * const list = await client.getSelectionList(nodeId)
+ * if (list) {
+ *   console.log('Permitted values:', list.selections)
+ *   list.selectionDescriptions.forEach((desc, i) =>
+ *     console.log(`  [${i}] ${desc.text} →`, list.selections[i])
+ *   )
+ *   if (list.restrictToList) {
+ *     console.log('Value must be one of the listed selections.')
+ *   }
+ * }
+ * ```
+ */
+type SelectionList = {
+    /** The NodeId of the queried variable. */
+    readonly nodeId: NodeId;
+    /**
+     * Array of permitted values for the variable
+     * (SelectionListType.Selections mandatory property, OPC 10000-5 §7.18).
+     *
+     * The DataType is `BaseDataType`; the concrete type of each element depends on
+     * the server configuration.
+     */
+    readonly selections: readonly unknown[];
+    /**
+     * Human-readable description for each permitted value
+     * (SelectionListType.SelectionDescriptions optional property, OPC 10000-5 §7.18).
+     *
+     * Empty when the property is not present on the node.
+     * When present, `selectionDescriptions[i]` describes `selections[i]`.
+     */
+    readonly selectionDescriptions: readonly LocalizedText[];
+    /**
+     * When `true`, the variable's value MUST be one of the values in `selections`
+     * (SelectionListType.RestrictToList optional property, OPC 10000-5 §7.18).
+     *
+     * Defaults to `false` when the property is absent on the node.
+     */
+    readonly restrictToList: boolean;
+};
+
 declare class Client {
     private configuration;
     private identity;
@@ -274,12 +517,63 @@ declare class Client {
     private ws?;
     private sessionHandler?;
     private keepAliveTimer?;
+    /** Set to true while a shutdown-triggered reconnect is pending to avoid duplicate attempts. */
+    private shutdownReconnectPending;
+    /** Most recently read NamespaceArray from the server (Session Client Renew NodeIds). */
+    private 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?: (oldTable: NamespaceTable, newTable: NamespaceTable) => void;
+    /**
+     * 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?: () => void;
     getSession(): Session;
     /**
      * (Re-)initialises all session-scoped services from the current `this.session`.
      * Called both after the initial `connect()` and after a session refresh.
      */
     private initServices;
+    /**
+     * 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.
+     */
+    private refreshNamespaceTable;
+    /**
+     * 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(): NamespaceTable | undefined;
     /**
      * Executes `fn` and, if it throws a `SessionInvalidError`, creates a fresh
      * session and retries the operation exactly once.
@@ -298,9 +592,40 @@ declare class Client {
      * 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.
      */
     private startKeepAlive;
     private stopKeepAlive;
+    /**
+     * 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.
+     */
+    private handleServerShutdownDetected;
+    /**
+     * 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`.
+     */
+    private computeReconnectDelayMs;
     connect(): Promise<void>;
     /**
      * Builds the full WebSocket → TCP → SecureChannel pipeline and returns the
@@ -342,21 +667,159 @@ declare class Client {
      * when the session has already expired on the server side.
      */
     disconnect(): Promise<void>;
-    read(ids: NodeId[]): Promise<ReadValueResult[]>;
+    /**
+     * 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: NodeId[], options?: RequestOptions): Promise<ReadValueResult[]> & {
+        requestHandle: number;
+    };
     /**
      * 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.
+     */
+    callMethod(objectId: NodeId, methodId: NodeId, inputArguments?: CallMethodArgument[], options?: RequestOptions): Promise<CallMethodResult> & {
+        requestHandle: number;
+    };
+    /**
+     * 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.
      */
-    callMethod(objectId: NodeId, methodId: NodeId, inputArguments?: CallMethodArgument[]): Promise<CallMethodResult>;
-    browse(nodeId: NodeId, recursive?: boolean): Promise<BrowseNodeResult[]>;
+    browse(nodeId: NodeId, recursive?: boolean, options?: RequestOptions): Promise<BrowseNodeResult[]> & {
+        requestHandle: number;
+    };
     private browseRecursive;
     subscribe(ids: NodeId[], callback: (data: {
         id: NodeId;
         value: unknown;
     }[]) => void, options?: SubscriptionOptions): Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    cancel(requestHandle: number): Promise<number>;
+    /**
+     * 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 ...
+     * ```
+     */
+    impersonate(identity: UserIdentity): Promise<void>;
+    /**
+     * 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: NodeId): Promise<SelectionList | null>;
+    /**
+     * Internal implementation of `getSelectionList`. Browses the node's
+     * HasProperty references to locate Selections/SelectionDescriptions/RestrictToList,
+     * then batch-reads their values.
+     */
+    private fetchSelectionList;
+    /**
+     * 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(): number;
     constructor(endpointUrl: string, configuration: ConfigurationClient, identity: UserIdentity);
 }
 
@@ -376,4 +839,27 @@ declare class SessionInvalidError extends Error {
     constructor(statusCode: number);
 }
 
-export { BrowseNodeResult, type CallMethodArgument, CallMethodResult, Client, ConfigurationClient, SECURITY_POLICY_NONE_URI, type ScalarCallMethodArgument, type SecurityConfiguration, SessionInvalidError, type SubscriptionOptions, type UnknownCertificatePolicy, UserIdentity };
+/**
+ * Thrown when the server rejects `CreateSession` because no (or an invalid)
+ * client certificate was supplied.
+ *
+ * This signals that the OPC UA 1.0 fallback path should be attempted: retry
+ * `CreateSession` with the `applicationInstanceCertificate` from the
+ * `SecurityConfiguration`.
+ *
+ * Relevant OPC UA status codes that trigger this error:
+ *  - `BadCertificateInvalid`      (0x80120000) – null/empty cert was rejected
+ *  - `BadSecurityChecksFailed`    (0x80130000) – security validation failed
+ *  - `BadNoValidCertificates`     (0x80590000) – server found no valid certificate
+ */
+declare class CertificateRequiredError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number);
+}
+/**
+ * Status codes that indicate the server requires a client certificate even
+ * when SecurityPolicy is None (OPC UA 1.0 servers).
+ */
+declare const CERTIFICATE_REQUIRED_STATUS_CODES: Set<number>;
+
+export { BrowseNodeResult, CERTIFICATE_REQUIRED_STATUS_CODES, type CallMethodArgument, CallMethodResult, CertificateRequiredError, Client, ConfigurationClient, NamespaceTable, type RequestOptions, ReturnDiagnosticsMask, SECURITY_POLICY_NONE_URI, type ScalarCallMethodArgument, type SecurityConfiguration, type SelectionList, SessionInvalidError, type SubscriptionOptions, type UnknownCertificatePolicy, UserIdentity };