lexmount 0.2.7 → 0.5.2

package/dist/index.d.mts

@@ -106,6 +106,12 @@ interface LexmountConfig {
      * Defaults to `https://api.lexmount.cn`.
      */
     baseUrl?: string;
+    /**
+     * Region ID to select from the public endpoint catalog.
+     *
+     * If omitted, the SDK uses the catalog default region when available.
+     */
+    region?: string;
     /**
      * Request timeout in milliseconds.
      *
@@ -117,6 +123,30 @@ interface LexmountConfig {
      */
     logLevel?: LogLevel;
 }
+interface RegionCatalogEntry {
+    region_id: string;
+    display_name?: string;
+    default?: boolean;
+    host: string;
+    tags?: string[];
+    probe_path?: string;
+}
+interface RegionInfo {
+    requestedRegion?: string;
+    selectedRegion?: string;
+    baseUrl: string;
+    endpointBaseUrl?: string;
+    host?: string;
+    resolved: boolean;
+    usingRegion: boolean;
+}
+interface CatalogInfo {
+    baseUrl: string;
+    available: boolean;
+    statusCode?: number;
+    regions: RegionCatalogEntry[];
+    error?: string;
+}
 /**
  * Session creation options.
  */
@@ -141,6 +171,28 @@ interface SessionCreateOptions {
      * Optional upstream proxy configuration.
      */
     proxy?: SessionProxyConfig;
+    /**
+     * Forward weak_lock to the API when creating sessions with read-write contexts.
+     */
+    weakLock?: boolean;
+    /**
+     * Use the async create API (`POST /instance/v2`) and poll until active.
+     *
+     * Defaults to true. Set to false to use the legacy synchronous `POST /instance`.
+     */
+    asyncCreate?: boolean;
+    /**
+     * Delay between async create status polls in milliseconds.
+     *
+     * Defaults to 1000.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum time to wait for async create activation in milliseconds.
+     *
+     * Defaults to 600000.
+     */
+    pollTimeoutMs?: number;
 }
 /**
  * Session list options.
@@ -536,6 +588,7 @@ declare class SessionsResource {
      * Create a new browser session.
      */
     create(options?: SessionCreateOptions): Promise<SessionCreateResponse>;
+    private createAsync;
     /**
      * Fetch one session by id.
      *
@@ -592,6 +645,12 @@ declare class Lexmount {
      * API base URL.
      */
     readonly baseUrl: string;
+    readonly region?: string;
+    selectedRegion?: string;
+    private endpointBaseUrl?;
+    private selectedHost?;
+    private regionResolutionAttempted;
+    private regionResolutionPromise?;
     /**
      * Session operations.
      */
@@ -624,6 +683,8 @@ declare class Lexmount {
      * @internal
      */
     _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    regionInfo(): Promise<RegionInfo>;
+    catalogInfo(): Promise<CatalogInfo>;
     /**
      * Close the client.
      *
@@ -637,6 +698,12 @@ declare class Lexmount {
     private request;
     private normalizeRequestError;
     private getDefaultHeaders;
+    private ensureRegionResolved;
+    private resolveRegion;
+    private selectCatalogRegion;
+    private probeRegionHost;
+    private isAllowedCatalogHost;
+    private rewriteUrl;
 }
 
 /**
@@ -704,6 +771,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.2.5";
+declare const VERSION = "0.5.2";
 
-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 };
+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 };

package/dist/index.d.ts

@@ -106,6 +106,12 @@ interface LexmountConfig {
      * Defaults to `https://api.lexmount.cn`.
      */
     baseUrl?: string;
+    /**
+     * Region ID to select from the public endpoint catalog.
+     *
+     * If omitted, the SDK uses the catalog default region when available.
+     */
+    region?: string;
     /**
      * Request timeout in milliseconds.
      *
@@ -117,6 +123,30 @@ interface LexmountConfig {
      */
     logLevel?: LogLevel;
 }
+interface RegionCatalogEntry {
+    region_id: string;
+    display_name?: string;
+    default?: boolean;
+    host: string;
+    tags?: string[];
+    probe_path?: string;
+}
+interface RegionInfo {
+    requestedRegion?: string;
+    selectedRegion?: string;
+    baseUrl: string;
+    endpointBaseUrl?: string;
+    host?: string;
+    resolved: boolean;
+    usingRegion: boolean;
+}
+interface CatalogInfo {
+    baseUrl: string;
+    available: boolean;
+    statusCode?: number;
+    regions: RegionCatalogEntry[];
+    error?: string;
+}
 /**
  * Session creation options.
  */
@@ -141,6 +171,28 @@ interface SessionCreateOptions {
      * Optional upstream proxy configuration.
      */
     proxy?: SessionProxyConfig;
+    /**
+     * Forward weak_lock to the API when creating sessions with read-write contexts.
+     */
+    weakLock?: boolean;
+    /**
+     * Use the async create API (`POST /instance/v2`) and poll until active.
+     *
+     * Defaults to true. Set to false to use the legacy synchronous `POST /instance`.
+     */
+    asyncCreate?: boolean;
+    /**
+     * Delay between async create status polls in milliseconds.
+     *
+     * Defaults to 1000.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum time to wait for async create activation in milliseconds.
+     *
+     * Defaults to 600000.
+     */
+    pollTimeoutMs?: number;
 }
 /**
  * Session list options.
@@ -536,6 +588,7 @@ declare class SessionsResource {
      * Create a new browser session.
      */
     create(options?: SessionCreateOptions): Promise<SessionCreateResponse>;
+    private createAsync;
     /**
      * Fetch one session by id.
      *
@@ -592,6 +645,12 @@ declare class Lexmount {
      * API base URL.
      */
     readonly baseUrl: string;
+    readonly region?: string;
+    selectedRegion?: string;
+    private endpointBaseUrl?;
+    private selectedHost?;
+    private regionResolutionAttempted;
+    private regionResolutionPromise?;
     /**
      * Session operations.
      */
@@ -624,6 +683,8 @@ declare class Lexmount {
      * @internal
      */
     _delete<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    regionInfo(): Promise<RegionInfo>;
+    catalogInfo(): Promise<CatalogInfo>;
     /**
      * Close the client.
      *
@@ -637,6 +698,12 @@ declare class Lexmount {
     private request;
     private normalizeRequestError;
     private getDefaultHeaders;
+    private ensureRegionResolved;
+    private resolveRegion;
+    private selectCatalogRegion;
+    private probeRegionHost;
+    private isAllowedCatalogHost;
+    private rewriteUrl;
 }
 
 /**
@@ -704,6 +771,6 @@ declare class TimeoutError extends LexmountError {
 /**
  * Lexmount Node.js SDK.
  */
-declare const VERSION = "0.2.5";
+declare const VERSION = "0.5.2";
 
-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 };
+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 };

package/dist/index.js

@@ -620,6 +620,11 @@ function normalizeContextMode(mode) {
   }
   return "read_only";
 }
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 var PaginationInfo = class {
   constructor(shape) {
     this.currentPage = shape.currentPage;
@@ -851,7 +856,6 @@ var SessionsResource = class {
    * Create a new browser session.
    */
   async create(options = {}) {
-    const url = `${this.client.baseUrl}/instance`;
     const payload = {
       api_key: this.client.apiKey,
       project_id: options.projectId ?? this.client.projectId,
@@ -875,6 +879,13 @@ var SessionsResource = class {
     if (options.proxy) {
       payload.proxy = this.normalizeProxy(options.proxy);
     }
+    if (options.weakLock) {
+      payload.weak_lock = true;
+    }
+    if (options.asyncCreate !== false) {
+      return this.createAsync(payload, options);
+    }
+    const url = `${this.client.baseUrl}/instance`;
     const response = await this.client._post(url, payload);
     if (response.status >= 400) {
       this.handleCreateError(response);
@@ -905,6 +916,59 @@ var SessionsResource = class {
       client: this.client
     });
   }
+  async createAsync(payload, options) {
+    const response = await this.client._post(`${this.client.baseUrl}/instance/v2`, payload);
+    if (response.status >= 400) {
+      this.handleCreateError(response);
+    }
+    const result = asRecord3(response.data);
+    const sessionId = getString3(result.session_id);
+    if (!sessionId) {
+      throw new APIError("Failed to create session: session_id missing from response", {
+        statusCode: response.status,
+        response: response.data
+      });
+    }
+    const projectId = options.projectId ?? this.client.projectId;
+    const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+    const pollTimeoutMs = options.pollTimeoutMs ?? 6e5;
+    const deadline = Date.now() + pollTimeoutMs;
+    while (Date.now() < deadline) {
+      const info = await this.get(sessionId, projectId);
+      if (info.status === "active") {
+        const wsUrl = await this._getWebSocketDebuggerUrl(sessionId);
+        getLogger().info(`Session created successfully (async): id=${sessionId}`);
+        return new SessionInfo({
+          id: sessionId,
+          status: "active",
+          apiKey: this.client.apiKey,
+          projectId,
+          browserType: info.browserType || (options.browserMode ?? "normal"),
+          createdAt: info.createdAt,
+          inspectUrl: info.inspectUrl,
+          containerId: info.containerId,
+          ws: wsUrl ?? info.ws,
+          client: this.client
+        });
+      }
+      if (info.status === "create_failed") {
+        throw new APIError("Session creation failed", {
+          statusCode: 500,
+          response: { session_id: sessionId, status: info.status }
+        });
+      }
+      if (info.status === "closed") {
+        throw new APIError("Session closed before activation", {
+          statusCode: 500,
+          response: { session_id: sessionId, status: info.status }
+        });
+      }
+      await delay(pollIntervalMs);
+    }
+    throw new TimeoutError(
+      `Timed out waiting for session ${sessionId} to become active after ${pollTimeoutMs}ms`
+    );
+  }
   /**
    * Fetch one session by id.
    *
@@ -1159,6 +1223,7 @@ var SessionsResource = class {
 dotenv.config();
 var Lexmount = class {
   constructor(config2 = {}) {
+    this.regionResolutionAttempted = false;
     this.apiKey = config2.apiKey ?? process.env.LEXMOUNT_API_KEY ?? "";
     if (!this.apiKey) {
       throw new ValidationError(
@@ -1172,6 +1237,7 @@ var Lexmount = class {
       );
     }
     this.baseUrl = (config2.baseUrl ?? process.env.LEXMOUNT_BASE_URL ?? "https://api.lexmount.cn").replace(/\/$/, "");
+    this.region = config2.region;
     if (config2.logLevel) {
       setLogLevel(config2.logLevel);
     }
@@ -1189,6 +1255,7 @@ var Lexmount = class {
    * @internal
    */
   async _post(url, data, config2 = {}) {
+    await this.ensureRegionResolved();
     return this.request("POST", url, { ...config2, data });
   }
   /**
@@ -1197,6 +1264,7 @@ var Lexmount = class {
    * @internal
    */
   async _get(url, params, config2 = {}) {
+    await this.ensureRegionResolved();
     return this.request("GET", url, { ...config2, params });
   }
   /**
@@ -1205,8 +1273,51 @@ var Lexmount = class {
    * @internal
    */
   async _delete(url, data, config2 = {}) {
+    await this.ensureRegionResolved();
     return this.request("DELETE", url, { ...config2, data });
   }
+  async regionInfo() {
+    await this.ensureRegionResolved();
+    return {
+      requestedRegion: this.region,
+      selectedRegion: this.selectedRegion,
+      baseUrl: this.baseUrl,
+      endpointBaseUrl: this.endpointBaseUrl,
+      host: this.selectedHost,
+      resolved: this.regionResolutionAttempted,
+      usingRegion: this.selectedRegion !== void 0
+    };
+  }
+  async catalogInfo() {
+    try {
+      const response = await this.httpClient.get(
+        `${this.baseUrl}/v1/regions/catalog`
+      );
+      if (response.status !== 200) {
+        return {
+          baseUrl: this.baseUrl,
+          available: false,
+          statusCode: response.status,
+          regions: []
+        };
+      }
+      const regions = Array.isArray(response.data?.regions) ? response.data.regions : [];
+      return {
+        baseUrl: this.baseUrl,
+        available: Array.isArray(response.data?.regions),
+        statusCode: response.status,
+        regions,
+        error: Array.isArray(response.data?.regions) ? void 0 : "invalid catalog regions"
+      };
+    } catch (error) {
+      return {
+        baseUrl: this.baseUrl,
+        available: false,
+        regions: [],
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   /**
    * Close the client.
    *
@@ -1224,7 +1335,8 @@ var Lexmount = class {
   async request(method, url, config2) {
     const logger2 = getLogger();
     const startTime = Date.now();
-    logger2.debug(`${method} request to ${url}`);
+    const requestUrl = this.rewriteUrl(url);
+    logger2.debug(`${method} request to ${requestUrl}`);
     try {
       const headers = {
         api_key: this.apiKey,
@@ -1234,12 +1346,14 @@ var Lexmount = class {
       };
       const response = await this.httpClient.request({
         method,
-        url,
+        url: requestUrl,
         ...config2,
         headers
       });
       const elapsed = Date.now() - startTime;
-      logger2.debug(`${method} response: status=${response.status}, duration=${elapsed.toFixed(2)}ms`);
+      logger2.debug(
+        `${method} response: status=${response.status}, duration=${elapsed.toFixed(2)}ms`
+      );
       return response;
     } catch (error) {
       const elapsed = Date.now() - startTime;
@@ -1278,10 +1392,101 @@ var Lexmount = class {
       "Content-Type": "application/json"
     };
   }
+  async ensureRegionResolved() {
+    if (this.regionResolutionAttempted) {
+      return;
+    }
+    if (!this.regionResolutionPromise) {
+      this.regionResolutionPromise = this.resolveRegion().finally(() => {
+        this.regionResolutionAttempted = true;
+        this.regionResolutionPromise = void 0;
+      });
+    }
+    await this.regionResolutionPromise;
+  }
+  async resolveRegion() {
+    const logger2 = getLogger();
+    try {
+      const response = await this.httpClient.get(
+        `${this.baseUrl}/v1/regions/catalog`
+      );
+      if (response.status !== 200 || !Array.isArray(response.data?.regions)) {
+        logger2.debug(
+          `Region catalog unavailable, falling back to baseUrl: status=${response.status}`
+        );
+        return;
+      }
+      const selected = this.selectCatalogRegion(response.data.regions);
+      if (!selected) {
+        if (this.region) {
+          logger2.warn(`Requested region not found in catalog: ${this.region}`);
+        } else {
+          logger2.debug("No default catalog region, falling back to baseUrl");
+        }
+        return;
+      }
+      const endpointBaseUrl = await this.probeRegionHost(selected);
+      if (!endpointBaseUrl) {
+        logger2.debug("Region probe failed, falling back to baseUrl");
+        return;
+      }
+      this.selectedRegion = selected.region_id;
+      this.selectedHost = selected.host;
+      this.endpointBaseUrl = endpointBaseUrl;
+    } catch (error) {
+      logger2.debug("Region resolution failed, falling back to baseUrl:", error);
+    }
+  }
+  selectCatalogRegion(regions) {
+    if (this.region) {
+      return regions.find((region) => region.region_id === this.region);
+    }
+    const defaultRegions = regions.filter((region) => region.default === true);
+    return defaultRegions.length === 1 ? defaultRegions[0] : void 0;
+  }
+  async probeRegionHost(region) {
+    const logger2 = getLogger();
+    const host = String(region.host || "").trim();
+    if (!host) {
+      return void 0;
+    }
+    if (!this.isAllowedCatalogHost(host)) {
+      logger2.warn(`Ignoring invalid region catalog host: ${host}`);
+      return void 0;
+    }
+    const endpointBaseUrl = `https://${host}`;
+    const probePath = String(region.probe_path || "/v1/region/probe").replace(/^(?!\/)/, "/");
+    try {
+      const response = await this.httpClient.get(`${endpointBaseUrl}${probePath}`);
+      return response.status === 200 ? endpointBaseUrl : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  isAllowedCatalogHost(host) {
+    let parsed;
+    try {
+      parsed = new URL(`https://${host}`);
+    } catch {
+      return false;
+    }
+    if (parsed.username || parsed.password || parsed.port || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+      return false;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    const allowedDomains = ["lexmount.cn", "lexmount.com", "lexmount.net"];
+    return allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+  }
+  rewriteUrl(url) {
+    if (!this.endpointBaseUrl || !url.startsWith(this.baseUrl)) {
+      return url;
+    }
+    return `${this.endpointBaseUrl}${url.slice(this.baseUrl.length)}`;
+  }
 };
 
 // src/index.ts
-var VERSION = "0.2.5";
+var VERSION = "0.5.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,