wreq-js 2.1.1 → 2.2.1

package/dist/wreq-js.js

@@ -39,6 +39,24 @@ function detectLibc() {
   }
 }
 var require2 = typeof import.meta !== "undefined" && import.meta.url ? createRequire(import.meta.url) : createRequire(__filename);
+function requirePlatformBinary(platformArch) {
+  switch (platformArch) {
+    case "darwin-x64":
+      return require2("../rust/wreq-js.darwin-x64.node");
+    case "darwin-arm64":
+      return require2("../rust/wreq-js.darwin-arm64.node");
+    case "linux-x64-gnu":
+      return require2("../rust/wreq-js.linux-x64-gnu.node");
+    case "linux-x64-musl":
+      return require2("../rust/wreq-js.linux-x64-musl.node");
+    case "linux-arm64-gnu":
+      return require2("../rust/wreq-js.linux-arm64-gnu.node");
+    case "win32-x64-msvc":
+      return require2("../rust/wreq-js.win32-x64-msvc.node");
+    default:
+      return void 0;
+  }
+}
 function loadNativeBinding() {
   const platform = process.platform;
   const arch = process.arch;
@@ -60,15 +78,18 @@ function loadNativeBinding() {
   }
   const binaryName = `wreq-js.${platformArch}.node`;
   try {
-    return require2(`../rust/${binaryName}`);
-  } catch {
-    try {
-      return require2("../rust/wreq-js.node");
-    } catch {
-      throw new Error(
-        `Failed to load native module for ${platform}-${arch}. Tried: ../rust/${binaryName} and ../rust/wreq-js.node. Make sure the package is installed correctly and the native module is built for your platform.`
-      );
+    const platformBinding = requirePlatformBinary(platformArch);
+    if (platformBinding) {
+      return platformBinding;
     }
+  } catch {
+  }
+  try {
+    return require2("../rust/wreq-js.node");
+  } catch {
+    throw new Error(
+      `Failed to load native module for ${platform}-${arch}. Tried: ../rust/${binaryName} and ../rust/wreq-js.node. Make sure the package is installed correctly and the native module is built for your platform.`
+    );
   }
 }
 nativeBinding = loadNativeBinding();
@@ -100,8 +121,7 @@ function generateSessionId() {
 function normalizeSessionOptions(options) {
   const sessionId = options?.sessionId ?? generateSessionId();
   const defaults = {
-    browser: options?.browser ?? DEFAULT_BROWSER,
-    os: options?.os ?? DEFAULT_OS
+    transportMode: resolveEmulationMode(options?.browser, options?.os, options?.emulation)
   };
   if (options?.proxy !== void 0) {
     defaults.proxy = options.proxy;
@@ -825,21 +845,26 @@ function resolveTransportContext(config, sessionDefaults) {
       throw new RequestError("Transport has been closed");
     }
     const hasProxy = config.proxy !== void 0;
-    if (config.browser !== void 0 || config.os !== void 0 || hasProxy || config.insecure !== void 0) {
-      throw new RequestError("`transport` cannot be combined with browser/os/proxy/insecure options");
+    if (config.browser !== void 0 || config.os !== void 0 || config.emulation !== void 0 || hasProxy || config.insecure !== void 0) {
+      throw new RequestError("`transport` cannot be combined with browser/os/emulation/proxy/insecure options");
     }
     return { transportId: config.transport.id };
   }
   if (sessionDefaults?.transportId) {
+    if (config.emulation !== void 0) {
+      throw new RequestError("Session emulation cannot be changed after creation");
+    }
     if (config.browser !== void 0) {
       validateBrowserProfile(config.browser);
-      if (config.browser !== sessionDefaults.browser) {
+      const lockedBrowser = sessionDefaults.transportMode.kind === "custom" ? void 0 : sessionDefaults.transportMode.browser;
+      if (config.browser !== lockedBrowser) {
         throw new RequestError("Session browser cannot be changed after creation");
       }
     }
     if (config.os !== void 0) {
       validateOperatingSystem(config.os);
-      if (config.os !== sessionDefaults.os) {
+      const lockedOs = sessionDefaults.transportMode.kind === "custom" ? void 0 : sessionDefaults.transportMode.os;
+      if (config.os !== lockedOs) {
         throw new RequestError("Session operating system cannot be changed after creation");
       }
     }
@@ -856,11 +881,9 @@ function resolveTransportContext(config, sessionDefaults) {
     }
     return { transportId: sessionDefaults.transportId };
   }
-  const browser = config.browser ?? DEFAULT_BROWSER;
-  const os = config.os ?? DEFAULT_OS;
-  validateBrowserProfile(browser);
-  validateOperatingSystem(os);
-  const resolved = { browser, os };
+  const resolved = {
+    mode: resolveEmulationMode(config.browser, config.os, config.emulation)
+  };
   if (config.proxy !== void 0) {
     resolved.proxy = config.proxy;
   }
@@ -1105,6 +1128,553 @@ function validatePositiveInteger(value, label) {
     throw new RequestError(`${label} must be greater than 0`);
   }
 }
+function validateIntegerInRange(value, min, max, label) {
+  validateNonNegativeInteger(value, label);
+  if (value < min || value > max) {
+    throw new RequestError(`${label} must be between ${min} and ${max}`);
+  }
+}
+var SUPPORTED_ALPN_PROTOCOLS = /* @__PURE__ */ new Set(["HTTP1", "HTTP2", "HTTP3"]);
+var SUPPORTED_ALPS_PROTOCOLS = /* @__PURE__ */ new Set(["HTTP1", "HTTP2", "HTTP3"]);
+var SUPPORTED_CERTIFICATE_COMPRESSION_ALGORITHMS = /* @__PURE__ */ new Set(["zlib", "brotli", "zstd"]);
+var HTTP2_SETTING_IDS = /* @__PURE__ */ new Set([
+  "HeaderTableSize",
+  "EnablePush",
+  "MaxConcurrentStreams",
+  "InitialWindowSize",
+  "MaxFrameSize",
+  "MaxHeaderListSize",
+  "EnableConnectProtocol",
+  "NoRfc7540Priorities"
+]);
+var HTTP2_PSEUDO_HEADER_IDS = /* @__PURE__ */ new Set(["Method", "Scheme", "Authority", "Path", "Protocol"]);
+var STANDARD_HTTP2_SETTING_ID_VALUES = /* @__PURE__ */ new Set([1, 2, 3, 4, 5, 6, 8, 9]);
+var MAX_HTTP2_EXPERIMENTAL_SETTING_ID = 15;
+var TLS_VERSION_ALIASES = /* @__PURE__ */ new Map([
+  ["1.0", "1.0"],
+  ["1.1", "1.1"],
+  ["1.2", "1.2"],
+  ["1.3", "1.3"],
+  ["tls1.0", "1.0"],
+  ["tls1.1", "1.1"],
+  ["tls1.2", "1.2"],
+  ["tls1.3", "1.3"]
+]);
+function isNonEmpty(value) {
+  for (const _ in value) return true;
+  return false;
+}
+function normalizeProtocolList(value, label, allowed) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    throw new RequestError(`${label} must be an array`);
+  }
+  for (const protocol of value) {
+    if (!allowed.has(protocol)) {
+      throw new RequestError(`${label} values must be one of: HTTP1, HTTP2, HTTP3`);
+    }
+  }
+  return [...value];
+}
+function normalizeTlsVersion(value, label) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new RequestError(`${label} must be a string`);
+  }
+  const normalized = TLS_VERSION_ALIASES.get(value.trim().toLowerCase());
+  if (!normalized) {
+    throw new RequestError(`${label} must be one of: 1.0, 1.1, 1.2, 1.3`);
+  }
+  return normalized;
+}
+function normalizeOrigHeaders(origHeaders) {
+  if (origHeaders === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(origHeaders)) {
+    throw new RequestError("emulation.origHeaders must be an array of strings");
+  }
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of origHeaders) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+      throw new RequestError("emulation.origHeaders entries must be non-empty strings");
+    }
+    const trimmed = entry.trim();
+    const duplicateKey = trimmed.toLowerCase();
+    if (seen.has(duplicateKey)) {
+      throw new RequestError(`Duplicate emulation.origHeaders entry: ${trimmed}`);
+    }
+    seen.add(duplicateKey);
+    normalized.push(trimmed);
+  }
+  return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeCustomTlsOptions(options) {
+  if (options === void 0) {
+    return void 0;
+  }
+  const normalized = {};
+  const alpnProtocols = normalizeProtocolList(
+    options.alpnProtocols,
+    "emulation.tlsOptions.alpnProtocols",
+    SUPPORTED_ALPN_PROTOCOLS
+  );
+  if (alpnProtocols !== void 0) {
+    normalized.alpnProtocols = alpnProtocols;
+  }
+  const alpsProtocols = normalizeProtocolList(
+    options.alpsProtocols,
+    "emulation.tlsOptions.alpsProtocols",
+    SUPPORTED_ALPS_PROTOCOLS
+  );
+  if (alpsProtocols !== void 0) {
+    normalized.alpsProtocols = alpsProtocols;
+  }
+  const minTlsVersion = normalizeTlsVersion(options.minTlsVersion, "emulation.tlsOptions.minTlsVersion");
+  if (minTlsVersion !== void 0) {
+    normalized.minTlsVersion = minTlsVersion;
+  }
+  const maxTlsVersion = normalizeTlsVersion(options.maxTlsVersion, "emulation.tlsOptions.maxTlsVersion");
+  if (maxTlsVersion !== void 0) {
+    normalized.maxTlsVersion = maxTlsVersion;
+  }
+  if (options.alpsUseNewCodepoint !== void 0) {
+    normalized.alpsUseNewCodepoint = options.alpsUseNewCodepoint;
+  }
+  if (options.sessionTicket !== void 0) {
+    normalized.sessionTicket = options.sessionTicket;
+  }
+  if (options.preSharedKey !== void 0) {
+    normalized.preSharedKey = options.preSharedKey;
+  }
+  if (options.enableEchGrease !== void 0) {
+    normalized.enableEchGrease = options.enableEchGrease;
+  }
+  if (options.permuteExtensions !== void 0) {
+    normalized.permuteExtensions = options.permuteExtensions;
+  }
+  if (options.greaseEnabled !== void 0) {
+    normalized.greaseEnabled = options.greaseEnabled;
+  }
+  if (options.enableOcspStapling !== void 0) {
+    normalized.enableOcspStapling = options.enableOcspStapling;
+  }
+  if (options.enableSignedCertTimestamps !== void 0) {
+    normalized.enableSignedCertTimestamps = options.enableSignedCertTimestamps;
+  }
+  if (options.pskSkipSessionTicket !== void 0) {
+    normalized.pskSkipSessionTicket = options.pskSkipSessionTicket;
+  }
+  if (options.pskDheKe !== void 0) {
+    normalized.pskDheKe = options.pskDheKe;
+  }
+  if (options.renegotiation !== void 0) {
+    normalized.renegotiation = options.renegotiation;
+  }
+  if (options.aesHwOverride !== void 0) {
+    normalized.aesHwOverride = options.aesHwOverride;
+  }
+  if (options.preserveTls13CipherList !== void 0) {
+    normalized.preserveTls13CipherList = options.preserveTls13CipherList;
+  }
+  if (options.randomAesHwOverride !== void 0) {
+    normalized.randomAesHwOverride = options.randomAesHwOverride;
+  }
+  if (options.delegatedCredentials !== void 0) {
+    normalized.delegatedCredentials = options.delegatedCredentials;
+  }
+  if (options.curvesList !== void 0) {
+    normalized.curvesList = options.curvesList;
+  }
+  if (options.cipherList !== void 0) {
+    normalized.cipherList = options.cipherList;
+  }
+  if (options.sigalgsList !== void 0) {
+    normalized.sigalgsList = options.sigalgsList;
+  }
+  if (options.recordSizeLimit !== void 0) {
+    validateIntegerInRange(options.recordSizeLimit, 0, 65535, "emulation.tlsOptions.recordSizeLimit");
+    normalized.recordSizeLimit = options.recordSizeLimit;
+  }
+  if (options.keySharesLimit !== void 0) {
+    validateIntegerInRange(options.keySharesLimit, 0, 255, "emulation.tlsOptions.keySharesLimit");
+    normalized.keySharesLimit = options.keySharesLimit;
+  }
+  if (options.certificateCompressionAlgorithms !== void 0) {
+    if (!Array.isArray(options.certificateCompressionAlgorithms)) {
+      throw new RequestError("emulation.tlsOptions.certificateCompressionAlgorithms must be an array");
+    }
+    const algorithms = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const algorithm of options.certificateCompressionAlgorithms) {
+      if (!SUPPORTED_CERTIFICATE_COMPRESSION_ALGORITHMS.has(algorithm)) {
+        throw new RequestError(
+          "emulation.tlsOptions.certificateCompressionAlgorithms values must be one of: zlib, brotli, zstd"
+        );
+      }
+      if (seen.has(algorithm)) {
+        throw new RequestError(`Duplicate emulation.tlsOptions.certificateCompressionAlgorithms entry: ${algorithm}`);
+      }
+      seen.add(algorithm);
+      algorithms.push(algorithm);
+    }
+    normalized.certificateCompressionAlgorithms = algorithms;
+  }
+  if (options.extensionPermutation !== void 0) {
+    if (!Array.isArray(options.extensionPermutation)) {
+      throw new RequestError("emulation.tlsOptions.extensionPermutation must be an array");
+    }
+    const permutation = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const extensionId of options.extensionPermutation) {
+      validateIntegerInRange(extensionId, 0, 65535, "emulation.tlsOptions.extensionPermutation");
+      if (seen.has(extensionId)) {
+        throw new RequestError(`Duplicate emulation.tlsOptions.extensionPermutation entry: ${extensionId}`);
+      }
+      seen.add(extensionId);
+      permutation.push(extensionId);
+    }
+    normalized.extensionPermutation = permutation;
+  }
+  return isNonEmpty(normalized) ? normalized : void 0;
+}
+function normalizeCustomHttp1Options(options) {
+  if (options === void 0) {
+    return void 0;
+  }
+  const normalized = {};
+  if (options.http09Responses !== void 0) {
+    normalized.http09Responses = options.http09Responses;
+  }
+  if (options.writev !== void 0) {
+    normalized.writev = options.writev;
+  }
+  if (options.ignoreInvalidHeadersInResponses !== void 0) {
+    normalized.ignoreInvalidHeadersInResponses = options.ignoreInvalidHeadersInResponses;
+  }
+  if (options.allowSpacesAfterHeaderNameInResponses !== void 0) {
+    normalized.allowSpacesAfterHeaderNameInResponses = options.allowSpacesAfterHeaderNameInResponses;
+  }
+  if (options.allowObsoleteMultilineHeadersInResponses !== void 0) {
+    normalized.allowObsoleteMultilineHeadersInResponses = options.allowObsoleteMultilineHeadersInResponses;
+  }
+  if (options.maxHeaders !== void 0) {
+    validateNonNegativeInteger(options.maxHeaders, "emulation.http1Options.maxHeaders");
+    normalized.maxHeaders = options.maxHeaders;
+  }
+  if (options.readBufExactSize !== void 0) {
+    validateNonNegativeInteger(options.readBufExactSize, "emulation.http1Options.readBufExactSize");
+    normalized.readBufExactSize = options.readBufExactSize;
+  }
+  if (options.maxBufSize !== void 0) {
+    validateNonNegativeInteger(options.maxBufSize, "emulation.http1Options.maxBufSize");
+    if (options.maxBufSize < 8192) {
+      throw new RequestError("emulation.http1Options.maxBufSize must be greater than or equal to 8192");
+    }
+    normalized.maxBufSize = options.maxBufSize;
+  }
+  if (normalized.readBufExactSize !== void 0 && normalized.maxBufSize !== void 0) {
+    throw new RequestError("emulation.http1Options.readBufExactSize and maxBufSize cannot both be set");
+  }
+  return isNonEmpty(normalized) ? normalized : void 0;
+}
+function normalizeHttp2StreamDependency(dependency, label) {
+  if (!isPlainObject(dependency)) {
+    throw new RequestError(`${label} must be an object`);
+  }
+  validateIntegerInRange(dependency.dependencyId, 0, 2147483647, `${label}.dependencyId`);
+  validateIntegerInRange(dependency.weight, 0, 255, `${label}.weight`);
+  const normalized = {
+    dependencyId: dependency.dependencyId,
+    weight: dependency.weight
+  };
+  if (dependency.exclusive !== void 0) {
+    normalized.exclusive = dependency.exclusive;
+  }
+  return normalized;
+}
+function normalizeCustomHttp2Options(options) {
+  if (options === void 0) {
+    return void 0;
+  }
+  const normalized = {};
+  if (options.adaptiveWindow !== void 0) {
+    normalized.adaptiveWindow = options.adaptiveWindow;
+  }
+  if (options.keepAliveWhileIdle !== void 0) {
+    normalized.keepAliveWhileIdle = options.keepAliveWhileIdle;
+  }
+  if (options.enablePush !== void 0) {
+    normalized.enablePush = options.enablePush;
+  }
+  if (options.enableConnectProtocol !== void 0) {
+    normalized.enableConnectProtocol = options.enableConnectProtocol;
+  }
+  if (options.noRfc7540Priorities !== void 0) {
+    normalized.noRfc7540Priorities = options.noRfc7540Priorities;
+  }
+  if (options.initialStreamId !== void 0) {
+    validateNonNegativeInteger(options.initialStreamId, "emulation.http2Options.initialStreamId");
+    normalized.initialStreamId = options.initialStreamId;
+  }
+  if (options.initialConnectionWindowSize !== void 0) {
+    validateNonNegativeInteger(
+      options.initialConnectionWindowSize,
+      "emulation.http2Options.initialConnectionWindowSize"
+    );
+    normalized.initialConnectionWindowSize = options.initialConnectionWindowSize;
+  }
+  if (options.initialWindowSize !== void 0) {
+    validateNonNegativeInteger(options.initialWindowSize, "emulation.http2Options.initialWindowSize");
+    normalized.initialWindowSize = options.initialWindowSize;
+  }
+  if (options.initialMaxSendStreams !== void 0) {
+    validateNonNegativeInteger(options.initialMaxSendStreams, "emulation.http2Options.initialMaxSendStreams");
+    normalized.initialMaxSendStreams = options.initialMaxSendStreams;
+  }
+  if (options.maxFrameSize !== void 0) {
+    validateNonNegativeInteger(options.maxFrameSize, "emulation.http2Options.maxFrameSize");
+    normalized.maxFrameSize = options.maxFrameSize;
+  }
+  if (options.keepAliveInterval !== void 0) {
+    validateNonNegativeInteger(options.keepAliveInterval, "emulation.http2Options.keepAliveInterval");
+    normalized.keepAliveInterval = options.keepAliveInterval;
+  }
+  if (options.keepAliveTimeout !== void 0) {
+    validateNonNegativeInteger(options.keepAliveTimeout, "emulation.http2Options.keepAliveTimeout");
+    normalized.keepAliveTimeout = options.keepAliveTimeout;
+  }
+  if (options.maxConcurrentResetStreams !== void 0) {
+    validateNonNegativeInteger(options.maxConcurrentResetStreams, "emulation.http2Options.maxConcurrentResetStreams");
+    normalized.maxConcurrentResetStreams = options.maxConcurrentResetStreams;
+  }
+  if (options.maxSendBufferSize !== void 0) {
+    validateNonNegativeInteger(options.maxSendBufferSize, "emulation.http2Options.maxSendBufferSize");
+    normalized.maxSendBufferSize = options.maxSendBufferSize;
+  }
+  if (options.maxConcurrentStreams !== void 0) {
+    validateNonNegativeInteger(options.maxConcurrentStreams, "emulation.http2Options.maxConcurrentStreams");
+    normalized.maxConcurrentStreams = options.maxConcurrentStreams;
+  }
+  if (options.maxHeaderListSize !== void 0) {
+    validateNonNegativeInteger(options.maxHeaderListSize, "emulation.http2Options.maxHeaderListSize");
+    normalized.maxHeaderListSize = options.maxHeaderListSize;
+  }
+  if (options.maxPendingAcceptResetStreams !== void 0) {
+    validateNonNegativeInteger(
+      options.maxPendingAcceptResetStreams,
+      "emulation.http2Options.maxPendingAcceptResetStreams"
+    );
+    normalized.maxPendingAcceptResetStreams = options.maxPendingAcceptResetStreams;
+  }
+  if (options.headerTableSize !== void 0) {
+    validateNonNegativeInteger(options.headerTableSize, "emulation.http2Options.headerTableSize");
+    normalized.headerTableSize = options.headerTableSize;
+  }
+  if (options.settingsOrder !== void 0) {
+    if (!Array.isArray(options.settingsOrder)) {
+      throw new RequestError("emulation.http2Options.settingsOrder must be an array");
+    }
+    const settingsOrder = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const settingId of options.settingsOrder) {
+      if (!HTTP2_SETTING_IDS.has(settingId)) {
+        throw new RequestError("emulation.http2Options.settingsOrder contains an unsupported setting id");
+      }
+      if (seen.has(settingId)) {
+        throw new RequestError(`Duplicate emulation.http2Options.settingsOrder entry: ${settingId}`);
+      }
+      seen.add(settingId);
+      settingsOrder.push(settingId);
+    }
+    normalized.settingsOrder = settingsOrder;
+  }
+  if (options.headersPseudoOrder !== void 0) {
+    if (!Array.isArray(options.headersPseudoOrder)) {
+      throw new RequestError("emulation.http2Options.headersPseudoOrder must be an array");
+    }
+    const headersPseudoOrder = [];
+    const seenPseudo = /* @__PURE__ */ new Set();
+    for (const pseudoId of options.headersPseudoOrder) {
+      if (!HTTP2_PSEUDO_HEADER_IDS.has(pseudoId)) {
+        throw new RequestError("emulation.http2Options.headersPseudoOrder contains an unsupported pseudo-header id");
+      }
+      if (seenPseudo.has(pseudoId)) {
+        throw new RequestError(`Duplicate emulation.http2Options.headersPseudoOrder entry: ${pseudoId}`);
+      }
+      seenPseudo.add(pseudoId);
+      headersPseudoOrder.push(pseudoId);
+    }
+    normalized.headersPseudoOrder = headersPseudoOrder;
+  }
+  if (options.headersStreamDependency !== void 0) {
+    normalized.headersStreamDependency = normalizeHttp2StreamDependency(
+      options.headersStreamDependency,
+      "emulation.http2Options.headersStreamDependency"
+    );
+  }
+  if (options.priorities !== void 0) {
+    if (!Array.isArray(options.priorities)) {
+      throw new RequestError("emulation.http2Options.priorities must be an array");
+    }
+    const priorities = [];
+    const seenStreamIds = /* @__PURE__ */ new Set();
+    for (const [index, priority] of options.priorities.entries()) {
+      if (!isPlainObject(priority)) {
+        throw new RequestError(`emulation.http2Options.priorities[${index}] must be an object`);
+      }
+      validatePositiveInteger(priority.streamId, `emulation.http2Options.priorities[${index}].streamId`);
+      if (seenStreamIds.has(priority.streamId)) {
+        throw new RequestError(`Duplicate emulation.http2Options.priorities streamId: ${priority.streamId}`);
+      }
+      seenStreamIds.add(priority.streamId);
+      priorities.push({
+        streamId: priority.streamId,
+        dependency: normalizeHttp2StreamDependency(
+          priority.dependency,
+          `emulation.http2Options.priorities[${index}].dependency`
+        )
+      });
+    }
+    normalized.priorities = priorities;
+  }
+  if (options.experimentalSettings !== void 0) {
+    if (!Array.isArray(options.experimentalSettings)) {
+      throw new RequestError("emulation.http2Options.experimentalSettings must be an array");
+    }
+    const experimentalSettings = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    for (const [index, setting] of options.experimentalSettings.entries()) {
+      if (!isPlainObject(setting)) {
+        throw new RequestError(`emulation.http2Options.experimentalSettings[${index}] must be an object`);
+      }
+      validateIntegerInRange(
+        setting.id,
+        1,
+        MAX_HTTP2_EXPERIMENTAL_SETTING_ID,
+        `emulation.http2Options.experimentalSettings[${index}].id`
+      );
+      if (STANDARD_HTTP2_SETTING_ID_VALUES.has(setting.id)) {
+        throw new RequestError(
+          `emulation.http2Options.experimentalSettings[${index}].id must not be a standard HTTP/2 setting id`
+        );
+      }
+      if (seenIds.has(setting.id)) {
+        throw new RequestError(`Duplicate emulation.http2Options.experimentalSettings id: ${setting.id}`);
+      }
+      seenIds.add(setting.id);
+      validateIntegerInRange(
+        setting.value,
+        0,
+        4294967295,
+        `emulation.http2Options.experimentalSettings[${index}].value`
+      );
+      experimentalSettings.push({
+        id: setting.id,
+        value: setting.value
+      });
+    }
+    normalized.experimentalSettings = experimentalSettings;
+  }
+  return isNonEmpty(normalized) ? normalized : void 0;
+}
+function normalizeCustomEmulationOptions(emulation, allowEmpty) {
+  if (emulation === void 0) {
+    return void 0;
+  }
+  if (!isPlainObject(emulation)) {
+    throw new RequestError("emulation must be an object");
+  }
+  const source = emulation;
+  const normalized = {};
+  const tlsOptions = normalizeCustomTlsOptions(source.tlsOptions);
+  if (tlsOptions !== void 0) {
+    normalized.tlsOptions = tlsOptions;
+  }
+  const http1Options = normalizeCustomHttp1Options(source.http1Options);
+  if (http1Options !== void 0) {
+    normalized.http1Options = http1Options;
+  }
+  const http2Options = normalizeCustomHttp2Options(source.http2Options);
+  if (http2Options !== void 0) {
+    normalized.http2Options = http2Options;
+  }
+  if (source.headers !== void 0) {
+    const headers = headersToTuples(source.headers);
+    if (headers.length > 0) {
+      normalized.headers = headers;
+    }
+  }
+  const origHeaders = normalizeOrigHeaders(source.origHeaders);
+  if (origHeaders !== void 0) {
+    normalized.origHeaders = origHeaders;
+  }
+  if (!allowEmpty && !isNonEmpty(normalized)) {
+    throw new RequestError(
+      "Standalone custom emulation requires at least one of tlsOptions, http1Options, http2Options, headers, or origHeaders"
+    );
+  }
+  return isNonEmpty(normalized) ? normalized : void 0;
+}
+function serializeCustomEmulationOptions(emulation, allowEmpty) {
+  const normalized = normalizeCustomEmulationOptions(emulation, allowEmpty);
+  return normalized ? JSON.stringify(normalized) : void 0;
+}
+function resolveEmulationMode(browser, os, emulation) {
+  if (browser !== void 0) {
+    validateBrowserProfile(browser);
+    if (os !== void 0) {
+      validateOperatingSystem(os);
+    }
+    const emulationJson = serializeCustomEmulationOptions(emulation, true);
+    return {
+      kind: "preset",
+      browser,
+      os: os ?? DEFAULT_OS,
+      ...emulationJson !== void 0 && { emulationJson }
+    };
+  }
+  if (os !== void 0) {
+    validateOperatingSystem(os);
+    const emulationJson = serializeCustomEmulationOptions(emulation, true);
+    return {
+      kind: "preset",
+      browser: DEFAULT_BROWSER,
+      os,
+      ...emulationJson !== void 0 && { emulationJson }
+    };
+  }
+  if (emulation !== void 0) {
+    const emulationJson = serializeCustomEmulationOptions(emulation, false);
+    if (emulationJson === void 0) {
+      throw new RequestError(
+        "Standalone custom emulation requires at least one of tlsOptions, http1Options, http2Options, headers, or origHeaders"
+      );
+    }
+    return { kind: "custom", emulationJson };
+  }
+  return {
+    kind: "preset",
+    browser: DEFAULT_BROWSER,
+    os: DEFAULT_OS
+  };
+}
+function applyNativeEmulationMode(target, mode) {
+  if (mode.kind === "custom") {
+    target.emulationJson = mode.emulationJson;
+    return;
+  }
+  target.browser = mode.browser;
+  target.os = mode.os;
+  if (mode.emulationJson !== void 0) {
+    target.emulationJson = mode.emulationJson;
+  }
+}
 async function dispatchRequest(options, requestUrl, signal) {
   if (!signal) {
     const requestId2 = generateRequestId();
@@ -1179,8 +1749,9 @@ async function fetch(input, init) {
   if (transport.transportId) {
     requestOptions.transportId = transport.transportId;
   } else {
-    requestOptions.browser = transport.browser ?? DEFAULT_BROWSER;
-    requestOptions.os = transport.os ?? DEFAULT_OS;
+    if (transport.mode !== void 0) {
+      applyNativeEmulationMode(requestOptions, transport.mode);
+    }
     if (transport.proxy !== void 0) {
       requestOptions.proxy = transport.proxy;
     }
@@ -1204,10 +1775,7 @@ async function fetch(input, init) {
   return dispatchRequest(requestOptions, url, config.signal ?? null);
 }
 async function createTransport(options) {
-  const browser = options?.browser ?? DEFAULT_BROWSER;
-  const os = options?.os ?? DEFAULT_OS;
-  validateBrowserProfile(browser);
-  validateOperatingSystem(os);
+  const mode = resolveEmulationMode(options?.browser, options?.os, options?.emulation);
   if (options?.poolIdleTimeout !== void 0) {
     validatePositiveNumber(options.poolIdleTimeout, "poolIdleTimeout");
   }
@@ -1224,9 +1792,7 @@ async function createTransport(options) {
     validatePositiveNumber(options.readTimeout, "readTimeout");
   }
   try {
-    const id = nativeBinding.createTransport({
-      browser,
-      os,
+    const transportOptions = {
       ...options?.proxy !== void 0 && { proxy: options.proxy },
       ...options?.insecure !== void 0 && { insecure: options.insecure },
       ...options?.poolIdleTimeout !== void 0 && { poolIdleTimeout: options.poolIdleTimeout },
@@ -1234,7 +1800,9 @@ async function createTransport(options) {
       ...options?.poolMaxSize !== void 0 && { poolMaxSize: options.poolMaxSize },
       ...options?.connectTimeout !== void 0 && { connectTimeout: options.connectTimeout },
       ...options?.readTimeout !== void 0 && { readTimeout: options.readTimeout }
-    });
+    };
+    applyNativeEmulationMode(transportOptions, mode);
+    const id = nativeBinding.createTransport(transportOptions);
     return new Transport(id);
   } catch (error) {
     throw new RequestError(String(error));
@@ -1242,17 +1810,15 @@ async function createTransport(options) {
 }
 async function createSession(options) {
   const { sessionId, defaults } = normalizeSessionOptions(options);
-  validateBrowserProfile(defaults.browser);
-  validateOperatingSystem(defaults.os);
   let createdId;
   let transportId;
   try {
-    transportId = nativeBinding.createTransport({
-      browser: defaults.browser,
-      os: defaults.os,
+    const transportOptions = {
       ...defaults.proxy !== void 0 && { proxy: defaults.proxy },
       ...defaults.insecure !== void 0 && { insecure: defaults.insecure }
-    });
+    };
+    applyNativeEmulationMode(transportOptions, defaults.transportMode);
+    transportId = nativeBinding.createTransport(transportOptions);
   } catch (error) {
     throw new RequestError(String(error));
   }
@@ -1301,6 +1867,9 @@ async function request(options) {
   if (rest.os !== void 0) {
     init.os = rest.os;
   }
+  if (rest.emulation !== void 0) {
+    init.emulation = rest.emulation;
+  }
   if (rest.proxy !== void 0) {
     init.proxy = rest.proxy;
   }
@@ -1434,6 +2003,9 @@ function normalizeStandaloneWebSocketOptions(options) {
   if (options.os !== void 0) {
     normalized.os = options.os;
   }
+  if (options.emulation !== void 0) {
+    normalized.emulation = options.emulation;
+  }
   if (options.headers !== void 0) {
     normalized.headers = options.headers;
   }
@@ -1465,6 +2037,11 @@ function normalizeSessionWebSocketOptions(options) {
   if (optionsWithOverrides.os !== void 0) {
     throw new RequestError("`os` is not supported in session.websocket(); the session controls OS emulation.");
   }
+  if (optionsWithOverrides.emulation !== void 0) {
+    throw new RequestError(
+      "`emulation` is not supported in session.websocket(); the session transport controls emulation."
+    );
+  }
   if (optionsWithOverrides.proxy !== void 0) {
     throw new RequestError("`proxy` is not supported in session.websocket(); the session transport controls proxying.");
   }
@@ -1630,10 +2207,11 @@ var WebSocket = class _WebSocket {
       typeof protocolsOrOptions === "string" || Array.isArray(protocolsOrOptions) ? protocolsOrOptions : normalizedOptions.protocols
     );
     assertNoManualWebSocketProtocolHeader(normalizedOptions.headers);
-    validateBrowserProfile(normalizedOptions.browser);
-    const os = normalizedOptions.os ?? DEFAULT_OS;
-    validateOperatingSystem(os);
-    const browser = normalizedOptions.browser ?? DEFAULT_BROWSER;
+    const emulationMode = resolveEmulationMode(
+      normalizedOptions.browser,
+      normalizedOptions.os,
+      normalizedOptions.emulation
+    );
     const protocols = normalizeWebSocketProtocolList(
       typeof protocolsOrOptions === "string" || Array.isArray(protocolsOrOptions) ? protocolsOrOptions : normalizedOptions.protocols
     );
@@ -1642,17 +2220,19 @@ var WebSocket = class _WebSocket {
       url: normalizeWebSocketUrl(url),
       options: normalizedOptions,
       openDispatchMode: "automatic",
-      connect: (callbacks) => nativeBinding.websocketConnect({
-        url: normalizeWebSocketUrl(url),
-        browser,
-        os,
-        headers: headersToTuples(normalizedOptions.headers ?? {}),
-        ...protocols && protocols.length > 0 && { protocols },
-        ...normalizedOptions.proxy !== void 0 && { proxy: normalizedOptions.proxy },
-        onMessage: callbacks.onMessage,
-        onClose: callbacks.onClose,
-        onError: callbacks.onError
-      }),
+      connect: (callbacks) => {
+        const nativeOptions = {
+          url: normalizeWebSocketUrl(url),
+          headers: headersToTuples(normalizedOptions.headers ?? {}),
+          ...protocols && protocols.length > 0 && { protocols },
+          ...normalizedOptions.proxy !== void 0 && { proxy: normalizedOptions.proxy },
+          onMessage: callbacks.onMessage,
+          onClose: callbacks.onClose,
+          onError: callbacks.onError
+        };
+        applyNativeEmulationMode(nativeOptions, emulationMode);
+        return nativeBinding.websocketConnect(nativeOptions);
+      },
       legacyCallbacks: extractLegacyWebSocketCallbacks(optionsCandidate)
     };
   }
@@ -2046,27 +2626,30 @@ async function websocket(urlOrOptions, options) {
   const normalized = normalizeStandaloneWebSocketArgs(urlOrOptions, options);
   validateWebSocketProtocols(normalized.options.protocols);
   assertNoManualWebSocketProtocolHeader(normalized.options.headers);
-  validateBrowserProfile(normalized.options.browser);
-  const os = normalized.options.os ?? DEFAULT_OS;
-  validateOperatingSystem(os);
-  const browser = normalized.options.browser ?? DEFAULT_BROWSER;
+  const emulationMode = resolveEmulationMode(
+    normalized.options.browser,
+    normalized.options.os,
+    normalized.options.emulation
+  );
   const protocols = normalizeWebSocketProtocolList(normalized.options.protocols);
   return WebSocket._connectWithInit({
     _internal: true,
     url: normalized.url,
     options: normalized.options,
     openDispatchMode: "deferred",
-    connect: (callbacks) => nativeBinding.websocketConnect({
-      url: normalized.url,
-      browser,
-      os,
-      headers: headersToTuples(normalized.options.headers ?? {}),
-      ...protocols && protocols.length > 0 && { protocols },
-      ...normalized.options.proxy !== void 0 && { proxy: normalized.options.proxy },
-      onMessage: callbacks.onMessage,
-      onClose: callbacks.onClose,
-      onError: callbacks.onError
-    }),
+    connect: (callbacks) => {
+      const nativeOptions = {
+        url: normalized.url,
+        headers: headersToTuples(normalized.options.headers ?? {}),
+        ...protocols && protocols.length > 0 && { protocols },
+        ...normalized.options.proxy !== void 0 && { proxy: normalized.options.proxy },
+        onMessage: callbacks.onMessage,
+        onClose: callbacks.onClose,
+        onError: callbacks.onError
+      };
+      applyNativeEmulationMode(nativeOptions, emulationMode);
+      return nativeBinding.websocketConnect(nativeOptions);
+    },
     legacyCallbacks: normalized.legacyCallbacks
   });
 }