lexmount 0.2.0 → 0.2.3

package/README.md

@@ -14,6 +14,9 @@ Node.js SDK for the Lexmount browser automation service.
 - Typed public API with ESM and CommonJS support
 - Session management with pagination support
 - Persistent context management
+- Extension upload/list/get/delete
+- Session downloads list/get/archive/delete
+- Session creation with upstream proxy support
 - Structured SDK errors
 - Configurable SDK logging
 - TSDoc + TypeDoc based API documentation generation
@@ -93,6 +96,20 @@ const session = await client.sessions.create({
 });
 ```
 
+Create a session with extensions and an upstream proxy:
+
+```ts
+const session = await client.sessions.create({
+  extensionIds: ['ext_123'],
+  proxy: {
+    type: 'external',
+    server: 'http://10.3.6.54:28080',
+    username: 'user',
+    password: 'pass',
+  },
+});
+```
+
 List sessions with pagination metadata:
 
 ```ts
@@ -110,6 +127,15 @@ Delete a session:
 await client.sessions.delete({ sessionId: 'session-id' });
 ```
 
+List and archive session downloads:
+
+```ts
+const downloads = await client.sessions.downloads.list(session.id);
+console.log(downloads.summary.count);
+
+const archive = await client.sessions.downloads.archive(session.id);
+```
+
 ### Contexts
 
 Create and inspect contexts:
@@ -138,6 +164,30 @@ Force release a stuck lock:
 await client.contexts.forceRelease('context-id');
 ```
 
+### Extensions
+
+Upload an extension archive:
+
+```ts
+const extension = await client.extensions.upload('/absolute/path/to/extension.zip', {
+  name: 'demo-extension',
+});
+```
+
+List and inspect extensions:
+
+```ts
+const extensions = await client.extensions.list({ limit: 10 });
+const details = await client.extensions.get(extension.id);
+console.log(details.name);
+```
+
+Delete an uploaded extension:
+
+```ts
+await client.extensions.delete(extension.id);
+```
+
 ### Playwright Example
 
 ```ts
@@ -224,6 +274,9 @@ Example scripts live in [examples](./examples):
 - `context-list-get.ts`
 - `context-modes.ts`
 - `context-lock-handling.ts`
+- `extension-basic.ts`
+- `proxy-session.ts`
+- `session-downloads.ts`
 
 Run them with:
 
@@ -232,6 +285,9 @@ cd examples
 npm install
 npm run playwright-basic
 npm run session-management
+npm run extension-basic
+npm run proxy-session
+npm run session-downloads
 ```
 
 ### Development
@@ -259,6 +315,9 @@ Lexmount 浏览器自动化服务的 Node.js SDK。
 - 提供完整类型定义，同时支持 ESM 和 CommonJS
 - 会话管理，支持分页信息
 - 持久化 context 管理
+- 扩展上传、查询、详情、删除
+- 会话下载的查询、获取、归档、清理
+- 支持通过上游代理创建会话
 - 结构化 SDK 异常
 - 可配置 SDK 日志
 - 基于 TSDoc + TypeDoc 的自动文档生成能力
@@ -338,6 +397,20 @@ const session = await client.sessions.create({
 });
 ```
 
+结合扩展和上游代理创建会话：
+
+```ts
+const session = await client.sessions.create({
+  extensionIds: ['ext_123'],
+  proxy: {
+    type: 'external',
+    server: 'http://10.3.6.54:28080',
+    username: 'user',
+    password: 'pass',
+  },
+});
+```
+
 分页列出会话：
 
 ```ts
@@ -355,6 +428,15 @@ for (const session of result) {
 await client.sessions.delete({ sessionId: 'session-id' });
 ```
 
+列出并归档会话下载：
+
+```ts
+const downloads = await client.sessions.downloads.list(session.id);
+console.log(downloads.summary.count);
+
+const archive = await client.sessions.downloads.archive(session.id);
+```
+
 ### Contexts
 
 创建并查看 context：
@@ -383,6 +465,30 @@ const contexts = await client.contexts.list({
 await client.contexts.forceRelease('context-id');
 ```
 
+### Extensions
+
+上传扩展压缩包：
+
+```ts
+const extension = await client.extensions.upload('/absolute/path/to/extension.zip', {
+  name: 'demo-extension',
+});
+```
+
+列出并查看扩展详情：
+
+```ts
+const extensions = await client.extensions.list({ limit: 10 });
+const details = await client.extensions.get(extension.id);
+console.log(details.name);
+```
+
+删除已上传扩展：
+
+```ts
+await client.extensions.delete(extension.id);
+```
+
 ### Playwright 示例
 
 ```ts
@@ -469,6 +575,9 @@ npm run docs:html
 - `context-list-get.ts`
 - `context-modes.ts`
 - `context-lock-handling.ts`
+- `extension-basic.ts`
+- `proxy-session.ts`
+- `session-downloads.ts`
 
 运行方式：
 
@@ -477,6 +586,9 @@ cd examples
 npm install
 npm run playwright-basic
 npm run session-management
+npm run extension-basic
+npm run proxy-session
+npm run session-downloads
 ```
 
 ### 开发

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AxiosResponse } from 'axios';
+import { AxiosRequestConfig, AxiosResponse } from 'axios';
 
 /**
  * Supported SDK log levels.
@@ -67,6 +67,27 @@ interface SessionContext {
      */
     mode: ContextAccessMode;
 }
+/**
+ * Upstream proxy configuration for a session.
+ */
+interface SessionProxyConfig {
+    /**
+     * Proxy type. Currently `external` is supported by the API.
+     */
+    type?: 'external' | string;
+    /**
+     * Upstream proxy server URL.
+     */
+    server: string;
+    /**
+     * Optional upstream proxy username.
+     */
+    username?: string;
+    /**
+     * Optional upstream proxy password.
+     */
+    password?: string;
+}
 /**
  * SDK client configuration.
  */
@@ -112,6 +133,14 @@ interface SessionCreateOptions {
      * Optional persistent context configuration.
      */
     context?: SessionContext;
+    /**
+     * Optional uploaded browser extension identifiers to mount.
+     */
+    extensionIds?: string[];
+    /**
+     * Optional upstream proxy configuration.
+     */
+    proxy?: SessionProxyConfig;
 }
 /**
  * Session list options.
@@ -174,6 +203,72 @@ interface ForceReleaseResponse {
     status: string;
     message: string;
 }
+/**
+ * Extension metadata returned by the API.
+ */
+interface ExtensionInfoShape {
+    id: string;
+    name: string;
+    projectId: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Extension upload options.
+ */
+interface ExtensionUploadOptions {
+    /**
+     * Optional display name for the uploaded extension.
+     */
+    name?: string;
+    /**
+     * Override the default project identifier.
+     */
+    projectId?: string;
+}
+/**
+ * Extension list options.
+ */
+interface ExtensionListOptions {
+    /**
+     * Override the default project identifier.
+     */
+    projectId?: string;
+    /**
+     * Maximum number of extensions to return.
+     */
+    limit?: number;
+    /**
+     * Number of extensions to skip.
+     */
+    offset?: number;
+}
+/**
+ * Session download metadata returned by the API.
+ */
+interface SessionDownloadInfoShape {
+    id: string;
+    filename: string;
+    contentType: string | null;
+    size: number;
+    sha256: string | null;
+    status: string;
+    createdAt: string;
+}
+/**
+ * Structured response from session download listing.
+ */
+interface SessionDownloadsListResponseShape {
+    count: number;
+    totalSize: number;
+}
+/**
+ * Structured response from session download deletion.
+ */
+interface SessionDownloadsDeleteResponseShape {
+    status: string;
+    deletedCount: number;
+}
 /**
  * Session pagination metadata.
  */
@@ -250,6 +345,35 @@ declare class ContextsResource {
     private handleError;
 }
 
+/**
+ * Extension resource implementation.
+ */
+
+/**
+ * Extension metadata returned by the API.
+ */
+declare class ExtensionInfo implements ExtensionInfoShape {
+    readonly id: string;
+    readonly name: string;
+    readonly projectId: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    constructor(shape: ExtensionInfoShape);
+}
+/**
+ * Browser extension resource operations.
+ */
+declare class ExtensionsResource {
+    private readonly client;
+    constructor(client: Lexmount);
+    upload(filePath: string, options?: ExtensionUploadOptions): Promise<ExtensionInfo>;
+    list(options?: ExtensionListOptions): Promise<ExtensionInfo[]>;
+    get(extensionId: string, projectId?: string): Promise<ExtensionInfo>;
+    delete(extensionId: string): Promise<void>;
+    private parseInfo;
+    private handleError;
+}
+
 /**
  * Session resource implementation.
  */
@@ -327,6 +451,47 @@ declare class SessionListResponse implements Iterable<SessionInfo> {
     [Symbol.iterator](): Iterator<SessionInfo>;
     at(index: number): SessionInfo | undefined;
 }
+/**
+ * Session download metadata returned by the API.
+ */
+declare class SessionDownloadInfo implements SessionDownloadInfoShape {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string | null;
+    readonly size: number;
+    readonly sha256: string | null;
+    readonly status: string;
+    readonly createdAt: string;
+    constructor(shape: SessionDownloadInfoShape);
+}
+/**
+ * Structured response from `sessions.downloads.list()`.
+ */
+declare class SessionDownloadsListResponse {
+    readonly downloads: SessionDownloadInfo[];
+    readonly summary: SessionDownloadsListResponseShape;
+    constructor(downloads: SessionDownloadInfo[], summary: SessionDownloadsListResponseShape);
+}
+/**
+ * Structured response from `sessions.downloads.delete()`.
+ */
+declare class SessionDownloadsDeleteResponse implements SessionDownloadsDeleteResponseShape {
+    readonly status: string;
+    readonly deletedCount: number;
+    constructor(shape: SessionDownloadsDeleteResponseShape);
+}
+/**
+ * Session download operations.
+ */
+declare class SessionDownloadsResource {
+    private readonly client;
+    constructor(client: Lexmount);
+    list(sessionId: string, projectId?: string): Promise<SessionDownloadsListResponse>;
+    get(sessionId: string, downloadId: string, projectId?: string): Promise<Buffer>;
+    archive(sessionId: string, projectId?: string): Promise<Buffer>;
+    delete(sessionId: string, projectId?: string): Promise<SessionDownloadsDeleteResponse>;
+    private handleError;
+}
 /**
  * Alias kept for parity with the Python SDK.
  */
@@ -336,6 +501,7 @@ type SessionCreateResponse = SessionInfo;
  */
 declare class SessionsResource {
     private readonly client;
+    readonly downloads: SessionDownloadsResource;
     constructor(client: Lexmount);
     /**
      * Create a new browser session.
@@ -355,6 +521,7 @@ declare class SessionsResource {
      * @internal
      */
     _getWebSocketDebuggerUrl(sessionId: string): Promise<string | null>;
+    private normalizeProxy;
     private handleCreateError;
     private handleListError;
     private handleDeleteError;
@@ -388,6 +555,10 @@ declare class Lexmount {
      * Persistent context operations.
      */
     readonly contexts: ContextsResource;
+    /**
+     * Browser extension operations.
+     */
+    readonly extensions: ExtensionsResource;
     private readonly httpClient;
     constructor(config?: LexmountConfig);
     /**
@@ -395,19 +566,19 @@ declare class Lexmount {
      *
      * @internal
      */
-    _post<T = unknown>(url: string, data: Record<string, unknown>): Promise<AxiosResponse<T>>;
+    _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>): Promise<AxiosResponse<T>>;
+    _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: Record<string, unknown>): Promise<AxiosResponse<T>>;
+    _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
     /**
      * Close the client.
      *
@@ -420,6 +591,7 @@ declare class Lexmount {
     toString(): string;
     private request;
     private normalizeRequestError;
+    private getDefaultHeaders;
 }
 
 /**
@@ -489,4 +661,4 @@ declare class TimeoutError extends LexmountError {
  */
 declare const VERSION = "0.2.0";
 
-export { APIError, AuthenticationError, type BrowserMode, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, type ForceReleaseResponse, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionStatus, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };
+export { APIError, AuthenticationError, type BrowserMode, 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 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, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };