lexmount 0.2.5 → 0.2.7

package/README.md

@@ -149,6 +149,14 @@ const details = await client.contexts.get(context.id);
 console.log(details.status);
 ```
 
+Fork an available context into a new context:
+
+```ts
+const source = await client.contexts.create();
+const forked = await client.contexts.fork(source.id);
+console.log(forked.id);
+```
+
 List contexts:
 
 ```ts
@@ -164,6 +172,13 @@ Force release a stuck lock:
 await client.contexts.forceRelease('context-id');
 ```
 
+Current `context fork` limitations:
+
+- Only supports offline snapshot copy from an `available` context
+- Does not support hot fork from a `locked` context
+- Does not support copy-on-write
+- Does not support parent/child lineage tracking
+
 ### Extensions
 
 Upload an extension archive:
@@ -271,6 +286,7 @@ Example scripts live in [examples](./examples):
 - `playwright-basic.ts`
 - `session-management.ts`
 - `context-basic.ts`
+- `context-fork.ts`
 - `context-list-get.ts`
 - `context-modes.ts`
 - `context-lock-handling.ts`
@@ -283,6 +299,7 @@ Run them with:
 ```bash
 cd examples
 npm install
+npm run context-fork
 npm run playwright-basic
 npm run session-management
 npm run extension-basic
@@ -450,6 +467,14 @@ const details = await client.contexts.get(context.id);
 console.log(details.status);
 ```
 
+基于一个 `available` context 创建新的 fork：
+
+```ts
+const source = await client.contexts.create();
+const forked = await client.contexts.fork(source.id);
+console.log(forked.id);
+```
+
 列出 context：
 
 ```ts
@@ -465,6 +490,13 @@ const contexts = await client.contexts.list({
 await client.contexts.forceRelease('context-id');
 ```
 
+当前 `context fork` 第一版限制：
+
+- 只支持对 `available context` 做离线快照复制
+- 不支持 `locked` context 的热 fork
+- 不支持 copy-on-write
+- 不支持父子链追踪
+
 ### Extensions
 
 上传扩展压缩包：
@@ -572,6 +604,7 @@ npm run docs:html
 - `playwright-basic.ts`
 - `session-management.ts`
 - `context-basic.ts`
+- `context-fork.ts`
 - `context-list-get.ts`
 - `context-modes.ts`
 - `context-lock-handling.ts`
@@ -584,6 +617,7 @@ npm run docs:html
 ```bash
 cd examples
 npm install
+npm run context-fork
 npm run playwright-basic
 npm run session-management
 npm run extension-basic

package/dist/index.d.mts

@@ -269,6 +269,19 @@ interface SessionDownloadsDeleteResponseShape {
     status: string;
     deletedCount: number;
 }
+/**
+ * Session target metadata returned by `/json`.
+ */
+interface SessionTargetInfoShape {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    description: string;
+    inspectUrl: string | null;
+    webSocketDebuggerUrl: string | null;
+    webSocketDebuggerUrlTransformed: string | null;
+}
 /**
  * Session pagination metadata.
  */
@@ -334,6 +347,10 @@ declare class ContextsResource {
      * Fetch a single context.
      */
     get(contextId: string): Promise<ContextInfo>;
+    /**
+     * Fork an existing persistent context into a new context.
+     */
+    fork(contextId: string): Promise<ContextInfo>;
     /**
      * Delete a persistent context.
      */
@@ -478,6 +495,20 @@ declare class SessionDownloadsDeleteResponse implements SessionDownloadsDeleteRe
     readonly deletedCount: number;
     constructor(shape: SessionDownloadsDeleteResponseShape);
 }
+/**
+ * Session target metadata returned by `/json`.
+ */
+declare class SessionTargetInfo implements SessionTargetInfoShape {
+    readonly id: string;
+    readonly title: string;
+    readonly type: string;
+    readonly url: string;
+    readonly description: string;
+    readonly inspectUrl: string | null;
+    readonly webSocketDebuggerUrl: string | null;
+    readonly webSocketDebuggerUrlTransformed: string | null;
+    constructor(shape: SessionTargetInfoShape);
+}
 /**
  * Session download operations.
  */
@@ -520,6 +551,10 @@ declare class SessionsResource {
      * Delete a browser session.
      */
     delete(options: SessionDeleteOptions): Promise<void>;
+    /**
+     * List target/page metadata for a session via `/json`.
+     */
+    listTargets(sessionId: string): Promise<SessionTargetInfo[]>;
     /**
      * Fetch the debugger WebSocket URL for a session.
      *
@@ -530,8 +565,10 @@ declare class SessionsResource {
     private handleCreateError;
     private handleGetError;
     private handleListError;
+    private handleListTargetsError;
     private handleDeleteError;
     private mapSessionInfo;
+    private mapSessionTarget;
     private _getCreatedSession;
 }
 
@@ -669,4 +706,4 @@ declare class TimeoutError extends LexmountError {
  */
 declare const VERSION = "0.2.5";
 
-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 };
+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, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };

package/dist/index.d.ts

@@ -269,6 +269,19 @@ interface SessionDownloadsDeleteResponseShape {
     status: string;
     deletedCount: number;
 }
+/**
+ * Session target metadata returned by `/json`.
+ */
+interface SessionTargetInfoShape {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    description: string;
+    inspectUrl: string | null;
+    webSocketDebuggerUrl: string | null;
+    webSocketDebuggerUrlTransformed: string | null;
+}
 /**
  * Session pagination metadata.
  */
@@ -334,6 +347,10 @@ declare class ContextsResource {
      * Fetch a single context.
      */
     get(contextId: string): Promise<ContextInfo>;
+    /**
+     * Fork an existing persistent context into a new context.
+     */
+    fork(contextId: string): Promise<ContextInfo>;
     /**
      * Delete a persistent context.
      */
@@ -478,6 +495,20 @@ declare class SessionDownloadsDeleteResponse implements SessionDownloadsDeleteRe
     readonly deletedCount: number;
     constructor(shape: SessionDownloadsDeleteResponseShape);
 }
+/**
+ * Session target metadata returned by `/json`.
+ */
+declare class SessionTargetInfo implements SessionTargetInfoShape {
+    readonly id: string;
+    readonly title: string;
+    readonly type: string;
+    readonly url: string;
+    readonly description: string;
+    readonly inspectUrl: string | null;
+    readonly webSocketDebuggerUrl: string | null;
+    readonly webSocketDebuggerUrlTransformed: string | null;
+    constructor(shape: SessionTargetInfoShape);
+}
 /**
  * Session download operations.
  */
@@ -520,6 +551,10 @@ declare class SessionsResource {
      * Delete a browser session.
      */
     delete(options: SessionDeleteOptions): Promise<void>;
+    /**
+     * List target/page metadata for a session via `/json`.
+     */
+    listTargets(sessionId: string): Promise<SessionTargetInfo[]>;
     /**
      * Fetch the debugger WebSocket URL for a session.
      *
@@ -530,8 +565,10 @@ declare class SessionsResource {
     private handleCreateError;
     private handleGetError;
     private handleListError;
+    private handleListTargetsError;
     private handleDeleteError;
     private mapSessionInfo;
+    private mapSessionTarget;
     private _getCreatedSession;
 }
 
@@ -669,4 +706,4 @@ declare class TimeoutError extends LexmountError {
  */
 declare const VERSION = "0.2.5";
 
-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 };
+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, SessionTargetInfo, type SessionTargetInfoShape, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };

package/dist/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   SessionInfo: () => SessionInfo,
   SessionListResponse: () => SessionListResponse,
   SessionNotFoundError: () => SessionNotFoundError,
+  SessionTargetInfo: () => SessionTargetInfo,
   SessionsResource: () => SessionsResource,
   TimeoutError: () => TimeoutError,
   VERSION: () => VERSION,
@@ -360,6 +361,37 @@ var ContextsResource = class {
     getLogger().info(`Retrieved context '${contextInfo.id}' (status: ${contextInfo.status})`);
     return contextInfo;
   }
+  /**
+   * Fork an existing persistent context into a new context.
+   */
+  async fork(contextId) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}/fork`;
+    const payload = {
+      api_key: this.client.apiKey,
+      project_id: this.client.projectId
+    };
+    const response = await this.client._post(url, payload);
+    if (response.status >= 400) {
+      this.handleError(response, "fork", contextId);
+    }
+    const result = asRecord(response.data);
+    const forkedContextId = getString(result.context_id);
+    if (!forkedContextId) {
+      throw new APIError("Failed to fork context: context_id missing from response", {
+        statusCode: response.status,
+        response: response.data
+      });
+    }
+    const contextInfo = new ContextInfo({
+      id: forkedContextId,
+      status: normalizeContextStatus(result.locked),
+      metadata: result.metadata ?? {},
+      createdAt: parseTimestamp(result.created_at),
+      updatedAt: parseTimestamp(result.updated_at)
+    });
+    getLogger().info(`Successfully forked context '${contextId}' -> '${contextInfo.id}'`);
+    return contextInfo;
+  }
   /**
    * Delete a persistent context.
    */
@@ -406,7 +438,7 @@ var ContextsResource = class {
       const suffix = contextId ? `: ${contextId}` : "";
       throw new ContextNotFoundError(`Context not found${suffix}`);
     }
-    if (response.status === 409 && errorCode === "context_locked") {
+    if (response.status === 409 && (errorCode === "context_locked" || errorCode === "CONTEXT_FORK_SOURCE_LOCKED")) {
       throw new ContextLockedError(errorMessage, {
         activeSessionId: getString(metadata.activeSessionId),
         retryAfter: typeof metadata.retryAfter === "number" ? metadata.retryAfter : void 0
@@ -697,6 +729,18 @@ var SessionDownloadsDeleteResponse = class {
     this.deletedCount = shape.deletedCount;
   }
 };
+var SessionTargetInfo = class {
+  constructor(shape) {
+    this.id = shape.id;
+    this.title = shape.title;
+    this.type = shape.type;
+    this.url = shape.url;
+    this.description = shape.description;
+    this.inspectUrl = shape.inspectUrl;
+    this.webSocketDebuggerUrl = shape.webSocketDebuggerUrl;
+    this.webSocketDebuggerUrlTransformed = shape.webSocketDebuggerUrlTransformed;
+  }
+};
 var SessionDownloadsResource = class {
   constructor(client) {
     this.client = client;
@@ -927,6 +971,19 @@ var SessionsResource = class {
     }
     getLogger().info(`Session deleted successfully: ${options.sessionId}`);
   }
+  /**
+   * List target/page metadata for a session via `/json`.
+   */
+  async listTargets(sessionId) {
+    const response = await this.client._get(`${this.client.baseUrl}/json`, {
+      session_id: sessionId
+    });
+    if (response.status >= 400) {
+      this.handleListTargetsError(response, sessionId);
+    }
+    const result = Array.isArray(response.data) ? response.data : [];
+    return result.map((item) => this.mapSessionTarget(asRecord3(item)));
+  }
   /**
    * Fetch the debugger WebSocket URL for a session.
    *
@@ -1022,6 +1079,24 @@ var SessionsResource = class {
       response: response.data
     });
   }
+  handleListTargetsError(response, sessionId) {
+    const errorData = asRecord3(response.data);
+    const errorMessage = getString3(errorData.error) ?? getString3(errorData.message) ?? "Unknown error";
+    if (response.status === 401) {
+      throw new AuthenticationError(
+        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
+      );
+    }
+    if (response.status === 404) {
+      throw new SessionNotFoundError(
+        `Session not found: ${errorMessage}. Session ID '${sessionId}' may not exist in this project.`
+      );
+    }
+    throw new APIError(`Failed to list session targets: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
   handleDeleteError(response, sessionId) {
     const errorData = asRecord3(response.data);
     const errorMessage = getString3(errorData.error) ?? getString3(errorData.message) ?? "Unknown error";
@@ -1055,6 +1130,18 @@ var SessionsResource = class {
       client: this.client
     });
   }
+  mapSessionTarget(raw) {
+    return new SessionTargetInfo({
+      id: getString3(raw.id) ?? "",
+      title: getString3(raw.title) ?? "",
+      type: getString3(raw.type) ?? "",
+      url: getString3(raw.url) ?? "",
+      description: getString3(raw.description) ?? "",
+      inspectUrl: getString3(raw.inspectUrl) ?? getString3(raw.inspect_url) ?? null,
+      webSocketDebuggerUrl: getString3(raw.webSocketDebuggerUrl) ?? getString3(raw.web_socket_debugger_url) ?? null,
+      webSocketDebuggerUrlTransformed: getString3(raw.webSocketDebuggerUrlTransformed) ?? getString3(raw.web_socket_debugger_url_transformed) ?? null
+    });
+  }
   async _getCreatedSession(sessionId, projectId) {
     try {
       return await this.get(sessionId, projectId);
@@ -1218,6 +1305,7 @@ var VERSION = "0.2.5";
   SessionInfo,
   SessionListResponse,
   SessionNotFoundError,
+  SessionTargetInfo,
   SessionsResource,
   TimeoutError,
   VERSION,