opcjs-client 0.1.13 → 0.1.14

package/dist/index.d.ts

@@ -1,24 +1,88 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, Encoder, Decoder } 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;
     protected secureChannel: ISecureChannel;
-    protected createRequestHeader(): RequestHeader;
+    /**
+     * 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").
+     */
+    protected checkServiceResult(result: number | undefined, context: string): void;
+    /**
+     * 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);
 }
 
 declare class SessionService extends ServiceBase {
     private configuration;
-    createSession(): Promise<{
+    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(clientCertificate?: Uint8Array | null): Promise<{
         sessionId: number;
         authToken: NodeId;
         endpoint: EndpointDescription;
     }>;
+    /**
+     * 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).
+     */
     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
+     *   associated with this Session, freeing their resources immediately.
+     *   Pass false to keep Subscriptions alive for transfer to another Session.
+     */
+    closeSession(deleteSubscriptions: boolean): Promise<void>;
     recreate(authToken: NodeId): SessionService;
     constructor(authToken: NodeId, secureChannel: ISecureChannel, configuration: Configuration);
 }
 
+interface IssuerEndpointUrl {
+    'ua.resourceId': string;
+    'ua.authorityUrl': string;
+    'ua.authorityProfileUri': string;
+    'ua.tokenEndpoint': string;
+    'ua.authorizationEndpoint': string;
+    'ua.requestTypes': string[];
+    'ua.scopes': string[];
+}
 declare class IssuerConfiguration {
     resourceId: string;
     authorityUrl: string;
@@ -27,7 +91,7 @@ declare class IssuerConfiguration {
     authorizationEndpoint: string;
     requestTypes: string[];
     scopes: string[];
-    static newFrom(issuerEndpointUrl: any): IssuerConfiguration;
+    static newFrom(issuerEndpointUrl: IssuerEndpointUrl): IssuerConfiguration;
     constructor(resourceId: string, authorityUrl: string, authorityProfileUri: string, tokenEndpoint: string, authorizationEndpoint: string, requestTypes: string[], scopes: string[]);
 }
 
@@ -55,36 +119,747 @@ declare class Session {
     private sessionServices;
     activateSession(identity: UserIdentity): Promise<void>;
     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
+     *   tied to this Session. Defaults to true.
+     */
+    close(deleteSubscriptions?: boolean): Promise<void>;
     constructor(sessionId: number, authToken: NodeId, endpoint: EndpointDescription, sessionServices: SessionService);
 }
 
 declare class ReadValueResult {
     value: unknown;
-    status: string;
-    constructor(value: unknown, status: string);
+    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. */
+interface SubscriptionOptions {
+    /** Requested publishing interval in milliseconds. Default: 2000. */
+    requestedPublishingInterval?: number;
+    /** Requested lifetime count (number of publishing intervals before subscription times out). Default: 360000. */
+    requestedLifetimeCount?: number;
+    /** Requested max keep-alive count. Default: 60000. */
+    requestedMaxKeepAliveCount?: number;
+    /** Maximum number of notifications per publish response. 0 = no limit. Default: 200. */
+    maxNotificationsPerPublish?: number;
+    /** Subscription priority relative to other subscriptions. Default: 1. */
+    priority?: number;
+    /** Requested sampling interval in milliseconds. -1 = use subscription publishing interval. */
+    samplingInterval?: number;
+    /** Requested queue size for each monitored item. */
+    queueSize?: number;
 }
 
+/** URI for the SecurityPolicy None profile. */
+declare const SECURITY_POLICY_NONE_URI = "http://opcfoundation.org/UA/SecurityPolicy#None";
+/**
+ * How the client should handle a server certificate it cannot verify.
+ *
+ * - `'reject'` — abort the connection (secure default when `trustedCAs` is configured).
+ * - `'trust'`  — accept any certificate without verification (development convenience;
+ *                **insecure in production**).
+ *
+ * @note Enforcement is deferred until certificate-based security policies are
+ *       implemented. The value is stored and will be honoured when that support lands.
+ */
+type UnknownCertificatePolicy = 'reject' | 'trust';
+/**
+ * OPC UA client security configuration (OPC UA Part 2, Security Administration CU).
+ *
+ * Restricts which security options the client will accept when connecting to or
+ * negotiating with a server. All fields are optional; omitting a field applies
+ * the permissive default so that existing callers need no changes.
+ *
+ * @example
+ * ```ts
+ * const config = ConfigurationClient.getSimple('MyApp', 'MyCompany')
+ * config.securityConfiguration = {
+ *   allowedUserTokenTypes: [UserTokenTypeEnum.UserName],
+ *   allowSecurityPolicyNone: false,   // require an encrypted channel
+ * }
+ * ```
+ */
+type SecurityConfiguration = {
+    /**
+     * User-identity-token types the client is willing to accept.
+     *
+     * When set, `connect()` will throw if:
+     * - The supplied `UserIdentity`'s token type is not in this list, OR
+     * - The server endpoint does not offer any type from this list.
+     *
+     * Default: all token types are accepted (no restriction).
+     */
+    allowedUserTokenTypes?: UserTokenTypeEnum[];
+    /**
+     * Allow connecting when the negotiated SecurityPolicy is `None` (unencrypted,
+     * unsigned channel).
+     *
+     * Set to `false` to require a secure channel — `connect()` will throw rather
+     * than establish a cleartext connection.
+     *
+     * Currently the only supported security policy is `None`. Setting this to `false`
+     * will therefore cause `connect()` to always throw until non-None policies are
+     * added to this client implementation.
+     *
+     * Default: `true` (SecurityPolicy None is permitted).
+     */
+    allowSecurityPolicyNone?: boolean;
+    /**
+     * Required `MessageSecurityMode` for the secure channel.
+     *
+     * When set, `connect()` verifies that the channel's negotiated mode matches
+     * this value and throws otherwise.
+     *
+     * Currently only `MessageSecurityModeEnum.None` is supported.
+     *
+     * Default: no requirement (any mode is accepted).
+     */
+    messageSecurityMode?: MessageSecurityModeEnum;
+    /**
+     * DER-encoded X.509 trusted CA certificates used to verify the server's
+     * application instance certificate.
+     *
+     * @note Reserved for future use. Certificate verification is not yet implemented.
+     *       Providing this field has no effect until non-None security policies land.
+     */
+    trustedCAs?: Uint8Array[];
+    /**
+     * How to handle a server certificate that cannot be verified against `trustedCAs`.
+     *
+     * - `'reject'` — refuse the connection (default when `trustedCAs` is provided).
+     * - `'trust'`  — accept any certificate (development only; insecure in production).
+     *
+     * @note Reserved for future use. Has no effect until certificate verification is
+     *       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 {
-    static getSimple(name: string, company: string): ConfigurationClient;
-    constructor(applicationName: string, applicationUri: string, productName: string, productUri: string, encoder: Encoder, decoder: Decoder);
+    /**
+     * 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?: 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);
 }
 
+declare class CallMethodResult {
+    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 {
+    referenceTypeId: NodeId;
+    isForward: boolean;
+    nodeId: ExpandedNodeId;
+    browseName: QualifiedName;
+    displayName: LocalizedText;
+    nodeClass: NodeClassEnum;
+    typeDefinition: ExpandedNodeId;
+    constructor(referenceTypeId: NodeId, isForward: boolean, nodeId: ExpandedNodeId, browseName: QualifiedName, displayName: LocalizedText, nodeClass: NodeClassEnum, typeDefinition: ExpandedNodeId);
+}
+
+/**
+ * A single (scalar) value that may be passed as a method argument.
+ * `Variant` is intentionally excluded — callers work with concrete OPC UA types;
+ * the conversion to `Variant` is done internally by `callMethod`.
+ */
+type ScalarCallMethodArgument = UaPrimitive | NodeId | ExpandedNodeId | QualifiedName | LocalizedText | XmlElement | ExtensionObject | DataValue | DiagnosticInfo;
+/**
+ * A value (or homogeneous array of values) that may be passed as a method argument
+ * to {@link Client.callMethod}.
+ *
+ * Pass a plain array to create an array-rank Variant input argument, e.g.:
+ * ```ts
+ * client.callMethod(objId, methodId, [[uaDouble(1.0), uaDouble(2.0)]])
+ * ```
+ * Arrays must be homogeneous — all elements must be of the same OPC UA type.
+ */
+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;
     private endpointUrl;
-    private channel?;
+    private attributeService?;
+    private methodService?;
+    private browseService?;
     private session?;
     private subscriptionHandler?;
+    private logger;
+    private secureChannel?;
+    private secureChannelFacade?;
+    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.
+     *
+     * 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.
+     */
+    private withSessionRefresh;
+    /**
+     * 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
+     * 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()`.
+     */
+    private openTransportAndChannel;
+    /**
+     * 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.
+     */
+    private enforceChannelSecurityConfig;
+    /**
+     * 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.
+     */
+    private reconnectAndReactivate;
+    /**
+     * 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.
+     */
     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).
+     * @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.
+     */
+    browse(nodeId: NodeId, recursive?: boolean, options?: RequestOptions): Promise<BrowseNodeResult[]> & {
+        requestHandle: number;
+    };
+    private browseRecursive;
     subscribe(ids: NodeId[], callback: (data: {
         id: NodeId;
         value: unknown;
-    }[]) => void): Promise<void>;
+    }[]) => 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);
 }
 
-export { Client, ConfigurationClient, UserIdentity };
+/**
+ * Thrown when the server signals that the current Session is no longer valid.
+ *
+ * Callers that want to react to a dropped session (e.g. by creating a new one
+ * and retrying the operation) should catch this specific error type instead of
+ * the generic `Error` class.
+ *
+ * Relevant OPC UA status codes:
+ *  - `BadSessionIdInvalid` (0x80250000) – session no longer exists on the server
+ *  - `BadSessionClosed`    (0x80260000) – session was closed explicitly
+ */
+declare class SessionInvalidError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number);
+}
+
+/**
+ * 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 };