@scalar/workspace-store 0.49.2 → 0.51.0

package/dist/request-example/builder/build-request.js

@@ -1,18 +1,79 @@
+import { X_SCALAR_DATE, X_SCALAR_DNT, X_SCALAR_REFERER, X_SCALAR_USER_AGENT } from '@scalar/helpers/http/scalar-headers';
 import { replaceEnvVariables } from '@scalar/helpers/regex/replace-variables';
+import { err, ok } from '@scalar/helpers/types/result';
+import { safeRun } from '@scalar/helpers/types/safe-run';
 import { redirectToProxy, shouldUseProxy } from '@scalar/helpers/url/redirect-to-proxy';
 import { encode as encodeBase64 } from 'js-base64';
 import { buildRequestCookieHeader } from '../../request-example/builder/header/build-request-cookie-header.js';
 import { applyAllowReservedToUrl } from '../../request-example/builder/helpers/apply-allow-reserved-to-url.js';
-import { resolveRequestFactoryUrl } from '../../request-example/builder/resolve-request-factory-url.js';
+import { resolveRequestFactoryUrl, } from '../../request-example/builder/resolve-request-factory-url.js';
 import { contextFunctions, isContextFunctionName } from '../../request-example/functions.js';
-export const buildRequest = (request, options) => {
-    /** Replace the value with the environment variable or context function */
-    const replace = (value) => {
+const FORBIDDEN_HEADERS = [
+    { header: 'date', scalarHeader: X_SCALAR_DATE },
+    { header: 'dnt', scalarHeader: X_SCALAR_DNT },
+    { header: 'referer', scalarHeader: X_SCALAR_REFERER },
+    { header: 'user-agent', scalarHeader: X_SCALAR_USER_AGENT },
+];
+const formatSecurityValue = (security, replace) => {
+    const substitutedValue = replaceEnvVariables(security.value, replace);
+    if (security.format === 'basic') {
+        return `Basic ${encodeBase64(substitutedValue)}`;
+    }
+    if (security.format === 'bearer') {
+        return `Bearer ${substitutedValue}`;
+    }
+    return substitutedValue;
+};
+const createEnvReplaceFn = (envVariables) => {
+    return (value) => {
         if (isContextFunctionName(value)) {
             return contextFunctions[value].fn() ?? null;
         }
-        return options.envVariables[value] ?? null;
+        return envVariables[value] ?? null;
     };
+};
+/**
+ * Resolved request URL string (path vars, operation query, **security query**
+ * params, env substitution, reserved-query rules) without proxy rewriting —
+ * aligned with {@link buildRequest} before `redirectToProxy`.
+ *
+ * By default allows incomplete merged URLs (same as permissive copy / preview); pass
+ * `allowMissingRequestServerBase: false` to enforce a complete absolute URL.
+ */
+export const resolveExecutableRequestUrl = (request, envVariables, resolveOptions) => {
+    const replace = createEnvReplaceFn(envVariables);
+    const securityQueryParams = new URLSearchParams();
+    if (!request.options?.disableSecurity) {
+        request.security.forEach((security) => {
+            if (security.in !== 'query') {
+                return;
+            }
+            const name = replaceEnvVariables(security.name, replace);
+            securityQueryParams.append(name, formatSecurityValue(security, replace));
+        });
+    }
+    const requestUrl = resolveRequestFactoryUrl(request, {
+        envVariables: replace,
+        securityQueryParams,
+        allowMissingRequestServerBase: resolveOptions?.allowMissingRequestServerBase ?? true,
+    });
+    if (!requestUrl.ok) {
+        throw new Error(requestUrl.message ?? requestUrl.error);
+    }
+    return applyAllowReservedToUrl(requestUrl.data, request.allowedReservedQueryParameters ?? new Set());
+};
+/** Catch-all code when an unexpected synchronous error escapes a helper during request construction. */
+export const BUILD_REQUEST_FAILED = 'BUILD_REQUEST_FAILED';
+export const buildRequest = (request, options) => {
+    const guarded = safeRun(() => buildRequestInner(request, options));
+    if (!guarded.ok) {
+        return err(BUILD_REQUEST_FAILED, guarded.error);
+    }
+    return guarded.data;
+};
+const buildRequestInner = (request, options) => {
+    /** Replace the value with the environment variable or context function */
+    const replace = createEnvReplaceFn(options.envVariables);
     /** Create a new abort controller */
     const controller = new AbortController();
     /** Create a new headers object with the replaced values */
@@ -60,16 +121,7 @@ export const buildRequest = (request, options) => {
             // - For 'basic': prefix with 'Basic' and base64-encode the value (username:password).
             // - For 'bearer': prefix with 'Bearer'.
             // - Otherwise: use the substituted value as is (for API keys, etc).
-            const securityValue = (() => {
-                const substitutedValue = replaceEnvVariables(security.value, replace);
-                if (security.format === 'basic') {
-                    return `Basic ${encodeBase64(substitutedValue)}`;
-                }
-                if (security.format === 'bearer') {
-                    return `Bearer ${substitutedValue}`;
-                }
-                return substitutedValue;
-            })();
+            const securityValue = formatSecurityValue(security, replace);
             if (security.in === 'header') {
                 // Set the header (use replaced header name so {{ env }} placeholders work)
                 headers.append(name, securityValue);
@@ -89,10 +141,15 @@ export const buildRequest = (request, options) => {
         });
     }
     /** Resolve the request URL with the replaced values */
-    const requestUrl = resolveRequestFactoryUrl(request, {
+    const requestUrlResult = resolveRequestFactoryUrl(request, {
         envVariables: replace,
         securityQueryParams: securityQueryParams,
+        allowMissingRequestServerBase: options.allowMissingRequestServerBase,
     });
+    if (!requestUrlResult.ok) {
+        return err(requestUrlResult.error, requestUrlResult.message);
+    }
+    const requestUrl = requestUrlResult.data;
     /** Check if the request should be proxied */
     const isUsingProxy = shouldUseProxy(request.proxyUrl, requestUrl);
     /** Create a new cookies array with the replaced values */
@@ -112,10 +169,24 @@ export const buildRequest = (request, options) => {
     if (cookieHeader) {
         headers.set(cookieHeader.name, cookieHeader.value);
     }
+    /**
+     * Browsers strip some forbidden headers from outgoing requests.
+     * For a small, explicit allowlist we mirror those values to `X-Scalar-*`
+     * so proxy/Electron can apply them server-side.
+     */
+    if (isUsingProxy || request.options?.isElectron) {
+        FORBIDDEN_HEADERS.forEach(({ header, scalarHeader }) => {
+            const headerValue = headers.get(header);
+            if (headerValue) {
+                headers.set(scalarHeader, headerValue);
+                headers.delete(header);
+            }
+        });
+    }
     /** Encode the URL with the allowed reserved query parameters */
     const encodedUrl = applyAllowReservedToUrl(requestUrl, request.allowedReservedQueryParameters ?? new Set());
     const finalUrl = isUsingProxy ? redirectToProxy(request.proxyUrl, encodedUrl) : encodedUrl;
-    return {
+    return ok({
         requestPayload: [
             finalUrl,
             {
@@ -133,5 +204,5 @@ export const buildRequest = (request, options) => {
         ],
         controller,
         isUsingProxy,
-    };
+    });
 };

package/dist/request-example/builder/index.d.ts

@@ -1,6 +1,6 @@
 export { getExampleFromBody } from './body/get-request-body-example.js';
 export { getSelectedBodyContentType } from './body/get-selected-body-content-type.js';
-export { type RequestPayload, buildRequest } from './build-request.js';
+export { BUILD_REQUEST_FAILED, type BuildRequestData, type BuildRequestFailureCode, type BuildRequestResult, type RequestPayload, buildRequest, resolveExecutableRequestUrl, } from './build-request.js';
 export { deSerializeParameter } from './header/de-serialize-parameter.js';
 export { filterGlobalCookie } from './header/filter-global-cookies.js';
 export { serializeContentValue, serializeDeepObjectStyle, serializeFormStyle, serializeFormStyleForCookies, serializePipeDelimitedStyle, serializeSimpleStyle, serializeSpaceDelimitedStyle, } from './header/serialize-parameter.js';
@@ -11,6 +11,7 @@ export { getResolvedUrl } from './helpers/get-resolved-url.js';
 export { getServerVariables } from './helpers/get-server-variables.js';
 export type { RequestFactory } from './request-factory.js';
 export { requestFactory } from './request-factory.js';
+export { INVALID_REQUEST_FACTORY_URL, MISSING_REQUEST_SERVER_BASE, type ResolveRequestFactoryUrlError, type ResolveRequestFactoryUrlResult, resolveRequestFactoryUrl, } from './resolve-request-factory-url.js';
 export { buildRequestSecurity } from './security/build-request-security.js';
 export type { ApiKeyObjectSecret, HttpObjectSecret, OAuth2ObjectSecret, OAuthFlowAuthorizationCodeSecret, OAuthFlowClientCredentialsSecret, OAuthFlowImplicitSecret, OAuthFlowPasswordSecret, OAuthFlowsObjectSecret, OpenIdConnectObjectSecret, SecuritySchemeObjectSecret, } from './security/secret-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/request-example/builder/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,4BAA4B,EAC5B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AACxE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,gCAAgC,EAChC,gCAAgC,EAChC,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,EACL,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,YAAY,EACZ,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,4BAA4B,EAC5B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,6BAA6B,EAClC,KAAK,8BAA8B,EACnC,wBAAwB,GACzB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AACxE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,gCAAgC,EAChC,gCAAgC,EAChC,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAA"}

package/dist/request-example/builder/index.js

@@ -1,6 +1,6 @@
 export { getExampleFromBody } from './body/get-request-body-example.js';
 export { getSelectedBodyContentType } from './body/get-selected-body-content-type.js';
-export { buildRequest } from './build-request.js';
+export { BUILD_REQUEST_FAILED, buildRequest, resolveExecutableRequestUrl, } from './build-request.js';
 export { deSerializeParameter } from './header/de-serialize-parameter.js';
 export { filterGlobalCookie } from './header/filter-global-cookies.js';
 export { serializeContentValue, serializeDeepObjectStyle, serializeFormStyle, serializeFormStyleForCookies, serializePipeDelimitedStyle, serializeSimpleStyle, serializeSpaceDelimitedStyle, } from './header/serialize-parameter.js';
@@ -10,4 +10,5 @@ export { getExampleFromSchema } from './helpers/get-example-from-schema.js';
 export { getResolvedUrl } from './helpers/get-resolved-url.js';
 export { getServerVariables } from './helpers/get-server-variables.js';
 export { requestFactory } from './request-factory.js';
+export { INVALID_REQUEST_FACTORY_URL, MISSING_REQUEST_SERVER_BASE, resolveRequestFactoryUrl, } from './resolve-request-factory-url.js';
 export { buildRequestSecurity } from './security/build-request-security.js';

package/dist/request-example/builder/request-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-factory.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/request-factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2EAA2E,CAAA;AACnH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qEAAqE,CAAA;AACxG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8DAA8D,CAAA;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAG5F,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,2DAA2D,CAAA;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAA;AACjG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,EAAE,KAAK,WAAW,EAAoB,MAAM,2BAA2B,CAAA;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,EAAE;QACJ;;;;;WAKG;QACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACjC;;;;;WAKG;QACH,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;IAED;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAA;IAEtB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;;OAIG;IACH,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IAExB;;;;OAIG;IACH,OAAO,EAAE,aAAa,EAAE,CAAA;IAExB;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAA;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,0BAA0B,EAAE,CAAA;IAEtC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAE5C;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;QACf;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAA;QACnB;;;WAGG;QACH,eAAe,EAAE,OAAO,CAAA;KACzB,CAAC,CAAA;CACH,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,kKAY5B,kBAAkB,GAAG;IACtB,2BAA2B;IAC3B,SAAS,EAAE,eAAe,CAAA;IAC1B,8CAA8C;IAC9C,WAAW,EAAE,kBAAkB,CAAA;IAC/B,mCAAmC;IACnC,aAAa,EAAE,aAAa,EAAE,CAAA;IAC9B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IAC3B,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAA;IACnB,8DAA8D;IAC9D,uBAAuB,EAAE,0BAA0B,EAAE,CAAA;IACrD,sEAAsE;IACtE,+BAA+B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzD,KAAG;IACF,OAAO,EAAE,cAAc,CAAA;CAyExB,CAAA"}
+{"version":3,"file":"request-factory.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/request-factory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2EAA2E,CAAA;AACnH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qEAAqE,CAAA;AACxG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8DAA8D,CAAA;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAG5F,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,2DAA2D,CAAA;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAA;AACjG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAGjE,OAAO,EAAE,KAAK,WAAW,EAAoB,MAAM,2BAA2B,CAAA;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,EAAE;QACJ;;;;;WAKG;QACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACjC;;;;;WAKG;QACH,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;IAED;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAA;IAEtB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;;OAIG;IACH,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IAExB;;;;OAIG;IACH,OAAO,EAAE,aAAa,EAAE,CAAA;IAExB;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAA;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,0BAA0B,EAAE,CAAA;IAEtC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAE5C;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;QACf;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAA;QACnB;;;WAGG;QACH,eAAe,EAAE,OAAO,CAAA;KACzB,CAAC,CAAA;CACH,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,kKAY5B,kBAAkB,GAAG;IACtB,2BAA2B;IAC3B,SAAS,EAAE,eAAe,CAAA;IAC1B,8CAA8C;IAC9C,WAAW,EAAE,kBAAkB,CAAA;IAC/B,mCAAmC;IACnC,aAAa,EAAE,aAAa,EAAE,CAAA;IAC9B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IAC3B,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAA;IACnB,8DAA8D;IAC9D,uBAAuB,EAAE,0BAA0B,EAAE,CAAA;IACrD,sEAAsE;IACtE,+BAA+B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzD,KAAG;IACF,OAAO,EAAE,cAAc,CAAA;CAqExB,CAAA"}

package/dist/request-example/builder/request-factory.js

@@ -1,9 +1,9 @@
 import { canMethodHaveBody } from '@scalar/helpers/http/can-method-have-body';
-import { X_SCALAR_USER_AGENT } from '@scalar/helpers/http/scalar-headers';
 import { replacePathVariables } from '@scalar/helpers/regex/replace-variables';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getServerVariables } from '../../request-example/builder/helpers/get-server-variables.js';
 import { buildRequestSecurity, } from '../../request-example/builder/security/build-request-security.js';
+import { filterDisabledDefaultHeaders } from '../context/headers.js';
 import { buildRequestBody } from './body/build-request-body.js';
 import { buildRequestParameters } from './header/build-request-parameters.js';
 /**
@@ -15,7 +15,10 @@ export const requestFactory = ({ exampleName, globalCookies, method, operation,
     /** Build out the request parameters */
     const params = buildRequestParameters(operation.parameters ?? [], exampleName);
     const security = buildRequestSecurity(selectedSecuritySchemes);
-    const headers = new Headers({ ...defaultHeaders, ...params.headers });
+    const headers = new Headers({
+        ...filterDisabledDefaultHeaders(operation, exampleName, defaultHeaders),
+        ...params.headers,
+    });
     // If the method can have a body, build the request body, otherwise set it to null
     const body = canMethodHaveBody(method)
         ? buildRequestBody(requestBody, exampleName, requestBodyCompositionSelection)
@@ -27,12 +30,6 @@ export const requestFactory = ({ exampleName, globalCookies, method, operation,
     /** Combine the server url, path and url params into a single url */
     const serverVariables = getServerVariables(server);
     const baseUrl = replacePathVariables(server?.url ?? '', serverVariables);
-    // If we are running in Electron, we need to add a custom header
-    // that's then forwarded as a `User-Agent` header.
-    const userAgentHeader = headers.get('User-Agent');
-    if (isElectron && userAgentHeader) {
-        headers.set(X_SCALAR_USER_AGENT, userAgentHeader);
-    }
     const globalCookieFilter = operation['x-scalar-disable-parameters']?.['global-cookies']?.[exampleName] ?? {};
     const cookiesList = [
         ...globalCookies.map((c) => ({

package/dist/request-example/builder/resolve-request-factory-url.d.ts

@@ -1,4 +1,16 @@
+import { type Result } from '@scalar/helpers/types/result';
 import type { RequestFactory } from '../../request-example/builder/request-factory.js';
+/**
+ * Discriminated error code when the merged request URL is not a complete absolute target
+ * (for example no OpenAPI server, or unresolved `{{environment}}` segments left in the merged URL).
+ */
+export declare const MISSING_REQUEST_SERVER_BASE: "MISSING_REQUEST_SERVER_BASE";
+/**
+ * Discriminated error code when the merged URL cannot be encoded or parsed (invalid path params, malformed URL).
+ */
+export declare const INVALID_REQUEST_FACTORY_URL: "INVALID_REQUEST_FACTORY_URL";
+export type ResolveRequestFactoryUrlError = typeof MISSING_REQUEST_SERVER_BASE | typeof INVALID_REQUEST_FACTORY_URL;
+export type ResolveRequestFactoryUrlResult = Result<string, ResolveRequestFactoryUrlError>;
 /**
  * Resolves the request URL string from a {@link RequestFactory} using the same
  * rules as {@link buildRequest} (path variables, query, security query params),
@@ -7,5 +19,10 @@ import type { RequestFactory } from '../../request-example/builder/request-facto
 export declare const resolveRequestFactoryUrl: (request: RequestFactory, options: {
     envVariables: Record<string, string> | ((value: string) => string | null);
     securityQueryParams: URLSearchParams;
-}) => string;
+    /**
+     * When true, skips incomplete-URL validation (embedded modal, copy URL, tests).
+     * @default false
+     */
+    allowMissingRequestServerBase?: boolean;
+}) => ResolveRequestFactoryUrlResult;
 //# sourceMappingURL=resolve-request-factory-url.d.ts.map

package/dist/request-example/builder/resolve-request-factory-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-request-factory-url.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/resolve-request-factory-url.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,CAAA;IACzE,mBAAmB,EAAE,eAAe,CAAA;CACrC,KACA,MAkCF,CAAA"}
+{"version":3,"file":"resolve-request-factory-url.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/resolve-request-factory-url.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,8BAA8B,CAAA;AAKnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAA;AAEjF;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAA;AAEjF,MAAM,MAAM,6BAA6B,GAAG,OAAO,2BAA2B,GAAG,OAAO,2BAA2B,CAAA;AAEnH,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAA;AAK1F;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,CAAA;IACzE,mBAAmB,EAAE,eAAe,CAAA;IACpC;;;OAGG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAA;CACxC,KACA,8BAqDF,CAAA"}

package/dist/request-example/builder/resolve-request-factory-url.js

@@ -1,5 +1,18 @@
 import { replaceEnvVariables, replacePathVariables } from '@scalar/helpers/regex/replace-variables';
+import { err, ok } from '@scalar/helpers/types/result';
+import { safeRun } from '@scalar/helpers/types/safe-run';
+import { isRelativePath } from '@scalar/helpers/url/is-relative-path';
 import { mergeSearchParams, mergeUrls } from '@scalar/helpers/url/merge-urls';
+/**
+ * Discriminated error code when the merged request URL is not a complete absolute target
+ * (for example no OpenAPI server, or unresolved `{{environment}}` segments left in the merged URL).
+ */
+export const MISSING_REQUEST_SERVER_BASE = 'MISSING_REQUEST_SERVER_BASE';
+/**
+ * Discriminated error code when the merged URL cannot be encoded or parsed (invalid path params, malformed URL).
+ */
+export const INVALID_REQUEST_FACTORY_URL = 'INVALID_REQUEST_FACTORY_URL';
+const INCOMPLETE_MERGED_URL_MESSAGE = 'No server URL is configured for this request. Add a servers entry to your OpenAPI document (or set a server in the client) before sending.';
 /**
  * Resolves the request URL string from a {@link RequestFactory} using the same
  * rules as {@link buildRequest} (path variables, query, security query params),
@@ -7,20 +20,32 @@ import { mergeSearchParams, mergeUrls } from '@scalar/helpers/url/merge-urls';
  */
 export const resolveRequestFactoryUrl = (request, options) => {
     const variables = options.envVariables;
-    const pathVariables = Object.fromEntries(Object.entries(request.path.variables).map(([key, value]) => [
+    const pathVariablesEncoded = safeRun(() => Object.fromEntries(Object.entries(request.path.variables).map(([key, value]) => [
         key,
         encodeURIComponent(replaceEnvVariables(value, variables)),
-    ]));
+    ])));
+    if (!pathVariablesEncoded.ok) {
+        return err(INVALID_REQUEST_FACTORY_URL, 'The request URL contains invalid characters in path parameters.');
+    }
+    const pathVariables = pathVariablesEncoded.data;
     const baseUrl = replaceEnvVariables(request.baseUrl, variables);
     const rawPath = replaceEnvVariables(request.path.raw, variables);
     const path = replacePathVariables(rawPath, pathVariables);
     const mergedUrl = mergeUrls(baseUrl, path);
+    if (!options.allowMissingRequestServerBase && isRelativePath(mergedUrl)) {
+        return err(MISSING_REQUEST_SERVER_BASE, INCOMPLETE_MERGED_URL_MESSAGE);
+    }
     // When rendered inside an iframe with srcdoc, the browser reports
     // window.location.origin as the string "null" instead of a real origin.
     // Fall back to localhost so relative URLs can still be resolved.
     const origin = globalThis.window?.location?.origin;
     const urlBase = origin && origin !== 'null' ? origin : 'http://localhost:3000';
-    const url = new URL(mergedUrl, urlBase);
+    // Fallback for modal layout without a base server url (it should use the current origin)
+    const urlParsed = safeRun(() => new URL(mergedUrl, urlBase));
+    if (!urlParsed.ok) {
+        return err(INVALID_REQUEST_FACTORY_URL, 'The request URL could not be parsed. Check the server URL and path for invalid characters.');
+    }
+    const url = urlParsed.data;
     const operationQueryParams = new URLSearchParams();
     for (const [key, value] of request.query.entries()) {
         operationQueryParams.append(replaceEnvVariables(key, variables), replaceEnvVariables(value, variables));
@@ -30,5 +55,5 @@ export const resolveRequestFactoryUrl = (request, options) => {
         securityQueryParams.append(key, value);
     }
     url.search = mergeSearchParams(url.searchParams, operationQueryParams, securityQueryParams).toString();
-    return url.toString();
+    return ok(url.toString());
 };

package/dist/request-example/context/environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,KAAK,kBAAkB,EAA4B,MAAM,qDAAqD,CAAA;AAEvH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WAAW,cAAc,GAAG,IAAI,EAChC,UAAU,iBAAiB,GAAG,IAAI,KACjC;IACD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;CAqChC,CAAA"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,KAAK,kBAAkB,EAA4B,MAAM,qDAAqD,CAAA;AAGvH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WAAW,cAAc,GAAG,IAAI,EAChC,UAAU,iBAAiB,GAAG,IAAI,KACjC;IACD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;CAqChC,CAAA"}

package/dist/request-example/context/environment.js

@@ -1,4 +1,5 @@
 import { xScalarEnvironmentSchema } from '../../schemas/extensions/document/x-scalar-environments.js';
+import { isOpenApiDocument } from '../../schemas/type-guards.js';
 import { coerceValue } from '../../schemas/typebox-coerce.js';
 /**
  * Returns the active environment context for a given workspace and document.
@@ -34,7 +35,7 @@ export const getActiveEnvironment = (workspace, document) => {
     const workspaceEnv = workspace.workspace['x-scalar-environments']?.[activeEnv] ?? {
         variables: [],
     };
-    const documentEnv = document?.['x-scalar-environments']?.[activeEnv] ?? {
+    const documentEnv = (isOpenApiDocument(document) ? document['x-scalar-environments']?.[activeEnv] : undefined) ?? {
         variables: [],
     };
     // Merge workspace and document variables, with document variables appended

package/dist/request-example/context/get-request-example-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-request-example-context.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/get-request-example-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAE9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAA;AAIjG,OAAO,EAAE,KAAK,MAAM,EAAqB,MAAM,iCAAiC,CAAA;AAIhF,OAAO,EAAE,KAAK,qBAAqB,EAAiB,MAAM,mDAAmD,CAAA;AAE7G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAA;AAC7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAA;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;QACnB,WAAW,EAAE,kBAAkB,CAAA;KAChC,CAAA;IACD,OAAO,EAAE;QACP,SAAS,EAAE,aAAa,EAAE,CAAA;QAC1B,QAAQ,EAAE,aAAa,EAAE,CAAA;KAC1B,CAAA;IACD,OAAO,EAAE;QACP,IAAI,EAAE,YAAY,EAAE,CAAA;QACpB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;QAC7B,IAAI,EAAE,UAAU,CAAA;KACjB,CAAA;IACD,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KACnB,CAAA;IACD,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,qBAAqB,CAAA;QAC9B,YAAY,EAAE,yBAAyB,EAAE,CAAA;QACzC,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,eAAe,EAAE,0BAA0B,EAAE,CAAA;QAC7C,IAAI,EAAE,QAAQ,CAAA;KACf,CAAA;CACF,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,gBAAgB,cAAc,EAC9B,cAAc,MAAM,EACpB,oBAAoB,kBAAkB,EACtC,UAAS,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,cAAc,EAAE,2BAA2B,CAAA;IAC3C;;;;OAIG;IACH,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC3C,CAAM,KACN,MAAM,CAAC,0BAA0B,CAuInC,CAAA"}
+{"version":3,"file":"get-request-example-context.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/get-request-example-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAE9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAA;AAIjG,OAAO,EAAE,KAAK,MAAM,EAAqB,MAAM,iCAAiC,CAAA;AAIhF,OAAO,EAAE,KAAK,qBAAqB,EAAiB,MAAM,mDAAmD,CAAA;AAE7G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAA;AAC7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAA;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;QACnB,WAAW,EAAE,kBAAkB,CAAA;KAChC,CAAA;IACD,OAAO,EAAE;QACP,SAAS,EAAE,aAAa,EAAE,CAAA;QAC1B,QAAQ,EAAE,aAAa,EAAE,CAAA;KAC1B,CAAA;IACD,OAAO,EAAE;QACP,IAAI,EAAE,YAAY,EAAE,CAAA;QACpB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;QAC7B,IAAI,EAAE,UAAU,CAAA;KACjB,CAAA;IACD,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KACnB,CAAA;IACD,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,qBAAqB,CAAA;QAC9B,YAAY,EAAE,yBAAyB,EAAE,CAAA;QACzC,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,eAAe,EAAE,0BAA0B,EAAE,CAAA;QAC7C,IAAI,EAAE,QAAQ,CAAA;KACf,CAAA;CACF,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,gBAAgB,cAAc,EAC9B,cAAc,MAAM,EACpB,oBAAoB,kBAAkB,EACtC,UAAS,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,cAAc,EAAE,2BAA2B,CAAA;IAC3C;;;;OAIG;IACH,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC3C,CAAM,KACN,MAAM,CAAC,0BAA0B,CA6InC,CAAA"}

package/dist/request-example/context/get-request-example-context.js

@@ -8,6 +8,7 @@ import { getSecuritySchemes } from '../../request-example/context/security/get-s
 import { getSelectedSecurity } from '../../request-example/context/security/get-selected-security.js';
 import { mergeSecurity } from '../../request-example/context/security/merge-security.js';
 import { getSelectedServer, getServers } from '../../request-example/context/servers.js';
+import { isOpenApiDocument } from '../../schemas/type-guards.js';
 export const getRequestExampleContext = (workspaceStore, documentName, requestExampleMeta, options = {}) => {
     const { path, method, exampleName } = requestExampleMeta;
     const document = workspaceStore.workspace.documents[documentName] ?? options.fallbackDocument ?? undefined;
@@ -17,6 +18,12 @@ export const getRequestExampleContext = (workspaceStore, documentName, requestEx
             error: `Document ${documentName} not found`,
         };
     }
+    if (!isOpenApiDocument(document)) {
+        return {
+            ok: false,
+            error: `Document ${documentName} is not an OpenAPI document`,
+        };
+    }
     const pathItem = getResolvedRef(document.paths?.[path]);
     if (!pathItem) {
         return {

package/dist/request-example/context/headers.d.ts

@@ -1,30 +1,45 @@
 import type { HttpMethod } from '@scalar/helpers/http/http-methods';
 import type { OperationObject } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
 /**
- * Generates a list of default headers for an OpenAPI operation and HTTP method.
+ * Restores conventional casing for well-known default headers.
  *
- * This function intelligently adds standard HTTP headers based on the request context:
+ * We keep this intentionally scoped to the defaults we auto-generate so we do not
+ * unexpectedly rewrite user-defined header parameter names.
+ */
+export declare const restoreConventionalHeaderName: (headerName: string) => string;
+/**
+ * Restores conventional casing for default header keys.
+ */
+export declare const restoreConventionalDefaultHeaderNames: (headers: Record<string, string>) => Record<string, string>;
+/**
+ * Drops default header entries that are disabled for this example via
+ * `operation['x-scalar-disable-parameters']['default-headers'][exampleName]`.
+ *
+ * Context builders keep the full default header map for the UI; call this when merging into the
+ * outbound request (for example in `requestFactory`).
+ */
+export declare const filterDisabledDefaultHeaders: (operation: OperationObject, exampleName: string, headers: Record<string, string>) => Record<string, string>;
+/**
+ * Generates default headers for an OpenAPI operation and HTTP method.
+ *
+ * This function adds standard HTTP headers based on the request context:
  * - Content-Type: Added only if the HTTP method supports a request body and the OpenAPI operation
  *   defines a request body content type. Uses the selected content type from the operation or the
- *   first defined request body content type.
+ *   first defined request body content type. Omitted when the selection is `none` or `other`.
  * - Accept: Derived from the 2xx response content types in the spec (joined as a comma-separated list), falling back to a wildcard.
  * - User-Agent: Added in Electron environments (desktop app or proxy) to identify the client.
  *
- * The function respects OpenAPI operation parameters and marks headers as overridden
- * if they are explicitly defined in the operation. It also supports hiding disabled
- * headers for specific request examples using x-scalar-disable-parameters.
- *
- * @param method The HTTP method of the operation (GET, POST, etc.)
- * @param operation The OpenAPI OperationObject describing the endpoint
- * @param exampleKey The current request example key
- * @param hideDisabledHeaders If true, filters out headers marked as disabled for this example
- * @returns Array of default header objects with their values and override status
+ * @param hideDisabledHeaders If true, filters out headers marked as disabled for this example via
+ *   `x-scalar-disable-parameters.default-headers`.
+ * @param hideOverriddenHeaders If true, omits any default header whose name matches an **enabled**
+ *   operation parameter with `in: header` (disabled optional header parameters do not shadow defaults).
  */
-export declare const getDefaultHeaders: ({ method, operation, exampleName, hideDisabledHeaders, options, }: {
+export declare const getDefaultHeaders: ({ method, operation, exampleName, hideDisabledHeaders, hideOverriddenHeaders, options, }: {
     method: HttpMethod;
     operation: OperationObject;
     exampleName: string;
     hideDisabledHeaders?: boolean;
+    hideOverriddenHeaders?: boolean;
     options?: {
         appVersion: string;
         isElectron: boolean;

package/dist/request-example/context/headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/headers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAKnG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,mEAS/B;IACD,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,OAAO,CAAA;KACpB,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAoCxB,CAAA"}
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/headers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAanG;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,YAAY,MAAM,KAAG,MACQ,CAAA;AAE3E;;GAEG;AACH,eAAO,MAAM,qCAAqC,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CACK,CAAA;AAkDlH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACvC,WAAW,eAAe,EAC1B,aAAa,MAAM,EACnB,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAIpB,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,0FAU/B;IACD,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,OAAO,CAAA;KACpB,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAuCxB,CAAA"}

package/dist/request-example/context/headers.js

@@ -1,39 +1,100 @@
 import { canMethodHaveBody } from '@scalar/helpers/http/can-method-have-body';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { isParamDisabled } from '../../request-example/builder/header/is-param-disabled.js';
 /** Default Accept header value to accept all response types. */
 const DEFAULT_ACCEPT = '*/*';
+const CONVENTIONAL_DEFAULT_HEADER_NAMES = {
+    accept: 'Accept',
+    'content-type': 'Content-Type',
+    'user-agent': 'User-Agent',
+};
 /**
- * Generates a list of default headers for an OpenAPI operation and HTTP method.
+ * Restores conventional casing for well-known default headers.
  *
- * This function intelligently adds standard HTTP headers based on the request context:
+ * We keep this intentionally scoped to the defaults we auto-generate so we do not
+ * unexpectedly rewrite user-defined header parameter names.
+ */
+export const restoreConventionalHeaderName = (headerName) => CONVENTIONAL_DEFAULT_HEADER_NAMES[headerName.toLowerCase()] ?? headerName;
+/**
+ * Restores conventional casing for default header keys.
+ */
+export const restoreConventionalDefaultHeaderNames = (headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [restoreConventionalHeaderName(name), value]));
+/**
+ * Lowercase names of **enabled** operation parameters with `in: header` for the given example.
+ * Uses the same rules as the request builder (`isParamDisabled`): optional parameters are treated
+ * as disabled unless `examples[exampleName]['x-disabled']` is explicitly `false`.
+ */
+const getEnabledOperationHeaderParameterNames = (operation, exampleName) => {
+    const names = new Set();
+    for (const ref of operation.parameters ?? []) {
+        const param = getResolvedRef(ref);
+        if (param.in !== 'header') {
+            continue;
+        }
+        const rawExample = 'examples' in param && param.examples?.[exampleName] ? param.examples[exampleName] : undefined;
+        const example = rawExample ? getResolvedRef(rawExample) : undefined;
+        if (!isParamDisabled(param, example)) {
+            names.add(param.name.toLowerCase());
+        }
+    }
+    return names;
+};
+const filterDefaultHeadersByVisibility = (operation, exampleName, headers, flags) => {
+    const headerParamNames = flags.hideOverriddenHeaders
+        ? getEnabledOperationHeaderParameterNames(operation, exampleName)
+        : null;
+    const disabledHeaders = flags.hideDisabledHeaders
+        ? (operation['x-scalar-disable-parameters']?.['default-headers']?.[exampleName] ?? {})
+        : null;
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => {
+        const key = name.toLowerCase();
+        if (headerParamNames?.has(key)) {
+            return false;
+        }
+        if (disabledHeaders && disabledHeaders[key] === true) {
+            return false;
+        }
+        return true;
+    }));
+};
+/**
+ * Drops default header entries that are disabled for this example via
+ * `operation['x-scalar-disable-parameters']['default-headers'][exampleName]`.
+ *
+ * Context builders keep the full default header map for the UI; call this when merging into the
+ * outbound request (for example in `requestFactory`).
+ */
+export const filterDisabledDefaultHeaders = (operation, exampleName, headers) => filterDefaultHeadersByVisibility(operation, exampleName, headers, {
+    hideOverriddenHeaders: false,
+    hideDisabledHeaders: true,
+});
+/**
+ * Generates default headers for an OpenAPI operation and HTTP method.
+ *
+ * This function adds standard HTTP headers based on the request context:
  * - Content-Type: Added only if the HTTP method supports a request body and the OpenAPI operation
  *   defines a request body content type. Uses the selected content type from the operation or the
- *   first defined request body content type.
+ *   first defined request body content type. Omitted when the selection is `none` or `other`.
  * - Accept: Derived from the 2xx response content types in the spec (joined as a comma-separated list), falling back to a wildcard.
  * - User-Agent: Added in Electron environments (desktop app or proxy) to identify the client.
  *
- * The function respects OpenAPI operation parameters and marks headers as overridden
- * if they are explicitly defined in the operation. It also supports hiding disabled
- * headers for specific request examples using x-scalar-disable-parameters.
- *
- * @param method The HTTP method of the operation (GET, POST, etc.)
- * @param operation The OpenAPI OperationObject describing the endpoint
- * @param exampleKey The current request example key
- * @param hideDisabledHeaders If true, filters out headers marked as disabled for this example
- * @returns Array of default header objects with their values and override status
+ * @param hideDisabledHeaders If true, filters out headers marked as disabled for this example via
+ *   `x-scalar-disable-parameters.default-headers`.
+ * @param hideOverriddenHeaders If true, omits any default header whose name matches an **enabled**
+ *   operation parameter with `in: header` (disabled optional header parameters do not shadow defaults).
  */
-export const getDefaultHeaders = ({ method, operation, exampleName, hideDisabledHeaders = false, options = {
+export const getDefaultHeaders = ({ method, operation, exampleName, hideDisabledHeaders = false, hideOverriddenHeaders = false, options = {
     isElectron: false,
     appVersion: '0.0.0',
 }, }) => {
-    const disabledHeaders = operation['x-scalar-disable-parameters']?.['default-headers']?.[exampleName] ?? {};
     const headers = new Headers();
     const requestBody = getResolvedRef(operation.requestBody);
     // Add Content-Type header only for methods that support a request body
     if (canMethodHaveBody(method) && requestBody) {
         const contentType = requestBody['x-scalar-selected-content-type']?.[exampleName] ?? Object.keys(requestBody.content ?? {})[0];
         // We never want to add a content type of 'none' or invent one when the schema defines no body.
-        if (contentType && contentType !== 'none') {
+        // 'other' is a UI-only choice for a raw body without an auto-added Content-Type header.
+        if (contentType && contentType !== 'none' && contentType !== 'other') {
             headers.set('Content-Type', contentType);
         }
     }
@@ -46,9 +107,13 @@ export const getDefaultHeaders = ({ method, operation, exampleName, hideDisabled
     if (options.isElectron && options.appVersion) {
         headers.set('User-Agent', `Scalar/${options.appVersion}`);
     }
-    // Filter out disabled headers if requested
-    if (hideDisabledHeaders) {
-        return Object.fromEntries(Array.from(headers.entries()).filter(([headerName]) => disabledHeaders[headerName.toLowerCase()] !== true));
+    const result = Object.fromEntries(headers.entries());
+    if (hideOverriddenHeaders || hideDisabledHeaders) {
+        // return a new object with the filtered headers
+        return filterDefaultHeadersByVisibility(operation, exampleName, result, {
+            hideOverriddenHeaders,
+            hideDisabledHeaders,
+        });
     }
-    return Object.fromEntries(headers.entries());
+    return result;
 };

package/dist/request-example/context/index.d.ts

@@ -1,5 +1,6 @@
 export { getActiveEnvironment } from './environment.js';
 export { type BuildRequestExampleContext, getRequestExampleContext } from './get-request-example-context.js';
+export { filterDisabledDefaultHeaders, getDefaultHeaders, restoreConventionalDefaultHeaderNames, restoreConventionalHeaderName, } from './headers.js';
 export { combineParams } from './helpers/combine-params.js';
 export { getActiveProxyUrl } from './proxy.js';
 export { getSecurityRequirements } from './security/get-security-requirements.js';

package/dist/request-example/context/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,KAAK,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,KAAK,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACzG,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,qCAAqC,EACrC,6BAA6B,GAC9B,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}

package/dist/request-example/context/index.js

@@ -1,5 +1,6 @@
 export { getActiveEnvironment } from './environment.js';
 export { getRequestExampleContext } from './get-request-example-context.js';
+export { filterDisabledDefaultHeaders, getDefaultHeaders, restoreConventionalDefaultHeaderNames, restoreConventionalHeaderName, } from './headers.js';
 export { combineParams } from './helpers/combine-params.js';
 export { getActiveProxyUrl } from './proxy.js';
 export { getSecurityRequirements } from './security/get-security-requirements.js';