notte-sdk 0.0.22 → 1.9.0

package/dist/index.mjs

@@ -1,28 +1,38 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/version.ts
-var SDK_VERSION = true ? "0.0.22" : "dev";
+var SDK_VERSION = true ? "1.9.0" : "dev";
 var SDK_PACKAGE_NAME = true ? "notte-sdk" : "notte-sdk";
 
 // src/version-check.ts
 var DISABLE_ENV = "NOTTE_SDK_DISABLE_VERSION_CHECK";
 var VERSION_CHECK_TIMEOUT_MS = 1500;
-var hasStartedVersionCheck = false;
+var versionCheckPerformed = false;
+var cachedLatestVersion;
 function startVersionCheck() {
-  if (hasStartedVersionCheck || !shouldCheckVersion()) {
+  if (versionCheckPerformed || !shouldCheckVersion()) {
     return;
   }
-  hasStartedVersionCheck = true;
+  versionCheckPerformed = true;
   const timer = setTimeout(() => {
     void checkForLatestVersion().catch(() => void 0);
   }, 0);
   timer.unref?.();
 }
+function isVersionOlder(current, latest) {
+  return isVersionGreater(latest, current);
+}
+function upgradeSuggestion(currentVersion = SDK_VERSION) {
+  if (!cachedLatestVersion || !isPublishedVersion(currentVersion)) {
+    return void 0;
+  }
+  return isVersionOlder(currentVersion, cachedLatestVersion) ? cachedLatestVersion : void 0;
+}
+function createUpgradeErrorMessage(errorContext, latestVersion, originalError, currentVersion = SDK_VERSION, packageName = SDK_PACKAGE_NAME) {
+  let message = `${errorContext}. This might be due to API schema changes. Current SDK version: ${currentVersion}, Latest available: ${latestVersion}. Either you made a mistake in the request arguments, or you should upgrade to the latest ${packageName} version by running: 'npm install ${packageName}@${latestVersion}'`;
+  if (originalError) {
+    message += `. Original error: ${originalError}`;
+  }
+  return message;
+}
 async function checkForLatestVersion(options = {}) {
   const currentVersion = options.currentVersion ?? SDK_VERSION;
   const packageName = options.packageName ?? SDK_PACKAGE_NAME;
@@ -33,11 +43,15 @@ async function checkForLatestVersion(options = {}) {
     return;
   }
   const latestVersion = await fetchLatestVersion(packageName, fetchFn);
-  if (!latestVersion || !isVersionGreater(latestVersion, currentVersion)) {
+  if (!latestVersion) {
+    return;
+  }
+  cachedLatestVersion = latestVersion;
+  if (!isVersionGreater(latestVersion, currentVersion)) {
     return;
   }
   warnFn(
-    `[${packageName}] A newer version is available: ${currentVersion} -> ${latestVersion}. Update with: npm install ${packageName}@latest`
+    `\u26A0\uFE0F You are using ${packageName} version ${currentVersion}, but version ${latestVersion} is available on npm. Run 'npm install ${packageName}@${latestVersion}' to avoid any interruptions.`
   );
 }
 function shouldCheckVersion(currentVersion = SDK_VERSION, fetchFn = globalThis.fetch, env = getEnv()) {
@@ -53,7 +67,8 @@ async function fetchLatestVersion(packageName, fetchFn) {
   try {
     const response = await fetchFn(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`, {
       headers: {
-        accept: "application/json"
+        accept: "application/json",
+        "user-agent": `${packageName}/${SDK_VERSION} (https://github.com/nottelabs/notte)`
       },
       signal: controller?.signal
     });
@@ -157,7 +172,7 @@ function createSseClient({
   ...options
 }) {
   let lastEventId;
-  const sleep = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep2 = sseSleepFn ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)));
   const createStream = async function* () {
     let retryDelay = sseDefaultRetryDelay ?? 3e3;
     let attempt = 0;
@@ -261,7 +276,7 @@ function createSseClient({
           break;
         }
         const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 3e4);
-        await sleep(backoff);
+        await sleep2(backoff);
       }
     }
   };
@@ -658,9 +673,7 @@ var mergeHeaders = (...headers) => {
   return mergedHeaders;
 };
 var Interceptors = class {
-  constructor() {
-    this.fns = [];
-  }
+  fns = [];
   clear() {
     this.fns = [];
   }
@@ -916,7 +929,7 @@ var createClient = (config = {}) => {
 };
 
 // src/lib/client/client.gen.ts
-var client = createClient(createConfig({ baseUrl: "https://us-staging.notte.cc" }));
+var client = createClient(createConfig({ baseUrl: "https://api.notte.cc" }));
 
 // src/lib/client/sdk.gen.ts
 var listSessions = (options) => (options?.client ?? client).get({
@@ -1476,15 +1489,6 @@ var deleteSecret = (options) => (options.client ?? client).delete({
   url: "/secrets/{secret_id}",
   ...options
 });
-var mintProxyCredentials = (options) => (options.client ?? client).post({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/proxies/gateway/credentials",
-  ...options,
-  headers: {
-    "Content-Type": "application/json",
-    ...options.headers
-  }
-});
 var healthCheck = (options) => (options?.client ?? client).get({ url: "/health", ...options });
 var readyCheck = (options) => (options?.client ?? client).get({ url: "/ready", ...options });
 var scrapeWebpage = (options) => (options.client ?? client).post({
@@ -1515,6 +1519,582 @@ var scrapeFromHtml = (options) => (options.client ?? client).post({
   }
 });
 
+// src/session.ts
+import { existsSync } from "fs";
+import { writeFile as writeFile2 } from "fs/promises";
+import { resolve as resolve2 } from "path";
+
+// src/errors.ts
+var NotteError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+function describeBody(error) {
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+var NotteAPIError = class _NotteAPIError extends NotteError {
+  path;
+  statusCode;
+  error;
+  response;
+  constructor(path, statusCode, error, response) {
+    super(`Request to \`${path}\` failed with status code ${statusCode}: ${describeBody(error)}`);
+    this.path = path;
+    this.statusCode = statusCode;
+    this.error = error;
+    this.response = response;
+  }
+  /** The API's own error message, when it sent one. */
+  get apiMessage() {
+    const message = this.error.message ?? this.error.detail;
+    return typeof message === "string" ? message : void 0;
+  }
+  static fromBody(path, statusCode, body, response) {
+    return new _NotteAPIError(path, statusCode, normalizeErrorBody(body), response);
+  }
+};
+var NotteAPIExecutionError = class extends NotteAPIError {
+  constructor(path, statusCode, error, response) {
+    super(path, statusCode, error, response);
+    this.message = `Error on ${path}: ${describeBody(error)}`;
+  }
+};
+var AuthenticationError = class extends NotteError {
+  constructor(message) {
+    super(`Authentication failed. ${message}`);
+  }
+};
+var InvalidRequestError = class extends NotteError {
+  constructor(message) {
+    super(`Invalid request. ${message}`);
+  }
+};
+var NotteTimeoutError = class extends NotteError {
+};
+var FailedToRunCloudFunctionError = class extends NotteError {
+  functionId;
+  functionRunId;
+  response;
+  constructor(functionId, functionRunId, response) {
+    super(
+      `Function ${functionId} run ${functionRunId} failed: ${typeof response === "string" ? response : describeBody(response ?? {})}`
+    );
+    this.functionId = functionId;
+    this.functionRunId = functionRunId;
+    this.response = response;
+  }
+};
+var ScrapeFailedError = class extends NotteError {
+  structuredError;
+  constructor(error) {
+    super(`Scrape failed: ${error ?? "unknown error"}`);
+    this.structuredError = error;
+  }
+};
+var ActionExecutionError = class _ActionExecutionError extends NotteError {
+  errorType;
+  devMessage;
+  userMessage;
+  agentMessage;
+  shouldRetryLater;
+  shouldNotifyTeam;
+  constructor(detail) {
+    super(detail.dev_message || detail.user_message || detail.error_type);
+    this.errorType = detail.error_type;
+    this.devMessage = detail.dev_message;
+    this.userMessage = detail.user_message;
+    this.agentMessage = detail.agent_message;
+    this.shouldRetryLater = detail.should_retry_later ?? false;
+    this.shouldNotifyTeam = detail.should_notify_team ?? false;
+  }
+  static fromMessage(message, errorType = "NotteBaseError") {
+    return new _ActionExecutionError({
+      error_type: errorType,
+      dev_message: message,
+      user_message: message,
+      agent_message: message
+    });
+  }
+};
+var EvaluateJsNoDataError = class extends NotteError {
+  constructor() {
+    super("evaluate_js returned no data. Upgrade the Notte API to a build that returns the evaluated value.");
+  }
+};
+var FetchResponseDecodeError = class extends NotteError {
+  constructor(reason) {
+    super(`Failed to decode the response returned by the page fetch: ${reason}`);
+  }
+};
+function normalizeErrorBody(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  if (body === void 0 || body === null || body === "") {
+    return {};
+  }
+  return { message: typeof body === "string" ? body : String(body) };
+}
+var DEFAULT_RETRY_MESSAGE = "An error occurred while executing the function. Try again later...";
+function retry(fn, options) {
+  const {
+    maxTries,
+    delayMs = 5e3,
+    errorMessage = DEFAULT_RETRY_MESSAGE,
+    shouldRetry = () => true,
+    onRetry = (error, attempt, total) => {
+      console.warn(`Failed to execute ${fn.name || "function"}: ${String(error)} (attempt ${attempt}/${total})`);
+    }
+  } = options;
+  if (!Number.isInteger(maxTries) || maxTries < 1) {
+    throw new InvalidRequestError("maxTries must be a positive integer");
+  }
+  return async (...args) => {
+    let lastError;
+    for (let attempt = 1; attempt <= maxTries; attempt += 1) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        lastError = error;
+        if (attempt === maxTries || !shouldRetry(error, attempt)) {
+          break;
+        }
+        onRetry(error, attempt, maxTries);
+        await sleep(delayMs);
+      }
+    }
+    throw new Error(errorMessage, { cause: lastError });
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+
+// src/actions.ts
+function builder(type) {
+  return (...[input]) => ({ ...input ?? {}, type });
+}
+var goto = builder("goto");
+var gotoNewTab = builder("goto_new_tab");
+var closeTab = builder("close_tab");
+var switchTab = builder("switch_tab");
+var goBack = builder("go_back");
+var goForward = builder("go_forward");
+var reload = builder("reload");
+var wait = builder("wait");
+var pressKey = builder("press_key");
+var scrollUp = builder("scroll_up");
+var scrollDown = builder("scroll_down");
+var captchaSolve = builder("captcha_solve");
+var help = builder("help");
+var completion = builder("completion");
+var scrape = builder("scrape");
+var emailRead = builder("email_read");
+var emailVerificationRead = builder("email_verification_read");
+var smsRead = builder("sms_read");
+var evaluateJs = builder("evaluate_js");
+var formFill = builder("form_fill");
+var click = builder("click");
+var fill = builder("fill");
+var multiFactorFill = builder("multi_factor_fill");
+var fallbackFill = builder("fallback_fill");
+var check = builder("check");
+var selectDropdownOption = builder("select_dropdown_option");
+var uploadFile = builder("upload_file");
+var downloadFile = builder("download_file");
+var actions = {
+  goto,
+  gotoNewTab,
+  closeTab,
+  switchTab,
+  goBack,
+  goForward,
+  reload,
+  wait,
+  pressKey,
+  scrollUp,
+  scrollDown,
+  captchaSolve,
+  help,
+  completion,
+  scrape,
+  emailRead,
+  emailVerificationRead,
+  smsRead,
+  evaluateJs,
+  formFill,
+  click,
+  fill,
+  multiFactorFill,
+  fallbackFill,
+  check,
+  selectDropdownOption,
+  uploadFile,
+  downloadFile
+};
+function isCaptchaSolveAction(action) {
+  return action.type === "captcha_solve";
+}
+
+// src/page-fetch.ts
+var CONTENT_TYPE = "content-type";
+function hasHeader(headers, name) {
+  return Object.keys(headers).some((key) => key.toLowerCase() === name);
+}
+function urlencode(mapping) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(mapping)) {
+    if (Array.isArray(value)) {
+      for (const item of value) search.append(key, String(item));
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  return search.toString();
+}
+function withParams(url, params) {
+  const hashIndex = url.indexOf("#");
+  const fragment = hashIndex >= 0 ? url.slice(hashIndex) : "";
+  const base = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+  const queryIndex = base.indexOf("?");
+  const path = queryIndex >= 0 ? base.slice(0, queryIndex) : base;
+  const existing = queryIndex >= 0 ? base.slice(queryIndex + 1) : "";
+  let query = urlencode(params);
+  if (existing) {
+    query = `${existing}&${query}`;
+  }
+  return `${path}?${query}${fragment}`;
+}
+function buildFetchScript(url, options = {}) {
+  const { method = "GET", headers, params, json, data, timeoutMs, allowInsecure = false } = options;
+  const redirect = options.redirect ?? (allowInsecure ? "follow" : "manual");
+  if (json !== void 0 && data !== void 0) {
+    throw new InvalidRequestError("pass either json or data, not both");
+  }
+  if (timeoutMs !== void 0 && !(timeoutMs > 0)) {
+    throw new InvalidRequestError("timeout must be positive");
+  }
+  let requestUrl = url;
+  if (params && Object.keys(params).length > 0) {
+    requestUrl = withParams(url, params);
+  }
+  const requestHeaders = { ...headers ?? {} };
+  let body;
+  if (json !== void 0) {
+    body = JSON.stringify(json);
+    if (!hasHeader(requestHeaders, CONTENT_TYPE)) {
+      requestHeaders["Content-Type"] = "application/json";
+    }
+  } else if (data !== void 0 && typeof data !== "string") {
+    body = urlencode(data);
+    if (!hasHeader(requestHeaders, CONTENT_TYPE)) {
+      requestHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+    }
+  } else if (data !== void 0) {
+    body = data;
+  }
+  const init = {
+    method: method.toUpperCase(),
+    headers: requestHeaders,
+    credentials: "include",
+    redirect
+  };
+  if (body !== void 0) {
+    if (init.method === "GET" || init.method === "HEAD") {
+      throw new InvalidRequestError(`${String(init.method)} requests cannot have a body`);
+    }
+    init.body = body;
+  }
+  let abort = "";
+  if (timeoutMs !== void 0) {
+    abort = `const controller = new AbortController();setTimeout(() => controller.abort(), ${Math.trunc(timeoutMs)});init.signal = controller.signal;`;
+  }
+  return `(async () => {const init = ${JSON.stringify(init)};${abort}const target = new URL(${JSON.stringify(requestUrl)}, location.href);const allowInsecure = ${allowInsecure ? "true" : "false"};if (target.protocol !== 'https:' && !allowInsecure) {  throw new Error('Refusing to fetch ' + target.origin + ' over plaintext; pass allowInsecure: true to override');}const response = await fetch(target.toString(), init);if (response.type === 'opaqueredirect') {  throw new Error('The request to ' + target.origin + ' was redirected; redirects are not followed because the page cookies could be sent in cleartext. Fetch the final URL directly or pass allowInsecure: true');}if (!allowInsecure && new URL(response.url).protocol !== 'https:') {  throw new Error('Refusing to read a response served over plaintext from ' + new URL(response.url).origin + '; pass allowInsecure: true to override');}const bytes = new Uint8Array(await response.arrayBuffer());let binary = '';for (let i = 0; i < bytes.length; i += 0x8000) {  binary += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));}const headers = {};response.headers.forEach((value, key) => { headers[key] = value; });return JSON.stringify({status: response.status, url: response.url, headers: headers, body_b64: btoa(binary)});})()`;
+}
+var REASON_PHRASES = {
+  100: "Continue",
+  101: "Switching Protocols",
+  102: "Processing",
+  103: "Early Hints",
+  200: "OK",
+  201: "Created",
+  202: "Accepted",
+  203: "Non-Authoritative Information",
+  204: "No Content",
+  205: "Reset Content",
+  206: "Partial Content",
+  207: "Multi-Status",
+  208: "Already Reported",
+  226: "IM Used",
+  300: "Multiple Choices",
+  301: "Moved Permanently",
+  302: "Found",
+  303: "See Other",
+  304: "Not Modified",
+  305: "Use Proxy",
+  307: "Temporary Redirect",
+  308: "Permanent Redirect",
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Request Entity Too Large",
+  414: "Request-URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Requested Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required"
+};
+var PageFetchHTTPError = class extends NotteError {
+  response;
+  constructor(response) {
+    const kind = response.status < 500 ? "Client Error" : "Server Error";
+    super(`${response.status} ${kind}: ${response.statusText} for url: ${response.url}`);
+    this.response = response;
+  }
+};
+function encodingFor(headers, content) {
+  const contentType = Object.entries(headers).find(([key]) => key.toLowerCase() === CONTENT_TYPE)?.[1] ?? "";
+  for (const param of contentType.split(";").slice(1)) {
+    const [name, ...rest] = param.split("=");
+    const value = rest.join("=");
+    if (name?.trim().toLowerCase() === "charset" && value) {
+      return value.trim().replace(/^["']|["']$/g, "");
+    }
+  }
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(content);
+  } catch {
+    return void 0;
+  }
+  return "utf-8";
+}
+var PageFetchResponse = class {
+  status;
+  statusText;
+  headers;
+  /** The final URL after redirects. */
+  url;
+  /** The declared charset, `utf-8` when the body is valid utf-8, else `undefined`. */
+  encoding;
+  content;
+  constructor(init) {
+    this.status = init.status;
+    this.statusText = REASON_PHRASES[init.status] ?? "";
+    this.headers = new Headers(init.headers);
+    this.url = init.url;
+    this.content = init.content;
+    this.encoding = encodingFor(init.headers, init.content);
+  }
+  get ok() {
+    return this.status >= 200 && this.status < 300;
+  }
+  /** The raw body bytes. */
+  bytes() {
+    return this.content;
+  }
+  async arrayBuffer() {
+    return this.content.slice().buffer;
+  }
+  async text() {
+    let decoder;
+    try {
+      decoder = new TextDecoder(this.encoding ?? "utf-8");
+    } catch {
+      decoder = new TextDecoder("utf-8");
+    }
+    return decoder.decode(this.content);
+  }
+  async json() {
+    return JSON.parse(await this.text());
+  }
+  /** Throw `PageFetchHTTPError` on a 4xx/5xx status, like `requests.Response.raise_for_status()`. */
+  raiseForStatus() {
+    if (this.status >= 400) {
+      throw new PageFetchHTTPError(this);
+    }
+    return this;
+  }
+};
+var BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+function decodeBase64(value) {
+  if (!BASE64_PATTERN.test(value) || value.length % 4 !== 0) {
+    throw new Error("body_b64 is not valid base64");
+  }
+  return new Uint8Array(Buffer.from(value, "base64"));
+}
+function responseFromEvaluated(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (error) {
+    throw new FetchResponseDecodeError(error instanceof Error ? error.message : String(error));
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    throw new FetchResponseDecodeError("envelope is not an object");
+  }
+  const envelope = payload;
+  try {
+    if (!("status" in envelope)) {
+      throw new Error("'status'");
+    }
+    const status = Number(envelope.status);
+    if (!Number.isInteger(status)) {
+      throw new Error(`invalid status: ${String(envelope.status)}`);
+    }
+    const rawHeaders = envelope.headers ?? {};
+    if (typeof rawHeaders !== "object" || Array.isArray(rawHeaders)) {
+      throw new Error("headers is not an object");
+    }
+    const headers = {};
+    for (const [key, value] of Object.entries(rawHeaders)) {
+      headers[String(key)] = String(value);
+    }
+    const content = decodeBase64(String(envelope.body_b64 ?? ""));
+    const url = String(envelope.url ?? "");
+    return new PageFetchResponse({ status, headers, url, content });
+  } catch (error) {
+    throw new FetchResponseDecodeError(error instanceof Error ? error.message : String(error));
+  }
+}
+
+// src/cookies.ts
+import { readFile, writeFile } from "fs/promises";
+import { resolve } from "path";
+async function readCookiesFile(cookieFile) {
+  const cookies = JSON.parse(await readFile(cookieFile, "utf-8"));
+  if (!Array.isArray(cookies)) {
+    throw new InvalidRequestError(`Cookie file ${cookieFile} must contain a JSON list of cookies`);
+  }
+  return cookies;
+}
+async function createOrAppendCookiesToFile(cookieFile, cookies) {
+  console.info(`\u{1F36A} Automatically saving cookies to ${cookieFile}`);
+  await withFileLock(cookieFile, async () => {
+    let existing = [];
+    try {
+      existing = await readCookiesFile(cookieFile);
+    } catch (error) {
+      if (!isNotFound(error)) {
+        throw error;
+      }
+    }
+    existing.push(...cookies);
+    await writeFile(cookieFile, JSON.stringify(existing), "utf-8");
+  });
+}
+var fileLocks = /* @__PURE__ */ new Map();
+async function withFileLock(path, fn) {
+  const key = resolve(path);
+  const previous = fileLocks.get(key) ?? Promise.resolve();
+  let release;
+  const current = new Promise((done) => {
+    release = done;
+  });
+  const tail = previous.then(() => current);
+  fileLocks.set(key, tail);
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (fileLocks.get(key) === tail) {
+      fileLocks.delete(key);
+    }
+  }
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+
+// src/scrape.ts
+function isZodSchema(value) {
+  return typeof value === "object" && value !== null && typeof value.parse === "function";
+}
+function requiresSchema(options) {
+  return Boolean(options.response_format || options.instructions);
+}
+async function buildScrapeBody(options) {
+  const { raiseOnFailure: _raise, json_schema, response_format, ...rest } = options;
+  const body = { ...rest };
+  if (isZodSchema(response_format)) {
+    if (json_schema) {
+      body.response_format = json_schema;
+    } else {
+      const { z: z2 } = await import("zod");
+      body.response_format = z2.toJSONSchema(response_format);
+    }
+  } else if (response_format) {
+    body.response_format = response_format;
+  }
+  return body;
+}
+function processScrapeResponse(scrapeResponse, options) {
+  if (!scrapeResponse) {
+    throw new ScrapeFailedError("empty response");
+  }
+  const raiseOnFailure = options.raiseOnFailure ?? true;
+  if (options.only_images) {
+    return scrapeResponse.images ?? [];
+  }
+  if (requiresSchema(options)) {
+    const structured = scrapeResponse.structured;
+    if (!structured) {
+      throw new ScrapeFailedError("the API returned no structured data. This should not happen, please report it.");
+    }
+    const success = structured.success ?? false;
+    const schema = isZodSchema(options.response_format) ? options.response_format : void 0;
+    if (!success) {
+      if (raiseOnFailure) {
+        throw new ScrapeFailedError(structured.error ?? void 0);
+      }
+      return { success, error: structured.error ?? null, data: null };
+    }
+    const data = schema && structured.data != null ? schema.parse(structured.data) : structured.data;
+    if (raiseOnFailure) {
+      return data;
+    }
+    return { success, error: structured.error ?? null, data };
+  }
+  return scrapeResponse.markdown;
+}
+
 // src/utils.ts
 import { spawn } from "child_process";
 function formatError(error) {
@@ -1557,55 +2137,64 @@ function openBrowser(url) {
 }
 
 // src/session.ts
-import { z } from "zod";
-function processScrapeResponse(scrapeResponse, options) {
-  if (options.only_images && scrapeResponse.images) {
-    return scrapeResponse.images;
-  }
-  if (requiresSchema(options)) {
-    const structured = scrapeResponse.structured;
-    if (!structured) {
-      throw new Error("Failed to scrape structured data. This should not happen. Please report this issue.");
-    }
-    if (options.response_format && typeof options.response_format.parse === "function") {
-      if (structured.data) {
-        try {
-          const validatedData = options.response_format.parse(structured.data);
-          return validatedData;
-        } catch (error) {
-          throw new Error(`Schema validation failed: ${error instanceof Error ? error.message : String(error)}`);
-        }
-      }
-      return structured;
-    }
-    return structured;
-  }
-  if (options.response_format && typeof options.response_format.parse === "function") {
-    try {
-      const validatedData = options.response_format.parse(scrapeResponse);
-      return validatedData;
-    } catch (error) {
-      throw new Error(`Schema validation failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  return scrapeResponse.markdown;
+var SESSION_START_TRIES = 3;
+var CLUSTER_OVERLOAD_RETRY_DELAY_MS = 3e4;
+var CAPTCHA_SOLVE_TIMEOUT_MS = 1e5;
+var CAPTCHA_SOLVE_TRIES = 3;
+function observeServerOwnedDialog(_dialog) {
 }
-function requiresSchema(options) {
-  return !!(options.response_format || options.instructions);
+function installServerOwnedDialogPolicy(browser) {
+  for (const context of browser.contexts()) {
+    context.on("dialog", observeServerOwnedDialog);
+  }
 }
 var Session = class {
+  client;
+  options;
+  openViewer;
+  legacyHeadless;
+  defaultRaiseOnFailure;
+  defaultPerceptionType;
+  cookieFile;
+  fileStorage;
+  sessionId = null;
+  isActive = false;
+  response = null;
+  playwrightBrowser = null;
+  playwrightPage = null;
   constructor(client2, options = {}) {
-    this.sessionId = null;
-    this.isActive = false;
-    this.response = null;
     this.client = client2;
-    const { open_viewer = false, headless, ...sessionOptions } = options;
-    this.options = sessionOptions;
+    const {
+      open_viewer = false,
+      headless,
+      raiseOnFailure = true,
+      perception_type = "fast",
+      cookie_file,
+      storage,
+      ...sessionOptions
+    } = options;
+    this.options = storage ? { ...sessionOptions, use_file_storage: true } : sessionOptions;
     this.openViewer = open_viewer;
     this.legacyHeadless = headless;
-  }
+    this.defaultRaiseOnFailure = raiseOnFailure;
+    this.defaultPerceptionType = perception_type;
+    this.cookieFile = cookie_file;
+    this.fileStorage = storage;
+  }
+  // #######################################################################
+  // ############################# Session #################################
+  // #######################################################################
   /**
-   * Start the session - creates a new session on the server
+   * Start the session: creates a new session on the server.
+   *
+   * Retries up to `SESSION_START_TRIES` times on 5xx errors, waiting
+   * `CLUSTER_OVERLOAD_RETRY_DELAY_MS` on HTTP 529 (cluster overload). 4xx
+   * errors are never retried.
+   *
+   * Prefer `session.use(async session => { ... })`, which also stops the session.
+   * @example
+   * const session = client.Session();
+   * await session.start();
    */
   async start() {
     if (this.legacyHeadless === false) {
@@ -1620,93 +2209,171 @@ var Session = class {
     if (this.isActive) {
       throw new Error("Session is already active");
     }
-    let shouldOpenViewer = false;
+    const body = this.options;
+    let tries = SESSION_START_TRIES;
+    const origTries = tries;
+    let sessionData;
+    while (tries > 0) {
+      tries -= 1;
+      try {
+        const response = await sessionStart({ client: this.client.getClient(), body, throwOnError: true });
+        sessionData = response.data;
+        break;
+      } catch (error) {
+        if (tries === 0 || !(error instanceof NotteAPIError) || error.statusCode < 500) {
+          throw error;
+        }
+        const retryStr = `${origTries - tries}/${origTries - 1}`;
+        if (error.statusCode === 529) {
+          console.warn(
+            `Failed to start session due to cluster overload, retrying in ${CLUSTER_OVERLOAD_RETRY_DELAY_MS / 1e3} seconds (${retryStr})...`
+          );
+          await sleep(CLUSTER_OVERLOAD_RETRY_DELAY_MS);
+        } else {
+          console.warn(`Failed to start session: retrying (${retryStr})`);
+        }
+      }
+    }
+    if (!sessionData) {
+      throw new Error("Failed to start session: empty response");
+    }
+    this.sessionId = sessionData.session_id;
+    this.isActive = true;
+    this.response = sessionData;
+    this.fileStorage = this.fileStorage?.forSession(sessionData.session_id);
     try {
-      const response = await sessionStart({
-        client: this.client.getClient(),
-        body: this.options
-      });
-      if (response?.error) {
-        throw new Error(`Failed to create session: ${formatError(response.error)}`);
+      if (this.openViewer) {
+        this.openViewerInBrowser();
+      }
+      if (this.cookieFile !== void 0) {
+        if (existsSync(this.cookieFile)) {
+          console.info(`\u{1F36A} Automatically loading cookies from ${this.cookieFile}`);
+          await this.setCookiesFromFile(this.cookieFile);
+        } else {
+          console.warn(`\u{1F36A} Cookie file ${this.cookieFile} not found, skipping cookie loading`);
+        }
       }
-      const sessionData = response.data;
-      this.sessionId = sessionData.session_id;
-      this.isActive = true;
-      this.response = sessionData;
-      shouldOpenViewer = this.openViewer;
     } catch (error) {
-      throw new Error(`Failed to start session: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (shouldOpenViewer) {
-      this.openViewerInBrowser();
+      try {
+        await this.stop("error");
+      } catch (stopError) {
+        console.error(`[Session] Failed to stop ${sessionData.session_id} after a start failure: ${String(stopError)}`);
+      }
+      throw error;
     }
   }
   /**
-   * Stop the session - terminates the session on the server
+   * Stop the session and clean up resources (including any Playwright
+   * connection opened with `page()`). When a `cookie_file` was given, the
+   * session cookies are appended to it first. A session the API reports as
+   * already stopped is tolerated with a warning.
+   *
+   * @example
+   * await session.stop();
    */
   async stop(closeReason = "manual") {
     if (!this.isActive || !this.sessionId) {
       return;
     }
-    const response = await sessionStop({
-      client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      },
-      query: {
-        close_reason: closeReason
+    const sessionId = this.sessionId;
+    await this.closePlaywright();
+    if (this.cookieFile !== void 0) {
+      try {
+        const cookies = await this.getCookies();
+        await createOrAppendCookiesToFile(this.cookieFile, cookies);
+      } catch (error) {
+        console.error(`\u{1F36A} Error saving cookies to ${this.cookieFile}: ${String(error)}`);
+      }
+    }
+    try {
+      const response = await sessionStop({
+        client: this.client.getClient(),
+        path: { session_id: sessionId },
+        query: { close_reason: closeReason },
+        throwOnError: true
+      });
+      if (response.data.status !== "closed") {
+        throw new Error(`[Session] ${sessionId} failed to stop`);
+      }
+      this.response = response.data;
+    } catch (error) {
+      const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+      if (message.includes("already stopped") || message.includes("already closed")) {
+        console.warn(`Session ${sessionId} was already stopped`);
+      } else {
+        throw error;
       }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to stop session: ${formatError(response.error)}`);
     }
-    this.response = response.data;
     this.isActive = false;
     this.sessionId = null;
   }
+  async closePlaywright() {
+    const browser = this.playwrightBrowser;
+    this.playwrightBrowser = null;
+    this.playwrightPage = null;
+    if (browser) {
+      try {
+        await browser.close();
+      } catch (error) {
+        console.warn(`[Session] Failed to close the Playwright connection: ${String(error)}`);
+      }
+    }
+  }
   /**
-   * Get session status
+   * Get the current status of the session. Like Python, this keeps working
+   * after `stop()` (for example to read the recorded `steps`).
+   *
+   * @returns Current session metadata, including lifecycle status and recorded steps. Works after `stop()`.
+   * @throws Error if this session has never been started.
+   * @throws NotteAPIError if the status request fails.
+   * @example
+   * const status = await session.status();
+   * console.log(status.status); // 'active'
    */
   async status() {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
     const response = await sessionStatus({
       client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      }
+      path: { session_id: this.lastSessionId() },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to get session status: ${formatError(response.error)}`);
-    }
     return response.data;
   }
-  /**
-   * Get session ID
-   */
+  /** Session ID while the session is active, `null` otherwise. */
   getId() {
     return this.sessionId;
   }
-  /**
-   * Check if session is active
-   */
+  /** Whether the session has been started and not stopped yet. */
   isSessionActive() {
     return this.isActive;
   }
-  /**
-   * Get the last response from session operations
-   */
+  /** The last `SessionResponse` received from the API (start, stop or status). */
   getResponse() {
     return this.response;
   }
+  /** The file storage attached to the session, when one was given. */
+  get storage() {
+    return this.fileStorage;
+  }
+  requireSessionId() {
+    if (!this.sessionId) {
+      throw new Error("Session not started");
+    }
+    return this.sessionId;
+  }
+  /** Session ID of the active session, or of the last one when it was stopped. */
+  lastSessionId() {
+    const sessionId = this.sessionId ?? this.response?.session_id;
+    if (!sessionId) {
+      throw new Error("Session not started");
+    }
+    return sessionId;
+  }
   /**
    * Open the live viewer for this session in the local default browser.
+   * @throws If the session has not started or no viewer URL is available.
    */
   viewer() {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
+    this.requireSessionId();
     const viewerUrl = this.response?.viewer_url;
     if (!viewerUrl) {
       throw new Error("No viewer URL available for this session");
@@ -1722,154 +2389,381 @@ var Session = class {
     openBrowser(viewerUrl);
   }
   /**
-   * Set cookies for the session
+   * Get presigned URLs for the session replay. Recordings are finalized after
+   * the session is closed, so by default this polls on 404 until the replay is
+   * ready. It keeps working after `stop()`.
+   *
+   * Throws an `Error` when the API reports the session is still active and a
+   * `NotteTimeoutError` when the replay is not ready within `timeoutMs`.
+   * @example
+   * await session.stop();
+   * const replay = await session.replay();
+   * console.log(replay.mp4_url);
    */
-  async setCookies(cookies) {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
-    const response = await sessionCookiesSet({
-      client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      },
-      body: {
-        cookies
+  async replay(options = {}) {
+    const { wait: wait2 = true, timeoutMs = 24e4, pollIntervalMs = 5e3 } = options;
+    const sessionId = this.lastSessionId();
+    const request = async () => {
+      const response = await sessionReplay({
+        client: this.client.getClient(),
+        path: { session_id: sessionId },
+        throwOnError: true
+      });
+      if (!response.data) {
+        throw new Error("Failed to get session replay: empty response");
       }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to set cookies: ${formatError(response.error)}`);
-    }
+      return response.data;
+    };
+    if (!wait2) {
+      return request();
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      try {
+        return await request();
+      } catch (error) {
+        if (!(error instanceof NotteAPIError) || error.statusCode !== 404) {
+          throw error;
+        }
+        if (this.isActive && (error.apiMessage ?? "").includes("still active")) {
+          throw new Error(`Session ${sessionId} is still active \u2014 close the session first to generate the replay.`, {
+            cause: error
+          });
+        }
+        if (Date.now() + pollIntervalMs > deadline) {
+          throw new NotteTimeoutError(`Replay for session ${sessionId} not ready within ${timeoutMs}ms`, { cause: error });
+        }
+        await sleep(pollIntervalMs);
+      }
+    }
+  }
+  /**
+   * Download the MP4 replay to a local file, like `ReplayResponse.download()`
+   * in Python. Resolves with the absolute path of the written file and throws
+   * when the replay has no `mp4_url`.
+   *
+   * @example
+   * await session.stop();
+   * const file = await session.downloadReplay('session.mp4');
+   */
+  async downloadReplay(path = "replay.mp4", options = {}) {
+    const replay = await this.replay(options);
+    if (!replay.mp4_url) {
+      throw new Error("No mp4_url available for download");
+    }
+    const response = await fetch(replay.mp4_url);
+    if (!response.ok) {
+      throw new Error(`Failed to download replay: HTTP ${response.status}`);
+    }
+    const target = resolve2(path);
+    await writeFile2(target, new Uint8Array(await response.arrayBuffer()));
+    return target;
+  }
+  // #######################################################################
+  // ############################# Cookies #################################
+  // #######################################################################
+  /**
+   * Upload cookies to the session.
+   *
+   * @example
+   * await session.setCookies([{ name: 'token', value: 'abc', domain: 'example.com', path: '/', httpOnly: false }]);
+   */
+  async setCookies(cookies) {
+    const response = await sessionCookiesSet({
+      client: this.client.getClient(),
+      path: { session_id: this.requireSessionId() },
+      body: { cookies },
+      throwOnError: true
+    });
     return response.data;
   }
   /**
-   * Set cookies from a file
+   * Upload cookies from a JSON file (a list of cookies, like `getCookies()` returns).
+   *
+   * @example
+   * await session.setCookiesFromFile('cookies.json');
    */
   async setCookiesFromFile(cookieFile) {
-    const fs = await import("fs/promises");
-    const cookieData = await fs.readFile(cookieFile, "utf-8");
-    const cookies = JSON.parse(cookieData);
-    return this.setCookies(cookies);
+    return this.setCookies(await readCookiesFile(cookieFile));
   }
   /**
-   * Get cookies from the session
+   * Get the cookies of the session.
+   *
+   * @example
+   * const cookies = await session.getCookies();
+   * await fs.writeFile('cookies.json', JSON.stringify(cookies));
    */
   async getCookies() {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
     const response = await sessionCookiesGet({
       client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      }
+      path: { session_id: this.requireSessionId() },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to get cookies: ${formatError(response.error)}`);
-    }
     return response.data.cookies;
   }
+  // #######################################################################
+  // ############################# Debug / CDP #############################
+  // #######################################################################
+  /** Detailed debug information for the session (debug URL, websocket URLs, tabs). */
+  async debugInfo() {
+    const response = await sessionDebugInfo({
+      client: this.client.getClient(),
+      path: { session_id: this.requireSessionId() },
+      throwOnError: true
+    });
+    return response.data;
+  }
   /**
-   * Execute an action on the page
+   * Debug information for one tab of the session. The API client has no
+   * dedicated tab endpoint, so this reads the tab from `debugInfo().tabs`.
    */
-  async execute(action, raiseOnFailure = true) {
-    if (!this.sessionId) {
+  async debugTabInfo(tabIdx = 0) {
+    const debug = await this.debugInfo();
+    const tab = debug.tabs[tabIdx];
+    if (!tab) {
+      throw new Error(`Tab ${tabIdx} not found: the session has ${debug.tabs.length} tab(s)`);
+    }
+    return tab;
+  }
+  /**
+   * Get the Chrome DevTools Protocol WebSocket URL for the session.
+   *
+   * A `cdp_url` given at construction (another browser provider) is returned
+   * untouched. Notte-served URLs, from the start response or the debug info,
+   * carry the database preview branch when one is configured.
+   *
+   * @returns The CDP WebSocket URL for connecting a browser automation client.
+   * @throws Error if no session ID or CDP URL is available.
+   * @example
+   * const browser = await chromium.connectOverCDP(await session.cdpUrl());
+   */
+  async cdpUrl() {
+    if (!this.response) {
       throw new Error("Session not started");
     }
-    const response = await pageExecute({
-      client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      },
-      body: action
-    });
-    if (response?.error) {
-      throw new Error(`Failed to execute action: ${formatError(response.error)}`);
+    if (this.options.cdp_url) {
+      return this.options.cdp_url;
     }
-    const result = response.data;
-    if (raiseOnFailure && !result.success) {
-      throw new Error(`Action execution failed: ${result.message}`);
+    if (this.response.cdp_url) {
+      return this.client.withDbPreview(this.response.cdp_url);
     }
-    return result;
+    const debug = await this.debugInfo();
+    return this.client.withDbPreview(debug.ws.cdp);
   }
   /**
-   * Observe the current page state
+   * Get a Playwright page connected to the session via CDP. The connection is
+   * established lazily on first access, cached, and closed by `stop()`.
+   * Native dialogs are left to the Notte backend.
+   *
+   * Requires the optional `playwright-core` peer dependency
+   * (`npm install playwright-core`).
+   *
+   * @example
+   * const page = await session.page();
+   * await page.goto('https://www.google.com');
+   * await page.screenshot({ path: 'screenshot.png' });
    */
-  async observe(perceptionType = "fast") {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
+  async page() {
+    if (this.playwrightPage) {
+      return this.playwrightPage;
     }
-    const response = await pageObserve({
-      client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      },
-      body: {
-        perception_type: perceptionType
+    let playwright;
+    try {
+      playwright = await import("playwright-core");
+    } catch (error) {
+      throw new Error("Playwright not installed. Run `npm install playwright-core` to use `session.page()`.", {
+        cause: error
+      });
+    }
+    try {
+      if (!this.playwrightBrowser) {
+        const cdpUrl = await this.cdpUrl();
+        this.playwrightBrowser = await playwright.chromium.connectOverCDP(cdpUrl);
+        installServerOwnedDialogPolicy(this.playwrightBrowser);
       }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to observe page: ${formatError(response.error)}`);
+      const page = this.playwrightBrowser.contexts()[0]?.pages()[0];
+      if (!page) {
+        throw new Error("the browser has no open page");
+      }
+      this.playwrightPage = page;
+      return page;
+    } catch (error) {
+      throw new Error(`Failed to access the playwright page from CDP: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error
+      });
     }
-    return response.data;
   }
   /**
-   * Get session replay data
+   * Get the workflow code generated from the session steps
+   * (`GET /sessions/{id}/workflow/code`).
+   *
+   * @example
+   * const { python_script } = await session.getScript();
    */
-  async replay() {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
-    const response = await sessionReplay({
+  async getScript(options = {}) {
+    const { as_workflow = true, infer_response_format } = options;
+    const response = await getSessionScript({
       client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      }
+      path: { session_id: this.lastSessionId() },
+      query: { as_workflow, ...infer_response_format === void 0 ? {} : { infer_response_format } },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to get session replay: ${formatError(response.error)}`);
-    }
     return response.data;
   }
-  async scrape(options = {}) {
-    if (!this.sessionId) {
-      throw new Error("Session not started");
-    }
-    const apiOptions = { ...options };
-    if (options.response_format && typeof options.response_format.parse === "function") {
-      if (options.json_schema) {
-        apiOptions.response_format = options.json_schema;
-      } else {
-        apiOptions.response_format = z.toJSONSchema(options.response_format);
-      }
-      if (!apiOptions.instructions) {
-        const schemaStr = JSON.stringify(apiOptions.response_format);
-        if (schemaStr.includes("plans") || schemaStr.includes("plan")) {
-          apiOptions.instructions = "Extract pricing plans from the page";
-        } else if (schemaStr.includes("products") || schemaStr.includes("product")) {
-          apiOptions.instructions = "Extract product information from the page";
-        } else if (schemaStr.includes("articles") || schemaStr.includes("article")) {
-          apiOptions.instructions = "Extract article information from the page";
-        } else {
-          apiOptions.instructions = "Extract structured data from the page based on the provided schema";
+  // #######################################################################
+  // ############################# Page ####################################
+  // #######################################################################
+  /**
+   * Execute an action on the current page.
+   *
+   * When the action fails and `raiseOnFailure` is true (the default, see the
+   * session option), the structured `exception_detail` returned by the API is
+   * rehydrated into an `ActionExecutionError` whose `errorType` names the
+   * server-side error class. `captcha_solve` actions get a 100 s request
+   * timeout and are retried up to 3 times on HTTP 408.
+   *
+   * @param action - Action type, target, and action-specific arguments.
+   * @param options - Override failure handling for this call; otherwise use the session setting.
+   * @returns The execution response, including `success` and failure details when throwing is disabled.
+   * @throws ActionExecutionError if the action fails and failure throwing is enabled.
+   * @throws NotteAPIError if the API request fails.
+   * @example
+   * import { actions } from 'notte-sdk';
+   *
+   * await session.execute({ type: 'goto', url: 'https://www.notte.cc' });
+   * await session.execute(actions.fill({ selector: "input[name='email']", value: 'user@example.com' }));
+   * const result = await session.execute({ type: 'click', id: 'B1' }, { raiseOnFailure: false });
+   * if (!result.success) console.log(result.message);
+   */
+  async execute(action, options = {}) {
+    const sessionId = this.requireSessionId();
+    const raiseOnFailure = typeof options === "boolean" ? options : options.raiseOnFailure ?? this.defaultRaiseOnFailure;
+    const isCaptcha = isCaptchaSolveAction(action);
+    let result;
+    let lastError;
+    for (let attempt = 0; attempt < CAPTCHA_SOLVE_TRIES; attempt += 1) {
+      try {
+        const response = await pageExecute({
+          client: this.client.getClient(),
+          path: { session_id: sessionId },
+          body: action,
+          headers: isCaptcha ? { [TIMEOUT_HEADER]: String(CAPTCHA_SOLVE_TIMEOUT_MS) } : void 0,
+          throwOnError: true
+        });
+        result = response.data;
+        break;
+      } catch (error) {
+        if (isCaptcha && error instanceof NotteAPIError && error.statusCode === 408) {
+          lastError = error;
+          console.warn("Solve captcha action timed out. This can happen for long and complex captchas. Retrying...");
+          continue;
         }
+        throw error;
+      }
+    }
+    if (!result) {
+      throw lastError ?? new Error(`Failed to execute action '${action.type}'. This should not happen. Please report this issue.`);
+    }
+    if (raiseOnFailure && !result.success) {
+      console.error(`\u{1F6A8} Execution failed with message: '${result.message}'`);
+      if (result.exception_detail) {
+        throw new ActionExecutionError(result.exception_detail);
       }
+      const fallbackMessage = String(result.message ?? "").trim() || `Failed to execute action: ${action.type}`;
+      throw ActionExecutionError.fromMessage(fallbackMessage);
+    }
+    return result;
+  }
+  async evaluateJs(code, options = {}) {
+    const raiseOnFailure = options.raiseOnFailure ?? true;
+    const result = await this.execute({ type: "evaluate_js", code }, { raiseOnFailure });
+    if (!raiseOnFailure) {
+      return result;
+    }
+    if (!result.data) {
+      throw new EvaluateJsNoDataError();
+    }
+    return result.data.markdown;
+  }
+  /**
+   * Issue an HTTP request from the page the session is on and return the response.
+   *
+   * The request runs inside the browser through `fetch()`, so it carries the
+   * page's cookies, the session's proxy and the browser's own network
+   * fingerprint. A relative `url` resolves against the current page, which
+   * also makes it same-origin; a cross-origin URL is subject to CORS exactly
+   * as in a browser tab, so `goto` the target origin first. Redirects are
+   * followed and the final URL is on `response.url`. A non-2xx status is
+   * returned, not thrown; `response.raiseForStatus()` throws `PageFetchHTTPError`.
+   *
+   * `json` is serialised as the body with an `application/json` content type,
+   * `data` as a form body when it is an object or verbatim when it is a string.
+   *
+   * @param url - Absolute URL or a path relative to the current page.
+   * @param options - HTTP method, headers, and request body settings.
+   * @returns A response with status, headers, and body readers. Non-2xx responses are not automatically thrown.
+   * @throws ActionExecutionError if browser-side execution fails.
+   * @example
+   * await session.execute({ type: 'goto', url: 'https://en.wikipedia.org/wiki/Main_Page' });
+   * const summary = await (await session.fetch('/api/rest_v1/page/summary/Main_Page')).json();
+   */
+  async fetch(url, options = {}) {
+    const script = buildFetchScript(url, options);
+    return responseFromEvaluated(await this.evaluateJs(script));
+  }
+  /**
+   * Observe the current page: the list of actions that can be taken, a
+   * screenshot and page metadata.
+   *
+   * The `perception_type` defaults to the session option (`fast`). A bare
+   * string argument is accepted as the perception type.
+   *
+   * @param options - Observation settings, including an optional URL, or a perception-mode string.
+   * @returns Structured page analysis, available actions, and page metadata.
+   * @throws NotteAPIError if observation fails.
+   * @example
+   * const obs = await session.observe();
+   * console.log(obs.space.description);
+   * const deep = await session.observe({ perception_type: 'deep', max_nb_actions: 50 });
+   */
+  async observe(options = {}) {
+    const body = typeof options === "string" ? { perception_type: options } : { ...options };
+    if (body.perception_type == null) {
+      body.perception_type = this.defaultPerceptionType;
     }
+    const response = await pageObserve({
+      client: this.client.getClient(),
+      path: { session_id: this.requireSessionId() },
+      body,
+      throwOnError: true
+    });
+    return response.data;
+  }
+  async scrape(options = {}) {
+    const sessionId = this.requireSessionId();
+    const body = await buildScrapeBody(options);
     const response = await pageScrape({
       client: this.client.getClient(),
-      path: {
-        session_id: this.sessionId
-      },
-      body: apiOptions
+      path: { session_id: sessionId },
+      body,
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to scrape page: ${JSON.stringify(response.error)}`);
-    }
     return processScrapeResponse(response.data, options);
   }
+  // #######################################################################
+  // ############################# Lifecycle ###############################
+  // #######################################################################
   /**
-   * Context manager pattern - automatically start and stop session
-   * Usage: await session.use(async (session) => { ... })
+   * Context manager pattern: start the session, run the callback and stop the
+   * session, with close reason `error` when the callback throws.
+   *
+   * @param callback - Async work to perform with the started session.
+   * @returns The callback's return value after session cleanup has been attempted.
+   * @throws Error if startup fails, the callback throws, or cleanup fails after a successful callback.
+   * @example
+   * await client.Session().use(async session => {
+   *   await session.execute({ type: 'goto', url: 'https://www.notte.cc' });
+   * });
    */
   async use(callback) {
     await this.start();
@@ -1878,6 +2772,7 @@ var Session = class {
       return await callback(this);
     } catch (error) {
       callbackFailed = true;
+      console.warn(`Session exiting because of exception: ${String(error)}`);
       throw error;
     } finally {
       try {
@@ -1891,8 +2786,13 @@ var Session = class {
     }
   }
   /**
-   * Async iterator pattern for session lifecycle management
-   * Usage: for await (const session of sessionInstance) { ... }
+   * Async iterator pattern for session lifecycle management.
+   *
+   * ```ts
+   * for await (const session of client.Session()) {
+   *   await session.execute({ type: 'goto', url: 'https://www.notte.cc' });
+   * }
+   * ```
    */
   async *[Symbol.asyncIterator]() {
     await this.start();
@@ -1906,12 +2806,12 @@ var Session = class {
 
 // src/agent.ts
 import WebSocket from "ws";
-import { z as z2 } from "zod";
+import { z } from "zod";
 function prepareAgentRequest(data) {
   const apiData = { ...data };
   const rf = data.response_format;
   if (rf && typeof rf.parse === "function" && typeof rf.safeParse === "function") {
-    apiData.response_format = z2.toJSONSchema(rf);
+    apiData.response_format = z.toJSONSchema(rf);
     return { apiData, zodSchema: rf };
   }
   return { apiData, zodSchema: null };
@@ -2017,9 +2917,12 @@ var defaultStepLogger = (stepData, stepCounter, agentId) => {
   console.log("");
 };
 var Agent = class {
+  client;
+  request;
+  response = null;
+  websocket = null;
+  existingAgent;
   constructor(client2, options) {
-    this.response = null;
-    this.websocket = null;
     this.client = client2;
     if ("agent_id" in options && options.agent_id) {
       if (options.session) {
@@ -2106,22 +3009,29 @@ var Agent = class {
     if (!this.response) {
       throw new Error("Agent not started");
     }
+    const deadline = Date.now() + 3e5;
     try {
-      const result = await this.watchLogs(log, updateHandler);
-      if (result) {
+      const result = await this.watchLogs(log, updateHandler, deadline);
+      if (result && result.status !== "active") {
         return result;
       }
-      await new Promise((resolve) => setTimeout(resolve, 3e3));
-      return await this.status();
     } catch (error) {
-      console.error(`[Agent] ${this.agentId} failed to complete in time. Try running agent.status() after a few seconds.`);
-      return await this.status();
+      console.warn(`[Agent] ${this.agentId} log stream unavailable; polling for completion.`);
+    }
+    while (Date.now() < deadline) {
+      const result = await this.status(AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+      if (result.status !== "active") {
+        updateHandler?.({ type: "completion", data: result, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+        return result;
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, 1e3));
     }
+    throw new Error(`Agent ${this.agentId} did not complete before the polling timeout; retrieve status() later.`);
   }
   /**
    * Watch logs via WebSocket - mirrors Python watch_logs method
    */
-  async watchLogs(log = true, updateHandler = null) {
+  async watchLogs(log = true, updateHandler = null, deadline = Date.now() + 3e5) {
     if (this.existingAgent) {
       throw new Error("You cannot call watchLogs() on an agent instantiated from agent id");
     }
@@ -2129,18 +3039,39 @@ var Agent = class {
       throw new Error("Agent not started");
     }
     const config = this.client.getConfig();
-    const token = config.apiKey;
+    if (config.baseUrl?.startsWith("/")) return null;
     const agentId = this.response.agent_id;
     const sessionId = this.response.session_id;
-    const wsUrl = config.baseUrl?.replace("https://", "wss://").replace("http://", "ws://") + `/agents/${agentId}/debug/logs?token=${token}&session_id=${sessionId}`;
-    return new Promise((resolve, reject) => {
+    const debug = await sessionDebugInfo({
+      client: this.client.getClient(),
+      path: { session_id: sessionId },
+      throwOnError: true,
+      signal: AbortSignal.timeout(Math.max(1, deadline - Date.now()))
+    });
+    const wsUrl = new URL(this.client.withDbPreview(debug.data.ws.logs));
+    const token = wsUrl.searchParams.get("token");
+    if (!token || token === config.apiKey || wsUrl.protocol !== "wss:") return null;
+    wsUrl.pathname = `/agents/${encodeURIComponent(agentId)}/debug/logs`;
+    wsUrl.searchParams.set("session_id", sessionId);
+    return new Promise((resolve3, reject) => {
       this.websocket = new WebSocket(wsUrl);
+      const socket = this.websocket;
+      const timeout = setTimeout(() => finish(null), Math.max(0, deadline - Date.now()));
+      let settled = false;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        if (this.websocket === socket) this.websocket = null;
+        if (socket.readyState !== WebSocket.CLOSED) socket.terminate();
+        resolve3(result);
+      };
       let counter = 0;
       this.websocket.on("open", () => {
       });
       this.websocket.on("error", (error) => {
         console.error(`Connection error: ${agentId} ${error.message}`);
-        resolve(null);
+        finish(null);
       });
       this.websocket.on("message", (data) => {
         try {
@@ -2162,8 +3093,7 @@ var Agent = class {
             } else if (!finalStatus.success) {
               console.error(finalStatus.answer);
             }
-            this.disconnectWebSocket();
-            resolve(finalStatus);
+            finish(finalStatus);
             return;
           }
           if (log) {
@@ -2183,26 +3113,20 @@ var Agent = class {
         }
       });
       this.websocket.on("close", () => {
-        this.websocket = null;
-        resolve(null);
+        finish(null);
       });
-      setTimeout(() => {
-        if (this.websocket && this.websocket.readyState === WebSocket.OPEN) {
-          this.disconnectWebSocket();
-          resolve(null);
-        }
-      }, 3e5);
     });
   }
   /**
    * Get agent status - mirrors Python status method
    */
-  async status() {
+  async status(signal) {
     if (!this.response) {
       throw new Error("Agent not started or not accessible");
     }
     const response = await agentStatus({
       client: this.client.getClient(),
+      signal,
       path: {
         agent_id: this.response.agent_id
       }
@@ -2271,24 +3195,126 @@ var Agent = class {
     return this.response.session_id;
   }
   /**
-   * Check if agent is running - convenience method
+   * Whether `start()`/`run()` was called on this instance (or it was built from an agent id).
+   * This is a local check and does not contact the API.
    */
-  isRunning() {
+  hasStarted() {
     return this.response !== null;
   }
+  /**
+   * Whether the agent is still active on the server. Fetches the current status,
+   * like calling `agent.status()` in Python; an agent that was never started is not active.
+   */
+  async isActive() {
+    if (!this.response) {
+      return false;
+    }
+    const status = await this.status();
+    return status.status === "active";
+  }
+  /**
+   * @deprecated Only reports whether this instance was started; it does not
+   * contact the API. Use `hasStarted()` for that check or `isActive()` for the
+   * live server status.
+   */
+  isRunning() {
+    return this.hasStarted();
+  }
 };
 
 // src/vaults.ts
+import { getDomain } from "tldts";
+var CREDENTIAL_FIELDS = ["email", "username", "mfa_secret", "password"];
+function extractHostname(url) {
+  const trimmed = url.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+  const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
+  const candidates = hasScheme ? [trimmed] : [`https://${trimmed}`];
+  for (const candidate of candidates) {
+    try {
+      const { hostname } = new URL(candidate);
+      if (hostname.length > 0 && !hostname.startsWith(".")) {
+        return hostname.toLowerCase();
+      }
+    } catch {
+    }
+  }
+  return "";
+}
+function getRootDomain(url) {
+  const hostname = extractHostname(url);
+  if (hostname.length === 0) {
+    return "";
+  }
+  if (hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) {
+    return hostname;
+  }
+  const domain = getDomain(hostname, { allowPrivateDomains: false, detectIp: false });
+  if (domain) {
+    return domain.toLowerCase();
+  }
+  return hostname.toLowerCase();
+}
+function validateUrl(url) {
+  const domain = getRootDomain(url);
+  if (domain.length === 0) {
+    throw new InvalidRequestError(`Invalid URL: ${url}. Please provide a valid URL with a domain name.`);
+  }
+  return domain;
+}
+function isValidMfaSecret(secret) {
+  if (secret.length === 0) {
+    return false;
+  }
+  let padded = secret.toUpperCase();
+  if (padded.length % 8 !== 0) {
+    padded += "=".repeat(8 - padded.length % 8);
+  }
+  let end = padded.length;
+  while (end > 0 && padded[end - 1] === "=") {
+    end -= 1;
+  }
+  const stripped = padded.slice(0, end);
+  const padding = padded.length - stripped.length;
+  return /^[A-Z2-7]*$/.test(stripped) && [0, 1, 3, 4, 6].includes(padding);
+}
+function validateMfaSecret(secret) {
+  if (!isValidMfaSecret(secret)) {
+    throw new InvalidRequestError("Invalid MFA secret code: did you try to store an OTP instead of a secret?");
+  }
+}
+function validateCredentials(credentials) {
+  const hasUsername = credentials.username !== void 0 && credentials.username !== null;
+  const hasEmail = credentials.email !== void 0 && credentials.email !== null;
+  if (hasUsername && hasEmail) {
+    throw new InvalidRequestError("Can only set either username or email");
+  }
+  if (!hasUsername && !hasEmail) {
+    throw new InvalidRequestError("Need to have either username or email set");
+  }
+  if (credentials.mfa_secret !== void 0 && credentials.mfa_secret !== null) {
+    validateMfaSecret(credentials.mfa_secret);
+  }
+  return credentials;
+}
 var NotteVault = class {
+  client;
+  _vaultId = null;
+  initPromise = null;
+  createData = null;
   constructor(client2, options = {}) {
-    this._vaultId = null;
-    this.initPromise = null;
-    this.createData = null;
     this.client = client2;
-    if (options && "vault_id" in options && options.vault_id) {
+    if (options && "vault_id" in options && options.vault_id !== void 0) {
+      if (options.vault_id.length === 0) {
+        throw new InvalidRequestError("Vault ID cannot be empty");
+      }
       this.initPromise = this.initExistingVault(options.vault_id);
+      this.initPromise.catch(() => void 0);
     } else {
-      this.createData = options || {};
+      const { vault_id: _ignored, ...createData } = options ?? {};
+      this.createData = createData;
     }
   }
   async initExistingVault(vaultId) {
@@ -2299,29 +3325,20 @@ var NotteVault = class {
   async initNewVault(createData) {
     const response = await vaultCreate({
       client: this.client.getClient(),
-      body: createData
+      body: createData,
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to create vault: ${formatError(response.error)}`);
-    }
     const vault = response.data;
     console.warn(`[Vault] ${vault.vault_id} created since no vault id was provided. Please store this to retrieve it later.`);
     this._vaultId = vault.vault_id;
     return this._vaultId;
   }
   async verifyVaultExists(vaultId) {
-    if (vaultId.length === 0) {
-      throw new Error("Vault ID cannot be empty");
-    }
-    const response = await vaultCredentialsList({
+    await vaultCredentialsList({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      }
+      path: { vault_id: vaultId },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to verify vault exists: ${formatError(response.error)}`);
-    }
   }
   async ensureInitialized() {
     if (this._vaultId) {
@@ -2336,257 +3353,215 @@ var NotteVault = class {
       this.initPromise = this.initNewVault(createData);
       return await this.initPromise;
     }
-    throw new Error("Vault not initialized");
+    throw new InvalidRequestError("Vault not initialized");
   }
+  /** ID of the remote vault. Throws until the first API operation has created or verified it. */
   get vaultId() {
     if (!this._vaultId) {
-      throw new Error("Vault not initialized. Use await on vault operations first.");
+      throw new InvalidRequestError("Vault not initialized. Await a vault operation first.");
     }
     return this._vaultId;
   }
   /**
-   * Start the vault - no-op for compatibility with Python interface
+   * Start the vault. No-op kept for parity with Python's `SyncResource` interface.
    */
   start() {
   }
   /**
-   * Stop the vault - deletes it and all credentials
+   * Stop the vault: deletes it together with every credential it holds.
+   *
+   * ```ts
+   * await vault.stop();
+   * ```
    */
   async stop() {
     const vaultId = await this.ensureInitialized();
-    console.log(`[Vault] ${vaultId} deleted. All credentials have been deleted.`);
+    console.info(`[Vault] ${vaultId} deleted. All credentials have been deleted.`);
     await this.delete();
   }
   /**
-   * Add or update credentials for a URL
+   * Add or update the credentials stored for a website. The URL is reduced to
+   * its root domain (`https://github.com/login` → `github.com`) before it is
+   * sent, like Python's `AddCredentialsRequest`.
+   *
+   * ```ts
+   * await vault.addCredentials('https://github.com/', {
+   *   email: 'me@example.org',
+   *   password: 'secret', // pragma: allowlist secret
+   *   mfa_secret: 'JBSWY3DPEHPK3PXP', // pragma: allowlist secret
+   * });
+   * ```
    */
   async addCredentials(url, credentials) {
-    if (credentials.mfa_secret) {
-      this.validateMfaSecret(credentials.mfa_secret);
-    }
+    const domain = validateUrl(url);
+    validateCredentials(credentials);
     const vaultId = await this.ensureInitialized();
-    const response = await vaultCredentialsAdd({
+    await vaultCredentialsAdd({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      },
-      body: { url, credentials }
+      path: { vault_id: vaultId },
+      body: { url: domain, credentials },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to add credentials: ${formatError(response.error)}`);
-    }
   }
   /**
-   * Get credentials for a URL
+   * Get the credentials stored for a website. Rejects with a `NotteAPIError`
+   * when the vault holds no credentials for that domain, like Python's
+   * `get_credentials`.
+   *
+   * ```ts
+   * const { email, password } = await vault.getCredentials('https://github.com/login');
+   * ```
    */
   async getCredentials(url) {
-    try {
-      const vaultId = await this.ensureInitialized();
-      const response = await vaultCredentialsGet({
-        client: this.client.getClient(),
-        path: {
-          vault_id: vaultId
-        },
-        query: { url }
-      });
-      if (response?.error) {
-        return null;
-      }
-      const credentialsResponse = response.data;
-      return credentialsResponse.credentials;
-    } catch (error) {
-      return null;
-    }
-  }
-  /**
-   * Delete credentials for a URL
-   */
-  async deleteCredentials(url) {
+    const domain = validateUrl(url);
     const vaultId = await this.ensureInitialized();
-    const response = await vaultCredentialsDelete({
+    const response = await vaultCredentialsGet({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      },
-      query: { url }
+      path: { vault_id: vaultId },
+      query: { url: domain },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to delete credentials: ${formatError(response.error)}`);
-    }
+    return response.data.credentials;
   }
   /**
-   * Set credit card information
+   * Check whether the vault holds credentials for a website, the counterpart
+   * of `BaseVault.has_credential`. Never rejects for a missing credential.
+   *
+   * ```ts
+   * if (!(await vault.hasCredential('https://github.com/'))) {
+   *   await vault.addCredentialsFromEnv('https://github.com/');
+   * }
+   * ```
    */
-  async setCreditCard(creditCard) {
-    const vaultId = await this.ensureInitialized();
-    const response = await vaultCreditCardSet({
-      client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      },
-      body: { credit_card: creditCard }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to set credit card: ${formatError(response.error)}`);
-    }
+  async hasCredential(url) {
+    const domain = getRootDomain(url);
+    const credentials = await this.listCredentials();
+    return credentials.some((credential) => credential.url === url || credential.url === domain);
   }
   /**
-   * Get credit card information
+   * Delete the credentials stored for a website.
+   *
+   * ```ts
+   * await vault.deleteCredentials('https://github.com/');
+   * ```
    */
-  async getCreditCard() {
+  async deleteCredentials(url) {
+    const domain = validateUrl(url);
     const vaultId = await this.ensureInitialized();
-    const response = await vaultCreditCardGet({
+    await vaultCredentialsDelete({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      }
+      path: { vault_id: vaultId },
+      query: { url: domain },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to get credit card: ${formatError(response.error)}`);
-    }
-    const creditCardResponse = response.data;
-    return creditCardResponse.credit_card;
   }
   /**
-   * List all credentials in the vault
+   * List the websites the vault holds credentials for. Passwords are never returned.
+   *
+   * ```ts
+   * const credentials = await vault.listCredentials();
+   * console.log(credentials.map(c => c.url));
+   * ```
    */
   async listCredentials() {
     const vaultId = await this.ensureInitialized();
     const response = await vaultCredentialsList({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to list credentials: ${formatError(response.error)}`);
-    }
-    const credentialsResponse = response.data;
-    return credentialsResponse.credentials;
-  }
-  /**
-   * Delete credit card information
-   */
-  async deleteCreditCard() {
-    const vaultId = await this.ensureInitialized();
-    const response = await vaultCreditCardDelete({
-      client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      }
+      path: { vault_id: vaultId },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to delete credit card: ${formatError(response.error)}`);
-    }
+    return response.data.credentials;
   }
   /**
-   * Delete the entire vault
+   * Delete the vault and every credential it holds.
    */
   async delete() {
     const vaultId = await this.ensureInitialized();
-    const response = await vaultDelete({
+    await vaultDelete({
       client: this.client.getClient(),
-      path: {
-        vault_id: vaultId
-      }
+      path: { vault_id: vaultId },
+      throwOnError: true
     });
-    if (response?.error) {
-      throw new Error(`Failed to delete vault: ${formatError(response.error)}`);
-    }
   }
   /**
-   * Add credentials from environment variables
-   * Mirrors Python's add_credentials_from_env method
+   * Add credentials read from environment variables, the counterpart of
+   * `BaseVault.add_credentials_from_env`. For `https://github.com/` the
+   * variables are `GITHUB_COM_EMAIL`, `GITHUB_COM_USERNAME`,
+   * `GITHUB_COM_MFA_SECRET` and `GITHUB_COM_PASSWORD`.
+   *
+   * ```ts
+   * process.env.GITHUB_COM_EMAIL = 'me@example.org';
+   * process.env.GITHUB_COM_PASSWORD = 'secret'; // pragma: allowlist secret
+   * await vault.addCredentialsFromEnv('https://github.com/');
+   * ```
    */
   async addCredentialsFromEnv(url) {
-    const domain = this.extractDomainFromUrl(url);
-    const envPrefix = domain.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase();
-    const email = process.env[`${envPrefix}_EMAIL`] || process.env[`${envPrefix}_USERNAME`];
-    const password = process.env[`${envPrefix}_PASSWORD`];
-    if (!email || !password) {
-      throw new Error(`Environment variables ${envPrefix}_EMAIL/USERNAME and ${envPrefix}_PASSWORD are required`);
-    }
-    const credentials = { email, password };
-    const mfaSecret = process.env[`${envPrefix}_MFA_SECRET`];
-    if (mfaSecret) {
-      this.validateMfaSecret(mfaSecret);
-      credentials.mfa_secret = mfaSecret;
+    const rootDomain = validateUrl(url);
+    const prefix = rootDomain.replace(/\./g, "_").toUpperCase();
+    const credentials = {};
+    const variableNames = [];
+    for (const field of CREDENTIAL_FIELDS) {
+      const variable = `${prefix}_${field.toUpperCase()}`;
+      variableNames.push(variable);
+      const value = process.env[variable];
+      if (value !== void 0) {
+        credentials[field] = value;
+      }
+    }
+    if (Object.keys(credentials).length === 0) {
+      throw new InvalidRequestError(
+        `No credentials found in the environment for ${url}. Please set the following variables: ${variableNames.join(", ")}`
+      );
     }
     await this.addCredentials(url, credentials);
   }
   /**
-   * Extract domain from URL for environment variable naming
+   * Generate a secure random password, the counterpart of Python's
+   * `generate_password`. The result always contains a lowercase letter, an
+   * uppercase letter and a digit, plus a special character unless
+   * `includeSpecialChars` is false.
+   *
+   * ```ts
+   * const password = vault.generatePassword(24);
+   * ```
    */
-  extractDomainFromUrl(url) {
-    try {
-      const urlObj = new URL(url);
-      return urlObj.hostname.replace(/^www\./, "");
-    } catch {
-      const match = url.match(/(?:https?:\/\/)?(?:www\.)?([^\/]+)/);
-      return match ? match[1] : url;
-    }
-  }
-  /**
-   * Validate MFA secret format
-   * Mirrors Python's MFA secret validation
-   */
-  validateMfaSecret(mfaSecret) {
-    if (/^\d+$/.test(mfaSecret)) {
-      throw new Error("MFA secret cannot be all numbers. Please provide a valid base32 secret.");
-    }
-    if (mfaSecret.length < 16) {
-      throw new Error("MFA secret must be at least 16 characters long");
-    }
-  }
-  /**
-   * Generate a secure random password
-   * Mirrors Python's generate_password method
-   */
-  generatePassword(length = 20, includeSpecialChars = true) {
-    const minRequiredLength = includeSpecialChars ? 4 : 3;
-    if (length < minRequiredLength) {
-      throw new Error(`Password length must be at least ${minRequiredLength} characters`);
+  generatePassword(length = 20, includeSpecialChars = true) {
+    const minRequiredLength = includeSpecialChars ? 4 : 3;
+    if (length < minRequiredLength) {
+      throw new InvalidRequestError(`Password length must be at least ${minRequiredLength} characters`);
     }
     const lowercase = "abcdefghijklmnopqrstuvwxyz";
     const uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
     const digits = "0123456789";
     const specialChars = "!@#$%^&*()_+-=[]|;:,.<>?";
-    const crypto = globalThis.crypto || __require("crypto");
-    const array = new Uint8Array(length);
-    crypto.getRandomValues(array);
-    const allowedChars = includeSpecialChars ? "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_" : "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-    let password = Array.from(array, (byte) => allowedChars[byte % allowedChars.length]).join("").slice(0, length);
-    const passwordArray = password.split("");
-    if (!includeSpecialChars) {
-      for (let i = 0; i < passwordArray.length; i++) {
-        if (specialChars.includes(passwordArray[i])) {
-          const alphanumeric = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-          passwordArray[i] = alphanumeric[Math.floor(Math.random() * alphanumeric.length)];
+    const alphanumeric = uppercase + lowercase + digits;
+    const allowedChars = includeSpecialChars ? `${alphanumeric}-_` : alphanumeric;
+    const randomIndex = (size) => {
+      const limit = Math.floor(4294967296 / size) * size;
+      const buffer = new Uint32Array(1);
+      for (; ; ) {
+        const [value] = globalThis.crypto.getRandomValues(buffer);
+        if (value < limit) {
+          return value % size;
         }
       }
-    }
+    };
+    const passwordArray = Array.from({ length }, () => allowedChars[randomIndex(allowedChars.length)]);
+    const pick = (chars) => chars[randomIndex(chars.length)];
     let maxIterations = 10;
     while (maxIterations-- > 0) {
       let allRequirementsMet = true;
-      if (!passwordArray.some((c) => lowercase.includes(c))) {
-        const index = Math.floor(Math.random() * passwordArray.length);
-        passwordArray[index] = lowercase[Math.floor(Math.random() * lowercase.length)];
-        allRequirementsMet = false;
-      }
-      if (!passwordArray.some((c) => uppercase.includes(c))) {
-        const index = Math.floor(Math.random() * passwordArray.length);
-        passwordArray[index] = uppercase[Math.floor(Math.random() * uppercase.length)];
-        allRequirementsMet = false;
-      }
-      if (!passwordArray.some((c) => digits.includes(c))) {
-        const index = Math.floor(Math.random() * passwordArray.length);
-        passwordArray[index] = digits[Math.floor(Math.random() * digits.length)];
-        allRequirementsMet = false;
-      }
-      if (includeSpecialChars && !passwordArray.some((c) => specialChars.includes(c))) {
-        const index = Math.floor(Math.random() * passwordArray.length);
-        passwordArray[index] = specialChars[Math.floor(Math.random() * specialChars.length)];
-        allRequirementsMet = false;
+      const requirements = [
+        [true, lowercase],
+        [true, uppercase],
+        [true, digits],
+        [includeSpecialChars, specialChars]
+      ];
+      for (const [required, chars] of requirements) {
+        if (required && !passwordArray.some((c) => chars.includes(c))) {
+          passwordArray[randomIndex(passwordArray.length)] = pick(chars);
+          allRequirementsMet = false;
+        }
       }
       if (allRequirementsMet) {
         break;
@@ -2598,10 +3573,15 @@ var NotteVault = class {
 
 // src/personas.ts
 var NottePersona = class {
+  client;
+  _initRequest;
+  response = null;
+  initPromise = null;
+  _vault;
+  ownsPersona;
   constructor(client2, options = {}) {
-    this.response = null;
-    this.initPromise = null;
     this.client = client2;
+    this.ownsPersona = !("persona_id" in options && options.persona_id);
     if (options && "persona_id" in options && options.persona_id) {
       this.initPromise = this.initExistingPersona(options.persona_id);
       this._initRequest = {};
@@ -2702,9 +3682,7 @@ var NottePersona = class {
    * Start the persona - ensures initialization
    */
   async start() {
-    if (this.response === null) {
-      await this.create();
-    }
+    await this.ensureInitialized();
   }
   /**
    * Stop the persona - deletes it
@@ -2730,14 +3708,7 @@ var NottePersona = class {
     if (this.response !== null) {
       throw new Error(`Persona ${this.personaId} already initialized`);
     }
-    const response = await personaCreate({
-      client: this.client.getClient(),
-      body: this._initRequest
-    });
-    if (response?.error) {
-      throw new Error(`Failed to create persona: ${formatError(response.error)}`);
-    }
-    this.response = response.data;
+    await this.ensureInitialized();
   }
   /**
    * Delete the persona from the notte console
@@ -2813,13 +3784,15 @@ var NottePersona = class {
     return this.response;
   }
   /**
-   * Context manager for automatic cleanup
+   * Run a callback and automatically delete a persona created by this instance.
+   * Personas loaded by an existing ID are retained after the callback finishes.
    */
   async use(callback) {
+    await this.ensureInitialized();
     try {
       return await callback(this);
     } finally {
-      if (this._initRequest && !("persona_id" in this._initRequest)) {
+      if (this.ownsPersona) {
         try {
           await this.delete();
         } catch (error) {
@@ -2831,7 +3804,8 @@ var NottePersona = class {
 };
 
 // src/functions.ts
-import { writeFile } from "fs/promises";
+import { readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
+import { basename } from "path";
 
 // src/encryption.ts
 import { createDecipheriv, createHmac, pbkdf2Sync, timingSafeEqual } from "crypto";
@@ -2843,6 +3817,7 @@ var FERNET_IV_LENGTH = 16;
 var FERNET_HMAC_LENGTH = 32;
 var FERNET_HEADER_LENGTH = 1 + 8 + FERNET_IV_LENGTH;
 var Encryption = class {
+  rootKey;
   constructor(rootKey) {
     if (!rootKey) {
       throw new Error("Root key cannot be empty");
@@ -2884,141 +3859,385 @@ function decryptFernet(token, key) {
 
 // src/functions.ts
 var DOWNLOAD_TIMEOUT_MS = 3e4;
+var FUNCTION_RUN_TIMEOUT_MS = 5 * 60 * 1e3;
+var FUNCTION_RUN_ENDPOINTS = {
+  /** `POST` creates a run record without executing it (`CreateFunctionRunRequest`). */
+  create: "/functions/{function_id}/runs/create",
+  /** `POST` executes a previously created run (`StartFunctionRunRequest`). */
+  start: "/functions/{function_id}/runs/{run_id}"
+};
+var RUN_API_KEY_HEADER = "x-notte-api-key";
+var FUNCTION_RUNTIMES = ["standard", "extended"];
+var FUNCTION_RUN_STATUSES = ["closed", "active", "failed"];
 var NotteFunction = class {
+  client;
+  _functionId = null;
+  initPromise = null;
+  createData = null;
+  decryptionKey;
   constructor(client2, options) {
     this.client = client2;
-    this.functionId = options.function_id;
     this.decryptionKey = options.decryption_key;
+    if (options.function_id !== void 0) {
+      if (options.function_id.length === 0) {
+        throw new InvalidRequestError("function_id cannot be empty");
+      }
+      this._functionId = options.function_id;
+    } else if (options.path !== void 0) {
+      assertPythonPath(options.path);
+      this.createData = options;
+    } else {
+      throw new InvalidRequestError("Either 'function_id' or 'path' must be provided");
+    }
+  }
+  /** The function ID. Throws before a `path`-constructed function has been uploaded. */
+  get functionId() {
+    if (this._functionId === null) {
+      throw new InvalidRequestError(
+        "Function not initialized. Await a function operation (for example `await fn.get()`) before reading its ID."
+      );
+    }
+    return this._functionId;
+  }
+  /** Alias of the `functionId` accessor. */
+  getFunctionId() {
+    return this.functionId;
+  }
+  async ensureInitialized() {
+    if (this._functionId !== null) {
+      return this._functionId;
+    }
+    if (this.initPromise === null) {
+      const createData = this.createData;
+      this.createData = null;
+      if (createData === null) {
+        throw new InvalidRequestError("Function not initialized");
+      }
+      this.initPromise = this.createFunction(createData);
+    }
+    return this.initPromise;
+  }
+  async createFunction(data) {
+    const file = await readPythonFile(data.path);
+    const response = await functionCreate({
+      client: this.client.getClient(),
+      throwOnError: true,
+      body: { file, name: data.name, description: data.description, shared: data.shared }
+    });
+    this._functionId = response.data.function_id;
+    console.info(`[Function] ${this._functionId} created successfully.`);
+    return this._functionId;
   }
   /**
-   * Get metadata for a specific function run
+   * Get the function metadata together with its download URL, the
+   * counterpart of `client.functions.get()` in Python.
+   *
+   * @param options - Optional version selector; omitted means the latest version.
+   * @returns Function metadata, version history, and the download link returned by the API.
+   * @throws NotteAPIError if the function cannot be retrieved.
+   * @example
+   * const { latest_version, versions } = await fn.get();
    */
-  async retrieve(functionRunId) {
-    try {
-      const response = await functionRunGetMetadata({
-        client: this.client.getClient(),
-        path: {
-          function_id: this.functionId,
-          run_id: functionRunId
-        }
-      });
-      if (response?.error) {
-        throw new Error(`Failed to get function run metadata: ${formatError(response.error)}`);
-      }
-      return response.data;
-    } catch (error) {
-      if (error instanceof Error && error.message.startsWith("Failed to get function run metadata:")) {
-        throw error;
-      }
-      throw new Error(`Failed to get function run metadata: ${error instanceof Error ? error.message : String(error)}`);
+  async get(options = {}) {
+    const functionId = await this.ensureInitialized();
+    const response = await functionDownloadUrl({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      query: options.version !== void 0 ? { version: options.version } : {}
+    });
+    return response.data;
+  }
+  /**
+   * Upload a new version of the code, mirroring `function.update(path=...)`.
+   *
+   * @param options - Local Python file path, optional version, and code-access settings.
+   * @returns Updated function metadata, including its latest version.
+   * @throws InvalidRequestError if the path is missing or does not end in `.py`.
+   * @throws NotteAPIError if the upload is rejected.
+   * @example
+   * const updated = await fn.update({ path: './scraper.py' });
+   * console.log(updated.latest_version);
+   */
+  async update(options) {
+    if (options.path === void 0) {
+      throw new InvalidRequestError("'path' must be provided");
     }
+    const functionId = await this.ensureInitialized();
+    const file = await readPythonFile(options.path);
+    const response = await functionUpdate({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      query: {
+        restricted: options.restricted ?? true,
+        ...options.version !== void 0 ? { version: options.version } : {}
+      },
+      body: { file }
+    });
+    console.info(`[Function] ${functionId} updated successfully to version ${response.data.latest_version}.`);
+    return response.data;
+  }
+  /**
+   * Update the function metadata (name, description, default runtime, ...).
+   *
+   * @param options - Metadata fields to update, such as name, description, or default runtime.
+   * @returns Updated function metadata.
+   * @throws NotteAPIError if the metadata update is rejected.
+   * @example
+   * await fn.updateMetadata({ name: 'Price monitor', default_runtime: 'extended' });
+   */
+  async updateMetadata(options) {
+    const functionId = await this.ensureInitialized();
+    const response = await functionMetadataUpdate({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      body: options
+    });
+    return response.data;
+  }
+  /**
+   * Delete the function from the Notte console.
+   *
+   * @returns The API's function-deletion confirmation.
+   * @throws NotteAPIError if the function cannot be deleted.
+   * @example
+   * await fn.delete();
+   */
+  async delete() {
+    const functionId = await this.ensureInitialized();
+    const response = await functionDelete({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId }
+    });
+    console.info(`[Function] ${functionId} deleted successfully.`);
+    return response.data;
+  }
+  /**
+   * Schedule the function to run on a cron expression.
+   *
+   * @param options - Cron expression and optional variables passed to each scheduled execution.
+   * @returns The saved schedule configuration.
+   * @throws NotteAPIError if the schedule cannot be saved.
+   * @example
+   * await fn.setSchedule({ cron: '0 9 * * *', variables: { url: 'https://example.com' } });
+   */
+  async setSchedule(options) {
+    const functionId = await this.ensureInitialized();
+    const response = await functionScheduleSet({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      body: { cron: options.cron, variables: options.variables ?? null }
+    });
+    return response.data;
+  }
+  /**
+   * Remove the function schedule.
+   *
+   * @returns The API's schedule-deletion confirmation.
+   * @throws NotteAPIError if schedule deletion fails.
+   * @example
+   * await fn.deleteSchedule();
+   */
+  async deleteSchedule() {
+    const functionId = await this.ensureInitialized();
+    const response = await functionScheduleDelete({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId }
+    });
+    return response.data;
+  }
+  /**
+   * Roll the function back to a previous version.
+   *
+   * @param options - Target version and optional code-access restriction, which defaults to true.
+   * @returns Updated function metadata after rollback.
+   * @throws NotteAPIError if the requested version cannot be restored.
+   * @example
+   * const { versions } = await fn.get();
+   * await fn.rollback({ version: versions[0] });
+   */
+  async rollback(options) {
+    const functionId = await this.ensureInitialized();
+    const response = await functionRollback({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      query: { restricted: options.restricted ?? true },
+      body: { version: options.version }
+    });
+    return response.data;
+  }
+  /**
+   * Get metadata for a specific function run.
+   *
+   * @param functionRunId - ID of a run belonging to this function.
+   * @returns The run's current status, logs, and result metadata. This does not wait for completion.
+   * @throws NotteAPIError if the run cannot be retrieved.
+   * @example
+   * const run = await fn.getRun(result.function_run_id);
+   * console.log(run.status, run.logs);
+   */
+  async getRun(functionRunId) {
+    const functionId = await this.ensureInitialized();
+    const response = await functionRunGetMetadata({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId, run_id: functionRunId }
+    });
+    return response.data;
+  }
+  /**
+   * Compatibility alias for getRun().
+   * @deprecated Use getRun() instead. Retained for backwards compatibility.
+   */
+  async retrieve(functionRunId) {
+    return this.getRun(functionRunId);
+  }
+  /**
+   * Create a cloud run record without starting execution, like
+   * `function.create_run()` in Python. Use this only when you need the ID
+   * before execution, then pass it to `run(variables, { functionRunId })`.
+   * `run()` otherwise creates a new run on its own.
+   *
+   * @param options - Run-record settings; `local` defaults to false. Node execution remains cloud-only.
+   * @returns A created run record and its ID. No function code has executed yet.
+   * @throws NotteAPIError if run creation is rejected.
+   * @example
+   * const created = await fn.createRun();
+   * const result = await fn.run({ url: 'https://example.com' }, { functionRunId: created.function_run_id });
+   */
+  async createRun(options = {}) {
+    const functionId = await this.ensureInitialized();
+    return this.postRunEndpoint({
+      url: FUNCTION_RUN_ENDPOINTS.create,
+      path: { function_id: functionId },
+      body: { local: options.local ?? false }
+    });
   }
   /**
    * List the runs of this function.
    *
-   * `only_active` is sent as `false` unless the caller says otherwise, and that
-   * is deliberate rather than redundant. `GET /functions/{function_id}/runs`
-   * now defaults it to `false` server-side as well, but it used to default to
-   * `true`: the request model was a bare subclass of the session one, where
-   * "only active" reads sensibly as "list my running sessions" and, for "list
-   * this function's runs", was a trap. Hitting the endpoint with no query
-   * parameters returned only the runs executing right now - an empty list for
-   * any function that had finished. That cost us a bug in the anything-api
-   * console, where a function with 15 recorded runs displayed "Nothing has run
-   * this endpoint yet".
-   *
-   * Sending it explicitly pins this method to the documented behaviour against
-   * whichever API version it is talking to, including deployments that predate
-   * the server-side change. Callers who want only in-flight runs pass
-   * `only_active: true`.
+   * Includes completed runs by default. Set `only_active: true` to retrieve
+   * only in-flight runs. Use the response pagination metadata to request
+   * additional pages.
+   *
+   * @param options - Pagination and filtering options. `only_active` defaults to false, including completed runs.
+   * @returns One page of run records and pagination metadata; additional pages require another call.
+   * @throws NotteAPIError if the run history cannot be retrieved.
+   * @example
+   * const { items } = await fn.runs({ page_size: 20 });
    */
   async runs(options = {}) {
-    try {
-      const response = await listFunctionRunsByFunctionId({
-        client: this.client.getClient(),
-        path: {
-          function_id: this.functionId
-        },
-        query: {
-          ...options,
-          only_active: options.only_active ?? false
-        }
-      });
-      if (response?.error) {
-        throw new Error(`Failed to list function runs: ${formatError(response.error)}`);
-      }
-      return response.data;
-    } catch (error) {
-      if (error instanceof Error && error.message.startsWith("Failed to list function runs:")) {
-        throw error;
-      }
-      throw new Error(`Failed to list function runs: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    const functionId = await this.ensureInitialized();
+    const response = await listFunctionRunsByFunctionId({
+      client: this.client.getClient(),
+      throwOnError: true,
+      path: { function_id: functionId },
+      query: { ...options, only_active: options.only_active ?? false }
+    });
+    return response.data;
   }
   /**
-   * Start a function run
+   * Run the function on the cloud and wait for its result, streaming logs by
+   * default like `function.run(**variables)` in Python.
+   *
+   * Pass `{ stream: false }` to receive the backend's JSON response without
+   * live logs; execution still blocks until completion. Pass `functionRunId`
+   * to execute a record returned by `createRun()`; otherwise a new run record
+   * is created first, exactly like Python. A failed execution throws
+   * `FailedToRunCloudFunctionError` unless `raiseOnFailure` is false, and the
+   * wait is aborted with `NotteTimeoutError` after `timeoutMs`.
+   *
+   * @param variables - JSON-serializable keyword arguments passed to the Python function's `run` entry point.
+   * @param options - Log streaming, failure handling, runtime, run ID, and timeout settings.
+   * @returns The completed execution response. The function's return value is in `result`. Disabling streaming still waits for completion.
+   * @throws FailedToRunCloudFunctionError if execution fails and `raiseOnFailure` is true.
+   * @throws NotteTimeoutError if the execution request exceeds `timeoutMs`.
+   * @throws InvalidRequestError if the run options are invalid.
+   * @example
+   * const result = await fn.run({ url: 'https://example.com' });
+   * console.log(result.result);
+   *
+   * await fn.run({ url: 'https://example.com' }, { runtime: 'extended', onLog: line => logger.info(line) });
    */
   async run(variables = {}, options = {}) {
-    const apiKey = this.client.getConfig().apiKey || "";
-    if (!apiKey) {
-      throw new Error("API key is required. Provide it via config.apiKey or set the NOTTE_API_KEY environment variable.");
-    }
+    const stream = options.stream ?? true;
+    const timeoutMs = options.timeoutMs ?? FUNCTION_RUN_TIMEOUT_MS;
+    if (!(timeoutMs > 0)) {
+      throw new InvalidRequestError("timeoutMs must be a positive number");
+    }
+    if (options.runtime !== void 0 && !FUNCTION_RUNTIMES.includes(options.runtime)) {
+      throw new InvalidRequestError(`runtime must be one of ${FUNCTION_RUNTIMES.join(", ")}, got '${String(options.runtime)}'`);
+    }
+    const functionId = await this.ensureInitialized();
+    const functionRunId = options.functionRunId ?? (await this.createRun()).function_run_id;
+    const body = {
+      workflow_id: functionId,
+      variables,
+      stream,
+      ...options.runtime !== void 0 ? { runtime: options.runtime } : {}
+    };
+    const headers = { [TIMEOUT_HEADER]: "0" };
+    const apiKey = this.client.getConfig().apiKey;
+    if (apiKey) {
+      headers[RUN_API_KEY_HEADER] = apiKey;
+    }
+    const endpointPath = FUNCTION_RUN_ENDPOINTS.start.replace("{function_id}", functionId).replace("{run_id}", functionRunId);
+    const parseAs = stream ? "stream" : "json";
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = Number.isFinite(timeoutMs) ? setTimeout(() => {
+      timedOut = true;
+      controller.abort(new DOMException(`Function run timed out after ${timeoutMs}ms`, "TimeoutError"));
+    }, timeoutMs) : void 0;
+    timer?.unref?.();
     try {
-      const response = await functionRunStart({
-        client: this.client.getClient(),
-        path: {
-          function_id: this.functionId
-        },
-        headers: {
-          "x-notte-api-key": apiKey,
-          "x-notte-request-origin": "sdk-node",
-          "x-notte-sdk-version": SDK_VERSION
-        },
-        body: {
-          workflow_id: this.functionId,
-          variables,
-          stream: false,
-          ...options.runtime ? { runtime: options.runtime } : {}
-        }
+      const raw = await this.postRunEndpoint({
+        url: FUNCTION_RUN_ENDPOINTS.start,
+        path: { function_id: functionId, run_id: functionRunId },
+        body: { ...body, function_run_id: functionRunId },
+        parseAs,
+        headers,
+        signal: controller.signal
       });
-      if (response?.error) {
-        throw new Error(`Failed to start function run: ${formatError(response.error)}`);
+      const result = stream ? await readFunctionStream(raw, options.onLog ?? console.log, endpointPath, controller.signal) : parseFunctionRunResult(raw, endpointPath);
+      if (result.status === "failed" && (options.raiseOnFailure ?? true)) {
+        throw new FailedToRunCloudFunctionError(functionId, result.function_run_id, result);
       }
-      return response.data;
+      return result;
     } catch (error) {
-      if (error instanceof Error && error.message.startsWith("Failed to start function run:")) {
-        throw error;
+      if (timedOut) {
+        throw new NotteTimeoutError(`Function ${functionId} run timed out after ${timeoutMs}ms`, { cause: error });
       }
-      throw new Error(`Failed to run function: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    } finally {
+      clearTimeout(timer);
     }
   }
   /**
    * Get the download URL of the function code, decrypting it when the API
    * returns an encrypted one (Notte managed functions).
+   *
+   * @param options - Optional version and decryption-key override.
+   * @returns An HTTP(S) URL for downloading the function source.
+   * @throws InvalidRequestError if an encrypted URL has no usable decryption key.
+   * @throws NotteError if decryption does not produce an HTTP(S) URL.
+   * @example
+   * const url = await fn.getUrl({ version: 'v1' });
    */
   async getUrl(options = {}) {
-    let response;
-    try {
-      response = await functionDownloadUrl({
-        client: this.client.getClient(),
-        path: {
-          function_id: this.functionId
-        },
-        query: options.version ? { version: options.version } : {}
-      });
-    } catch (error) {
-      throw new Error(`Failed to get function download url: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (response?.error) {
-      throw new Error(`Failed to get function download url: ${formatError(response.error)}`);
-    }
-    const url = response.data.url;
+    const { url } = await this.get(options);
     if (isHttpUrl(url)) {
       return url;
     }
     const decryptionKey = options.decryption_key ?? this.decryptionKey;
-    if (!decryptionKey) {
-      throw new Error(
+    if (decryptionKey === void 0) {
+      throw new InvalidRequestError(
         "Decryption key is required to decrypt the function download url. Set it when creating the function, i.e. client.NotteFunction({ function_id: '<your-function-id>', decryption_key: '<your-key>' })."
       );
     }
@@ -3026,147 +4245,837 @@ var NotteFunction = class {
     try {
       decrypted = new Encryption(decryptionKey).decrypt(url);
     } catch (error) {
-      throw new Error(`Failed to decrypt the function download url: ${error instanceof Error ? error.message : String(error)}. Contact support@notte.cc if you need help.`);
+      throw new InvalidRequestError(
+        `Failed to decrypt the function download url: ${error instanceof Error ? error.message : String(error)}. Contact support@notte.cc if you need help.`
+      );
     }
     if (!isHttpUrl(decrypted)) {
-      throw new Error("Failed to decrypt the function download url: the decrypted value is not a URL. Contact support@notte.cc if you need help.");
+      throw new NotteError(
+        "Failed to decrypt the function download url: the decrypted value is not a URL. Contact support@notte.cc if you need help."
+      );
     }
     return decrypted;
   }
   /**
    * Download the function code as a python file. Returns the code, and writes
    * it to `path` when one is provided.
+   *
+   * @param options - Optional version, decryption key, and local `.py` destination path.
+   * @returns The Python source text, including when a local destination is supplied.
+   * @throws InvalidRequestError if the destination does not end in `.py` or the decryption key is invalid.
+   * @throws NotteError if the source download fails. Local filesystem failures also propagate.
+   * @example
+   * const code = await fn.download({ path: './scraper.py' });
    */
   async download(options = {}) {
     const { path } = options;
-    if (path !== void 0 && !path.endsWith(".py")) {
-      throw new Error(`Code file path must end with .py, got '${path}'`);
+    if (path !== void 0) {
+      assertPythonPath(path);
     }
     const url = await this.getUrl(options);
     let response;
     try {
       response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
     } catch (error) {
-      throw new Error(`Failed to download function code: ${error instanceof Error ? error.message : String(error)}`);
+      throw new NotteError(
+        `Failed to download function code in ${DOWNLOAD_TIMEOUT_MS / 1e3} seconds: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
     }
     if (!response.ok) {
-      throw new Error(`Failed to download function code: ${response.status} ${response.statusText}`);
+      throw new NotteError(`Failed to download function code: ${response.status} ${response.statusText}`);
     }
     const code = await response.text();
     if (path !== void 0) {
-      await writeFile(path, code, "utf8");
+      await writeFile3(path, code, "utf8");
     }
     return code;
   }
   /**
-   * Get the function ID
+   * Call one of the run endpoints that the OpenAPI spec does not describe
+   * (`FUNCTION_RUN_ENDPOINTS`). The generated client has no operation for
+   * them, so this is the single place where they are hand-rolled; the request
+   * and response shapes are transcribed from `notte_sdk.types`
+   * (`CreateFunctionRunRequest` / `CreateFunctionRunResponse` and
+   * `StartFunctionRunRequest` / `FunctionRunResponse`). Replace the callers
+   * with generated operations once the spec exposes these paths.
    */
-  getFunctionId() {
-    return this.functionId;
+  async postRunEndpoint(request) {
+    const response = await this.client.getClient().post({
+      url: request.url,
+      path: request.path,
+      body: request.body,
+      headers: { "Content-Type": "application/json", ...request.headers },
+      parseAs: request.parseAs ?? "json",
+      signal: request.signal,
+      throwOnError: true
+    });
+    return response.data;
   }
 };
 function isHttpUrl(value) {
   return value.startsWith("https://") || value.startsWith("http://");
 }
-
-// src/client.ts
-import { z as z3 } from "zod";
+function assertPythonPath(path) {
+  if (!path.endsWith(".py")) {
+    throw new InvalidRequestError(`Code file path must end with .py, got '${path}'`);
+  }
+}
+async function readPythonFile(path) {
+  assertPythonPath(path);
+  let bytes;
+  try {
+    bytes = await readFile2(path);
+  } catch (error) {
+    throw new InvalidRequestError(
+      `The file '${path}' could not be read: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  return new File([new Uint8Array(bytes)], basename(path), { type: "text/x-python" });
+}
+function unwrapRuntimeEnvelope(candidate, path) {
+  const { statusCode, body } = candidate;
+  if (typeof statusCode !== "number" || statusCode < 400 || !("body" in candidate)) {
+    return;
+  }
+  let parsed = body;
+  if (typeof body === "string") {
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      parsed = body;
+    }
+  }
+  throw NotteAPIError.fromBody(path, statusCode, parsed);
+}
+function parseFunctionRunResult(value, path) {
+  if (typeof value !== "object" || value === null) {
+    throw new NotteError("Invalid function result: expected an object");
+  }
+  const candidate = value;
+  unwrapRuntimeEnvelope(candidate, path);
+  const status = candidate.status;
+  if (typeof candidate.function_run_id !== "string" || typeof candidate.function_id !== "string" || typeof status !== "string" || !FUNCTION_RUN_STATUSES.includes(status) || !("result" in candidate)) {
+    throw new NotteError("Invalid function result: missing function_id, function_run_id, status or result");
+  }
+  return {
+    function_id: candidate.function_id,
+    function_run_id: candidate.function_run_id,
+    session_id: typeof candidate.session_id === "string" ? candidate.session_id : null,
+    result: candidate.result,
+    status
+  };
+}
+async function readFunctionStream(body, onLog, path, signal) {
+  if (!body?.getReader) {
+    throw new NotteError("Missing function response stream");
+  }
+  const reader = body.getReader();
+  const onAbort = () => {
+    reader.cancel(signal?.reason).catch(() => {
+    });
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let data = [];
+  let result;
+  let sawFrame = false;
+  let raw = "";
+  const dispatch = () => {
+    if (!data.length) return;
+    const payload = data.join("\n");
+    data = [];
+    let event;
+    try {
+      event = JSON.parse(payload);
+    } catch (error) {
+      throw new NotteError(`Malformed function stream event: ${payload}`, { cause: error });
+    }
+    if (event.type === "log") onLog(String(event.message ?? ""));
+    if (event.type === "error") throw new NotteError(`Function stream error: ${String(event.message ?? "")}`);
+    if (event.type === "result") {
+      const value = typeof event.message === "string" ? JSON.parse(event.message) : event.message;
+      result = parseFunctionRunResult(value, path);
+    }
+  };
+  const line = (value) => {
+    if (value === "") dispatch();
+    else if (value.startsWith("data:")) {
+      sawFrame = true;
+      data.push(value.slice(5).replace(/^ /, ""));
+    }
+  };
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      const text = decoder.decode(value, { stream: !done });
+      buffer += text;
+      if (!sawFrame) raw += text;
+      let end;
+      while ((end = buffer.indexOf("\n")) !== -1) {
+        line(buffer.slice(0, end).replace(/\r$/, ""));
+        buffer = buffer.slice(end + 1);
+      }
+      if (done) break;
+    }
+    if (buffer) line(buffer.replace(/\r$/, ""));
+    dispatch();
+    if (!result && !sawFrame && raw.trim().length > 0) {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        throw new NotteError(`Function stream ended without a result: ${raw.slice(0, 200)}`);
+      }
+      result = parseFunctionRunResult(parsed, path);
+    }
+    if (!result) throw new NotteError("Function stream ended without a result");
+    return result;
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
 
 // src/files.ts
+import { createWriteStream } from "fs";
+import { link, mkdir, readFile as readFile3, rename, rm, stat } from "fs/promises";
+import { basename as basename2, extname, join } from "path";
+import { randomBytes } from "crypto";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+var FileNotFoundError = class extends NotteError {
+};
+var FileExistsError = class extends NotteError {
+};
+var METADATA_PAGE_SIZE = 1e3;
+var MIME_TYPES_BY_EXTENSION = {
+  ".csv": "text/csv",
+  ".gif": "image/gif",
+  ".htm": "text/html",
+  ".html": "text/html",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".json": "application/json",
+  ".md": "text/markdown",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".webp": "image/webp",
+  ".xml": "application/xml",
+  ".zip": "application/zip"
+};
+function guessMimeType(filename) {
+  return MIME_TYPES_BY_EXTENSION[extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+function sanitizeFilename(filename) {
+  const segment = filename.split(/[\\/]+/).filter(Boolean).pop() ?? "";
+  return segment.replace(/^[a-zA-Z]:/, "");
+}
+function toFile(file, filename) {
+  if (file instanceof File && file.name === filename) {
+    return file;
+  }
+  const type = file instanceof Blob && file.type ? file.type : guessMimeType(filename);
+  return new File([file], filename, { type });
+}
 var SessionFiles = class {
   constructor(client2, sessionId) {
     this.client = client2;
     this.sessionId = sessionId;
   }
-  path(fileId) {
-    const root = `/sessions/${encodeURIComponent(this.sessionId)}/files`;
-    return fileId ? `${root}/${encodeURIComponent(fileId)}` : root;
-  }
+  /**
+   * Upload bytes as a session file. `filename` is what the browser sees when
+   * the file is later attached to a page.
+   *
+   * @param file - Bytes to upload as a Blob, File, or buffer.
+   * @param filename - Stored filename, defaulting to `file`.
+   * @returns Metadata for the uploaded file, including its ID, name, and size.
+   * @throws NotteAPIError if the storage API request fails.
+   */
   async upload(file, filename = "file") {
-    const body = new FormData();
-    body.append("file", file, filename);
-    const result = await this.client.request({
-      method: "POST",
-      url: this.path(),
-      body
+    const response = await uploadSessionFile({
+      client: this.client,
+      path: { session_id: this.sessionId },
+      body: { file: toFile(file, filename) },
+      throwOnError: true
     });
-    if (result.error || !result.data) throw new Error("Failed to upload session file");
-    return result.data;
+    return response.data;
   }
+  /** List the session's non-expired files, newest first.
+   *
+   * @param options - Optional source filter and pagination. Defaults to all sources, limit 100, and offset 0.
+   * @returns One page of non-expired files and the total count; pagination is not automatic.
+   * @throws NotteAPIError if the storage API request fails.
+   */
   async list(options = {}) {
-    const result = await this.client.request({
-      method: "GET",
-      url: this.path(),
-      query: { limit: options.limit ?? 100, offset: options.offset ?? 0, source: options.source }
+    const response = await listSessionFiles({
+      client: this.client,
+      path: { session_id: this.sessionId },
+      query: { limit: options.limit ?? 100, offset: options.offset ?? 0, source: options.source },
+      throwOnError: true
     });
-    if (result.error || !result.data) throw new Error("Failed to list session files");
-    return result.data;
+    return response.data;
+  }
+  /**
+   * Find a file's metadata by ID by scanning the session listing. Rejects with
+   * `FileNotFoundError` when the ID is unknown or expired.
+   *
+   * @param fileId - ID of a file belonging to this session.
+   * @returns The matching file's metadata.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws FileNotFoundError if the file ID is unknown or expired.
+   */
+  async metadata(fileId) {
+    let offset = 0;
+    while (true) {
+      const page = await this.list({ limit: METADATA_PAGE_SIZE, offset });
+      const match = page.files.find((file) => file.id === fileId);
+      if (match) {
+        return match;
+      }
+      offset += page.files.length;
+      if (offset >= page.total || page.files.length === 0) {
+        throw new FileNotFoundError(`File ${fileId} was not found in session ${this.sessionId}`);
+      }
+    }
   }
+  /** Download a file's bytes as a `Blob`.
+   *
+   * @param fileId - ID of a file belonging to this session.
+   * @returns The downloaded bytes as a Blob; no local file is written.
+   * @throws NotteAPIError if the storage API request fails.
+   */
   async download(fileId) {
-    const result = await this.client.request({
-      method: "GET",
-      url: this.path(fileId),
-      parseAs: "blob"
+    const response = await downloadSessionFile({
+      client: this.client,
+      path: { session_id: this.sessionId, file_id: fileId },
+      parseAs: "blob",
+      throwOnError: true
     });
-    if (result.error || !result.data) throw new Error(`Failed to download session file ${fileId}`);
-    return result.data;
+    return response.data;
   }
+  /** Stream a file's bytes. Used by `RemoteFileStorage.download()` to write to disk without buffering. */
+  async stream(fileId) {
+    const response = await downloadSessionFile({
+      client: this.client,
+      path: { session_id: this.sessionId, file_id: fileId },
+      parseAs: "stream",
+      throwOnError: true
+    });
+    const body = response.data;
+    if (!body) {
+      throw new NotteError(`Download of file ${fileId} returned no body`);
+    }
+    return body;
+  }
+  /** Delete a session file.
+   *
+   * @param fileId - ID of the session file to delete.
+   * @returns Resolves when deletion succeeds.
+   * @throws NotteAPIError if the storage API request fails.
+   */
   async delete(fileId) {
-    const result = await this.client.request({ method: "DELETE", url: this.path(fileId) });
-    if (result.error) throw new Error(`Failed to delete session file ${fileId}`);
+    await deleteSessionFile({
+      client: this.client,
+      path: { session_id: this.sessionId, file_id: fileId },
+      throwOnError: true
+    });
+  }
+};
+var RemoteFileStorage = class _RemoteFileStorage {
+  constructor(client2, sessionId) {
+    this.client = client2;
+    this._sessionId = sessionId ?? null;
+  }
+  _sessionId;
+  /** Bind the storage to a session. Called by `Session.start()` when the storage was passed to the session. */
+  setSessionId(sessionId) {
+    this._sessionId = sessionId;
+  }
+  /**
+   * Bind this storage once, cloning it when another session already owns it.
+   *
+   * ```ts
+   * const first = storage.forSession('session-a'); // first === storage
+   * const second = storage.forSession('session-b'); // a clone sharing the client
+   * ```
+   */
+  forSession(sessionId) {
+    if (this._sessionId === null) {
+      this._sessionId = sessionId;
+      return this;
+    }
+    if (this._sessionId === sessionId) {
+      return this;
+    }
+    return new _RemoteFileStorage(this.client, sessionId);
+  }
+  /** ID of the bound session. Throws `InvalidRequestError` while the storage is unbound. */
+  get sessionId() {
+    if (this._sessionId === null) {
+      throw new InvalidRequestError("A session ID is required for every file operation");
+    }
+    return this._sessionId;
+  }
+  /** Whether the storage has been bound to a session yet. */
+  get isBound() {
+    return this._sessionId !== null;
+  }
+  files() {
+    return new SessionFiles(this.client.getClient(), this.sessionId);
+  }
+  /**
+   * Upload a file to the session. A string is read as a local path and its
+   * basename becomes the uploaded filename unless `uploadFileName` is set.
+   *
+   * @param file - Local file path, Blob, File, or buffer to upload.
+   * @param uploadFileName - Optional stored filename. Local paths default to their basename; File objects keep their name.
+   * @returns Metadata for the uploaded file, including its ID, name, and size.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws InvalidRequestError if storage has not been bound to a session.
+   * @throws InvalidRequestError if a supplied local path is not a file.
+   * @example
+   * await storage.upload('./data/resume.pdf');
+   * await storage.upload(Buffer.from('hello'), 'hello.txt');
+   */
+  async upload(file, uploadFileName) {
+    const files = this.files();
+    if (typeof file === "string") {
+      const info = await stat(file).catch(() => null);
+      if (!info?.isFile()) {
+        throw new InvalidRequestError(`Cannot upload file ${file}: it is not a file`);
+      }
+      const bytes = await readFile3(file);
+      return files.upload(bytes, uploadFileName ?? basename2(file));
+    }
+    const filename = uploadFileName ?? (file instanceof File ? file.name : "file");
+    return files.upload(file, filename);
+  }
+  /**
+   * List the session's files.
+   *
+   * @param options - Optional source filter and pagination. Defaults to all sources, limit 100, and offset 0.
+   * @returns One page of non-expired files and the total count; pagination is not automatic.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws InvalidRequestError if storage has not been bound to a session.
+   * @example
+   * const downloads = await storage.list({ source: 'session_download', limit: 1000 });
+   */
+  async list(options = {}) {
+    return this.files().list(options);
+  }
+  /** Metadata of a file by ID. Rejects with `FileNotFoundError` when unknown.
+   *
+   * @param fileId - ID of a file belonging to this session.
+   * @returns The matching file's metadata.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws FileNotFoundError if the file ID is unknown or expired.
+   * @throws InvalidRequestError if storage has not been bound to a session.
+   */
+  async metadata(fileId) {
+    return this.files().metadata(fileId);
+  }
+  /**
+   * Download a file to `<localDir>/<filename>` and return the local path. The
+   * file is written atomically (temporary file + rename). Rejects with
+   * `FileExistsError` when the destination exists unless `force` is set.
+   *
+   * @param fileId - ID of the file to download.
+   * @param localDir - Destination directory, created if needed. Defaults to the current directory.
+   * @param options - Set `force` to overwrite an existing destination; defaults to false.
+   * @returns The local file path after the download has been written successfully.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws InvalidRequestError if storage has not been bound to a session.
+   * @throws FileExistsError if the destination exists and `force` is false. Filesystem errors also propagate.
+   * @example
+   * const path = await storage.download(fileId, './downloads', { force: true });
+   */
+  async download(fileId, localDir = ".", options = {}) {
+    const files = this.files();
+    const metadata = await files.metadata(fileId);
+    const safeName = sanitizeFilename(metadata.filename);
+    if (safeName === "" || safeName === "." || safeName === "..") {
+      throw new NotteError(`Unsafe filename returned for file ${fileId}: ${JSON.stringify(metadata.filename)}`);
+    }
+    await mkdir(localDir, { recursive: true });
+    const destination = join(localDir, safeName);
+    if (!options.force) {
+      const exists = await stat(destination).then(() => true, () => false);
+      if (exists) {
+        throw new FileExistsError(`${destination} already exists; pass force: true to overwrite it`);
+      }
+    }
+    const body = await files.stream(fileId);
+    const temporary = join(localDir, `.${safeName}.${randomBytes(8).toString("hex")}.part`);
+    try {
+      await pipeline(
+        Readable.fromWeb(body),
+        createWriteStream(temporary, { flags: "wx" })
+      );
+      if (options.force) {
+        await rename(temporary, destination);
+      } else {
+        try {
+          await link(temporary, destination);
+        } catch (error) {
+          if (error.code === "EEXIST") {
+            throw new FileExistsError(`${destination} already exists; pass force: true to overwrite it`);
+          }
+          throw error;
+        }
+        await rm(temporary, { force: true });
+      }
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+    return destination;
+  }
+  /** Download a file's bytes as a `Blob` without touching the local filesystem. */
+  async downloadBlob(fileId) {
+    return this.files().download(fileId);
+  }
+  /** Stream a file's bytes without buffering the whole file in memory. */
+  async stream(fileId) {
+    return this.files().stream(fileId);
+  }
+  /** Delete a session file.
+   *
+   * @param fileId - ID of the session file to delete.
+   * @returns Resolves when deletion succeeds.
+   * @throws NotteAPIError if the storage API request fails.
+   * @throws InvalidRequestError if storage has not been bound to a session.
+   */
+  async delete(fileId) {
+    await this.files().delete(fileId);
+  }
+};
+
+// src/anything.ts
+var NotteAnything = class {
+  client;
+  constructor(client2) {
+    this.client = client2;
+  }
+  /**
+   * Start building a function for `task`. Building is slow (minutes) and
+   * billable; prefer the marketplace (`client.functions.list()`) when a
+   * ready-made function already fits.
+   *
+   * ```ts
+   * const result = await client.anything.start({ task: 'get the weather in Paris' });
+   * if (typeof result.function_id === 'string') {
+   *   const fn = client.NotteFunction({ function_id: result.function_id });
+   * }
+   * ```
+   *
+   * Rejects with a `NotteAPIError` when the API answers with a non-2xx status.
+   */
+  async start(body) {
+    const response = await anythingStart({
+      client: this.client.getClient(),
+      body,
+      throwOnError: true
+    });
+    return response.data ?? {};
+  }
+};
+
+// src/secrets.ts
+var NotteSecrets = class {
+  client;
+  constructor(client2) {
+    this.client = client2;
+  }
+  /**
+   * List secret metadata (never the values), optionally filtered by namespace.
+   *
+   * ```ts
+   * const secrets = await client.secrets.list({ namespace: 'llm_provider' });
+   * secrets.forEach(s => console.log(s.name, s.key_hint));
+   * ```
+   */
+  async list(options = {}) {
+    const response = await listSecrets({ client: this.client.getClient(), query: options, throwOnError: true });
+    return response.data?.items ?? [];
+  }
+  /**
+   * Store (or overwrite) a secret and return its metadata.
+   *
+   * ```ts
+   * const meta = await client.secrets.store({ namespace: 'function_env', name: 'API_TOKEN', value: 'xyz' });
+   * console.log(meta.id, meta.key_hint);
+   * ```
+   */
+  async store(body) {
+    const response = await storeSecret({ client: this.client.getClient(), body, throwOnError: true });
+    return response.data;
+  }
+  /**
+   * Read the value of a secret by name within a namespace.
+   *
+   * ```ts
+   * const { value } = await client.secrets.get('API_TOKEN', 'function_env');
+   * ```
+   */
+  async get(name, namespace) {
+    const response = await getSecret({
+      client: this.client.getClient(),
+      path: { name },
+      query: { namespace },
+      throwOnError: true
+    });
+    return response.data;
+  }
+  /**
+   * Delete a secret by id (the `id` field of `SecretMetadata`).
+   *
+   * ```ts
+   * const meta = await client.secrets.store({ namespace: 'function_env', name: 'TMP', value: 'x' });
+   * await client.secrets.delete(meta.id);
+   * ```
+   */
+  async delete(secretId) {
+    await deleteSecret({ client: this.client.getClient(), path: { secret_id: secretId }, throwOnError: true });
+  }
+};
+
+// src/usage.ts
+var NotteUsage = class {
+  client;
+  constructor(client2) {
+    this.client = client2;
+  }
+  /**
+   * Usage summary for a monthly period (current month by default).
+   *
+   * ```ts
+   * const usage = await client.usage.get({ period: 'May 2025' });
+   * console.log(`${usage.session_count} sessions, $${usage.total_cost}`);
+   * ```
+   */
+  async get(options = {}) {
+    const response = await getUsage({ client: this.client.getClient(), query: options, throwOnError: true });
+    return response.data;
+  }
+  /**
+   * Paginated per-request usage logs, optionally filtered by endpoint.
+   *
+   * ```ts
+   * const page = await client.usage.logs({ endpoint: 'sessions.start', page: 1, page_size: 50 });
+   * page.items.forEach(log => console.log(log.created_at, log.endpoint, log.duration_ms));
+   * ```
+   */
+  async logs(options = {}) {
+    const response = await getUsageLogs({ client: this.client.getClient(), query: options, throwOnError: true });
+    return response.data;
   }
 };
 
 // src/client.ts
-var NotteClient = class {
+var DEFAULT_NOTTE_API_URL = "https://api.notte.cc";
+var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+var REQUEST_ORIGIN = "sdk-node";
+var TIMEOUT_HEADER = "x-notte-timeout-ms";
+var DB_PREVIEW_ENV = "NOTTE_DB_PREVIEW_BRANCH";
+var DB_PREVIEW_HEADER = "x-db-preview";
+var EXECUTION_ERROR_CLASS = "NotteApiExecutionError";
+function isRelativeProxyUrl(baseUrl) {
+  return /^\/(?!\/)/.test(baseUrl);
+}
+var NotteClient3 = class {
+  config;
+  client = createClient();
   constructor(config = {}) {
     const apiKey = config.apiKey || process.env.NOTTE_API_KEY;
-    const isProxyMode = config.baseUrl && !config.baseUrl.startsWith("https://");
+    const baseUrl = config.baseUrl || process.env.NOTTE_API_URL || DEFAULT_NOTTE_API_URL;
+    const dbPreview = config.dbPreview || process.env[DB_PREVIEW_ENV] || void 0;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!(timeoutMs >= 0)) {
+      throw new InvalidRequestError("timeoutMs must be a non-negative number");
+    }
+    const isProxyMode = isRelativeProxyUrl(baseUrl);
+    if (!isProxyMode) {
+      const url = new URL(baseUrl);
+      const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+      if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new InvalidRequestError(
+          "API base URL must use HTTPS (HTTP is only allowed on loopback for local development)"
+        );
+      }
+    }
     if (!apiKey && !isProxyMode) {
-      throw new Error("API key is required. Provide it via config.apiKey or set the NOTTE_API_KEY environment variable.");
+      throw new AuthenticationError(
+        "NOTTE_API_KEY needs to be provided. Pass config.apiKey or set the NOTTE_API_KEY environment variable."
+      );
     }
-    this.config = {
-      baseUrl: config.baseUrl || process.env.NOTTE_API_URL || "https://api.notte.cc",
-      apiKey,
-      ...config
-    };
-    client.setConfig({
+    this.config = { baseUrl, apiKey, timeoutMs, dbPreview, verbose: config.verbose ?? false };
+    if (baseUrl !== DEFAULT_NOTTE_API_URL && !isProxyMode) {
+      console.warn(`NOTTE_API_URL is set to: ${baseUrl}`);
+    }
+    this.client.setConfig({
       baseUrl: this.config.baseUrl,
-      redirect: "manual"
+      redirect: "manual",
+      throwOnError: true
     });
-    client.interceptors.request.use((request) => {
-      request.headers.set("Authorization", `Bearer ${this.config.apiKey}`);
-      request.headers.set("x-notte-request-origin", "sdk-node");
-      request.headers.set("x-notte-sdk-version", SDK_VERSION);
-      return request;
+    this.client.interceptors.request.use((request) => {
+      const headers = new Headers(request.headers);
+      if (this.config.apiKey) headers.set("Authorization", `Bearer ${this.config.apiKey}`);
+      headers.set("x-notte-request-origin", REQUEST_ORIGIN);
+      headers.set("x-notte-sdk-version", SDK_VERSION);
+      if (this.config.dbPreview) headers.set(DB_PREVIEW_HEADER, this.config.dbPreview);
+      const override = headers.get(TIMEOUT_HEADER);
+      headers.delete(TIMEOUT_HEADER);
+      const timeoutMs2 = override !== null ? Number(override) : this.config.timeoutMs;
+      if (this.config.verbose) {
+        console.info(`Making \`${request.method}\` request to \`${request.url}\``);
+      }
+      if (!(timeoutMs2 > 0)) {
+        return new Request(request, { headers });
+      }
+      const deadline = withTimeout(request.signal, timeoutMs2);
+      const timed = new Request(request, { headers, signal: deadline.signal });
+      pendingDeadlines.set(timed, deadline.release);
+      return timed;
     });
-    client.interceptors.response.use(async (response, request, opts) => {
-      if ((response.status === 307 || response.status === 308) && response.headers.get("location")) {
-        const location = response.headers.get("location");
-        const headers = new Headers(request.headers);
-        if (new URL(location).origin !== new URL(request.url).origin) {
+    this.client.interceptors.response.use(async (response, request, opts) => {
+      const initialUrl = new URL(request.url);
+      let currentUrl = initialUrl;
+      const headers = new Headers(request.headers);
+      const apiUrl = new URL(this.config.baseUrl, initialUrl);
+      const executionPrefix = `${apiUrl.pathname.replace(/\/$/, "")}/functions/`;
+      const executionPath = initialUrl.pathname.slice(executionPrefix.length);
+      const runtimeHandoff = request.method === "POST" && initialUrl.origin === apiUrl.origin && initialUrl.pathname.startsWith(executionPrefix) && /^[^/]+\/runs\/[^/]+$/.test(executionPath) && !executionPath.endsWith("/create");
+      for (let hop = 0; (response.status === 307 || response.status === 308) && response.headers.get("location"); hop++) {
+        if (hop >= 10) throw new InvalidRequestError("Too many API redirects");
+        const location = new URL(response.headers.get("location"), currentUrl);
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname);
+        if (location.protocol !== "https:" && !(location.protocol === "http:" && loopback)) {
+          throw new InvalidRequestError(`Refusing to follow a redirect to an insecure URL: ${location.origin}`);
+        }
+        if (location.username || location.password) {
+          throw new InvalidRequestError("Refusing to follow a redirect containing URL credentials");
+        }
+        if (location.origin !== currentUrl.origin) {
           headers.delete("Authorization");
+          const localHandoff = location.protocol === "http:" && initialUrl.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(initialUrl.hostname) && loopback;
+          if (!(hop === 0 && runtimeHandoff && (location.protocol === "https:" || localHandoff))) {
+            headers.delete("x-notte-api-key");
+          }
         }
+        if (hop > 0) headers.delete("x-notte-api-key");
+        await response.body?.cancel();
         const headerRecord = {};
         headers.forEach((v, k) => {
           headerRecord[k] = v;
         });
-        const redirected = await fetch(location, {
+        response = await (opts.fetch ?? fetch)(location.toString(), {
           method: request.method,
           headers: headerRecord,
-          body: opts.serializedBody ?? void 0
+          body: opts.serializedBody ?? void 0,
+          signal: request.signal,
+          redirect: "manual"
         });
-        return redirected;
+        currentUrl = location;
       }
       const ct = response.headers.get("content-type") ?? "";
-      if (ct.split(";")[0]?.trim() === "text/plain") {
+      if (opts.parseAs !== "stream" && ct.split(";")[0]?.trim() === "text/plain") {
         const body = await response.arrayBuffer();
-        const headers = new Headers(response.headers);
-        headers.set("content-type", "application/json");
-        return new Response(body, { status: response.status, statusText: response.statusText, headers });
+        const headers2 = new Headers(response.headers);
+        headers2.set("content-type", "application/json");
+        return new Response(body, { status: response.status, statusText: response.statusText, headers: headers2 });
       }
       return response;
     });
+    this.client.interceptors.response.use(async (response, request, opts) => {
+      try {
+        const parseAs = opts.parseAs === "auto" ? getParseAs(response.headers.get("content-type")) : opts.parseAs;
+        if (parseAs !== "stream" && response.body) {
+          const body = await response.arrayBuffer();
+          const buffered = new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers
+          });
+          Object.defineProperty(buffered, "url", { value: response.url });
+          return buffered;
+        }
+        return response;
+      } finally {
+        releaseDeadline(request);
+      }
+    });
+    this.client.interceptors.error.use((error, response, request) => {
+      releaseDeadline(request);
+      return this.toTypedError(error, response, request);
+    });
+    startVersionCheck();
+  }
+  /**
+   * Map the raw value the generated client rejects with into a `NotteError`.
+   * HTTP failures become `NotteAPIError` (or `NotteAPIExecutionError` when the
+   * API flags them), timeouts become `NotteTimeoutError`, anything else is
+   * returned untouched.
+   */
+  toTypedError(error, response, request) {
+    if (error instanceof NotteAPIError) {
+      return error;
+    }
+    if (request?.signal.aborted) {
+      error = request.signal.reason ?? error;
+    }
+    if (isTimeoutAbort(error)) {
+      const target = request ? ` to \`${requestPath(request)}\`` : "";
+      return new NotteTimeoutError(`Request${target} ${error.message}`, { cause: error });
+    }
+    if (request?.signal.aborted) return error;
+    if (response) {
+      const path = requestPath(request, response);
+      const body = normalizeErrorBody(error);
+      if (response.status === 422) {
+        const latest = upgradeSuggestion();
+        const message = typeof body.message === "string" ? body.message : "";
+        const looksLikeSchemaMismatch = message.includes("extra_forbidden") || message.includes("Extra inputs are not permitted") || message.includes("'type':");
+        if (latest && looksLikeSchemaMismatch) {
+          return new NotteAPIError(
+            path,
+            response.status,
+            { ...body, message: createUpgradeErrorMessage("API returned 422 validation error", latest, message) },
+            response
+          );
+        }
+      }
+      if (response.headers.get("x-error-class") === EXECUTION_ERROR_CLASS) {
+        return new NotteAPIExecutionError(path, response.status, body, response);
+      }
+      return new NotteAPIError(path, response.status, body, response);
+    }
+    return error;
+  }
+  /**
+   * Add the database preview branch to a websocket URL served by the Notte API.
+   * The websocket handshake reads the branch from the query string, so without
+   * it a preview-branch session is looked up in the default database.
+   */
+  withDbPreview(url) {
+    if (!this.config.dbPreview) {
+      return url;
+    }
+    const parsed = new URL(url);
+    parsed.searchParams.set("db_preview", this.config.dbPreview);
+    return parsed.toString();
+  }
+  /**
+   * Health check the Notte API. Resolves when the API answers 200 and rejects
+   * with a `NotteAPIError` (or a network error) otherwise.
+   */
+  async healthCheck() {
+    await healthCheck({ client: this.client });
   }
   /**
    * Create a new session
@@ -3178,6 +5087,20 @@ var NotteClient = class {
   Files(sessionId) {
     return new SessionFiles(this.getClient(), sessionId);
   }
+  /**
+   * File storage to attach to a session, the counterpart of `client.FileStorage()`.
+   *
+   * ```ts
+   * const storage = client.FileStorage();
+   * await client.Session({ storage }).use(async session => {
+   *   await storage.upload('./invoice.pdf');
+   *   const files = await storage.list({ source: 'session_download' });
+   * });
+   * ```
+   */
+  FileStorage(sessionId) {
+    return new RemoteFileStorage(this, sessionId);
+  }
   /**
    * Create a new agent
    */
@@ -3202,6 +5125,66 @@ var NotteClient = class {
   NotteFunction(options) {
     return new NotteFunction(this, options);
   }
+  /** Alias of `NotteFunction`, matching `client.Function` in Python. */
+  Function(options) {
+    return this.NotteFunction(options);
+  }
+  /** Sessions listing, the counterpart of `client.sessions.list()`. */
+  get sessions() {
+    return {
+      list: async (options = {}) => {
+        const response = await listSessions({ client: this.getClient(), query: options });
+        return response.data?.items ?? [];
+      }
+    };
+  }
+  /** Agents listing, the counterpart of `client.agents.list()`. */
+  get agents() {
+    return {
+      list: async (options = {}) => {
+        const response = await listAgents({ client: this.getClient(), query: options });
+        return response.data?.items ?? [];
+      }
+    };
+  }
+  /** Vaults listing, the counterpart of `client.vaults.list()`. */
+  get vaults() {
+    return {
+      list: async (options = {}) => {
+        const response = await listVaults({ client: this.getClient(), query: options });
+        return response.data?.items ?? [];
+      }
+    };
+  }
+  /** Functions listing, the counterpart of `client.functions.list()`. */
+  get functions() {
+    return {
+      list: async (options = {}) => {
+        const response = await listFunctions({ client: this.getClient(), query: options });
+        return response.data?.items ?? [];
+      }
+    };
+  }
+  async search(query, options = {}) {
+    const response = await searchWeb({
+      client: this.getClient(),
+      body: { ...options, q: query },
+      throwOnError: true
+    });
+    return response.data;
+  }
+  /** Anything API (`POST /anything/start`). */
+  get anything() {
+    return new NotteAnything(this);
+  }
+  /** Workspace secrets (`/secrets`). */
+  get secrets() {
+    return new NotteSecrets(this);
+  }
+  /** Usage and billing (`/usage`, `/usage/logs`). */
+  get usage() {
+    return new NotteUsage(this);
+  }
   /**
    * Personas client for listing and managing personas
    */
@@ -3212,9 +5195,6 @@ var NotteClient = class {
           client: this.getClient(),
           query: options || {}
         });
-        if (response?.error) {
-          throw new Error(`Failed to list personas: ${JSON.stringify(response.error)}`);
-        }
         return response.data?.items || [];
       }
     };
@@ -3223,49 +5203,80 @@ var NotteClient = class {
    * Get the configured client instance
    */
   getClient() {
-    return client;
+    return this.client;
   }
   async scrape(url, options = {}) {
-    const apiOptions = { ...options };
-    if (options.response_format && typeof options.response_format.parse === "function") {
-      if (options.json_schema) {
-        apiOptions.response_format = options.json_schema;
-      } else {
-        apiOptions.response_format = z3.toJSONSchema(options.response_format);
-      }
-      if (!apiOptions.instructions) {
-        const schemaStr = JSON.stringify(apiOptions.response_format);
-        if (schemaStr.includes("plans") || schemaStr.includes("plan")) {
-          apiOptions.instructions = "Extract pricing plans from the page";
-        } else if (schemaStr.includes("products") || schemaStr.includes("product")) {
-          apiOptions.instructions = "Extract product information from the page";
-        } else if (schemaStr.includes("articles") || schemaStr.includes("article")) {
-          apiOptions.instructions = "Extract article information from the page";
-        } else {
-          apiOptions.instructions = "Extract structured data from the page based on the provided schema";
-        }
-      }
-    }
+    const body = await buildScrapeBody(options);
     const response = await scrapeWebpage({
       client: this.getClient(),
-      body: {
-        url,
-        ...apiOptions
-      }
+      body: { url, ...body }
     });
-    if (response?.error) {
-      throw new Error(`Failed to scrape webpage: ${JSON.stringify(response.error)}`);
-    }
-    const scrapeResponse = response.data;
-    return processScrapeResponse(scrapeResponse, options);
+    return processScrapeResponse(response.data, options);
   }
   /**
    * Get the client configuration
    */
   getConfig() {
-    return this.config;
+    return { ...this.config };
   }
 };
+function requestPath(request, response) {
+  const url = request?.url ?? response?.url;
+  if (!url) {
+    return "unknown";
+  }
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+function isTimeoutAbort(error) {
+  return typeof error === "object" && error !== null && error.name === "TimeoutError";
+}
+function timeoutReason(timeoutMs) {
+  return new DOMException(`timed out after ${timeoutMs}ms`, "TimeoutError");
+}
+var pendingDeadlines = /* @__PURE__ */ new WeakMap();
+function releaseDeadline(request) {
+  if (!request) return;
+  const release = pendingDeadlines.get(request);
+  if (release) {
+    pendingDeadlines.delete(request);
+    release();
+  }
+}
+function withTimeout(signal, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(timeoutReason(timeoutMs)), timeoutMs);
+  timer.unref?.();
+  let detach = () => void 0;
+  let composite;
+  const signalAny = AbortSignal.any;
+  if (typeof signalAny === "function") {
+    composite = signalAny.call(AbortSignal, signal ? [signal, controller.signal] : [controller.signal]);
+  } else {
+    composite = controller.signal;
+    if (signal) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        const forward = () => controller.abort(signal.reason);
+        signal.addEventListener("abort", forward, { once: true });
+        detach = () => signal.removeEventListener("abort", forward);
+      }
+    }
+  }
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    clearTimeout(timer);
+    detach();
+  };
+  composite.addEventListener("abort", release, { once: true });
+  return { signal: composite, release };
+}
 
 // src/proxy/types.ts
 var NotteProxyAuthError = class extends Error {
@@ -3276,33 +5287,65 @@ var NotteProxyAuthError = class extends Error {
 };
 
 // src/index.ts
-startVersionCheck();
 var createClient2 = (config) => {
+  const client2 = createClient({ baseUrl: config?.baseUrl || DEFAULT_NOTTE_API_URL });
   if (config?.baseUrl) {
-    client.setConfig({ baseUrl: config.baseUrl });
+    client2.setConfig({ baseUrl: config.baseUrl });
   }
   if (config?.token) {
-    client.interceptors.request.use((request) => {
+    client2.interceptors.request.use((request) => {
       request.headers.set("Authorization", `Bearer ${config.token}`);
       return request;
     });
   }
-  return client;
+  return client2;
 };
 export {
+  ActionExecutionError,
   Agent,
+  AuthenticationError,
+  CAPTCHA_SOLVE_TIMEOUT_MS,
+  CLUSTER_OVERLOAD_RETRY_DELAY_MS,
+  CREDENTIAL_FIELDS,
+  DEFAULT_NOTTE_API_URL,
+  DEFAULT_REQUEST_TIMEOUT_MS,
   Encryption,
-  NotteClient,
+  EvaluateJsNoDataError,
+  FUNCTION_RUN_ENDPOINTS,
+  FUNCTION_RUN_TIMEOUT_MS,
+  FailedToRunCloudFunctionError,
+  FetchResponseDecodeError,
+  FileExistsError,
+  FileNotFoundError,
+  InvalidRequestError,
+  NotteAPIError,
+  NotteAPIExecutionError,
+  NotteAnything,
+  NotteClient3 as NotteClient,
+  NotteError,
   NotteFunction,
   NottePersona,
   NotteProxyAuthError,
+  NotteSecrets,
+  NotteTimeoutError,
+  NotteUsage,
   NotteVault,
+  PageFetchHTTPError,
+  PageFetchResponse,
+  RUN_API_KEY_HEADER,
+  RemoteFileStorage,
+  SESSION_START_TRIES,
+  ScrapeFailedError,
   Session,
   SessionFiles,
+  TIMEOUT_HEADER,
+  actions,
   agentStart,
   agentStatus,
   agentStop,
   anythingStart,
+  buildFetchScript,
+  checkForLatestVersion,
   client,
   connectLinkContext,
   connectLinkMailboxConnect,
@@ -3311,7 +5354,8 @@ export {
   connectLinkStatus,
   connectLinkSubmit,
   createClient2 as createClient,
-  NotteClient as default,
+  createOrAppendCookiesToFile,
+  NotteClient3 as default,
   deleteSecret,
   deleteSessionFile,
   downloadSessionFile,
@@ -3329,6 +5373,7 @@ export {
   functionScheduleDelete,
   functionScheduleSet,
   functionUpdate,
+  getRootDomain,
   getScript,
   getSecret,
   getSessionScript,
@@ -3336,6 +5381,9 @@ export {
   getUsageLogs,
   healthCheck,
   improvePrompt,
+  installServerOwnedDialogPolicy,
+  isCaptchaSolveAction,
+  isValidMfaSecret,
   listAgents,
   listFunctionRunsByFunctionId,
   listFunctions,
@@ -3351,18 +5399,21 @@ export {
   mailboxSync,
   mailboxUpdate,
   managedAuthConnectLinkCreate,
-  mintProxyCredentials,
   nudgePrompt,
+  observeServerOwnedDialog,
   pageExecute,
   pageObserve,
   pageScrape,
   pageScreenshot,
+  parseAgentStatusMessage,
   personaCreate,
   personaDelete,
   personaEmailsList,
   personaGet,
   personaSmsList,
   personaUpdate,
+  prepareAgentRequest,
+  processScrapeResponse,
   profileCookiesGet,
   profileCookiesSet,
   profileCreate,
@@ -3370,7 +5421,11 @@ export {
   profileDuplicate,
   profileGet,
   profileList,
+  readCookiesFile,
   readyCheck,
+  responseFromEvaluated,
+  retry,
+  sanitizeFilename,
   scrapeFromHtml,
   scrapeWebpage,
   searchWeb,
@@ -3383,8 +5438,12 @@ export {
   sessionStart,
   sessionStatus,
   sessionStop,
+  startVersionCheck,
   storeSecret,
   uploadSessionFile,
+  validateCredentials,
+  validateMfaSecret,
+  validateUrl,
   vaultCreate,
   vaultCredentialsAdd,
   vaultCredentialsDelete,