lexmount 0.5.4 → 0.5.6

package/README.md

@@ -224,6 +224,41 @@ await session.close();
 client.close();
 ```
 
+### Integrated Auth with lexmount-extra
+
+For NTLM or Kerberos integrated auth, install `lexmount-extra` in your
+application and register the callback factories it provides:
+
+```ts
+import { Lexmount, connectOverCDP, registerIntegratedAuthCallback } from 'lexmount';
+import { createKerberosAuthCallback, createNTLMAuthCallback } from 'lexmount-extra';
+
+const client = new Lexmount();
+const session = await client.sessions.create({ browserMode: 'normal' });
+const cdpClient = await connectOverCDP(session);
+
+await registerIntegratedAuthCallback(
+  cdpClient,
+  createNTLMAuthCallback({
+    hostname: 'web.lab.local',
+    domain: 'LAB',
+    username: process.env.LEXMOUNT_NTLM_USERNAME,
+    password: process.env.LEXMOUNT_NTLM_PASSWORD,
+  })
+);
+
+await registerIntegratedAuthCallback(
+  cdpClient,
+  createKerberosAuthCallback({
+    hostname: 'web.lab.test',
+  })
+);
+```
+
+`lexmount-extra` can derive some NTLM and Kerberos defaults from the current
+environment, but explicit callback options are usually clearer for reproducible
+integrations.
+
 ### Error Handling
 
 ```ts
@@ -283,6 +318,7 @@ Generated files are written to `generated-docs/` and are not meant to be committ
 
 Example scripts live in [examples](./examples):
 
+- `auth-basic.ts`
 - `playwright-basic.ts`
 - `session-management.ts`
 - `context-basic.ts`
@@ -299,6 +335,7 @@ Run them with:
 ```bash
 cd examples
 npm install
+npm run auth-basic
 npm run context-fork
 npm run playwright-basic
 npm run session-management
@@ -542,6 +579,40 @@ await session.close();
 client.close();
 ```
 
+### 使用 lexmount-extra 集成认证
+
+如果需要 NTLM 或 Kerberos 集成认证，可以在业务项目中安装 `lexmount-extra`，
+并注册它提供的回调工厂：
+
+```ts
+import { Lexmount, connectOverCDP, registerIntegratedAuthCallback } from 'lexmount';
+import { createKerberosAuthCallback, createNTLMAuthCallback } from 'lexmount-extra';
+
+const client = new Lexmount();
+const session = await client.sessions.create({ browserMode: 'normal' });
+const cdpClient = await connectOverCDP(session);
+
+await registerIntegratedAuthCallback(
+  cdpClient,
+  createNTLMAuthCallback({
+    hostname: 'web.lab.local',
+    domain: 'LAB',
+    username: process.env.LEXMOUNT_NTLM_USERNAME,
+    password: process.env.LEXMOUNT_NTLM_PASSWORD,
+  })
+);
+
+await registerIntegratedAuthCallback(
+  cdpClient,
+  createKerberosAuthCallback({
+    hostname: 'web.lab.test',
+  })
+);
+```
+
+`lexmount-extra` 可以从当前环境推导部分 NTLM/Kerberos 默认值，但显式传入回调
+选项更适合可复现的集成。
+
 ### 错误处理
 
 ```ts
@@ -601,6 +672,7 @@ npm run docs:html
 
 示例脚本位于 [examples](./examples)：
 
+- `auth-basic.ts`
 - `playwright-basic.ts`
 - `session-management.ts`
 - `context-basic.ts`
@@ -617,6 +689,7 @@ npm run docs:html
 ```bash
 cd examples
 npm install
+npm run auth-basic
 npm run context-fork
 npm run playwright-basic
 npm run session-management

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+/// <reference path="../types/chrome-remote-interface.d.ts" />
+import { EventEmitter } from 'events';
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 
 /**
@@ -443,6 +445,87 @@ declare class ExtensionsResource {
     private handleError;
 }
 
+/**
+ * Lexmount API client.
+ */
+
+/**
+ * Main Lexmount SDK client.
+ */
+declare class Lexmount {
+    /**
+     * API key used for authentication.
+     */
+    readonly apiKey: string;
+    /**
+     * Default project identifier used by resource methods.
+     */
+    readonly projectId: string;
+    /**
+     * API base URL.
+     */
+    readonly baseUrl: string;
+    readonly region?: string;
+    selectedRegion?: string;
+    private endpointBaseUrl?;
+    private selectedHost?;
+    private regionResolutionAttempted;
+    private regionResolutionPromise?;
+    /**
+     * Session operations.
+     */
+    readonly sessions: SessionsResource;
+    /**
+     * Persistent context operations.
+     */
+    readonly contexts: ContextsResource;
+    /**
+     * Browser extension operations.
+     */
+    readonly extensions: ExtensionsResource;
+    private readonly httpClient;
+    constructor(config?: LexmountConfig);
+    /**
+     * Internal POST request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Internal GET request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _get<T = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Internal DELETE request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    regionInfo(): Promise<RegionInfo>;
+    catalogInfo(): Promise<CatalogInfo>;
+    /**
+     * Close the client.
+     *
+     * Axios does not require explicit teardown, but the method is kept for API symmetry.
+     */
+    close(): void;
+    /**
+     * String representation of the client.
+     */
+    toString(): string;
+    private request;
+    private normalizeRequestError;
+    private getDefaultHeaders;
+    private ensureRegionResolved;
+    private resolveRegion;
+    private selectCatalogRegion;
+    private probeRegionHost;
+    private isAllowedCatalogHost;
+    private rewriteUrl;
+}
+
 /**
  * Session resource implementation.
  */
@@ -630,85 +713,65 @@ declare class SessionsResource {
 }
 
 /**
- * Lexmount API client.
+ * Chrome DevTools Protocol connection helpers.
  */
 
+interface CDPEventMessage {
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}
 /**
- * Main Lexmount SDK client.
+ * Lexmount CDP client.
+ *
+ * It forwards Chrome DevTools Protocol notifications through EventEmitter and
+ * exposes `send()` for raw CDP commands.
  */
-declare class Lexmount {
-    /**
-     * API key used for authentication.
-     */
-    readonly apiKey: string;
-    /**
-     * Default project identifier used by resource methods.
-     */
-    readonly projectId: string;
-    /**
-     * API base URL.
-     */
-    readonly baseUrl: string;
-    readonly region?: string;
-    selectedRegion?: string;
-    private endpointBaseUrl?;
-    private selectedHost?;
-    private regionResolutionAttempted;
-    private regionResolutionPromise?;
-    /**
-     * Session operations.
-     */
-    readonly sessions: SessionsResource;
-    /**
-     * Persistent context operations.
-     */
-    readonly contexts: ContextsResource;
-    /**
-     * Browser extension operations.
-     */
-    readonly extensions: ExtensionsResource;
-    private readonly httpClient;
-    constructor(config?: LexmountConfig);
-    /**
-     * Internal POST request helper with timeout and network error mapping.
-     *
-     * @internal
-     */
-    _post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-    /**
-     * Internal GET request helper with timeout and network error mapping.
-     *
-     * @internal
-     */
-    _get<T = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+declare class CDPClient extends EventEmitter {
+    readonly session: SessionInfo;
+    private closed;
+    private rawClient?;
+    constructor(session: SessionInfo);
     /**
-     * Internal DELETE request helper with timeout and network error mapping.
-     *
-     * @internal
+     * Connect the CDP client to the session.
      */
-    _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-    regionInfo(): Promise<RegionInfo>;
-    catalogInfo(): Promise<CatalogInfo>;
+    connect(): Promise<this>;
     /**
-     * Close the client.
+     * Send a raw Chrome DevTools Protocol command.
      *
-     * Axios does not require explicit teardown, but the method is kept for API symmetry.
+     * Returns `undefined` if called before the client has connected.
      */
-    close(): void;
+    send(method: string, params?: any, sessionId?: string): Promise<any | undefined>;
     /**
-     * String representation of the client.
+     * Close the CDP connection and release internal listeners.
      */
-    toString(): string;
-    private request;
-    private normalizeRequestError;
-    private getDefaultHeaders;
-    private ensureRegionResolved;
-    private resolveRegion;
-    private selectCatalogRegion;
-    private probeRegionHost;
-    private isAllowedCatalogHost;
-    private rewriteUrl;
+    close(): Promise<void>;
 }
+/**
+ * Connect to a Lexmount browser session over Chrome DevTools Protocol.
+ */
+declare function connectOverCDP(session: SessionInfo): Promise<CDPClient>;
+
+/**
+ * Integrated authentication helpers.
+ */
+
+type IntegratedAuthCallbackResult = {
+    cancel: true;
+} | {
+    cancel: false;
+    scheme: string;
+    token: string;
+};
+type IntegratedAuthCallback = (params: any, callback: (result: IntegratedAuthCallbackResult) => Promise<void>) => void | Promise<void>;
+/**
+ * Register an integrated auth callback for a session.
+ */
+declare function registerIntegratedAuthCallback(sessionOrClient: SessionInfo | CDPClient, callback: IntegratedAuthCallback): Promise<void>;
+/**
+ * Deregister a previously registered integrated auth callback.
+ */
+declare function deregisterIntegratedAuthCallback(sessionOrClient: SessionInfo | CDPClient, callback: IntegratedAuthCallback): void;
 
 /**
  * Lexmount SDK error hierarchy.
@@ -775,6 +838,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.5.4";
+declare const VERSION = "0.5.6";
 
-export { APIError, AuthenticationError, type BrowserMode, type CatalogInfo, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, ExtensionInfo, type ExtensionInfoShape, type ExtensionListOptions, type ExtensionUploadOptions, ExtensionsResource, type ForceReleaseResponse, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type RegionCatalogEntry, type RegionInfo, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionDownloadInfo, type SessionDownloadInfoShape, SessionDownloadsDeleteResponse, type SessionDownloadsDeleteResponseShape, SessionDownloadsListResponse, type SessionDownloadsListResponseShape, SessionDownloadsResource, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionProxyConfig, type SessionStatus, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };
+export { APIError, AuthenticationError, type BrowserMode, CDPClient, type CDPEventMessage, type CatalogInfo, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, ExtensionInfo, type ExtensionInfoShape, type ExtensionListOptions, type ExtensionUploadOptions, ExtensionsResource, type ForceReleaseResponse, type IntegratedAuthCallback, type IntegratedAuthCallbackResult, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type RegionCatalogEntry, type RegionInfo, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionDownloadInfo, type SessionDownloadInfoShape, SessionDownloadsDeleteResponse, type SessionDownloadsDeleteResponseShape, SessionDownloadsListResponse, type SessionDownloadsListResponseShape, SessionDownloadsResource, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionProxyConfig, type SessionStatus, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, connectOverCDP, Lexmount as default, deregisterIntegratedAuthCallback, disableLogging, enableLogging, getLogger, registerIntegratedAuthCallback, setLogLevel };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="../types/chrome-remote-interface.d.ts" />
+import { EventEmitter } from 'events';
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 
 /**
@@ -443,6 +445,87 @@ declare class ExtensionsResource {
     private handleError;
 }
 
+/**
+ * Lexmount API client.
+ */
+
+/**
+ * Main Lexmount SDK client.
+ */
+declare class Lexmount {
+    /**
+     * API key used for authentication.
+     */
+    readonly apiKey: string;
+    /**
+     * Default project identifier used by resource methods.
+     */
+    readonly projectId: string;
+    /**
+     * API base URL.
+     */
+    readonly baseUrl: string;
+    readonly region?: string;
+    selectedRegion?: string;
+    private endpointBaseUrl?;
+    private selectedHost?;
+    private regionResolutionAttempted;
+    private regionResolutionPromise?;
+    /**
+     * Session operations.
+     */
+    readonly sessions: SessionsResource;
+    /**
+     * Persistent context operations.
+     */
+    readonly contexts: ContextsResource;
+    /**
+     * Browser extension operations.
+     */
+    readonly extensions: ExtensionsResource;
+    private readonly httpClient;
+    constructor(config?: LexmountConfig);
+    /**
+     * Internal POST request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Internal GET request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _get<T = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Internal DELETE request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    regionInfo(): Promise<RegionInfo>;
+    catalogInfo(): Promise<CatalogInfo>;
+    /**
+     * Close the client.
+     *
+     * Axios does not require explicit teardown, but the method is kept for API symmetry.
+     */
+    close(): void;
+    /**
+     * String representation of the client.
+     */
+    toString(): string;
+    private request;
+    private normalizeRequestError;
+    private getDefaultHeaders;
+    private ensureRegionResolved;
+    private resolveRegion;
+    private selectCatalogRegion;
+    private probeRegionHost;
+    private isAllowedCatalogHost;
+    private rewriteUrl;
+}
+
 /**
  * Session resource implementation.
  */
@@ -630,85 +713,65 @@ declare class SessionsResource {
 }
 
 /**
- * Lexmount API client.
+ * Chrome DevTools Protocol connection helpers.
  */
 
+interface CDPEventMessage {
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}
 /**
- * Main Lexmount SDK client.
+ * Lexmount CDP client.
+ *
+ * It forwards Chrome DevTools Protocol notifications through EventEmitter and
+ * exposes `send()` for raw CDP commands.
  */
-declare class Lexmount {
-    /**
-     * API key used for authentication.
-     */
-    readonly apiKey: string;
-    /**
-     * Default project identifier used by resource methods.
-     */
-    readonly projectId: string;
-    /**
-     * API base URL.
-     */
-    readonly baseUrl: string;
-    readonly region?: string;
-    selectedRegion?: string;
-    private endpointBaseUrl?;
-    private selectedHost?;
-    private regionResolutionAttempted;
-    private regionResolutionPromise?;
-    /**
-     * Session operations.
-     */
-    readonly sessions: SessionsResource;
-    /**
-     * Persistent context operations.
-     */
-    readonly contexts: ContextsResource;
-    /**
-     * Browser extension operations.
-     */
-    readonly extensions: ExtensionsResource;
-    private readonly httpClient;
-    constructor(config?: LexmountConfig);
-    /**
-     * Internal POST request helper with timeout and network error mapping.
-     *
-     * @internal
-     */
-    _post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-    /**
-     * Internal GET request helper with timeout and network error mapping.
-     *
-     * @internal
-     */
-    _get<T = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+declare class CDPClient extends EventEmitter {
+    readonly session: SessionInfo;
+    private closed;
+    private rawClient?;
+    constructor(session: SessionInfo);
     /**
-     * Internal DELETE request helper with timeout and network error mapping.
-     *
-     * @internal
+     * Connect the CDP client to the session.
      */
-    _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
-    regionInfo(): Promise<RegionInfo>;
-    catalogInfo(): Promise<CatalogInfo>;
+    connect(): Promise<this>;
     /**
-     * Close the client.
+     * Send a raw Chrome DevTools Protocol command.
      *
-     * Axios does not require explicit teardown, but the method is kept for API symmetry.
+     * Returns `undefined` if called before the client has connected.
      */
-    close(): void;
+    send(method: string, params?: any, sessionId?: string): Promise<any | undefined>;
     /**
-     * String representation of the client.
+     * Close the CDP connection and release internal listeners.
      */
-    toString(): string;
-    private request;
-    private normalizeRequestError;
-    private getDefaultHeaders;
-    private ensureRegionResolved;
-    private resolveRegion;
-    private selectCatalogRegion;
-    private probeRegionHost;
-    private isAllowedCatalogHost;
-    private rewriteUrl;
+    close(): Promise<void>;
 }
+/**
+ * Connect to a Lexmount browser session over Chrome DevTools Protocol.
+ */
+declare function connectOverCDP(session: SessionInfo): Promise<CDPClient>;
+
+/**
+ * Integrated authentication helpers.
+ */
+
+type IntegratedAuthCallbackResult = {
+    cancel: true;
+} | {
+    cancel: false;
+    scheme: string;
+    token: string;
+};
+type IntegratedAuthCallback = (params: any, callback: (result: IntegratedAuthCallbackResult) => Promise<void>) => void | Promise<void>;
+/**
+ * Register an integrated auth callback for a session.
+ */
+declare function registerIntegratedAuthCallback(sessionOrClient: SessionInfo | CDPClient, callback: IntegratedAuthCallback): Promise<void>;
+/**
+ * Deregister a previously registered integrated auth callback.
+ */
+declare function deregisterIntegratedAuthCallback(sessionOrClient: SessionInfo | CDPClient, callback: IntegratedAuthCallback): void;
 
 /**
  * Lexmount SDK error hierarchy.
@@ -775,6 +838,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.5.4";
+declare const VERSION = "0.5.6";
 
-export { APIError, AuthenticationError, type BrowserMode, type CatalogInfo, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, ExtensionInfo, type ExtensionInfoShape, type ExtensionListOptions, type ExtensionUploadOptions, ExtensionsResource, type ForceReleaseResponse, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type RegionCatalogEntry, type RegionInfo, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionDownloadInfo, type SessionDownloadInfoShape, SessionDownloadsDeleteResponse, type SessionDownloadsDeleteResponseShape, SessionDownloadsListResponse, type SessionDownloadsListResponseShape, SessionDownloadsResource, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionProxyConfig, type SessionStatus, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };
+export { APIError, AuthenticationError, type BrowserMode, CDPClient, type CDPEventMessage, type CatalogInfo, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, ExtensionInfo, type ExtensionInfoShape, type ExtensionListOptions, type ExtensionUploadOptions, ExtensionsResource, type ForceReleaseResponse, type IntegratedAuthCallback, type IntegratedAuthCallbackResult, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type RegionCatalogEntry, type RegionInfo, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionDownloadInfo, type SessionDownloadInfoShape, SessionDownloadsDeleteResponse, type SessionDownloadsDeleteResponseShape, SessionDownloadsListResponse, type SessionDownloadsListResponseShape, SessionDownloadsResource, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionProxyConfig, type SessionStatus, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, connectOverCDP, Lexmount as default, deregisterIntegratedAuthCallback, disableLogging, enableLogging, getLogger, registerIntegratedAuthCallback, setLogLevel };