lexmount 0.2.4 → 0.2.6

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

@@ -334,6 +334,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.
      */
@@ -505,6 +509,13 @@ declare class SessionsResource {
      * Create a new browser session.
      */
     create(options?: SessionCreateOptions): Promise<SessionCreateResponse>;
+    /**
+     * Fetch one session by id.
+     *
+     * The upstream API uses POST /instance/session for this lookup, so this SDK method
+     * intentionally uses POST even though the operation is read-only.
+     */
+    get(sessionId: string, projectId?: string): Promise<SessionInfo>;
     /**
      * List sessions for the current project.
      */
@@ -521,8 +532,11 @@ declare class SessionsResource {
     _getWebSocketDebuggerUrl(sessionId: string): Promise<string | null>;
     private normalizeProxy;
     private handleCreateError;
+    private handleGetError;
     private handleListError;
     private handleDeleteError;
+    private mapSessionInfo;
+    private _getCreatedSession;
 }
 
 /**
@@ -657,6 +671,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.2.4";
+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 };

package/dist/index.d.ts

@@ -334,6 +334,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.
      */
@@ -505,6 +509,13 @@ declare class SessionsResource {
      * Create a new browser session.
      */
     create(options?: SessionCreateOptions): Promise<SessionCreateResponse>;
+    /**
+     * Fetch one session by id.
+     *
+     * The upstream API uses POST /instance/session for this lookup, so this SDK method
+     * intentionally uses POST even though the operation is read-only.
+     */
+    get(sessionId: string, projectId?: string): Promise<SessionInfo>;
     /**
      * List sessions for the current project.
      */
@@ -521,8 +532,11 @@ declare class SessionsResource {
     _getWebSocketDebuggerUrl(sessionId: string): Promise<string | null>;
     private normalizeProxy;
     private handleCreateError;
+    private handleGetError;
     private handleListError;
     private handleDeleteError;
+    private mapSessionInfo;
+    private _getCreatedSession;
 }
 
 /**
@@ -657,6 +671,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.2.4";
+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 };

package/dist/index.js

@@ -360,6 +360,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 +437,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
@@ -844,22 +875,40 @@ var SessionsResource = class {
       });
     }
     const containerId = getString3(result.container_id) ?? null;
-    const wsUrl = await this._getWebSocketDebuggerUrl(sessionId);
     const projectId = options.projectId ?? this.client.projectId;
+    const createdSession = await this._getCreatedSession(sessionId, projectId);
+    const wsUrl = await this._getWebSocketDebuggerUrl(sessionId);
     getLogger().info(`Session created successfully: id=${sessionId}, container_id=${containerId}`);
     return new SessionInfo({
       id: sessionId,
-      status: "active",
+      status: createdSession?.status ?? "active",
       apiKey: this.client.apiKey,
       projectId,
-      browserType: options.browserMode ?? "normal",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      inspectUrl: `${this.client.baseUrl}/inspect?session_id=${sessionId}`,
-      containerId,
-      ws: wsUrl,
+      browserType: createdSession?.browserType ?? (options.browserMode ?? "normal"),
+      createdAt: createdSession?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      inspectUrl: createdSession?.inspectUrl ?? `${this.client.baseUrl}/inspect?session_id=${sessionId}`,
+      containerId: createdSession?.containerId ?? containerId,
+      ws: wsUrl ?? createdSession?.ws ?? null,
       client: this.client
     });
   }
+  /**
+   * Fetch one session by id.
+   *
+   * The upstream API uses POST /instance/session for this lookup, so this SDK method
+   * intentionally uses POST even though the operation is read-only.
+   */
+  async get(sessionId, projectId) {
+    const response = await this.client._post(`${this.client.baseUrl}/instance/session`, {
+      api_key: this.client.apiKey,
+      project_id: projectId ?? this.client.projectId,
+      session_id: sessionId
+    });
+    if (response.status >= 400) {
+      this.handleGetError(response, sessionId);
+    }
+    return this.mapSessionInfo(asRecord3(response.data), projectId);
+  }
   /**
    * List sessions for the current project.
    */
@@ -879,22 +928,7 @@ var SessionsResource = class {
     const result = asRecord3(response.data);
     const sessionsData = Array.isArray(result.sessions) ? result.sessions : [];
     const paginationData = asRecord3(result.pagination);
-    const sessions = sessionsData.map((item) => {
-      const session = asRecord3(item);
-      const sessionId = getString3(session.id) ?? "";
-      return new SessionInfo({
-        id: sessionId,
-        status: getString3(session.status) ?? "active",
-        apiKey: getString3(session.api_key) ?? this.client.apiKey,
-        projectId: getString3(session.project_id) ?? (options.projectId ?? this.client.projectId),
-        browserType: getString3(session.browser_type) ?? "normal",
-        createdAt: getString3(session.created_at) ?? "",
-        inspectUrl: getString3(session.inspect_url) ?? `${this.client.baseUrl}/inspect?session_id=${sessionId}`,
-        containerId: getString3(session.container_id) ?? null,
-        ws: getString3(session.ws) ?? null,
-        client: this.client
-      });
-    });
+    const sessions = sessionsData.map((item) => this.mapSessionInfo(asRecord3(item), options.projectId));
     const pagination = new PaginationInfo({
       currentPage: getNumber(paginationData.currentPage) ?? 1,
       pageSize: getNumber(paginationData.pageSize) ?? sessions.length,
@@ -988,6 +1022,24 @@ var SessionsResource = class {
       response: response.data
     });
   }
+  handleGetError(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 get session: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
   handleListError(response) {
     const errorData = asRecord3(response.data);
     const errorMessage = getString3(errorData.error) ?? getString3(errorData.message) ?? "Unknown error";
@@ -1019,6 +1071,32 @@ var SessionsResource = class {
       response: response.data
     });
   }
+  mapSessionInfo(raw, projectId) {
+    const sessionId = getString3(raw.session_id) ?? getString3(raw.id) ?? "";
+    return new SessionInfo({
+      id: sessionId,
+      status: getString3(raw.status) ?? "active",
+      apiKey: getString3(raw.api_key) ?? this.client.apiKey,
+      projectId: getString3(raw.project_id) ?? (projectId ?? this.client.projectId),
+      browserType: getString3(raw.browser_type) ?? getString3(raw.browser_mode) ?? "normal",
+      createdAt: getString3(raw.created_at) ?? "",
+      inspectUrl: getString3(raw.inspect_url) ?? `${this.client.baseUrl}/inspect?session_id=${sessionId}`,
+      containerId: getString3(raw.container_id) ?? null,
+      ws: getString3(raw.ws) ?? null,
+      client: this.client
+    });
+  }
+  async _getCreatedSession(sessionId, projectId) {
+    try {
+      return await this.get(sessionId, projectId);
+    } catch (error) {
+      getLogger().warn(
+        `Failed to fetch created session ${sessionId}; falling back to locally derived session fields:`,
+        error
+      );
+      return null;
+    }
+  }
 };
 
 // src/client.ts
@@ -1147,7 +1225,7 @@ var Lexmount = class {
 };
 
 // src/index.ts
-var VERSION = "0.2.4";
+var VERSION = "0.2.5";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,