lexmount 0.5.3 → 0.5.5

package/dist/index.mjs

@@ -1,7 +1,6 @@
-// src/client.ts
-import { isAxiosError } from "axios";
-import axios from "axios";
-import * as dotenv from "dotenv";
+// src/cdp.ts
+import { EventEmitter } from "events";
+import CDP from "chrome-remote-interface";
 
 // src/errors.ts
 var LexmountError = class extends Error {
@@ -134,1031 +133,1262 @@ function enableLogging(level = "INFO") {
   setLogLevel(level);
 }
 
-// src/contexts.ts
+// src/cdp.ts
+function hasExplicitPort(url) {
+  const authority = url.match(/^[a-z][a-z\d+\-.]*:\/\/([^/?#]+)/i)?.[1] ?? "";
+  const host = authority.includes("@") ? authority.slice(authority.lastIndexOf("@") + 1) : authority;
+  if (host.startsWith("[")) {
+    return /\]:\d+$/.test(host);
+  }
+  return /:\d+$/.test(host);
+}
+function getDefaultPort(url) {
+  const protocol = getProtocol(url);
+  if (protocol === "ws") {
+    return 80;
+  }
+  if (protocol === "wss") {
+    return 443;
+  }
+  return void 0;
+}
+function getProtocol(url) {
+  return url.match(/^([a-z][a-z\d+\-.]*):\/\//i)?.[1]?.toLowerCase();
+}
+var CDPClient = class extends EventEmitter {
+  constructor(session) {
+    super();
+    this.closed = false;
+    const connectUrl = session.connectUrl;
+    if (!connectUrl) {
+      throw new ValidationError(`Session ${session.sessionId} does not include a CDP connect URL`);
+    }
+    this.session = session;
+  }
+  /**
+   * Connect the CDP client to the session.
+   */
+  async connect() {
+    if (this.rawClient && !this.closed) {
+      return this;
+    }
+    this.closed = false;
+    getLogger().debug(`Connecting to session ${this.session.sessionId} over CDP`);
+    const options = {
+      target: this.session.connectUrl,
+      local: true
+    };
+    const defaultPort = getDefaultPort(this.session.connectUrl);
+    if (!hasExplicitPort(this.session.connectUrl) && defaultPort) {
+      options.port = defaultPort;
+    }
+    if (getProtocol(this.session.connectUrl) === "wss") {
+      options.secure = true;
+    }
+    this.rawClient = await CDP(options);
+    this.rawClient.on("event", (message) => {
+      this.emit(message.method, message.params, message.sessionId);
+    });
+    this.rawClient.on("error", (err) => {
+      this.emit("error", err);
+    });
+    this.rawClient.on("disconnect", () => {
+      void this.close().catch((err) => {
+        getLogger().error(`Failed to close CDP client for session ${this.session.sessionId} after disconnect`, err);
+      });
+      this.emit("disconnect");
+    });
+    return this;
+  }
+  /**
+   * Send a raw Chrome DevTools Protocol command.
+   *
+   * Returns `undefined` if called before the client has connected.
+   */
+  async send(method, params, sessionId) {
+    if (this.closed) {
+      throw new ValidationError("Cannot send CDP command after client is closed");
+    }
+    const rawClient = this.rawClient;
+    if (!rawClient) {
+      return void 0;
+    }
+    return rawClient.send(method, params, sessionId);
+  }
+  /**
+   * Close the CDP connection and release internal listeners.
+   */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    if (this.rawClient) {
+      this.rawClient.removeAllListeners("event");
+      this.rawClient.removeAllListeners("disconnect");
+      this.rawClient.removeAllListeners("error");
+      await this.rawClient.close();
+    }
+  }
+};
+async function connectOverCDP(session) {
+  const client = new CDPClient(session);
+  await client.connect();
+  return client;
+}
+
+// src/sessions.ts
 function asRecord(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
 function getString(value) {
   return typeof value === "string" ? value : void 0;
 }
-function parseTimestamp(value) {
-  if (typeof value === "string" && value.length > 0) {
-    return value;
-  }
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return new Date(value).toISOString();
-  }
-  return null;
+function getNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function normalizeContextStatus(value) {
-  if (value === true || value === "locked") {
-    return "locked";
-  }
-  if (value === false || value === "available") {
-    return "available";
+function normalizeContextMode(mode) {
+  if (mode === "readWrite" || mode === "read_write") {
+    return "read_write";
   }
-  return typeof value === "string" ? value : "available";
+  return "read_only";
 }
-var ContextInfo = class {
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+var PaginationInfo = class {
+  constructor(shape) {
+    this.currentPage = shape.currentPage;
+    this.pageSize = shape.pageSize;
+    this.totalCount = shape.totalCount;
+    this.totalPages = shape.totalPages;
+    this.activeCount = shape.activeCount;
+    this.closedCount = shape.closedCount;
+  }
+};
+var SessionInfo = class {
+  /** @internal */
   constructor(options) {
+    this.closed = false;
     this.id = options.id;
+    this.sessionId = options.id;
     this.status = options.status;
-    this.metadata = options.metadata ?? {};
-    this.createdAt = options.createdAt ?? null;
-    this.updatedAt = options.updatedAt ?? null;
+    this.apiKey = options.apiKey;
+    this.projectId = options.projectId;
+    this.regionId = options.regionId ?? null;
+    this.region_id = this.regionId;
+    this.browserType = options.browserType;
+    this.createdAt = options.createdAt;
+    this.inspectUrl = options.inspectUrl;
+    this.containerId = options.containerId;
+    this.ws = options.ws ?? null;
+    this.client = options.client;
+  }
+  /**
+   * Playwright/CDP connection URL.
+   */
+  get connectUrl() {
+    return this.ws ?? "";
   }
+  /**
+   * Parsed session creation time.
+   */
   get createdAtDate() {
-    if (!this.createdAt) {
-      return null;
-    }
     const date = new Date(this.createdAt);
     return Number.isNaN(date.getTime()) ? null : date;
   }
-  get updatedAtDate() {
-    if (!this.updatedAt) {
-      return null;
+  /**
+   * Close the current session.
+   *
+   * This method is idempotent. Errors are logged and swallowed to keep cleanup safe.
+   */
+  async close() {
+    if (this.closed) {
+      getLogger().debug(`Session ${this.sessionId} is already closed.`);
+      return;
+    }
+    if (!this.client) {
+      getLogger().warn(
+        `Cannot close session ${this.sessionId}: client was not provided during session creation.`
+      );
+      return;
+    }
+    try {
+      getLogger().debug(`Closing session ${this.sessionId}`);
+      await this.client.sessions.delete({
+        sessionId: this.sessionId,
+        projectId: this.projectId
+      });
+      this.closed = true;
+      getLogger().info(`Session closed: ${this.sessionId}`);
+    } catch (error) {
+      getLogger().warn(`Failed to close session ${this.sessionId}:`, error);
     }
-    const date = new Date(this.updatedAt);
-    return Number.isNaN(date.getTime()) ? null : date;
-  }
-  isLocked() {
-    return this.status === "locked";
-  }
-  isAvailable() {
-    return this.status === "available";
   }
 };
-var ContextListResponse = class {
-  constructor(data) {
-    this.data = data;
+var SessionListResponse = class {
+  constructor(sessions, pagination) {
+    this.sessions = sessions;
+    this.pagination = pagination;
   }
+  /**
+   * Number of sessions in the current page.
+   */
   get length() {
-    return this.data.length;
+    return this.sessions.length;
   }
   [Symbol.iterator]() {
-    return this.data[Symbol.iterator]();
+    return this.sessions[Symbol.iterator]();
   }
   at(index) {
-    return this.data[index];
+    return this.sessions[index];
   }
 };
-var ContextsResource = class {
+var SessionDownloadInfo = class {
+  constructor(shape) {
+    this.id = shape.id;
+    this.filename = shape.filename;
+    this.contentType = shape.contentType;
+    this.size = shape.size;
+    this.sha256 = shape.sha256;
+    this.status = shape.status;
+    this.createdAt = shape.createdAt;
+  }
+};
+var SessionDownloadsListResponse = class {
+  constructor(downloads, summary) {
+    this.downloads = downloads;
+    this.summary = summary;
+  }
+};
+var SessionDownloadsDeleteResponse = class {
+  constructor(shape) {
+    this.status = shape.status;
+    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;
   }
-  /**
-   * Create a new persistent context.
-   */
-  async create(options = {}) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/create-context`;
-    const payload = {
-      api_key: this.client.apiKey,
-      project_id: this.client.projectId
-    };
-    if (options.metadata) {
-      payload.metadata = options.metadata;
-    }
-    const response = await this.client._post(url, payload);
+  async list(sessionId, projectId) {
+    const response = await this.client._post(
+      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/list`,
+      {
+        api_key: this.client.apiKey,
+        project_id: projectId ?? this.client.projectId
+      }
+    );
     if (response.status >= 400) {
-      this.handleError(response, "create");
+      this.handleError("list session downloads", response, sessionId);
     }
     const result = asRecord(response.data);
-    const contextId = getString(result.context_id);
-    if (!contextId) {
-      throw new APIError("Failed to create context: context_id missing from response", {
-        statusCode: response.status,
-        response: response.data
+    const items = Array.isArray(result.downloads) ? result.downloads : [];
+    const downloads = items.map((item) => {
+      const download = asRecord(item);
+      return new SessionDownloadInfo({
+        id: getString(download.id) ?? "",
+        filename: getString(download.filename) ?? "",
+        contentType: getString(download.content_type) ?? null,
+        size: getNumber(download.size) ?? 0,
+        sha256: getString(download.sha256) ?? null,
+        status: getString(download.status) ?? "available",
+        createdAt: getString(download.created_at) ?? ""
       });
-    }
-    const context = new ContextInfo({
-      id: contextId,
-      status: normalizeContextStatus(result.locked),
-      metadata: result.metadata ?? options.metadata ?? {},
-      createdAt: parseTimestamp(result.created_at)
     });
-    getLogger().info(`Successfully created context '${context.id}'`);
-    return context;
+    const summary = asRecord(result.summary);
+    return new SessionDownloadsListResponse(downloads, {
+      count: getNumber(summary.count) ?? downloads.length,
+      totalSize: getNumber(summary.total_size) ?? 0
+    });
   }
-  /**
-   * List contexts in the current project.
-   */
-  async list(options = {}) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/list-contexts`;
-    const payload = {
-      api_key: this.client.apiKey,
-      project_id: this.client.projectId,
-      limit: options.limit ?? 20
-    };
-    if (options.status) {
-      payload.status = options.status;
-    }
-    const response = await this.client._post(url, payload);
+  async get(sessionId, downloadId, projectId) {
+    const response = await this.client._get(
+      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/${downloadId}`,
+      {
+        api_key: this.client.apiKey,
+        project_id: projectId ?? this.client.projectId
+      },
+      {
+        responseType: "arraybuffer"
+      }
+    );
     if (response.status >= 400) {
-      this.handleError(response, "list");
+      this.handleError("fetch session download", response, sessionId);
     }
-    const result = asRecord(response.data);
-    const contexts = Array.isArray(result.contexts) ? result.contexts.map((item) => {
-      const context = asRecord(item);
-      return new ContextInfo({
-        id: getString(context.context_id) ?? "",
-        status: normalizeContextStatus(context.locked),
-        createdAt: parseTimestamp(context.created_at),
-        updatedAt: parseTimestamp(context.updated_at),
-        metadata: context.metadata ?? {}
-      });
-    }) : [];
-    getLogger().info(`Retrieved ${contexts.length} contexts`);
-    return new ContextListResponse(contexts);
+    return Buffer.from(response.data);
   }
-  /**
-   * Fetch a single context.
-   */
-  async get(contextId) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}`;
-    const payload = {
-      api_key: this.client.apiKey,
-      project_id: this.client.projectId
-    };
-    const response = await this.client._post(url, payload);
+  async archive(sessionId, projectId) {
+    const response = await this.client._get(
+      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/archive`,
+      {
+        api_key: this.client.apiKey,
+        project_id: projectId ?? this.client.projectId
+      },
+      {
+        responseType: "arraybuffer"
+      }
+    );
     if (response.status >= 400) {
-      this.handleError(response, "get", contextId);
+      this.handleError("archive session downloads", response, sessionId);
+    }
+    return Buffer.from(response.data);
+  }
+  async delete(sessionId, projectId) {
+    const response = await this.client._delete(
+      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads`,
+      {
+        api_key: this.client.apiKey,
+        project_id: projectId ?? this.client.projectId
+      }
+    );
+    if (response.status >= 400) {
+      this.handleError("delete session downloads", response, sessionId);
     }
     const result = asRecord(response.data);
-    const context = asRecord(result.context);
-    const contextInfo = new ContextInfo({
-      id: getString(context.context_id) ?? contextId,
-      status: normalizeContextStatus(context.locked),
-      metadata: context.metadata ?? {},
-      createdAt: parseTimestamp(context.created_at),
-      updatedAt: parseTimestamp(context.updated_at)
+    return new SessionDownloadsDeleteResponse({
+      status: getString(result.status) ?? "",
+      deletedCount: getNumber(result.deleted_count) ?? 0
     });
-    getLogger().info(`Retrieved context '${contextInfo.id}' (status: ${contextInfo.status})`);
-    return contextInfo;
+  }
+  handleError(action, response, sessionId) {
+    const errorData = asRecord(response.data);
+    const errorMessage = getString(errorData.error) ?? getString(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 downloads not found for ${sessionId}: ${errorMessage}`);
+    }
+    throw new APIError(`Failed to ${action}: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
+};
+var SessionsResource = class {
+  constructor(client) {
+    this.client = client;
+    this.downloads = new SessionDownloadsResource(client);
   }
   /**
-   * Fork an existing persistent context into a new context.
+   * Create a new browser session.
    */
-  async fork(contextId) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}/fork`;
+  async create(options = {}) {
     const payload = {
       api_key: this.client.apiKey,
-      project_id: this.client.projectId
+      project_id: options.projectId ?? this.client.projectId,
+      browser_mode: options.browserMode ?? "normal"
     };
+    if (options.context) {
+      const contextPayload = {
+        id: options.context.id,
+        mode: normalizeContextMode(options.context.mode)
+      };
+      payload.context = contextPayload;
+      getLogger().debug(
+        `Creating session with context (id=${options.context.id}, mode=${contextPayload.mode})`
+      );
+    } else {
+      getLogger().debug(`Creating session with browser_mode=${payload.browser_mode}`);
+    }
+    if (options.extensionIds && options.extensionIds.length > 0) {
+      payload.extension_ids = options.extensionIds;
+    }
+    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.handleError(response, "fork", contextId);
+      this.handleCreateError(response);
     }
     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", {
+    const sessionId = getString(result.session_id);
+    if (!sessionId) {
+      throw new APIError("Failed to create session: session_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)
+    const containerId = getString(result.container_id) ?? null;
+    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: createdSession?.status ?? "active",
+      apiKey: this.client.apiKey,
+      projectId,
+      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
     });
-    getLogger().info(`Successfully forked context '${contextId}' -> '${contextInfo.id}'`);
-    return contextInfo;
+  }
+  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 = asRecord(response.data);
+    const sessionId = getString(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") {
+        this.handleAsyncCreateFailed(payload);
+        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`
+    );
   }
   /**
-   * Delete a persistent context.
+   * 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 delete(contextId) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}`;
-    const payload = {
+  async get(sessionId, projectId) {
+    const response = await this.client._post(`${this.client.baseUrl}/instance/session`, {
       api_key: this.client.apiKey,
-      project_id: this.client.projectId
-    };
-    const response = await this.client._delete(url, payload);
+      project_id: projectId ?? this.client.projectId,
+      session_id: sessionId
+    });
     if (response.status >= 400) {
-      this.handleError(response, "delete", contextId);
+      this.handleGetError(response, sessionId);
     }
-    getLogger().info(`Successfully deleted context '${contextId}'`);
+    return this.mapSessionInfo(asRecord(response.data), projectId);
   }
   /**
-   * Force-release a stuck lock on a context.
+   * List sessions for the current project.
    */
-  async forceRelease(contextId) {
-    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}/force-release`;
+  async list(options = {}) {
+    const url = `${this.client.baseUrl}/instance/v2/sessions`;
     const payload = {
       api_key: this.client.apiKey,
-      project_id: this.client.projectId
+      project_id: options.projectId ?? this.client.projectId
     };
+    if (options.status) {
+      payload.status = options.status;
+    }
     const response = await this.client._post(url, payload);
     if (response.status >= 400) {
-      this.handleError(response, "force_release", contextId);
+      this.handleListError(response);
     }
     const result = asRecord(response.data);
-    return {
-      status: getString(result.status) ?? "unlocked",
-      message: getString(result.message) ?? "Lock released successfully"
-    };
+    const sessionsData = Array.isArray(result.sessions) ? result.sessions : [];
+    const paginationData = asRecord(result.pagination);
+    const sessions = sessionsData.map((item) => this.mapSessionInfo(asRecord(item), options.projectId));
+    const pagination = new PaginationInfo({
+      currentPage: getNumber(paginationData.currentPage) ?? 1,
+      pageSize: getNumber(paginationData.pageSize) ?? sessions.length,
+      totalCount: getNumber(paginationData.totalCount) ?? sessions.length,
+      totalPages: getNumber(paginationData.totalPages) ?? 1,
+      activeCount: getNumber(paginationData.activeCount) ?? 0,
+      closedCount: getNumber(paginationData.closedCount) ?? 0
+    });
+    getLogger().info(
+      `Retrieved ${sessions.length} sessions (total: ${pagination.totalCount}, active: ${pagination.activeCount}, closed: ${pagination.closedCount})`
+    );
+    return new SessionListResponse(sessions, pagination);
   }
-  handleError(response, operation, contextId) {
-    const errorData = asRecord(response.data);
+  /**
+   * Delete a browser session.
+   */
+  async delete(options) {
+    const url = `${this.client.baseUrl}/instance`;
+    const payload = {
+      api_key: this.client.apiKey,
+      project_id: options.projectId ?? this.client.projectId,
+      session_id: options.sessionId
+    };
+    const response = await this.client._delete(url, payload);
+    if (response.status >= 400) {
+      this.handleDeleteError(response, options.sessionId);
+    }
+    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(asRecord(item)));
+  }
+  /**
+   * Fetch the debugger WebSocket URL for a session.
+   *
+   * @internal
+   */
+  async _getWebSocketDebuggerUrl(sessionId) {
+    try {
+      const response = await this.client._get(`${this.client.baseUrl}/json/version`, {
+        session_id: sessionId
+      });
+      if (response.status >= 400) {
+        getLogger().error("Error getting WebSocket debugger URL:", response.data);
+        return null;
+      }
+      const result = asRecord(response.data);
+      return getString(result.webSocketDebuggerUrlTransformed) ?? getString(result.webSocketDebuggerUrl) ?? null;
+    } catch (error) {
+      getLogger().error("Error getting WebSocket debugger URL:", error);
+      return null;
+    }
+  }
+  normalizeProxy(proxy) {
+    if (!proxy.server) {
+      throw new ValidationError("proxy.server is required when proxy is provided");
+    }
+    const normalizedProxy = {
+      type: proxy.type ?? "external",
+      server: proxy.server
+    };
+    if (proxy.username) {
+      normalizedProxy.username = proxy.username;
+    }
+    if (proxy.password) {
+      normalizedProxy.password = proxy.password;
+    }
+    return normalizedProxy;
+  }
+  handleAsyncCreateFailed(payload) {
+    const context = asRecord(payload.context);
+    const contextId = getString(context.id);
+    const contextMode = getString(context.mode);
+    if (contextId && contextMode === "read_write" && payload.weak_lock !== true) {
+      throw new ContextLockedError("Context is locked by another active session");
+    }
+  }
+  handleCreateError(response) {
+    const errorData = asRecord(response.data);
     const errorMessage = getString(errorData.error) ?? getString(errorData.message) ?? "Unknown error";
     const errorCode = getString(errorData.code);
     const metadata = asRecord(errorData.metadata);
     if (response.status === 401) {
-      throw new AuthenticationError(`Authentication failed: ${errorMessage}`);
+      throw new AuthenticationError(
+        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
+      );
+    }
+    if (response.status === 404 && errorCode === "context_not_found") {
+      throw new ContextNotFoundError(`Context not found: ${errorMessage}`);
     }
     if (response.status === 404) {
-      const suffix = contextId ? `: ${contextId}` : "";
-      throw new ContextNotFoundError(`Context not found${suffix}`);
+      throw new SessionNotFoundError(`Resource not found: ${errorMessage}`);
     }
-    if (response.status === 409 && (errorCode === "context_locked" || errorCode === "CONTEXT_FORK_SOURCE_LOCKED")) {
+    if (response.status === 409 && errorCode === "context_locked") {
       throw new ContextLockedError(errorMessage, {
         activeSessionId: getString(metadata.activeSessionId),
-        retryAfter: typeof metadata.retryAfter === "number" ? metadata.retryAfter : void 0
+        retryAfter: getNumber(metadata.retryAfter)
       });
     }
-    if (response.status === 409 && errorCode === "session_active") {
-      throw new APIError(
-        `Cannot ${operation} context: ${errorMessage} (session is active)`,
-        {
-          statusCode: response.status,
-          response: response.data
-        }
+    throw new APIError(`Failed to create session: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
+  handleGetError(response, sessionId) {
+    const errorData = asRecord(response.data);
+    const errorMessage = getString(errorData.error) ?? getString(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 === 500) {
-      const details = getString(errorData.details);
-      throw new APIError(
-        `Internal server error (500) during ${operation}: ${errorMessage}${details ? `. Details: ${details}` : ""}`,
-        {
-          statusCode: response.status,
-          response: response.data
-        }
+    if (response.status === 404) {
+      throw new SessionNotFoundError(
+        `Session not found: ${errorMessage}. Session ID '${sessionId}' may not exist in this project.`
       );
     }
-    if (response.status === 502) {
-      throw new APIError(
-        `Server gateway error (502) during ${operation}: The service may be temporarily unavailable. Please retry.`,
-        {
-          statusCode: response.status,
-          response: response.data
-        }
+    throw new APIError(`Failed to get session: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
+  handleListError(response) {
+    const errorData = asRecord(response.data);
+    const errorMessage = getString(errorData.error) ?? getString(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 === 503) {
-      throw new APIError(
-        `Service unavailable (503) during ${operation}: The service is temporarily unavailable. Please retry later.`,
-        {
-          statusCode: response.status,
-          response: response.data
-        }
+    throw new APIError(`Failed to list sessions: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
+  handleListTargetsError(response, sessionId) {
+    const errorData = asRecord(response.data);
+    const errorMessage = getString(errorData.error) ?? getString(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 === 504) {
-      throw new APIError(
-        `Gateway timeout (504) during ${operation}: The request timed out. Please retry.`,
-        {
-          statusCode: response.status,
-          response: response.data
-        }
+    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 ${operation} context: ${errorMessage}`, {
+    throw new APIError(`Failed to list session targets: ${errorMessage}`, {
       statusCode: response.status,
       response: response.data
     });
   }
+  handleDeleteError(response, sessionId) {
+    const errorData = asRecord(response.data);
+    const errorMessage = getString(errorData.error) ?? getString(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 have already been deleted or never existed.`
+      );
+    }
+    throw new APIError(`Failed to delete session: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
+  }
+  mapSessionInfo(raw, projectId) {
+    const sessionId = getString(raw.session_id) ?? getString(raw.id) ?? "";
+    return new SessionInfo({
+      id: sessionId,
+      status: getString(raw.status) ?? "active",
+      apiKey: getString(raw.api_key) ?? this.client.apiKey,
+      projectId: getString(raw.project_id) ?? (projectId ?? this.client.projectId),
+      regionId: getString(raw.region_id) ?? this.client.selectedRegion ?? this.client.region ?? null,
+      browserType: getString(raw.browser_type) ?? getString(raw.browser_mode) ?? "normal",
+      createdAt: getString(raw.created_at) ?? "",
+      inspectUrl: getString(raw.inspect_url) ?? `${this.client.baseUrl}/inspect?session_id=${sessionId}`,
+      containerId: getString(raw.container_id) ?? null,
+      ws: getString(raw.ws) ?? null,
+      client: this.client
+    });
+  }
+  mapSessionTarget(raw) {
+    return new SessionTargetInfo({
+      id: getString(raw.id) ?? "",
+      title: getString(raw.title) ?? "",
+      type: getString(raw.type) ?? "",
+      url: getString(raw.url) ?? "",
+      description: getString(raw.description) ?? "",
+      inspectUrl: getString(raw.inspectUrl) ?? getString(raw.inspect_url) ?? null,
+      webSocketDebuggerUrl: getString(raw.webSocketDebuggerUrl) ?? getString(raw.web_socket_debugger_url) ?? null,
+      webSocketDebuggerUrlTransformed: getString(raw.webSocketDebuggerUrlTransformed) ?? getString(raw.web_socket_debugger_url_transformed) ?? null
+    });
+  }
+  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/extensions.ts
-import { readFile } from "fs/promises";
-import path from "path";
+// src/auth.ts
+var integratedAuthCallbacks = /* @__PURE__ */ new Map();
+var cdpClients = /* @__PURE__ */ new Map();
+function getIntegratedAuthKey(sessionOrClient) {
+  const session = sessionOrClient instanceof SessionInfo ? sessionOrClient : sessionOrClient.session;
+  const connectUrl = session.connectUrl;
+  if (!connectUrl) {
+    throw new ValidationError(`Session ${session.sessionId} does not include a CDP connect URL`);
+  }
+  return connectUrl;
+}
+async function registerIntegratedAuthCallback(sessionOrClient, callback) {
+  const key = getIntegratedAuthKey(sessionOrClient);
+  let sessionCallbacks = integratedAuthCallbacks.get(key);
+  if (sessionCallbacks?.has(callback)) {
+    return;
+  }
+  let client = cdpClients.get(key);
+  if (!client) {
+    if (sessionOrClient instanceof SessionInfo) {
+      client = await connectOverCDP(sessionOrClient);
+    } else {
+      client = sessionOrClient;
+    }
+    await client.send("Fetch.enable", { handleAuthRequests: true });
+    cdpClients.set(key, client);
+    client.on("disconnect", () => {
+      cdpClients.delete(key);
+      integratedAuthCallbacks.delete(key);
+    });
+    client.on("Fetch.requestPaused", async (event, sessionId) => {
+      try {
+        await client.send(
+          "Fetch.continueRequest",
+          {
+            requestId: event.requestId
+          },
+          sessionId
+        );
+      } catch (error) {
+        getLogger().error("Failed to continue paused fetch request", error);
+      }
+    });
+    client.on("Fetch.integratedAuthRequired", async (params, sessionId) => {
+      try {
+        const sessionCallbacks2 = integratedAuthCallbacks.get(key);
+        if (!sessionCallbacks2) {
+          await client.send(
+            "Fetch.continueWithIntegratedAuth",
+            {
+              requestId: params.requestId,
+              authChallengeResponse: {
+                response: "CancelAuth"
+              }
+            },
+            sessionId
+          );
+          return;
+        }
+        const sender = async (result) => {
+          if (result.cancel) {
+            await client.send(
+              "Fetch.continueWithIntegratedAuth",
+              {
+                requestId: params.requestId,
+                authChallengeResponse: {
+                  response: "CancelAuth"
+                }
+              },
+              sessionId
+            );
+            return;
+          }
+          await client.send(
+            "Fetch.continueWithIntegratedAuth",
+            {
+              requestId: params.requestId,
+              authChallengeResponse: {
+                response: "ProvideIntegratedCredentials",
+                scheme: result.scheme,
+                token: result.token
+              }
+            },
+            sessionId
+          );
+        };
+        for (const cb of sessionCallbacks2) {
+          try {
+            const result = cb(params, sender);
+            void Promise.resolve(result).catch((error) => {
+              getLogger().error("Integrated auth callback failed", error);
+            });
+          } catch (error) {
+            getLogger().error("Integrated auth callback failed", error);
+          }
+        }
+      } catch (error) {
+        getLogger().error("Failed to handle integrated auth request", error);
+      }
+    });
+  }
+  if (!sessionCallbacks) {
+    sessionCallbacks = /* @__PURE__ */ new Set();
+    integratedAuthCallbacks.set(key, sessionCallbacks);
+  }
+  sessionCallbacks.add(callback);
+}
+function deregisterIntegratedAuthCallback(sessionOrClient, callback) {
+  const key = getIntegratedAuthKey(sessionOrClient);
+  const sessionCallbacks = integratedAuthCallbacks.get(key);
+  if (!sessionCallbacks?.has(callback)) {
+    return;
+  }
+  sessionCallbacks.delete(callback);
+  if (sessionCallbacks.size === 0) {
+    integratedAuthCallbacks.delete(key);
+  }
+}
+
+// src/client.ts
+import { isAxiosError } from "axios";
+import axios from "axios";
+import * as dotenv from "dotenv";
+
+// src/contexts.ts
 function asRecord2(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
 function getString2(value) {
   return typeof value === "string" ? value : void 0;
 }
-var ExtensionInfo = class {
-  constructor(shape) {
-    this.id = shape.id;
-    this.name = shape.name;
-    this.projectId = shape.projectId;
-    this.createdAt = shape.createdAt;
-    this.updatedAt = shape.updatedAt;
+function parseTimestamp(value) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
   }
-};
-var ExtensionsResource = class {
-  constructor(client) {
-    this.client = client;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
   }
-  async upload(filePath, options = {}) {
-    const fileBuffer = await readFile(filePath);
-    const form = new FormData();
-    const usedProjectId = options.projectId ?? this.client.projectId;
-    form.append("project_id", usedProjectId);
-    if (options.name) {
-      form.append("name", options.name);
-    }
-    form.append(
-      "file",
-      new Blob([fileBuffer], { type: "application/octet-stream" }),
-      path.basename(filePath)
-    );
-    const response = await this.client._post(
-      `${this.client.baseUrl}/instance/v1/extension/upload`,
-      form,
-      {
-        headers: {
-          project_id: usedProjectId
-        }
-      }
-    );
-    if (response.status >= 400) {
-      this.handleError("upload extension", response);
-    }
-    getLogger().info(`Extension uploaded successfully: ${filePath}`);
-    return this.parseInfo(response.data);
-  }
-  async list(options = {}) {
-    const response = await this.client._post(`${this.client.baseUrl}/instance/v1/extension/list`, {
-      project_id: options.projectId ?? this.client.projectId,
-      limit: options.limit ?? 20,
-      offset: options.offset ?? 0
-    });
-    if (response.status >= 400) {
-      this.handleError("list extensions", response);
-    }
-    const result = asRecord2(response.data);
-    const items = Array.isArray(result.data) ? result.data : [];
-    return items.map((item) => this.parseInfo(item));
-  }
-  async get(extensionId, projectId) {
-    const response = await this.client._post(`${this.client.baseUrl}/instance/v1/extension/info`, {
-      project_id: projectId ?? this.client.projectId,
-      extension_id: extensionId
-    });
-    if (response.status >= 400) {
-      this.handleError("get extension", response);
-    }
-    return this.parseInfo(response.data);
-  }
-  async delete(extensionId) {
-    const response = await this.client._delete(
-      `${this.client.baseUrl}/instance/v1/extension/${extensionId}`
-    );
-    if (response.status >= 400) {
-      this.handleError("delete extension", response);
-    }
-    getLogger().info(`Extension deleted successfully: ${extensionId}`);
-  }
-  parseInfo(data) {
-    const item = asRecord2(data);
-    return new ExtensionInfo({
-      id: getString2(item.id) ?? "",
-      name: getString2(item.name) ?? "",
-      projectId: getString2(item.project_id) ?? "",
-      createdAt: getString2(item.created_at),
-      updatedAt: getString2(item.updated_at)
-    });
-  }
-  handleError(action, response) {
-    const errorData = asRecord2(response.data);
-    const errorMessage = getString2(errorData.message) ?? getString2(errorData.error) ?? "Unknown error";
-    if (response.status === 401) {
-      throw new AuthenticationError(
-        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
-      );
-    }
-    throw new APIError(`Failed to ${action}: ${errorMessage}`, {
-      statusCode: response.status,
-      response: response.data
-    });
-  }
-};
-
-// src/sessions.ts
-function asRecord3(value) {
-  return typeof value === "object" && value !== null ? value : {};
-}
-function getString3(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function getNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  return null;
 }
-function normalizeContextMode(mode) {
-  if (mode === "readWrite" || mode === "read_write") {
-    return "read_write";
+function normalizeContextStatus(value) {
+  if (value === true || value === "locked") {
+    return "locked";
   }
-  return "read_only";
-}
-function delay(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-var PaginationInfo = class {
-  constructor(shape) {
-    this.currentPage = shape.currentPage;
-    this.pageSize = shape.pageSize;
-    this.totalCount = shape.totalCount;
-    this.totalPages = shape.totalPages;
-    this.activeCount = shape.activeCount;
-    this.closedCount = shape.closedCount;
+  if (value === false || value === "available") {
+    return "available";
   }
-};
-var SessionInfo = class {
-  /** @internal */
+  return typeof value === "string" ? value : "available";
+}
+var ContextInfo = class {
   constructor(options) {
-    this.closed = false;
     this.id = options.id;
-    this.sessionId = options.id;
     this.status = options.status;
-    this.apiKey = options.apiKey;
-    this.projectId = options.projectId;
-    this.browserType = options.browserType;
-    this.createdAt = options.createdAt;
-    this.inspectUrl = options.inspectUrl;
-    this.containerId = options.containerId;
-    this.ws = options.ws ?? null;
-    this.client = options.client;
-  }
-  /**
-   * Playwright/CDP connection URL.
-   */
-  get connectUrl() {
-    return this.ws ?? "";
+    this.metadata = options.metadata ?? {};
+    this.createdAt = options.createdAt ?? null;
+    this.updatedAt = options.updatedAt ?? null;
   }
-  /**
-   * Parsed session creation time.
-   */
   get createdAtDate() {
+    if (!this.createdAt) {
+      return null;
+    }
     const date = new Date(this.createdAt);
     return Number.isNaN(date.getTime()) ? null : date;
   }
-  /**
-   * Close the current session.
-   *
-   * This method is idempotent. Errors are logged and swallowed to keep cleanup safe.
-   */
-  async close() {
-    if (this.closed) {
-      getLogger().debug(`Session ${this.sessionId} is already closed.`);
-      return;
-    }
-    if (!this.client) {
-      getLogger().warn(
-        `Cannot close session ${this.sessionId}: client was not provided during session creation.`
-      );
-      return;
-    }
-    try {
-      getLogger().debug(`Closing session ${this.sessionId}`);
-      await this.client.sessions.delete({
-        sessionId: this.sessionId,
-        projectId: this.projectId
-      });
-      this.closed = true;
-      getLogger().info(`Session closed: ${this.sessionId}`);
-    } catch (error) {
-      getLogger().warn(`Failed to close session ${this.sessionId}:`, error);
-    }
-  }
-};
-var SessionListResponse = class {
-  constructor(sessions, pagination) {
-    this.sessions = sessions;
-    this.pagination = pagination;
-  }
-  /**
-   * Number of sessions in the current page.
-   */
-  get length() {
-    return this.sessions.length;
-  }
-  [Symbol.iterator]() {
-    return this.sessions[Symbol.iterator]();
-  }
-  at(index) {
-    return this.sessions[index];
-  }
-};
-var SessionDownloadInfo = class {
-  constructor(shape) {
-    this.id = shape.id;
-    this.filename = shape.filename;
-    this.contentType = shape.contentType;
-    this.size = shape.size;
-    this.sha256 = shape.sha256;
-    this.status = shape.status;
-    this.createdAt = shape.createdAt;
-  }
-};
-var SessionDownloadsListResponse = class {
-  constructor(downloads, summary) {
-    this.downloads = downloads;
-    this.summary = summary;
-  }
-};
-var SessionDownloadsDeleteResponse = class {
-  constructor(shape) {
-    this.status = shape.status;
-    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;
-  }
-  async list(sessionId, projectId) {
-    const response = await this.client._post(
-      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/list`,
-      {
-        api_key: this.client.apiKey,
-        project_id: projectId ?? this.client.projectId
-      }
-    );
-    if (response.status >= 400) {
-      this.handleError("list session downloads", response, sessionId);
-    }
-    const result = asRecord3(response.data);
-    const items = Array.isArray(result.downloads) ? result.downloads : [];
-    const downloads = items.map((item) => {
-      const download = asRecord3(item);
-      return new SessionDownloadInfo({
-        id: getString3(download.id) ?? "",
-        filename: getString3(download.filename) ?? "",
-        contentType: getString3(download.content_type) ?? null,
-        size: getNumber(download.size) ?? 0,
-        sha256: getString3(download.sha256) ?? null,
-        status: getString3(download.status) ?? "available",
-        createdAt: getString3(download.created_at) ?? ""
-      });
-    });
-    const summary = asRecord3(result.summary);
-    return new SessionDownloadsListResponse(downloads, {
-      count: getNumber(summary.count) ?? downloads.length,
-      totalSize: getNumber(summary.total_size) ?? 0
-    });
-  }
-  async get(sessionId, downloadId, projectId) {
-    const response = await this.client._get(
-      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/${downloadId}`,
-      {
-        api_key: this.client.apiKey,
-        project_id: projectId ?? this.client.projectId
-      },
-      {
-        responseType: "arraybuffer"
-      }
-    );
-    if (response.status >= 400) {
-      this.handleError("fetch session download", response, sessionId);
-    }
-    return Buffer.from(response.data);
-  }
-  async archive(sessionId, projectId) {
-    const response = await this.client._get(
-      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads/archive`,
-      {
-        api_key: this.client.apiKey,
-        project_id: projectId ?? this.client.projectId
-      },
-      {
-        responseType: "arraybuffer"
-      }
-    );
-    if (response.status >= 400) {
-      this.handleError("archive session downloads", response, sessionId);
-    }
-    return Buffer.from(response.data);
-  }
-  async delete(sessionId, projectId) {
-    const response = await this.client._delete(
-      `${this.client.baseUrl}/instance/v1/sessions/${sessionId}/downloads`,
-      {
-        api_key: this.client.apiKey,
-        project_id: projectId ?? this.client.projectId
-      }
-    );
-    if (response.status >= 400) {
-      this.handleError("delete session downloads", response, sessionId);
-    }
-    const result = asRecord3(response.data);
-    return new SessionDownloadsDeleteResponse({
-      status: getString3(result.status) ?? "",
-      deletedCount: getNumber(result.deleted_count) ?? 0
-    });
-  }
-  handleError(action, 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 downloads not found for ${sessionId}: ${errorMessage}`);
+  get updatedAtDate() {
+    if (!this.updatedAt) {
+      return null;
     }
-    throw new APIError(`Failed to ${action}: ${errorMessage}`, {
-      statusCode: response.status,
-      response: response.data
-    });
+    const date = new Date(this.updatedAt);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  isLocked() {
+    return this.status === "locked";
+  }
+  isAvailable() {
+    return this.status === "available";
   }
 };
-var SessionsResource = class {
+var ContextListResponse = class {
+  constructor(data) {
+    this.data = data;
+  }
+  get length() {
+    return this.data.length;
+  }
+  [Symbol.iterator]() {
+    return this.data[Symbol.iterator]();
+  }
+  at(index) {
+    return this.data[index];
+  }
+};
+var ContextsResource = class {
   constructor(client) {
     this.client = client;
-    this.downloads = new SessionDownloadsResource(client);
   }
   /**
-   * Create a new browser session.
+   * Create a new persistent context.
    */
   async create(options = {}) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/create-context`;
     const payload = {
       api_key: this.client.apiKey,
-      project_id: options.projectId ?? this.client.projectId,
-      browser_mode: options.browserMode ?? "normal"
+      project_id: this.client.projectId
     };
-    if (options.context) {
-      const contextPayload = {
-        id: options.context.id,
-        mode: normalizeContextMode(options.context.mode)
-      };
-      payload.context = contextPayload;
-      getLogger().debug(
-        `Creating session with context (id=${options.context.id}, mode=${contextPayload.mode})`
-      );
-    } else {
-      getLogger().debug(`Creating session with browser_mode=${payload.browser_mode}`);
-    }
-    if (options.extensionIds && options.extensionIds.length > 0) {
-      payload.extension_ids = options.extensionIds;
-    }
-    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);
+    if (options.metadata) {
+      payload.metadata = options.metadata;
     }
-    const url = `${this.client.baseUrl}/instance`;
     const response = await this.client._post(url, payload);
     if (response.status >= 400) {
-      this.handleCreateError(response);
+      this.handleError(response, "create");
     }
-    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", {
+    const result = asRecord2(response.data);
+    const contextId = getString2(result.context_id);
+    if (!contextId) {
+      throw new APIError("Failed to create context: context_id missing from response", {
         statusCode: response.status,
         response: response.data
       });
     }
-    const containerId = getString3(result.container_id) ?? null;
-    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: createdSession?.status ?? "active",
-      apiKey: this.client.apiKey,
-      projectId,
-      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
+    const context = new ContextInfo({
+      id: contextId,
+      status: normalizeContextStatus(result.locked),
+      metadata: result.metadata ?? options.metadata ?? {},
+      createdAt: parseTimestamp(result.created_at)
     });
-  }
-  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") {
-        this.handleAsyncCreateFailed(payload);
-        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`
-    );
+    getLogger().info(`Successfully created context '${context.id}'`);
+    return context;
   }
   /**
-   * 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.
+   * List contexts in the current project.
    */
-  async get(sessionId, projectId) {
-    const response = await this.client._post(`${this.client.baseUrl}/instance/session`, {
+  async list(options = {}) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/list-contexts`;
+    const payload = {
       api_key: this.client.apiKey,
-      project_id: projectId ?? this.client.projectId,
-      session_id: sessionId
-    });
+      project_id: this.client.projectId,
+      limit: options.limit ?? 20
+    };
+    if (options.status) {
+      payload.status = options.status;
+    }
+    const response = await this.client._post(url, payload);
     if (response.status >= 400) {
-      this.handleGetError(response, sessionId);
+      this.handleError(response, "list");
     }
-    return this.mapSessionInfo(asRecord3(response.data), projectId);
+    const result = asRecord2(response.data);
+    const contexts = Array.isArray(result.contexts) ? result.contexts.map((item) => {
+      const context = asRecord2(item);
+      return new ContextInfo({
+        id: getString2(context.context_id) ?? "",
+        status: normalizeContextStatus(context.locked),
+        createdAt: parseTimestamp(context.created_at),
+        updatedAt: parseTimestamp(context.updated_at),
+        metadata: context.metadata ?? {}
+      });
+    }) : [];
+    getLogger().info(`Retrieved ${contexts.length} contexts`);
+    return new ContextListResponse(contexts);
   }
   /**
-   * List sessions for the current project.
+   * Fetch a single context.
    */
-  async list(options = {}) {
-    const url = `${this.client.baseUrl}/instance/v2/sessions`;
+  async get(contextId) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}`;
     const payload = {
       api_key: this.client.apiKey,
-      project_id: options.projectId ?? this.client.projectId
+      project_id: this.client.projectId
     };
-    if (options.status) {
-      payload.status = options.status;
-    }
     const response = await this.client._post(url, payload);
     if (response.status >= 400) {
-      this.handleListError(response);
+      this.handleError(response, "get", contextId);
     }
-    const result = asRecord3(response.data);
-    const sessionsData = Array.isArray(result.sessions) ? result.sessions : [];
-    const paginationData = asRecord3(result.pagination);
-    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,
-      totalCount: getNumber(paginationData.totalCount) ?? sessions.length,
-      totalPages: getNumber(paginationData.totalPages) ?? 1,
-      activeCount: getNumber(paginationData.activeCount) ?? 0,
-      closedCount: getNumber(paginationData.closedCount) ?? 0
+    const result = asRecord2(response.data);
+    const context = asRecord2(result.context);
+    const contextInfo = new ContextInfo({
+      id: getString2(context.context_id) ?? contextId,
+      status: normalizeContextStatus(context.locked),
+      metadata: context.metadata ?? {},
+      createdAt: parseTimestamp(context.created_at),
+      updatedAt: parseTimestamp(context.updated_at)
     });
-    getLogger().info(
-      `Retrieved ${sessions.length} sessions (total: ${pagination.totalCount}, active: ${pagination.activeCount}, closed: ${pagination.closedCount})`
-    );
-    return new SessionListResponse(sessions, pagination);
+    getLogger().info(`Retrieved context '${contextInfo.id}' (status: ${contextInfo.status})`);
+    return contextInfo;
   }
   /**
-   * Delete a browser session.
+   * Fork an existing persistent context into a new context.
    */
-  async delete(options) {
-    const url = `${this.client.baseUrl}/instance`;
+  async fork(contextId) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}/fork`;
     const payload = {
       api_key: this.client.apiKey,
-      project_id: options.projectId ?? this.client.projectId,
-      session_id: options.sessionId
+      project_id: this.client.projectId
     };
-    const response = await this.client._delete(url, payload);
+    const response = await this.client._post(url, payload);
     if (response.status >= 400) {
-      this.handleDeleteError(response, options.sessionId);
+      this.handleError(response, "fork", contextId);
     }
-    getLogger().info(`Session deleted successfully: ${options.sessionId}`);
+    const result = asRecord2(response.data);
+    const forkedContextId = getString2(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;
   }
   /**
-   * List target/page metadata for a session via `/json`.
+   * Delete a persistent context.
    */
-  async listTargets(sessionId) {
-    const response = await this.client._get(`${this.client.baseUrl}/json`, {
-      session_id: sessionId
-    });
+  async delete(contextId) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}`;
+    const payload = {
+      api_key: this.client.apiKey,
+      project_id: this.client.projectId
+    };
+    const response = await this.client._delete(url, payload);
     if (response.status >= 400) {
-      this.handleListTargetsError(response, sessionId);
+      this.handleError(response, "delete", contextId);
     }
-    const result = Array.isArray(response.data) ? response.data : [];
-    return result.map((item) => this.mapSessionTarget(asRecord3(item)));
+    getLogger().info(`Successfully deleted context '${contextId}'`);
   }
   /**
-   * Fetch the debugger WebSocket URL for a session.
-   *
-   * @internal
+   * Force-release a stuck lock on a context.
    */
-  async _getWebSocketDebuggerUrl(sessionId) {
-    try {
-      const response = await this.client._get(`${this.client.baseUrl}/json/version`, {
-        session_id: sessionId
-      });
-      if (response.status >= 400) {
-        getLogger().error("Error getting WebSocket debugger URL:", response.data);
-        return null;
-      }
-      const result = asRecord3(response.data);
-      return getString3(result.webSocketDebuggerUrlTransformed) ?? getString3(result.webSocketDebuggerUrl) ?? null;
-    } catch (error) {
-      getLogger().error("Error getting WebSocket debugger URL:", error);
-      return null;
-    }
-  }
-  normalizeProxy(proxy) {
-    if (!proxy.server) {
-      throw new ValidationError("proxy.server is required when proxy is provided");
-    }
-    const normalizedProxy = {
-      type: proxy.type ?? "external",
-      server: proxy.server
+  async forceRelease(contextId) {
+    const url = `${this.client.baseUrl}/instance/v1/contexts/${contextId}/force-release`;
+    const payload = {
+      api_key: this.client.apiKey,
+      project_id: this.client.projectId
     };
-    if (proxy.username) {
-      normalizedProxy.username = proxy.username;
-    }
-    if (proxy.password) {
-      normalizedProxy.password = proxy.password;
-    }
-    return normalizedProxy;
-  }
-  handleAsyncCreateFailed(payload) {
-    const context = asRecord3(payload.context);
-    const contextId = getString3(context.id);
-    const contextMode = getString3(context.mode);
-    if (contextId && contextMode === "read_write" && payload.weak_lock !== true) {
-      throw new ContextLockedError("Context is locked by another active session");
+    const response = await this.client._post(url, payload);
+    if (response.status >= 400) {
+      this.handleError(response, "force_release", contextId);
     }
+    const result = asRecord2(response.data);
+    return {
+      status: getString2(result.status) ?? "unlocked",
+      message: getString2(result.message) ?? "Lock released successfully"
+    };
   }
-  handleCreateError(response) {
-    const errorData = asRecord3(response.data);
-    const errorMessage = getString3(errorData.error) ?? getString3(errorData.message) ?? "Unknown error";
-    const errorCode = getString3(errorData.code);
-    const metadata = asRecord3(errorData.metadata);
+  handleError(response, operation, contextId) {
+    const errorData = asRecord2(response.data);
+    const errorMessage = getString2(errorData.error) ?? getString2(errorData.message) ?? "Unknown error";
+    const errorCode = getString2(errorData.code);
+    const metadata = asRecord2(errorData.metadata);
     if (response.status === 401) {
-      throw new AuthenticationError(
-        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
-      );
-    }
-    if (response.status === 404 && errorCode === "context_not_found") {
-      throw new ContextNotFoundError(`Context not found: ${errorMessage}`);
+      throw new AuthenticationError(`Authentication failed: ${errorMessage}`);
     }
     if (response.status === 404) {
-      throw new SessionNotFoundError(`Resource not found: ${errorMessage}`);
+      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: getString3(metadata.activeSessionId),
-        retryAfter: getNumber(metadata.retryAfter)
+        activeSessionId: getString2(metadata.activeSessionId),
+        retryAfter: typeof metadata.retryAfter === "number" ? metadata.retryAfter : void 0
       });
     }
-    throw new APIError(`Failed to create session: ${errorMessage}`, {
-      statusCode: response.status,
-      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 === 409 && errorCode === "session_active") {
+      throw new APIError(
+        `Cannot ${operation} context: ${errorMessage} (session is active)`,
+        {
+          statusCode: response.status,
+          response: response.data
+        }
       );
     }
-    if (response.status === 404) {
-      throw new SessionNotFoundError(
-        `Session not found: ${errorMessage}. Session ID '${sessionId}' may not exist in this project.`
+    if (response.status === 500) {
+      const details = getString2(errorData.details);
+      throw new APIError(
+        `Internal server error (500) during ${operation}: ${errorMessage}${details ? `. Details: ${details}` : ""}`,
+        {
+          statusCode: response.status,
+          response: response.data
+        }
       );
     }
-    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";
-    if (response.status === 401) {
-      throw new AuthenticationError(
-        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
+    if (response.status === 502) {
+      throw new APIError(
+        `Server gateway error (502) during ${operation}: The service may be temporarily unavailable. Please retry.`,
+        {
+          statusCode: response.status,
+          response: response.data
+        }
       );
     }
-    throw new APIError(`Failed to list sessions: ${errorMessage}`, {
-      statusCode: response.status,
-      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 === 503) {
+      throw new APIError(
+        `Service unavailable (503) during ${operation}: The service is temporarily unavailable. Please retry later.`,
+        {
+          statusCode: response.status,
+          response: response.data
+        }
       );
     }
-    if (response.status === 404) {
-      throw new SessionNotFoundError(
-        `Session not found: ${errorMessage}. Session ID '${sessionId}' may not exist in this project.`
+    if (response.status === 504) {
+      throw new APIError(
+        `Gateway timeout (504) during ${operation}: The request timed out. Please retry.`,
+        {
+          statusCode: response.status,
+          response: response.data
+        }
       );
     }
-    throw new APIError(`Failed to list session targets: ${errorMessage}`, {
+    throw new APIError(`Failed to ${operation} context: ${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";
-    if (response.status === 401) {
-      throw new AuthenticationError(
-        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
-      );
+};
+
+// src/extensions.ts
+import { readFile } from "fs/promises";
+import path from "path";
+function asRecord3(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+function getString3(value) {
+  return typeof value === "string" ? value : void 0;
+}
+var ExtensionInfo = class {
+  constructor(shape) {
+    this.id = shape.id;
+    this.name = shape.name;
+    this.projectId = shape.projectId;
+    this.createdAt = shape.createdAt;
+    this.updatedAt = shape.updatedAt;
+  }
+};
+var ExtensionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async upload(filePath, options = {}) {
+    const fileBuffer = await readFile(filePath);
+    const form = new FormData();
+    const usedProjectId = options.projectId ?? this.client.projectId;
+    form.append("project_id", usedProjectId);
+    if (options.name) {
+      form.append("name", options.name);
     }
-    if (response.status === 404) {
-      throw new SessionNotFoundError(
-        `Session not found: ${errorMessage}. Session ID '${sessionId}' may have already been deleted or never existed.`
-      );
+    form.append(
+      "file",
+      new Blob([fileBuffer], { type: "application/octet-stream" }),
+      path.basename(filePath)
+    );
+    const response = await this.client._post(
+      `${this.client.baseUrl}/instance/v1/extension/upload`,
+      form,
+      {
+        headers: {
+          project_id: usedProjectId
+        }
+      }
+    );
+    if (response.status >= 400) {
+      this.handleError("upload extension", response);
     }
-    throw new APIError(`Failed to delete session: ${errorMessage}`, {
-      statusCode: response.status,
-      response: response.data
+    getLogger().info(`Extension uploaded successfully: ${filePath}`);
+    return this.parseInfo(response.data);
+  }
+  async list(options = {}) {
+    const response = await this.client._post(`${this.client.baseUrl}/instance/v1/extension/list`, {
+      project_id: options.projectId ?? this.client.projectId,
+      limit: options.limit ?? 20,
+      offset: options.offset ?? 0
     });
+    if (response.status >= 400) {
+      this.handleError("list extensions", response);
+    }
+    const result = asRecord3(response.data);
+    const items = Array.isArray(result.data) ? result.data : [];
+    return items.map((item) => this.parseInfo(item));
   }
-  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 get(extensionId, projectId) {
+    const response = await this.client._post(`${this.client.baseUrl}/instance/v1/extension/info`, {
+      project_id: projectId ?? this.client.projectId,
+      extension_id: extensionId
     });
+    if (response.status >= 400) {
+      this.handleError("get extension", response);
+    }
+    return this.parseInfo(response.data);
   }
-  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 delete(extensionId) {
+    const response = await this.client._delete(
+      `${this.client.baseUrl}/instance/v1/extension/${extensionId}`
+    );
+    if (response.status >= 400) {
+      this.handleError("delete extension", response);
+    }
+    getLogger().info(`Extension deleted successfully: ${extensionId}`);
+  }
+  parseInfo(data) {
+    const item = asRecord3(data);
+    return new ExtensionInfo({
+      id: getString3(item.id) ?? "",
+      name: getString3(item.name) ?? "",
+      projectId: getString3(item.project_id) ?? "",
+      createdAt: getString3(item.created_at),
+      updatedAt: getString3(item.updated_at)
     });
   }
-  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
+  handleError(action, response) {
+    const errorData = asRecord3(response.data);
+    const errorMessage = getString3(errorData.message) ?? getString3(errorData.error) ?? "Unknown error";
+    if (response.status === 401) {
+      throw new AuthenticationError(
+        `Authentication failed: ${errorMessage}. Please check your API key and project ID.`
       );
-      return null;
     }
+    throw new APIError(`Failed to ${action}: ${errorMessage}`, {
+      statusCode: response.status,
+      response: response.data
+    });
   }
 };
 
@@ -1429,10 +1659,11 @@ var Lexmount = class {
 };
 
 // src/index.ts
-var VERSION = "0.5.3";
+var VERSION = "0.5.5";
 export {
   APIError,
   AuthenticationError,
+  CDPClient,
   ContextInfo,
   ContextListResponse,
   ContextLockedError,
@@ -1457,10 +1688,13 @@ export {
   TimeoutError,
   VERSION,
   ValidationError,
+  connectOverCDP,
   Lexmount as default,
+  deregisterIntegratedAuthCallback,
   disableLogging,
   enableLogging,
   getLogger,
+  registerIntegratedAuthCallback,
   setLogLevel
 };
 //# sourceMappingURL=index.mjs.map