@scalar/workspace-store 0.42.0 → 0.43.0

package/dist/request-example/builder/body/get-selected-body-content-type.js

@@ -0,0 +1,10 @@
+/**
+ * Returns the selected body content type for the given request body and exampleKey.
+ * Priority:
+ *   1. requestBody?.['x-scalar-selected-content-type']?.[exampleKey] (if set)
+ *   2. First key in requestBody?.content (if available)
+ *   3. null (if none available)
+ */
+export const getSelectedBodyContentType = (requestBody, exampleKey = 'default') => {
+    return (requestBody?.['x-scalar-selected-content-type']?.[exampleKey] ?? Object.keys(requestBody?.content ?? {})[0] ?? null);
+};

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

@@ -0,0 +1,9 @@
+import type { RequestFactory } from '../../request-example/builder/request-factory.js';
+export declare const buildRequest: (request: RequestFactory, options: {
+    envVariables: Record<string, string>;
+}) => {
+    request: Request;
+    controller: AbortController;
+    isUsingProxy: boolean;
+};
+//# sourceMappingURL=build-request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/build-request.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAG/E,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC;;;;CAwKF,CAAA"}

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

@@ -0,0 +1,135 @@
+import { replaceEnvVariables, replacePathVariables } from '@scalar/helpers/regex/replace-variables';
+import { mergeUrls } from '@scalar/helpers/url/merge-urls';
+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';
+export const buildRequest = (request, options) => {
+    const controller = new AbortController();
+    const headers = (() => {
+        const variables = options.envVariables;
+        const headers = new Headers();
+        request.headers.forEach((value, key) => {
+            headers.set(replaceEnvVariables(key, variables), replaceEnvVariables(value, variables));
+        });
+        return headers;
+    })();
+    const body = (() => {
+        const variables = options.envVariables;
+        if (request.body?.mode === 'raw') {
+            if (typeof request.body.value === 'string') {
+                return replaceEnvVariables(request.body.value, variables);
+            }
+            return request.body.value;
+        }
+        if (request.body?.mode === 'formdata') {
+            const form = new FormData();
+            request.body.value.forEach((item) => {
+                if (item.type === 'text') {
+                    form.append(replaceEnvVariables(item.key, variables), replaceEnvVariables(item.value, variables));
+                    return;
+                }
+                form.append(replaceEnvVariables(item.key, variables), item.value);
+            });
+            return form;
+        }
+        if (request.body?.mode === 'urlencoded') {
+            return new URLSearchParams(request.body.value.map((item) => [
+                replaceEnvVariables(item.key, variables),
+                replaceEnvVariables(item.value, variables),
+            ]));
+        }
+        return null;
+    })();
+    const securityQueryParams = new URLSearchParams();
+    const securityCookies = [];
+    // Build the request security
+    request.security.forEach((security) => {
+        const name = replaceEnvVariables(security.name, options.envVariables);
+        const securityValue = replaceEnvVariables(security.value, options.envVariables);
+        if (security.in === 'header') {
+            // Build the value for the header
+            const buildValue = (() => {
+                if (security.type === 'basic') {
+                    return `Basic ${encodeBase64(securityValue)}`;
+                }
+                if (security.type === 'bearer') {
+                    return `Bearer ${securityValue}`;
+                }
+                return securityValue;
+            })();
+            // Set the header (use replaced header name so {{ env }} placeholders work)
+            headers.set(name, buildValue);
+            return;
+        }
+        if (security.in === 'query') {
+            securityQueryParams.set(name, securityValue);
+            return;
+        }
+        if (security.in === 'cookie') {
+            securityCookies.push({
+                name: name,
+                value: securityValue,
+                isDisabled: false,
+            });
+            return;
+        }
+    });
+    const requestUrl = (() => {
+        // construct replaced path variables
+        const pathVariables = Object.fromEntries(Object.entries(request.path.variables).map(([key, value]) => [
+            key,
+            encodeURIComponent(replaceEnvVariables(value, options.envVariables)),
+        ]));
+        const baseUrl = replaceEnvVariables(request.baseUrl, options.envVariables);
+        const path = replacePathVariables(request.path.raw, pathVariables);
+        const mergedUrl = mergeUrls(baseUrl, path);
+        const urlBase = globalThis.window?.location?.origin ?? 'http://localhost:3000';
+        // Replace the path variables with the environment variables and server variables
+        const url = new URL(mergedUrl, urlBase);
+        // Merge security query params
+        for (const [key, value] of securityQueryParams.entries()) {
+            url.searchParams.set(replaceEnvVariables(key, options.envVariables), replaceEnvVariables(value, options.envVariables));
+        }
+        // Replace the query params with the environment variables
+        for (const [key, value] of request.query.params.entries()) {
+            url.searchParams.set(replaceEnvVariables(key, options.envVariables), replaceEnvVariables(value, options.envVariables));
+        }
+        return url.toString();
+    })();
+    const isUsingProxy = shouldUseProxy(request.proxy.proxyUrl, requestUrl);
+    const cookies = [...request.cookies.list, ...securityCookies].map((c) => ({
+        ...c,
+        name: replaceEnvVariables(c.name, options.envVariables),
+        value: replaceEnvVariables(c.value, options.envVariables),
+    }));
+    const cookieHeader = buildRequestCookieHeader({
+        cookies,
+        originalCookieHeader: headers.get('cookie'),
+        url: requestUrl,
+        useCustomCookieHeader: (isUsingProxy || request.options?.isElectron) ?? false,
+    });
+    // Add the cookie header to the headers
+    if (cookieHeader) {
+        headers.set(cookieHeader.name, cookieHeader.value);
+    }
+    // final url
+    const encodedUrl = applyAllowReservedToUrl(requestUrl, request.allowedReservedQueryParameters ?? new Set());
+    const finalUrl = isUsingProxy ? redirectToProxy(request.proxy.proxyUrl, encodedUrl) : encodedUrl;
+    return {
+        request: new Request(finalUrl, {
+            /**
+             * Ensure that all methods are uppercased (though only needed for patch)
+             *
+             * @see https://github.com/whatwg/fetch/issues/50
+             */
+            method: request.method.toUpperCase(),
+            headers,
+            body,
+            cache: request.cache,
+            signal: controller.signal,
+        }),
+        controller,
+        isUsingProxy,
+    };
+};

package/dist/request-example/builder/header/build-request-cookie-header.d.ts

@@ -0,0 +1,25 @@
+import type { XScalarCookie } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
+/**
+ * Generate a cookie header from the cookie params
+ */
+export declare const getCookieHeader: (cookieParams: XScalarCookie[], originalCookieHeader: string | undefined) => string;
+/**
+ * Build out the cookies header taking in global, param and security scheme cookies
+ */
+export declare const buildRequestCookieHeader: ({ cookies, originalCookieHeader, url, useCustomCookieHeader, }: {
+    /** Parsed/replaced cookies from the parameters and security schemes */
+    cookies: XScalarCookie[];
+    /** Cookie header that previously exists from the spec OR from the user */
+    originalCookieHeader: string | undefined | null;
+    /** The url of the request used to filter global cookies by domain */
+    url: string;
+    /**
+     * If we are running in Electron or using the proxy, we need to add a custom header
+     * that's then forwarded as a `Cookie` header.
+     */
+    useCustomCookieHeader: boolean;
+}) => null | {
+    name: string;
+    value: string;
+};
+//# sourceMappingURL=build-request-cookie-header.d.ts.map

package/dist/request-example/builder/header/build-request-cookie-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-request-cookie-header.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/build-request-cookie-header.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qEAAqE,CAAA;AAYxG;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,cAAc,aAAa,EAAE,EAAE,sBAAsB,MAAM,GAAG,SAAS,KAAG,MAWzG,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,gEAKtC;IACD,uEAAuE;IACvE,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,0EAA0E;IAC1E,oBAAoB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IAC/C,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,qBAAqB,EAAE,OAAO,CAAA;CAC/B,KAAG,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAsBvC,CAAA"}

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

@@ -0,0 +1,39 @@
+import { filterGlobalCookie } from './filter-global-cookies.js';
+const CUSTOM_COOKIE_HEADER_WARNING = "We're using a `X-Scalar-Cookie` custom header to the request. The proxy will forward this as a `Cookie` header. We do this to avoid the browser omitting the `Cookie` header for cross-origin requests for security reasons.";
+const COOKIE_HEADER_WARNING = `We're trying to add a Cookie header, but browsers often omit them for cross-origin requests for various security reasons. If it's not working, that's probably why. Here are the requirements for it to work:
+
+        - The browser URL must be on the same domain as the server URL.
+        - The connection must be made over HTTPS.
+        `;
+/**
+ * Generate a cookie header from the cookie params
+ */
+export const getCookieHeader = (cookieParams, originalCookieHeader) => {
+    // Generate the cookie header from the cookie params
+    const cookieHeader = cookieParams.map((c) => `${c.name}=${c.value}`).join('; ');
+    // Merge with the original cookie header
+    if (originalCookieHeader && cookieHeader) {
+        return `${originalCookieHeader}; ${cookieHeader}`;
+    }
+    // Return whichever one exists, or empty string if both are empty
+    return originalCookieHeader || cookieHeader || '';
+};
+/**
+ * Build out the cookies header taking in global, param and security scheme cookies
+ */
+export const buildRequestCookieHeader = ({ cookies, originalCookieHeader, url, useCustomCookieHeader, }) => {
+    /** Filter the global cookies by domain + parse */
+    /** Generate the cookie header */
+    const cookieHeader = getCookieHeader(cookies.filter((cookie) => filterGlobalCookie({ url, cookie, disabledGlobalCookies: {} })), originalCookieHeader ?? undefined);
+    if (cookieHeader) {
+        // Add a custom header for the proxy (that's then forwarded as `Cookie`)
+        if (useCustomCookieHeader) {
+            console.warn(CUSTOM_COOKIE_HEADER_WARNING);
+            return { name: 'X-Scalar-Cookie', value: cookieHeader };
+        }
+        // or stick to the original header (which might be removed by the browser)
+        console.warn(COOKIE_HEADER_WARNING);
+        return { name: 'Cookie', value: cookieHeader };
+    }
+    return null;
+};

package/dist/request-example/builder/header/build-request-parameters.d.ts

@@ -0,0 +1,24 @@
+import { type XScalarCookie } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
+import type { ParameterObject, ReferenceType } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+/**
+ * Converts the parameters into a set of headers, cookies and url params while
+ * replacing environment variables and extracting example values. Also builds up a record of the path
+ * parameters which can then be used to replace variables in the path.
+ * Also handles both content based and schema based parameters.
+ *
+ * @param parameters - Unfiltered parameters
+ * @param exampleName - The key of the current example
+ * @returns A set of headers, cookies and url params
+ */
+export declare const buildRequestParameters: (
+/** All parameters */
+parameters?: ReferenceType<ParameterObject>[], 
+/** The key of the current example */
+exampleName?: string) => {
+    cookies: XScalarCookie[];
+    headers: Record<string, string>;
+    pathVariables: Record<string, string>;
+    allowReservedQueryParameters: Set<string>;
+    urlParams: URLSearchParams;
+};
+//# sourceMappingURL=build-request-parameters.d.ts.map

package/dist/request-example/builder/header/build-request-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-request-parameters.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/build-request-parameters.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,qEAAqE,CAAA;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAA;AAoBlH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;AACjC,qBAAqB;AACrB,aAAY,aAAa,CAAC,eAAe,CAAC,EAAO;AACjD,qCAAqC;AACrC,cAAa,MAAkB,KAC9B;IACD,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzC,SAAS,EAAE,eAAe,CAAA;CAwF3B,CAAA"}

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

@@ -0,0 +1,215 @@
+import { isDefined } from '@scalar/helpers/array/is-defined';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { xScalarCookieSchema, } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { deSerializeParameter } from '../../../request-example/builder/header/de-serialize-parameter.js';
+import { getExample } from '../helpers/get-example.js';
+import { isParamDisabled } from './is-param-disabled.js';
+import { serializeContentValue, serializeDeepObjectStyle, serializeFormStyle, serializeFormStyleForCookies, serializePipeDelimitedStyle, serializeSimpleStyle, serializeSpaceDelimitedStyle, } from './serialize-parameter.js';
+/** Helper to get explode value with default */
+const getExplode = (param, defaultValue) => 'explode' in param && param.explode !== undefined ? param.explode : defaultValue;
+/**
+ * Converts the parameters into a set of headers, cookies and url params while
+ * replacing environment variables and extracting example values. Also builds up a record of the path
+ * parameters which can then be used to replace variables in the path.
+ * Also handles both content based and schema based parameters.
+ *
+ * @param parameters - Unfiltered parameters
+ * @param exampleName - The key of the current example
+ * @returns A set of headers, cookies and url params
+ */
+export const buildRequestParameters = (
+/** All parameters */
+parameters = [], 
+/** The key of the current example */
+exampleName = 'default') => {
+    const result = {
+        cookies: [],
+        headers: {},
+        pathVariables: {},
+        allowReservedQueryParameters: new Set(),
+        urlParams: new URLSearchParams(),
+    };
+    // Early return for empty parameters
+    if (parameters.length === 0) {
+        return result;
+    }
+    // Second pass: process all parameters
+    for (const referencedParam of parameters) {
+        const param = getResolvedRef(referencedParam);
+        const example = getExample(param, exampleName, undefined);
+        // Skip disabled examples
+        if (!example || isParamDisabled(param, example)) {
+            continue;
+        }
+        /** Replace environment variables in the key and value */
+        const value = example.value;
+        /** De-serialize the example value if it is a string and matches the schema type */
+        const deSerializedValue = deSerializeParameter(value, param);
+        const paramName = param.name;
+        // Handle by parameter location
+        switch (param.in) {
+            case 'header': {
+                // Filter out Content-Type header when it is multipart/form-data
+                // The browser will automatically set this header with the proper boundary
+                const lowerParamName = paramName.toLowerCase();
+                if (lowerParamName === 'content-type' && deSerializedValue === 'multipart/form-data') {
+                    break;
+                }
+                /** Headers only support simple style according to OpenAPI 3.1.1 */
+                const serialized = serializeSimpleStyle(deSerializedValue, getExplode(param, false));
+                // Remove undefined/null headers
+                if (!isDefined(serialized)) {
+                    break;
+                }
+                /** Headers can only be strings so we can cast numbers etc */
+                const serializedString = String(serialized);
+                // If the header already exists, append with comma
+                if (result.headers[paramName]) {
+                    result.headers[paramName] = `${result.headers[paramName]},${serializedString}`;
+                }
+                else {
+                    result.headers[paramName] = serializedString;
+                }
+                break;
+            }
+            case 'path': {
+                // Path parameters use simple style by default
+                const serialized = serializeSimpleStyle(deSerializedValue, getExplode(param, false));
+                result.pathVariables[paramName] = String(serialized);
+                break;
+            }
+            case 'query': {
+                processQueryParameter(param, paramName, deSerializedValue, result.urlParams, result.allowReservedQueryParameters);
+                break;
+            }
+            case 'cookie': {
+                processCookieParameter(paramName, deSerializedValue, getExplode(param, true), result.cookies);
+                break;
+            }
+        }
+    }
+    return result;
+};
+/** Ensure we only apply the correcet style to the correct types */
+const getStyle = (param, replacedValue) => {
+    if (!('style' in param) || !param.style) {
+        return 'form';
+    }
+    // DeepObject can only apply to objects
+    if (param.style === 'deepObject') {
+        if (isObject(replacedValue)) {
+            return 'deepObject';
+        }
+        return 'form';
+    }
+    return param.style;
+};
+/** Whether the parameter allows reserved characters (from param or schema). */
+const isAllowReserved = (param) => {
+    if ('allowReserved' in param && param.allowReserved !== undefined) {
+        return param.allowReserved;
+    }
+    if ('schema' in param && param.schema && typeof param.schema === 'object' && 'allowReserved' in param.schema) {
+        return param.schema.allowReserved === true;
+    }
+    return false;
+};
+/** When allowReserved is true, add keys to the set so reserved chars stay unescaped in the URL. */
+const trackReservedKeys = (allowReservedQueryParameters, allowReserved, ...keys) => {
+    if (allowReserved) {
+        for (const key of keys) {
+            allowReservedQueryParameters.add(key);
+        }
+    }
+};
+/**
+ * Helper function to process query parameters.
+ * Extracted to reduce complexity in main function.
+ */
+const processQueryParameter = (param, paramName, replacedValue, urlParams, allowReservedQueryParameters) => {
+    /** If the parameter should be exploded, defaults to true for form style */
+    const explodeParam = 'explode' in param && param.explode !== undefined ? param.explode : true;
+    /** Whether the parameter allows reserved characters (from param or schema). */
+    const allowReserved = isAllowReserved(param);
+    /** Style of the parameter, defaults to form */
+    const style = getStyle(param, replacedValue);
+    // Content type parameters should be serialized according to the parameter's own content type
+    if ('content' in param && param.content) {
+        // We grab the first for now but eventually we should support selecting the content type per parameter
+        const paramContentType = Object.keys(param.content)[0] ?? 'application/json';
+        const serializedValue = serializeContentValue(replacedValue, paramContentType);
+        urlParams.set(paramName, serializedValue);
+        trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+        return;
+    }
+    // Handle deepObject style
+    if (style === 'deepObject' && explodeParam) {
+        const entries = serializeDeepObjectStyle(paramName, replacedValue);
+        for (const entry of entries) {
+            urlParams.append(entry.key, entry.value);
+            trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+        }
+        return;
+    }
+    // Handle spaceDelimited style
+    if (style === 'spaceDelimited') {
+        const serialized = serializeSpaceDelimitedStyle(replacedValue);
+        const existingValue = urlParams.get(paramName);
+        urlParams.set(paramName, existingValue ? `${existingValue} ${serialized}` : serialized);
+        trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+        return;
+    }
+    // Handle pipeDelimited style
+    if (style === 'pipeDelimited') {
+        const serialized = serializePipeDelimitedStyle(replacedValue);
+        const existingValue = urlParams.get(paramName);
+        urlParams.set(paramName, existingValue ? `${existingValue}|${serialized}` : serialized);
+        trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+        return;
+    }
+    // Handle form style (default)
+    const serialized = serializeFormStyle(replacedValue, explodeParam);
+    // If serialized is an array of key-value pairs (exploded object or array)
+    if (Array.isArray(serialized)) {
+        for (const entry of serialized) {
+            // If key is empty, use paramName (for arrays)
+            const key = entry.key || paramName;
+            urlParams.append(key, String(entry.value));
+            trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+        }
+    }
+    else {
+        // Otherwise, convert to string for URLSearchParams
+        urlParams.append(paramName, String(serialized));
+        trackReservedKeys(allowReservedQueryParameters, allowReserved, paramName);
+    }
+};
+/**
+ * Helper function to process cookie parameters.
+ * Extracted to reduce complexity in main function.
+ */
+const processCookieParameter = (paramName, replacedValue, explode, cookies) => {
+    // Cookies only support form style according to OpenAPI 3.1.1
+    const serialized = serializeFormStyleForCookies(replacedValue, explode);
+    // If serialized is an array of key-value pairs (exploded object or array)
+    if (Array.isArray(serialized)) {
+        for (const entry of serialized) {
+            const key = entry.key || paramName;
+            cookies.push(coerceValue(xScalarCookieSchema, {
+                name: key,
+                value: String(entry.value),
+                path: '/',
+            }));
+        }
+    }
+    else {
+        // Otherwise, convert to string for cookie value
+        cookies.push(coerceValue(xScalarCookieSchema, {
+            name: paramName,
+            value: String(serialized),
+            path: '/',
+        }));
+    }
+};

package/dist/request-example/builder/header/de-serialize-parameter.d.ts

@@ -0,0 +1,4 @@
+import type { ParameterObject } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+/** Helper that de-serializes the example value based on the parameter type */
+export declare const deSerializeParameter: (example: unknown, param: ParameterObject) => any;
+//# sourceMappingURL=de-serialize-parameter.d.ts.map

package/dist/request-example/builder/header/de-serialize-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"de-serialize-parameter.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/de-serialize-parameter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,8DAA8D,CAAA;AAErE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,GAAI,SAAS,OAAO,EAAE,OAAO,eAAe,QAS5E,CAAA"}

package/dist/request-example/builder/header/de-serialize-parameter.js

@@ -0,0 +1,49 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+/** Helper that de-serializes the example value based on the parameter type */
+export const deSerializeParameter = (example, param) => {
+    if ('content' in param) {
+        return deSerializeContentExample(example, Object.keys(param.content ?? {})[0] ?? '');
+    }
+    if ('schema' in param) {
+        return deSerializeSchemaExample(example, param.schema);
+    }
+    return example;
+};
+/** De-serialize the example value based on the content type */
+const deSerializeContentExample = (example, contentType) => {
+    if (typeof example === 'string' && contentType.includes('json')) {
+        try {
+            return JSON.parse(example);
+        }
+        catch {
+            // Ignore the error and return the original example
+        }
+    }
+    return example;
+};
+/** Create a set of all the types we wish to parse as JSON */
+const parseableTypesSet = new Set(['array', 'object', 'boolean', 'number', 'integer', 'null']);
+/** De-serialize the example value based on the schema type */
+const deSerializeSchemaExample = (example, schema) => {
+    const resolvedSchema = getResolvedRef(schema);
+    if (typeof example === 'string' && resolvedSchema && 'type' in resolvedSchema) {
+        const type = Array.isArray(resolvedSchema.type) ? resolvedSchema.type[0] : resolvedSchema.type;
+        if (type && parseableTypesSet.has(type)) {
+            try {
+                return JSON.parse(example);
+            }
+            catch {
+                // For array types, fall back to splitting comma-separated values.
+                // Users commonly enter array values as "foo,bar" or "foo, bar" in the UI
+                // text field, which is not valid JSON. Per the OpenAPI spec, the default
+                // serialization for query array parameters is style=form + explode=true,
+                // meaning each value should be sent as a separate query parameter.
+                if (type === 'array') {
+                    return example.split(/,\s?/).filter((v) => v !== '');
+                }
+                // Ignore the error and return the original example for other types
+            }
+        }
+    }
+    return example;
+};

package/dist/request-example/builder/header/filter-global-cookies.d.ts

@@ -0,0 +1,14 @@
+import type { XScalarCookie } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
+/**
+ * Filter a global cookie to determine if it should be included with a request to the given URL.
+ * - Returns false if the cookie is disabled, in the disabledGlobalCookies map, or missing a name.
+ * - Returns false if the domain does not match.
+ * - Returns false if the path is specified and does not match the URL pathname.
+ * - Returns true otherwise.
+ */
+export declare const filterGlobalCookie: ({ cookie, url, disabledGlobalCookies, }: {
+    cookie: XScalarCookie;
+    url: string;
+    disabledGlobalCookies: Record<string, boolean>;
+}) => boolean;
+//# sourceMappingURL=filter-global-cookies.d.ts.map

package/dist/request-example/builder/header/filter-global-cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-global-cookies.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/filter-global-cookies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qEAAqE,CAAA;AAIxG;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,yCAIhC;IACD,MAAM,EAAE,aAAa,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/C,KAAG,OAqBH,CAAA"}

package/dist/request-example/builder/header/filter-global-cookies.js

@@ -0,0 +1,26 @@
+import { matchesDomain } from './matches-domain.js';
+/**
+ * Filter a global cookie to determine if it should be included with a request to the given URL.
+ * - Returns false if the cookie is disabled, in the disabledGlobalCookies map, or missing a name.
+ * - Returns false if the domain does not match.
+ * - Returns false if the path is specified and does not match the URL pathname.
+ * - Returns true otherwise.
+ */
+export const filterGlobalCookie = ({ cookie, url, disabledGlobalCookies, }) => {
+    // Filter out disabled cookies, those disabled globally, or those missing a name.
+    if (cookie.isDisabled || disabledGlobalCookies[cookie.name.toLowerCase()] === true || !cookie.name) {
+        return false;
+    }
+    // Parse the URL to extract the pathname for path matching.
+    const urlObject = new URL(url, 'https://example.com');
+    // If a domain restriction exists, ensure the cookie is only sent for matching domains.
+    if (cookie.domain && !matchesDomain(url, cookie.domain)) {
+        return false;
+    }
+    // If a path restriction exists, ensure the cookie is only sent for URLs with a matching prefix.
+    if (cookie.path && !urlObject.pathname.startsWith(cookie.path)) {
+        return false;
+    }
+    // Cookie passed all checks; include it in the request.
+    return true;
+};

package/dist/request-example/builder/header/is-param-disabled.d.ts

@@ -0,0 +1,13 @@
+import type { ExampleObject, ParameterObject } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+/**
+ * Determines if a parameter is disabled
+ *
+ * First we explicitly check if its been disabled via the `x-disabled` extension.
+ * Then we check if its an optional parameter and not a path parameter.
+ *
+ * @param param - The parameter to check.
+ * @param example - The example to check.
+ * @returns true if the parameter is disabled, false otherwise.
+ */
+export declare const isParamDisabled: (param: ParameterObject, example: ExampleObject | undefined) => boolean;
+//# sourceMappingURL=is-param-disabled.d.ts.map

package/dist/request-example/builder/header/is-param-disabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-param-disabled.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/is-param-disabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAElH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,eAAe,EAAE,SAAS,aAAa,GAAG,SAAS,YAUzF,CAAA"}

package/dist/request-example/builder/header/is-param-disabled.js

@@ -0,0 +1,19 @@
+/**
+ * Determines if a parameter is disabled
+ *
+ * First we explicitly check if its been disabled via the `x-disabled` extension.
+ * Then we check if its an optional parameter and not a path parameter.
+ *
+ * @param param - The parameter to check.
+ * @param example - The example to check.
+ * @returns true if the parameter is disabled, false otherwise.
+ */
+export const isParamDisabled = (param, example) => {
+    const xDisabled = example?.['x-disabled'];
+    // If x-disabled is explicitly set (true or false), use that value
+    if (typeof xDisabled === 'boolean') {
+        return xDisabled;
+    }
+    // Otherwise, disable optional parameters (except path parameters which are always required)
+    return !param.required && param.in !== 'path';
+};

package/dist/request-example/builder/header/matches-domain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Matches, when:
+ * - Isn't scoped to a domain, or
+ * - matches the current host, or
+ * - or ends with the current host, or
+ * - matches the current host with a wildcard.
+ */
+export declare const matchesDomain: (givenUrl?: string, configuredHostname?: string) => boolean;
+//# sourceMappingURL=matches-domain.d.ts.map

package/dist/request-example/builder/header/matches-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matches-domain.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/matches-domain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,EAAE,qBAAqB,MAAM,KAAG,OAsB9E,CAAA"}