@scalar/workspace-store 0.31.0 → 0.31.1

package/dist/mutators/operation/operation.js

@@ -0,0 +1,197 @@
+import { isHttpMethod } from "@scalar/helpers/http/is-http-method";
+import { preventPollution } from "@scalar/helpers/object/prevent-pollution";
+import { findVariables } from "@scalar/helpers/regex/find-variables";
+import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
+import { unpackProxyObject } from "../../helpers/unpack-proxy.js";
+import { syncParametersForPathChange } from "../../mutators/operation/helpers/sync-path-parameters.js";
+import { getOperationEntries } from "../../navigation/index.js";
+import { getNavigationOptions } from "../../navigation/get-navigation-options.js";
+import { canHaveOrder, getOpenapiObject } from "../../navigation/helpers/get-openapi-object.js";
+const createOperation = (workspaceStore, payload) => {
+  const document = workspaceStore?.workspace.documents[payload.documentName];
+  if (!document) {
+    payload.callback?.(false);
+    return void 0;
+  }
+  const { path, method, operation } = payload;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  if (!document.paths) {
+    document.paths = {};
+  }
+  if (!document.paths[normalizedPath]) {
+    document.paths[normalizedPath] = {};
+  }
+  preventPollution(normalizedPath);
+  preventPollution(method);
+  document.paths[normalizedPath][method] = operation;
+  const { servers } = operation;
+  const firstServer = unpackProxyObject(servers?.[0]);
+  for (const server of servers ?? []) {
+    if (!document.servers?.some((s) => s.url === server.url)) {
+      if (!document.servers) {
+        document.servers = [];
+      }
+      document.servers.push(unpackProxyObject(server));
+    }
+  }
+  if (firstServer) {
+    document["x-scalar-selected-server"] = firstServer.url;
+  }
+  const newParameters = syncParametersForPathChange(normalizedPath, normalizedPath, operation.parameters ?? []);
+  if (newParameters.length > 0) {
+    operation.parameters = newParameters;
+  }
+  payload.callback?.(true);
+  return normalizedPath;
+};
+const updateOperationSummary = (document, { meta, payload: { summary } }) => {
+  if (!document) {
+    return;
+  }
+  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  if (!operation) {
+    return;
+  }
+  operation.summary = summary;
+};
+const updateOperationOrderId = ({
+  store,
+  operation,
+  generateId,
+  method,
+  path,
+  entries
+}) => {
+  entries?.forEach((entry) => {
+    if (!canHaveOrder(entry.parent)) {
+      return;
+    }
+    const parentOpenAPIObject = getOpenapiObject({ store, entry: entry.parent });
+    if (!parentOpenAPIObject || !("x-scalar-order" in parentOpenAPIObject)) {
+      return;
+    }
+    const order = parentOpenAPIObject["x-scalar-order"];
+    const index = order?.indexOf(entry.id);
+    if (!Array.isArray(order) || typeof index !== "number" || index < 0) {
+      return;
+    }
+    const parentTag = entry.parent.type === "tag" && "name" in parentOpenAPIObject ? { tag: parentOpenAPIObject, id: entry.parent.id } : void 0;
+    order[index] = generateId({
+      type: "operation",
+      path,
+      method,
+      operation,
+      parentId: entry.parent.id,
+      parentTag
+    });
+  });
+};
+const updateOperationPathMethod = (document, store, { meta, payload: { method, path }, callback }) => {
+  const methodChanged = meta.method !== method;
+  const pathChanged = meta.path !== path;
+  if (!methodChanged && !pathChanged) {
+    callback("no-change");
+    return;
+  }
+  const finalMethod = methodChanged ? method : meta.method;
+  const finalPath = pathChanged ? path : meta.path;
+  if (document?.paths?.[finalPath]?.[finalMethod]) {
+    callback("conflict");
+    return;
+  }
+  const documentNavigation = document?.["x-scalar-navigation"];
+  if (!documentNavigation || !store) {
+    console.error("Document or workspace not found", { document });
+    return;
+  }
+  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  if (!operation) {
+    console.error("Operation not found", { meta, document });
+    return;
+  }
+  if (pathChanged) {
+    const oldPathParams = findVariables(meta.path, { includePath: true, includeEnv: false }).filter(
+      (v) => v !== void 0
+    );
+    const newPathParams = findVariables(finalPath, { includePath: true, includeEnv: false }).filter(
+      (v) => v !== void 0
+    );
+    if (oldPathParams.length > 0 || newPathParams.length > 0) {
+      const existingParameters = operation.parameters ?? [];
+      operation.parameters = syncParametersForPathChange(finalPath, meta.path, existingParameters);
+    }
+  }
+  const { generateId } = getNavigationOptions(documentNavigation.name);
+  const operationEntriesMap = getOperationEntries(documentNavigation);
+  const entries = operationEntriesMap.get(`${meta.path}|${meta.method}`);
+  if (entries) {
+    updateOperationOrderId({ store, operation, generateId, method: finalMethod, path: finalPath, entries });
+  }
+  if (!document.paths) {
+    document.paths = {};
+  }
+  if (!document.paths[finalPath]) {
+    document.paths[finalPath] = {};
+  }
+  preventPollution(finalPath);
+  preventPollution(meta.path);
+  preventPollution(finalMethod);
+  document.paths[finalPath][finalMethod] = unpackProxyObject(operation);
+  const oldPathItems = document.paths[meta.path];
+  if (oldPathItems && isHttpMethod(meta.method)) {
+    delete oldPathItems[meta.method];
+    if (Object.keys(oldPathItems).length === 0) {
+      delete document.paths[meta.path];
+    }
+  }
+  store.history.clearOperationHistory(document["x-scalar-navigation"]?.name ?? "", meta.path, meta.method);
+  callback("success");
+};
+const deleteOperation = (workspace, { meta, documentName }) => {
+  const document = workspace?.workspace.documents[documentName];
+  if (!document) {
+    return;
+  }
+  preventPollution(meta.path);
+  preventPollution(meta.method);
+  delete document.paths?.[meta.path]?.[meta.method];
+  if (Object.keys(document.paths?.[meta.path] ?? {}).length === 0) {
+    delete document.paths?.[meta.path];
+  }
+};
+const deleteOperationExample = (workspace, { meta: { path, method, exampleKey }, documentName }) => {
+  const document = workspace?.workspace.documents[documentName];
+  if (!document) {
+    return;
+  }
+  const operation = getResolvedRef(document.paths?.[path]?.[method]);
+  if (!operation) {
+    return;
+  }
+  operation.parameters?.forEach((parameter) => {
+    const resolvedParameter = getResolvedRef(parameter);
+    if ("content" in resolvedParameter && resolvedParameter.content) {
+      Object.values(resolvedParameter.content).forEach((mediaType) => {
+        delete mediaType.examples?.[exampleKey];
+      });
+    }
+    if ("examples" in resolvedParameter && resolvedParameter.examples) {
+      delete resolvedParameter.examples?.[exampleKey];
+    }
+  });
+  const requestBody = getResolvedRef(operation.requestBody);
+  if (!requestBody) {
+    return;
+  }
+  Object.values(requestBody.content ?? {}).forEach((mediaType) => {
+    delete mediaType.examples?.[exampleKey];
+  });
+};
+export {
+  createOperation,
+  deleteOperation,
+  deleteOperationExample,
+  updateOperationPathMethod,
+  updateOperationSummary
+};
+//# sourceMappingURL=operation.js.map

package/dist/mutators/operation/operation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mutators/operation/operation.ts"],
+  "sourcesContent": ["import type { HttpMethod } from '@scalar/helpers/http/http-methods'\nimport { isHttpMethod } from '@scalar/helpers/http/is-http-method'\nimport { preventPollution } from '@scalar/helpers/object/prevent-pollution'\nimport { findVariables } from '@scalar/helpers/regex/find-variables'\n\nimport type { WorkspaceStore } from '@/client'\nimport type { OperationEvents } from '@/events/definitions/operation'\nimport { getResolvedRef } from '@/helpers/get-resolved-ref'\nimport { unpackProxyObject } from '@/helpers/unpack-proxy'\nimport { syncParametersForPathChange } from '@/mutators/operation/helpers/sync-path-parameters'\nimport { getOperationEntries } from '@/navigation'\nimport { getNavigationOptions } from '@/navigation/get-navigation-options'\nimport { canHaveOrder, getOpenapiObject } from '@/navigation/helpers/get-openapi-object'\nimport type { WorkspaceDocument } from '@/schemas'\nimport type { IdGenerator, TraversedOperation, TraversedWebhook, WithParent } from '@/schemas/navigation'\nimport type { OperationObject } from '@/schemas/v3.1/strict/operation'\n\n/**\n * Creates a new operation at a specific path and method in the document.\n * Automatically normalizes the path to ensure it starts with a slash.\n *\n * Returns the normalized path if successful, undefined otherwise.\n *\n * Example:\n * ```ts\n * createOperation(\n *   document,\n *   'users',\n *   'get',\n *   { tags: ['Users'] },\n * )\n * ```\n */\nexport const createOperation = (\n  workspaceStore: WorkspaceStore | null,\n  payload: OperationEvents['operation:create:operation'],\n): string | undefined => {\n  const document = workspaceStore?.workspace.documents[payload.documentName]\n  if (!document) {\n    payload.callback?.(false)\n    return undefined\n  }\n\n  const { path, method, operation } = payload\n\n  /** Ensure the path starts with a slash */\n  const normalizedPath = path.startsWith('/') ? path : `/${path}`\n\n  /** Create the operation in the document */\n  if (!document.paths) {\n    document.paths = {}\n  }\n\n  if (!document.paths[normalizedPath]) {\n    document.paths[normalizedPath] = {}\n  }\n\n  /** Prevent pollution of the path and method */\n  preventPollution(normalizedPath)\n  preventPollution(method)\n\n  /** Create the operation in the document */\n  document.paths[normalizedPath][method] = operation\n\n  // Make sure that we are selecting the new operation server\n  const { servers } = operation\n  const firstServer = unpackProxyObject(servers?.[0])\n\n  // For now we only support document servers but in the future we might support operation servers\n  for (const server of servers ?? []) {\n    // If the server does not exist in the document, add it\n    if (!document.servers?.some((s) => s.url === server.url)) {\n      if (!document.servers) {\n        document.servers = []\n      }\n      document.servers.push(unpackProxyObject(server))\n    }\n  }\n\n  // Update the selected server to the first server of the created operation\n  if (firstServer) {\n    document['x-scalar-selected-server'] = firstServer.url\n  }\n\n  // Sync path variables\n  const newParameters = syncParametersForPathChange(normalizedPath, normalizedPath, operation.parameters ?? [])\n  if (newParameters.length > 0) {\n    operation.parameters = newParameters\n  }\n\n  payload.callback?.(true)\n  return normalizedPath\n}\n\n/**\n * Updates the `summary` of an operation.\n * Safely no-ops if the document or operation does not exist.\n *\n * Example:\n * ```ts\n * updateOperationSummary(\n *   document,\n *   {\n *   meta: { method: 'get', path: '/users/{id}' },\n *   payload: { summary: 'Get a single user' },\n * })\n * ```\n */\nexport const updateOperationSummary = (\n  document: WorkspaceDocument | null,\n  { meta, payload: { summary } }: OperationEvents['operation:update:summary'],\n) => {\n  if (!document) {\n    return\n  }\n\n  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method as HttpMethod])\n  if (!operation) {\n    return\n  }\n\n  operation.summary = summary\n}\n\n/**\n * Updates the order ID of an operation in the sidebar.\n * Used when changing path or method so we do not lose the sidebar ordering\n */\nconst updateOperationOrderId = ({\n  store,\n  operation,\n  generateId,\n  method,\n  path,\n  entries,\n}: {\n  store: WorkspaceStore\n  operation: OperationObject\n  generateId: IdGenerator\n  method: HttpMethod\n  path: string\n  entries: (WithParent<TraversedOperation> | WithParent<TraversedWebhook>)[]\n}) => {\n  // Loop over the entries and replace the ID in the x-scalar-order with the new ID\n  entries?.forEach((entry) => {\n    if (!canHaveOrder(entry.parent)) {\n      return\n    }\n\n    // Ensure we have an x-scalar-order property\n    const parentOpenAPIObject = getOpenapiObject({ store, entry: entry.parent })\n    if (!parentOpenAPIObject || !('x-scalar-order' in parentOpenAPIObject)) {\n      return\n    }\n\n    const order = parentOpenAPIObject['x-scalar-order']\n    const index = order?.indexOf(entry.id)\n    if (!Array.isArray(order) || typeof index !== 'number' || index < 0) {\n      return\n    }\n\n    const parentTag =\n      entry.parent.type === 'tag' && 'name' in parentOpenAPIObject\n        ? { tag: parentOpenAPIObject, id: entry.parent.id }\n        : undefined\n\n    // Generate the new ID based on whether this is an operation or webhook\n    order[index] = generateId({\n      type: 'operation',\n      path,\n      method,\n      operation,\n      parentId: entry.parent.id,\n      parentTag,\n    })\n  })\n}\n\n/**\n * Updates the HTTP method and/or path of an operation and moves it to the new location.\n * This function:\n * 1. Moves the operation from the old method/path to the new method/path under paths\n * 2. Updates x-scalar-order to maintain the operation's position in the sidebar\n * 3. Syncs path parameters when the path changes\n *\n * Safely no-ops if nothing has changed, or if the document or operation does not exist.\n *\n * Example:\n * ```ts\n * updateOperationPathMethod({\n *   document,\n *   store,\n *   meta: { method: 'get', path: '/users' },\n *   payload: { method: 'post', path: '/api/users' },\n * })\n * ```\n */\nexport const updateOperationPathMethod = (\n  document: WorkspaceDocument | null,\n  store: WorkspaceStore | null,\n  { meta, payload: { method, path }, callback }: OperationEvents['operation:update:pathMethod'],\n): void => {\n  const methodChanged = meta.method !== method\n  const pathChanged = meta.path !== path\n\n  // If nothing has changed, no need to do anything\n  if (!methodChanged && !pathChanged) {\n    callback('no-change')\n    return\n  }\n\n  // Determine the final method and path\n  const finalMethod = methodChanged ? method : meta.method\n  const finalPath = pathChanged ? path : meta.path\n\n  // Check for conflicts at the target location\n  if (document?.paths?.[finalPath]?.[finalMethod as HttpMethod]) {\n    callback('conflict')\n    return\n  }\n\n  const documentNavigation = document?.['x-scalar-navigation']\n  if (!documentNavigation || !store) {\n    console.error('Document or workspace not found', { document })\n    return\n  }\n\n  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method as HttpMethod])\n  if (!operation) {\n    console.error('Operation not found', { meta, document })\n    return\n  }\n\n  // Sync path parameters if the path has changed\n  if (pathChanged) {\n    const oldPathParams = findVariables(meta.path, { includePath: true, includeEnv: false }).filter(\n      (v): v is string => v !== undefined,\n    )\n    const newPathParams = findVariables(finalPath, { includePath: true, includeEnv: false }).filter(\n      (v): v is string => v !== undefined,\n    )\n\n    if (oldPathParams.length > 0 || newPathParams.length > 0) {\n      const existingParameters = operation.parameters ?? []\n      operation.parameters = syncParametersForPathChange(finalPath, meta.path, existingParameters)\n    }\n  }\n\n  /**\n   * We don't pass navigation options as we don't have config on the client,\n   * and we don't change path or method on the references\n   */\n  const { generateId } = getNavigationOptions(documentNavigation.name)\n\n  /** Grabs all of the current operation entries for the given path and method */\n  const operationEntriesMap = getOperationEntries(documentNavigation)\n  const entries = operationEntriesMap.get(`${meta.path}|${meta.method}`)\n\n  // Updates the order ID so we don't lose the sidebar ordering when it rebuilds\n  if (entries) {\n    updateOperationOrderId({ store, operation, generateId, method: finalMethod, path: finalPath, entries })\n  }\n\n  // Initialize the paths object if it does not exist\n  if (!document.paths) {\n    document.paths = {}\n  }\n\n  // Initialize the new path if it does not exist\n  if (!document.paths[finalPath]) {\n    document.paths[finalPath] = {}\n  }\n\n  // Prevent assigning dangerous keys to the path items object\n  preventPollution(finalPath)\n  preventPollution(meta.path)\n  preventPollution(finalMethod)\n\n  // Move the operation to the new location\n  document.paths[finalPath][finalMethod] = unpackProxyObject(operation)\n\n  // Remove the operation from the old location\n  const oldPathItems = document.paths[meta.path]\n  if (oldPathItems && isHttpMethod(meta.method)) {\n    delete oldPathItems[meta.method]\n\n    // If the old path has no more operations, remove the path entry\n    if (Object.keys(oldPathItems).length === 0) {\n      delete document.paths[meta.path]\n    }\n  }\n\n  // We need to reset the history for the operation when the path or method changes\n  store.history.clearOperationHistory(document['x-scalar-navigation']?.name ?? '', meta.path, meta.method)\n\n  callback('success')\n}\n\n/**\n * Deletes an operation from the workspace\n *\n * Example:\n * ```ts\n * deleteOperation({\n *   document,\n *   meta: { method: 'get', path: '/users' },\n * })\n * ```\n */\nexport const deleteOperation = (\n  workspace: WorkspaceStore | null,\n  { meta, documentName }: OperationEvents['operation:delete:operation'],\n) => {\n  const document = workspace?.workspace.documents[documentName]\n  if (!document) {\n    return\n  }\n\n  preventPollution(meta.path)\n  preventPollution(meta.method)\n\n  delete document.paths?.[meta.path]?.[meta.method]\n\n  // If the path has no more operations, remove the path entry\n  if (Object.keys(document.paths?.[meta.path] ?? {}).length === 0) {\n    delete document.paths?.[meta.path]\n  }\n}\n\n/**\n * Deletes an example with the given exampleKey from operation parameters and request body.\n *\n * - Finds the target operation within the specified document and path/method.\n * - Removes example values matching exampleKey from both parameter-level and content-level examples.\n * - Safely no-ops if the document, operation, or request body does not exist.\n */\nexport const deleteOperationExample = (\n  workspace: WorkspaceStore | null,\n  { meta: { path, method, exampleKey }, documentName }: OperationEvents['operation:delete:example'],\n) => {\n  // Find the document in workspace based on documentName\n  const document = workspace?.workspace.documents[documentName]\n  if (!document) {\n    return\n  }\n\n  // Get the operation object for the given path and method\n  const operation = getResolvedRef(document.paths?.[path]?.[method])\n  if (!operation) {\n    return\n  }\n\n  // Remove the example from all operation parameters\n  operation.parameters?.forEach((parameter) => {\n    const resolvedParameter = getResolvedRef(parameter)\n\n    // Remove from content-level examples (if parameter uses content)\n    if ('content' in resolvedParameter && resolvedParameter.content) {\n      Object.values(resolvedParameter.content).forEach((mediaType) => {\n        delete mediaType.examples?.[exampleKey]\n      })\n    }\n\n    // Remove from parameter-level examples\n    if ('examples' in resolvedParameter && resolvedParameter.examples) {\n      delete resolvedParameter.examples?.[exampleKey]\n    }\n  })\n\n  // Remove the example from request body content types (if requestBody exists)\n  const requestBody = getResolvedRef(operation.requestBody)\n  if (!requestBody) {\n    return\n  }\n\n  // For each media type, remove the example matching exampleKey\n  Object.values(requestBody.content ?? {}).forEach((mediaType) => {\n    delete mediaType.examples?.[exampleKey]\n  })\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mutators/operation/parameters.d.ts

@@ -0,0 +1,65 @@
+import type { OperationEvents } from '../../events/definitions/operation.js';
+import type { WorkspaceDocument } from '../../schemas.js';
+/**
+ * Updates an existing parameter of a given `type` by its index within that
+ * type subset (e.g. the N-th query parameter). Supports updating name, value,
+ * and enabled state for the targeted example.
+ * Safely no-ops if the document, operation, or parameter does not exist.
+ *
+ * Example:
+ * ```ts
+ * updateOperationParameter({
+ *   document,
+ *   type: 'query',
+ *   index: 0,
+ *   meta: { method: 'get', path: '/search', exampleKey: 'default' },
+ *   payload: { value: 'alice', isDisabled: false },
+ * })
+ * ```
+ */
+export declare const upsertOperationParameter: (document: WorkspaceDocument | null, { meta, type, payload, originalParameter }: OperationEvents["operation:upsert:parameter"]) => void;
+/**
+ * Updates the disabled state of a default parameter for an operation.
+ * Default parameters are inherited from higher-level configurations (like collection or server defaults)
+ * and this allows individual operations to selectively disable them without removing them entirely.
+ *
+ * The disabled state is stored in the `x-scalar-disable-parameters` extension object, organized by
+ * parameter type and example key. Missing objects are initialized automatically.
+ *
+ * @param document - The current workspace document
+ * @param type - The parameter type (e.g., 'header'). Determines the storage key ('default-headers' for headers)
+ * @param meta.path - Path of the operation (e.g., '/users')
+ * @param meta.method - HTTP method of the operation (e.g., 'get')
+ * @param meta.exampleKey - Key identifying the relevant example
+ * @param meta.key - The specific parameter key being updated
+ * @param payload.isDisabled - Whether the parameter should be disabled
+ */
+export declare const updateOperationExtraParameters: (document: WorkspaceDocument | null, { type, meta, payload, in: location }: OperationEvents["operation:update:extra-parameters"]) => void;
+/**
+ * Removes a parameter from the operation OR path
+ *
+ * Example:
+ * ```ts
+ * deleteOperationParameter({
+ *   document,
+ *   originalParameter,
+ *   meta: { method: 'get', path: '/users', exampleKey: 'default' },
+ * })
+ * ```
+ */
+export declare const deleteOperationParameter: (document: WorkspaceDocument | null, { meta, originalParameter }: OperationEvents["operation:delete:parameter"]) => void;
+/**
+ * Deletes all parameters of a given `type` from the operation.
+ * Safely no-ops if the document or operation does not exist.
+ *
+ * Example:
+ * ```ts
+ * deleteAllOperationParameters({
+ *   document,
+ *   type: 'cookie',
+ *   meta: { method: 'get', path: '/users' },
+ * })
+ * ```
+ */
+export declare const deleteAllOperationParameters: (document: WorkspaceDocument | null, { meta, type }: OperationEvents["operation:delete-all:parameters"]) => void;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/mutators/operation/parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../src/mutators/operation/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAGrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,4CAA4C,eAAe,CAAC,4BAA4B,CAAC,SA8C1F,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B,GACzC,UAAU,iBAAiB,GAAG,IAAI,EAClC,uCAAuC,eAAe,CAAC,mCAAmC,CAAC,SA8C5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,6BAA6B,eAAe,CAAC,4BAA4B,CAAC,SA0B3E,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,GACvC,UAAU,iBAAiB,GAAG,IAAI,EAClC,gBAAgB,eAAe,CAAC,iCAAiC,CAAC,SAanE,CAAA"}

package/dist/mutators/operation/parameters.js

@@ -0,0 +1,101 @@
+import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
+import { unpackProxyObject } from "../../helpers/unpack-proxy.js";
+import { isContentTypeParameterObject } from "../../schemas/v3.1/strict/type-guards.js";
+const upsertOperationParameter = (document, { meta, type, payload, originalParameter }) => {
+  if (originalParameter) {
+    originalParameter.name = payload.name;
+    if (isContentTypeParameterObject(originalParameter)) {
+      return;
+    }
+    if (!originalParameter.examples) {
+      originalParameter.examples = {};
+    }
+    originalParameter.examples[meta.exampleKey] ||= {};
+    const example = getResolvedRef(originalParameter.examples[meta.exampleKey]);
+    example.value = payload.value;
+    example["x-disabled"] = payload.isDisabled;
+    return;
+  }
+  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
+  if (!operation) {
+    console.error("Operation not found", { meta, document });
+    return;
+  }
+  operation.parameters ||= [];
+  operation.parameters.push({
+    name: payload.name,
+    in: type,
+    required: type === "path" ? true : false,
+    examples: {
+      [meta.exampleKey]: {
+        value: payload.value,
+        // We always want a new parameter to be enabled by default
+        "x-disabled": false
+      }
+    }
+  });
+  return;
+};
+const updateOperationExtraParameters = (document, { type, meta, payload, in: location }) => {
+  if (!document) {
+    return;
+  }
+  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  if (!operation) {
+    return;
+  }
+  if (!operation["x-scalar-disable-parameters"]) {
+    operation["x-scalar-disable-parameters"] = {};
+  }
+  const mapping = {
+    global: { cookie: "global-cookies" },
+    default: { header: "default-headers" }
+  };
+  const key = mapping[type]?.[location];
+  if (!key) {
+    return;
+  }
+  if (!operation["x-scalar-disable-parameters"][key]) {
+    operation["x-scalar-disable-parameters"][key] = {};
+  }
+  operation["x-scalar-disable-parameters"][key][meta.exampleKey] = {
+    ...operation["x-scalar-disable-parameters"][key][meta.exampleKey] ?? {},
+    [meta.name]: payload.isDisabled ?? false
+  };
+};
+const deleteOperationParameter = (document, { meta, originalParameter }) => {
+  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
+  const operationIndex = operation?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
+  if (operation && operationIndex >= 0) {
+    operation.parameters = unpackProxyObject(
+      operation.parameters?.filter((_, i) => i !== operationIndex),
+      { depth: 1 }
+    );
+    return;
+  }
+  const path = getResolvedRef(document?.paths?.[meta.path]);
+  const pathIndex = path?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
+  if (path && pathIndex >= 0) {
+    path.parameters = unpackProxyObject(
+      path.parameters?.filter((_, i) => i !== pathIndex),
+      { depth: 1 }
+    );
+  }
+};
+const deleteAllOperationParameters = (document, { meta, type }) => {
+  if (!document) {
+    return;
+  }
+  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  if (!operation) {
+    return;
+  }
+  operation.parameters = operation.parameters?.filter((it) => getResolvedRef(it).in !== type) ?? [];
+};
+export {
+  deleteAllOperationParameters,
+  deleteOperationParameter,
+  updateOperationExtraParameters,
+  upsertOperationParameter
+};
+//# sourceMappingURL=parameters.js.map

package/dist/mutators/operation/parameters.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mutators/operation/parameters.ts"],
+  "sourcesContent": ["import type { OperationEvents } from '@/events/definitions/operation'\nimport { getResolvedRef } from '@/helpers/get-resolved-ref'\nimport { unpackProxyObject } from '@/helpers/unpack-proxy'\nimport type { WorkspaceDocument } from '@/schemas'\nimport type { DisableParametersConfig } from '@/schemas/extensions/operation/x-scalar-disable-parameters'\nimport { isContentTypeParameterObject } from '@/schemas/v3.1/strict/type-guards'\n\n/**\n * Updates an existing parameter of a given `type` by its index within that\n * type subset (e.g. the N-th query parameter). Supports updating name, value,\n * and enabled state for the targeted example.\n * Safely no-ops if the document, operation, or parameter does not exist.\n *\n * Example:\n * ```ts\n * updateOperationParameter({\n *   document,\n *   type: 'query',\n *   index: 0,\n *   meta: { method: 'get', path: '/search', exampleKey: 'default' },\n *   payload: { value: 'alice', isDisabled: false },\n * })\n * ```\n */\nexport const upsertOperationParameter = (\n  document: WorkspaceDocument | null,\n  { meta, type, payload, originalParameter }: OperationEvents['operation:upsert:parameter'],\n) => {\n  // We are editing an existing parameter\n  if (originalParameter) {\n    originalParameter.name = payload.name\n\n    if (isContentTypeParameterObject(originalParameter)) {\n      // TODO: handle content-type parameters\n      return\n    }\n\n    if (!originalParameter.examples) {\n      originalParameter.examples = {}\n    }\n\n    // Create the example if it doesn't exist\n    originalParameter.examples[meta.exampleKey] ||= {}\n    const example = getResolvedRef(originalParameter.examples[meta.exampleKey])!\n\n    // Update the example value and disabled state\n    example.value = payload.value\n    example['x-disabled'] = payload.isDisabled\n    return\n  }\n\n  // We are adding a new parameter\n  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method])\n  if (!operation) {\n    console.error('Operation not found', { meta, document })\n    return\n  }\n\n  operation.parameters ||= []\n  operation.parameters.push({\n    name: payload.name,\n    in: type,\n    required: type === 'path' ? true : false,\n    examples: {\n      [meta.exampleKey]: {\n        value: payload.value,\n        // We always want a new parameter to be enabled by default\n        'x-disabled': false,\n      },\n    },\n  })\n  return\n}\n\n/**\n * Updates the disabled state of a default parameter for an operation.\n * Default parameters are inherited from higher-level configurations (like collection or server defaults)\n * and this allows individual operations to selectively disable them without removing them entirely.\n *\n * The disabled state is stored in the `x-scalar-disable-parameters` extension object, organized by\n * parameter type and example key. Missing objects are initialized automatically.\n *\n * @param document - The current workspace document\n * @param type - The parameter type (e.g., 'header'). Determines the storage key ('default-headers' for headers)\n * @param meta.path - Path of the operation (e.g., '/users')\n * @param meta.method - HTTP method of the operation (e.g., 'get')\n * @param meta.exampleKey - Key identifying the relevant example\n * @param meta.key - The specific parameter key being updated\n * @param payload.isDisabled - Whether the parameter should be disabled\n */\nexport const updateOperationExtraParameters = (\n  document: WorkspaceDocument | null,\n  { type, meta, payload, in: location }: OperationEvents['operation:update:extra-parameters'],\n) => {\n  type Type = OperationEvents['operation:update:extra-parameters']['type']\n  type In = OperationEvents['operation:update:extra-parameters']['in']\n\n  // Ensure there's a valid document\n  if (!document) {\n    return\n  }\n\n  // Resolve the referenced operation from the document using the path and method\n  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method])\n  if (!operation) {\n    return\n  }\n\n  // Initialize the 'x-scalar-disable-parameters' object if it doesn't exist\n  if (!operation['x-scalar-disable-parameters']) {\n    operation['x-scalar-disable-parameters'] = {}\n  }\n\n  /**\n   * Maps parameter type and location to the corresponding config key.\n   * Only valid combinations are defined here.\n   */\n  const mapping: Partial<Record<Type, Partial<Record<In, keyof DisableParametersConfig>>>> = {\n    global: { cookie: 'global-cookies' },\n    default: { header: 'default-headers' },\n  }\n\n  const key = mapping[type]?.[location]\n\n  if (!key) {\n    return\n  }\n\n  // Initialize the 'default-headers' object within 'x-scalar-disable-parameters' if it doesn't exist\n  if (!operation['x-scalar-disable-parameters'][key]) {\n    operation['x-scalar-disable-parameters'][key] = {}\n  }\n\n  // Update (or create) the entry for the specific example and key, preserving any existing settings\n  operation['x-scalar-disable-parameters'][key][meta.exampleKey] = {\n    ...(operation['x-scalar-disable-parameters'][key][meta.exampleKey] ?? {}),\n    [meta.name]: payload.isDisabled ?? false,\n  }\n}\n\n/**\n * Removes a parameter from the operation OR path\n *\n * Example:\n * ```ts\n * deleteOperationParameter({\n *   document,\n *   originalParameter,\n *   meta: { method: 'get', path: '/users', exampleKey: 'default' },\n * })\n * ```\n */\nexport const deleteOperationParameter = (\n  document: WorkspaceDocument | null,\n  { meta, originalParameter }: OperationEvents['operation:delete:parameter'],\n) => {\n  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method])\n\n  // Lets check if its on the operation first as its more likely\n  const operationIndex = operation?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1\n\n  // We cannot call splice on a proxy object, so we unwrap the array and filter it\n  if (operation && operationIndex >= 0) {\n    operation.parameters = unpackProxyObject(\n      operation.parameters?.filter((_, i) => i !== operationIndex),\n      { depth: 1 },\n    )\n    return\n  }\n\n  // If it wasn't on the operation it might be on the path\n  const path = getResolvedRef(document?.paths?.[meta.path])\n  const pathIndex = path?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1\n\n  if (path && pathIndex >= 0) {\n    path.parameters = unpackProxyObject(\n      path.parameters?.filter((_, i) => i !== pathIndex),\n      { depth: 1 },\n    )\n  }\n}\n\n/**\n * Deletes all parameters of a given `type` from the operation.\n * Safely no-ops if the document or operation does not exist.\n *\n * Example:\n * ```ts\n * deleteAllOperationParameters({\n *   document,\n *   type: 'cookie',\n *   meta: { method: 'get', path: '/users' },\n * })\n * ```\n */\nexport const deleteAllOperationParameters = (\n  document: WorkspaceDocument | null,\n  { meta, type }: OperationEvents['operation:delete-all:parameters'],\n) => {\n  if (!document) {\n    return\n  }\n\n  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method])\n  if (!operation) {\n    return\n  }\n\n  // Filter out parameters of the specified type\n  operation.parameters = operation.parameters?.filter((it) => getResolvedRef(it).in !== type) ?? []\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/plugins/bundler/index.d.ts

@@ -91,4 +91,17 @@ export declare const normalizeAuthSchemes: () => LifecyclePlugin;
  * This keeps $ref references clean and predictable for downstream consumers.
  */
 export declare const normalizeRefs: () => LifecyclePlugin;
+/**
+ * Lifecycle plugin to sync path parameters for all operations under a path item.
+ *
+ * When processing a path item (e.g., '/users/{id}'), this plugin will:
+ *   - Extract path variables from the path string
+ *   - For each HTTP method operation (get, post, put, delete, etc.)
+ *   - Sync the operation's parameters to match the path variables
+ *   - Preserve existing parameter configurations when possible
+ *
+ * This ensures that path parameters are always in sync with the path string,
+ * even after bundling or other transformations.
+ */
+export declare const syncPathParameters: () => LifecyclePlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/plugins/bundler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAKhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAahC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAO,eA+BxC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAO,eAwCjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAO,eAuBtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,eAuBvC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAmBhC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAMhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAahC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAO,eA+BxC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAO,eAwCjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAO,eAuBtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,eAuBvC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAmBhC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAAO,eA4DrC,CAAA"}

package/dist/plugins/bundler/index.js

@@ -1,4 +1,7 @@
+import { HTTP_METHODS } from "@scalar/helpers/http/http-methods";
+import { isObject } from "@scalar/helpers/object/is-object";
 import { isLocalRef } from "../../helpers/general.js";
+import { syncParametersForPathChange } from "../../mutators/operation/helpers/sync-path-parameters.js";
 import { getResolvedRef } from "../../plugins/bundler/helpers.js";
 const loadingStatus = () => {
   return {
@@ -111,12 +114,55 @@ const normalizeRefs = () => {
     }
   };
 };
+const syncPathParameters = () => {
+  return {
+    type: "lifecycle",
+    onBeforeNodeProcess: (node, context) => {
+      const { path } = context;
+      if (path.length !== 2 || path[0] !== "paths" || typeof path[1] !== "string") {
+        return;
+      }
+      const pathString = path[1];
+      for (const method of HTTP_METHODS) {
+        const operation = getResolvedRef(node[method], context);
+        if (!isObject(operation)) {
+          continue;
+        }
+        const existingParameters = "parameters" in operation && Array.isArray(operation.parameters) ? operation.parameters : [];
+        const { path: pathParameters, other: restParameters } = existingParameters.reduce(
+          (acc, param) => {
+            const resolved = getResolvedRef(param, context);
+            if (!isObject(resolved)) {
+              return acc;
+            }
+            if (resolved.in === "path") {
+              acc.path.push(resolved);
+              return acc;
+            }
+            acc.other.push(param);
+            return acc;
+          },
+          {
+            path: [],
+            other: []
+          }
+        );
+        const syncedParameters = syncParametersForPathChange(pathString, pathString, pathParameters);
+        const result = [...syncedParameters, ...restParameters];
+        if (result.length > 0) {
+          operation.parameters = result;
+        }
+      }
+    }
+  };
+};
 export {
   externalValueResolver,
   loadingStatus,
   normalizeAuthSchemes,
   normalizeRefs,
   refsEverywhere,
-  restoreOriginalRefs
+  restoreOriginalRefs,
+  syncPathParameters
 };
 //# sourceMappingURL=index.js.map

package/dist/plugins/bundler/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/plugins/bundler/index.ts"],
-  "sourcesContent": ["/**\n * This file contains a collection of plugins used for the bundler.\n * Plugins defined here can extend or modify the behavior of the bundling process,\n * such as adding lifecycle hooks or custom processing logic.\n */\n\nimport type { LifecyclePlugin } from '@scalar/json-magic/bundle'\n\nimport { isLocalRef } from '@/helpers/general'\nimport { getResolvedRef } from '@/plugins/bundler/helpers'\n\n/**\n * A lifecycle plugin that adds a `$status` property to nodes during resolution.\n * - Sets `$status` to 'loading' when resolution starts.\n * - Sets `$status` to 'error' if resolution fails.\n * - Removes `$status` when resolution succeeds.\n */\nexport const loadingStatus = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onResolveStart: (node) => {\n      node['$status'] = 'loading'\n    },\n    onResolveError: (node) => {\n      node['$status'] = 'error'\n    },\n    onResolveSuccess: (node) => {\n      delete node['$status']\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to resolve and embed external content referenced by an 'externalValue' property in a node.\n *\n * When a node contains an 'externalValue' property (as a string), this plugin will:\n *   - Fetch the external resource (such as a URL or file) using the fetchUrls plugin.\n *   - If the fetch is successful, assign the fetched data to the node's 'value' property.\n *\n * This is useful for inlining external content (like examples or schemas) into the OpenAPI document during bundling.\n *\n * @param node - The node being processed, which may contain an 'externalValue' property.\n */\nexport const externalValueResolver = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onAfterNodeProcess: async (node, context) => {\n      const externalValue = node['externalValue']\n      const cache = context.resolutionCache\n\n      // Only process if 'externalValue' is a string\n      if (typeof externalValue !== 'string') {\n        return\n      }\n\n      const loader = context.loaders.find((it) => it.validate(externalValue))\n\n      // We can not process the external value\n      if (!loader) {\n        return\n      }\n\n      if (!cache.has(externalValue)) {\n        cache.set(externalValue, loader.exec(externalValue))\n      }\n\n      const result = await cache.get(externalValue)\n\n      // If fetch is successful, assign the data to the node's 'value' property\n      if (result?.ok) {\n        node['value'] = result.data\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to resolve $ref on any object, including non-standard locations like the info object.\n *\n * This plugin will:\n *   - Detect if a node contains a $ref property (as a string).\n *   - If the node is under the 'info' path, attempt to resolve the reference using fetchUrls.\n *   - Replace the node's properties with the resolved data if successful.\n *\n * Note: This currently only supports refs on the 'info' object and does not handle primitive types.\n */\nexport const refsEverywhere = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: async (node, context) => {\n      const { path, resolutionCache, parentNode } = context\n      const ref = node['$ref']\n\n      // Only process nodes that have a $ref property as a string\n      if (typeof ref !== 'string') {\n        return\n      }\n\n      // Can not resolve top level refs\n      if (!parentNode || !path.length) {\n        return\n      }\n\n      const loader = context.loaders.find((it) => it.validate(ref))\n\n      // Can not load the external ref\n      if (!loader) {\n        return\n      }\n\n      // Support resolving $ref on the info object\n      if (path[0] === 'info') {\n        // Use the cache to avoid duplicate fetches\n        if (!resolutionCache.has(ref)) {\n          resolutionCache.set(ref, loader.exec(ref))\n        }\n\n        const result = await resolutionCache.get(ref)\n\n        if (result?.ok) {\n          // Replace the ref with the resolved data\n          parentNode[path.at(-1)!] = result.data\n        }\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to restore original $ref values after processing.\n *\n * This plugin is intended to be used as a \"lifecycle\" plugin in the bundling process.\n * It operates in the `onAfterNodeProcess` hook, and its main purpose is to restore\n * the original $ref values for external references that may have been replaced or\n * rewritten during the bundling process.\n *\n * How it works:\n * - For each node processed, if the node contains a $ref property (as a string),\n *   and the root document contains an \"x-ext-urls\" mapping object,\n *   the plugin will attempt to restore the original $ref value.\n * - The \"x-ext-urls\" object is expected to be a mapping from the rewritten $ref\n *   (e.g., a hashed or compressed reference) back to the original external URL or path.\n * - If a mapping exists for the current $ref, the plugin replaces the $ref value\n *   with the original value from the mapping. If no mapping exists (e.g., for local refs),\n *   the $ref value is left unchanged.\n *\n * This is useful for scenarios where you want to present or export the bundled document\n * with the original external $ref values, rather than the internal or rewritten ones.\n *\n * @returns {LifecyclePlugin} The plugin object for use in the bundler.\n */\nexport const restoreOriginalRefs = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: (node, context) => {\n      const ref = node['$ref']\n      const root = context.rootNode\n      const extUrls = root['x-ext-urls']\n\n      // Only process if $ref is a string and x-ext-urls is a valid object\n      if (typeof ref !== 'string' || typeof extUrls !== 'object' || extUrls === null || !isLocalRef(ref)) {\n        return\n      }\n\n      // Working with local refs\n\n      const segments = ref.split('/')\n      const key = segments.at(-1) ?? ''\n\n      // Replace the $ref with the original version from the mapping,\n      // or keep the current version if there is no mapping (e.g., for local refs)\n      node['$ref'] = (extUrls as Record<string, string>)[key] ?? ref\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to normalize the `scheme` property in securitySchemes to lowercase.\n *\n * Our typebox schemas require the `scheme` property to be a lowercase string.\n * This plugin ensures that any `scheme` field under `components.securitySchemes` is normalized to lowercase, fixing\n * potential user input errors such as \"Bearer\" or \"BASIC\".\n *\n * Example:\n * ```yaml\n * Before normalization:\n *   components:\n *     securitySchemes:\n *       bearerAuth:\n *         type: http\n *         scheme: Bearer\n * ```\n * After normalization:\n * ```yaml\n *   components:\n *     securitySchemes:\n *       bearerAuth:\n *         type: http\n *         scheme: bearer\n * ```\n */\nexport const normalizeAuthSchemes = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onAfterNodeProcess: (node, context) => {\n      const { path } = context\n\n      // Check if we're at components.securitySchemes.{schemeName}\n      if (path.length === 3 && path[0] === 'components' && path[1] === 'securitySchemes') {\n        const targetNode = getResolvedRef(node, context)\n\n        // If the scheme exists and is a string, normalize to lowercase if not already\n        if (\n          typeof targetNode === 'object' &&\n          targetNode !== null &&\n          'scheme' in targetNode &&\n          typeof targetNode['scheme'] === 'string' &&\n          targetNode['scheme'].toLowerCase() !== targetNode['scheme']\n        ) {\n          targetNode['scheme'] = targetNode['scheme'].toLowerCase()\n        }\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to normalize $ref nodes:\n * Ensures that for any non-schema object containing a $ref, only $ref,\n * summary, description, and $status properties are preserved.\n * This keeps $ref references clean and predictable for downstream consumers.\n */\nexport const normalizeRefs = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: (node, context) => {\n      const { path } = context\n\n      // If the node is a $ref and we are not on the schema object, we need to normalize the $ref\n      if (typeof node['$ref'] === 'string' && !(path[0] === 'components' && path[1] === 'schemas')) {\n        // Remove any other properties from the node and only keep the '$ref', 'summary', 'description' and '$status'\n        const keepProperties = new Set(['$ref', 'summary', 'description', '$status'])\n\n        Object.keys(node).forEach((key) => {\n          if (!keepProperties.has(key)) {\n            delete node[key]\n          }\n        })\n      }\n    },\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * This file contains a collection of plugins used for the bundler.\n * Plugins defined here can extend or modify the behavior of the bundling process,\n * such as adding lifecycle hooks or custom processing logic.\n */\n\nimport { HTTP_METHODS } from '@scalar/helpers/http/http-methods'\nimport { isObject } from '@scalar/helpers/object/is-object'\nimport type { LifecyclePlugin } from '@scalar/json-magic/bundle'\n\nimport { isLocalRef } from '@/helpers/general'\nimport { syncParametersForPathChange } from '@/mutators/operation/helpers/sync-path-parameters'\nimport { getResolvedRef } from '@/plugins/bundler/helpers'\n\n/**\n * A lifecycle plugin that adds a `$status` property to nodes during resolution.\n * - Sets `$status` to 'loading' when resolution starts.\n * - Sets `$status` to 'error' if resolution fails.\n * - Removes `$status` when resolution succeeds.\n */\nexport const loadingStatus = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onResolveStart: (node) => {\n      node['$status'] = 'loading'\n    },\n    onResolveError: (node) => {\n      node['$status'] = 'error'\n    },\n    onResolveSuccess: (node) => {\n      delete node['$status']\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to resolve and embed external content referenced by an 'externalValue' property in a node.\n *\n * When a node contains an 'externalValue' property (as a string), this plugin will:\n *   - Fetch the external resource (such as a URL or file) using the fetchUrls plugin.\n *   - If the fetch is successful, assign the fetched data to the node's 'value' property.\n *\n * This is useful for inlining external content (like examples or schemas) into the OpenAPI document during bundling.\n *\n * @param node - The node being processed, which may contain an 'externalValue' property.\n */\nexport const externalValueResolver = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onAfterNodeProcess: async (node, context) => {\n      const externalValue = node['externalValue']\n      const cache = context.resolutionCache\n\n      // Only process if 'externalValue' is a string\n      if (typeof externalValue !== 'string') {\n        return\n      }\n\n      const loader = context.loaders.find((it) => it.validate(externalValue))\n\n      // We can not process the external value\n      if (!loader) {\n        return\n      }\n\n      if (!cache.has(externalValue)) {\n        cache.set(externalValue, loader.exec(externalValue))\n      }\n\n      const result = await cache.get(externalValue)\n\n      // If fetch is successful, assign the data to the node's 'value' property\n      if (result?.ok) {\n        node['value'] = result.data\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to resolve $ref on any object, including non-standard locations like the info object.\n *\n * This plugin will:\n *   - Detect if a node contains a $ref property (as a string).\n *   - If the node is under the 'info' path, attempt to resolve the reference using fetchUrls.\n *   - Replace the node's properties with the resolved data if successful.\n *\n * Note: This currently only supports refs on the 'info' object and does not handle primitive types.\n */\nexport const refsEverywhere = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: async (node, context) => {\n      const { path, resolutionCache, parentNode } = context\n      const ref = node['$ref']\n\n      // Only process nodes that have a $ref property as a string\n      if (typeof ref !== 'string') {\n        return\n      }\n\n      // Can not resolve top level refs\n      if (!parentNode || !path.length) {\n        return\n      }\n\n      const loader = context.loaders.find((it) => it.validate(ref))\n\n      // Can not load the external ref\n      if (!loader) {\n        return\n      }\n\n      // Support resolving $ref on the info object\n      if (path[0] === 'info') {\n        // Use the cache to avoid duplicate fetches\n        if (!resolutionCache.has(ref)) {\n          resolutionCache.set(ref, loader.exec(ref))\n        }\n\n        const result = await resolutionCache.get(ref)\n\n        if (result?.ok) {\n          // Replace the ref with the resolved data\n          parentNode[path.at(-1)!] = result.data\n        }\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to restore original $ref values after processing.\n *\n * This plugin is intended to be used as a \"lifecycle\" plugin in the bundling process.\n * It operates in the `onAfterNodeProcess` hook, and its main purpose is to restore\n * the original $ref values for external references that may have been replaced or\n * rewritten during the bundling process.\n *\n * How it works:\n * - For each node processed, if the node contains a $ref property (as a string),\n *   and the root document contains an \"x-ext-urls\" mapping object,\n *   the plugin will attempt to restore the original $ref value.\n * - The \"x-ext-urls\" object is expected to be a mapping from the rewritten $ref\n *   (e.g., a hashed or compressed reference) back to the original external URL or path.\n * - If a mapping exists for the current $ref, the plugin replaces the $ref value\n *   with the original value from the mapping. If no mapping exists (e.g., for local refs),\n *   the $ref value is left unchanged.\n *\n * This is useful for scenarios where you want to present or export the bundled document\n * with the original external $ref values, rather than the internal or rewritten ones.\n *\n * @returns {LifecyclePlugin} The plugin object for use in the bundler.\n */\nexport const restoreOriginalRefs = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: (node, context) => {\n      const ref = node['$ref']\n      const root = context.rootNode\n      const extUrls = root['x-ext-urls']\n\n      // Only process if $ref is a string and x-ext-urls is a valid object\n      if (typeof ref !== 'string' || typeof extUrls !== 'object' || extUrls === null || !isLocalRef(ref)) {\n        return\n      }\n\n      // Working with local refs\n\n      const segments = ref.split('/')\n      const key = segments.at(-1) ?? ''\n\n      // Replace the $ref with the original version from the mapping,\n      // or keep the current version if there is no mapping (e.g., for local refs)\n      node['$ref'] = (extUrls as Record<string, string>)[key] ?? ref\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to normalize the `scheme` property in securitySchemes to lowercase.\n *\n * Our typebox schemas require the `scheme` property to be a lowercase string.\n * This plugin ensures that any `scheme` field under `components.securitySchemes` is normalized to lowercase, fixing\n * potential user input errors such as \"Bearer\" or \"BASIC\".\n *\n * Example:\n * ```yaml\n * Before normalization:\n *   components:\n *     securitySchemes:\n *       bearerAuth:\n *         type: http\n *         scheme: Bearer\n * ```\n * After normalization:\n * ```yaml\n *   components:\n *     securitySchemes:\n *       bearerAuth:\n *         type: http\n *         scheme: bearer\n * ```\n */\nexport const normalizeAuthSchemes = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onAfterNodeProcess: (node, context) => {\n      const { path } = context\n\n      // Check if we're at components.securitySchemes.{schemeName}\n      if (path.length === 3 && path[0] === 'components' && path[1] === 'securitySchemes') {\n        const targetNode = getResolvedRef(node, context)\n\n        // If the scheme exists and is a string, normalize to lowercase if not already\n        if (\n          typeof targetNode === 'object' &&\n          targetNode !== null &&\n          'scheme' in targetNode &&\n          typeof targetNode['scheme'] === 'string' &&\n          targetNode['scheme'].toLowerCase() !== targetNode['scheme']\n        ) {\n          targetNode['scheme'] = targetNode['scheme'].toLowerCase()\n        }\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to normalize $ref nodes:\n * Ensures that for any non-schema object containing a $ref, only $ref,\n * summary, description, and $status properties are preserved.\n * This keeps $ref references clean and predictable for downstream consumers.\n */\nexport const normalizeRefs = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: (node, context) => {\n      const { path } = context\n\n      // If the node is a $ref and we are not on the schema object, we need to normalize the $ref\n      if (typeof node['$ref'] === 'string' && !(path[0] === 'components' && path[1] === 'schemas')) {\n        // Remove any other properties from the node and only keep the '$ref', 'summary', 'description' and '$status'\n        const keepProperties = new Set(['$ref', 'summary', 'description', '$status'])\n\n        Object.keys(node).forEach((key) => {\n          if (!keepProperties.has(key)) {\n            delete node[key]\n          }\n        })\n      }\n    },\n  }\n}\n\n/**\n * Lifecycle plugin to sync path parameters for all operations under a path item.\n *\n * When processing a path item (e.g., '/users/{id}'), this plugin will:\n *   - Extract path variables from the path string\n *   - For each HTTP method operation (get, post, put, delete, etc.)\n *   - Sync the operation's parameters to match the path variables\n *   - Preserve existing parameter configurations when possible\n *\n * This ensures that path parameters are always in sync with the path string,\n * even after bundling or other transformations.\n */\nexport const syncPathParameters = (): LifecyclePlugin => {\n  return {\n    type: 'lifecycle',\n    onBeforeNodeProcess: (node, context) => {\n      const { path } = context\n\n      // Only process path items (e.g., paths -> /users/{id} -> operations)\n      if (path.length !== 2 || path[0] !== 'paths' || typeof path[1] !== 'string') {\n        return\n      }\n\n      const pathString = path[1]\n\n      // Sync parameters for each operation method\n      for (const method of HTTP_METHODS) {\n        const operation = getResolvedRef(node[method], context)\n\n        if (!isObject(operation)) {\n          continue\n        }\n\n        const existingParameters =\n          'parameters' in operation && Array.isArray(operation.parameters) ? operation.parameters : []\n\n        const { path: pathParameters, other: restParameters } = existingParameters.reduce<{\n          path: any[]\n          other: any[]\n        }>(\n          (acc, param) => {\n            const resolved = getResolvedRef(param, context)\n\n            if (!isObject(resolved)) {\n              return acc\n            }\n\n            if (resolved.in === 'path') {\n              acc.path.push(resolved)\n              return acc\n            }\n            acc.other.push(param)\n            return acc\n          },\n          {\n            path: [],\n            other: [],\n          },\n        )\n\n        // Sync path parameters using the same path for old and new\n        // This ensures parameters match the current path string\n        const syncedParameters = syncParametersForPathChange(pathString, pathString, pathParameters)\n\n        const result = [...syncedParameters, ...restParameters]\n\n        if (result.length > 0) {\n          operation.parameters = result\n        }\n      }\n    },\n  }\n}\n"],
+  "mappings": "AAMA,SAAS,oBAAoB;AAC7B,SAAS,gBAAgB;AAGzB,SAAS,kBAAkB;AAC3B,SAAS,mCAAmC;AAC5C,SAAS,sBAAsB;AAQxB,MAAM,gBAAgB,MAAuB;AAClD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,gBAAgB,CAAC,SAAS;AACxB,WAAK,SAAS,IAAI;AAAA,IACpB;AAAA,IACA,gBAAgB,CAAC,SAAS;AACxB,WAAK,SAAS,IAAI;AAAA,IACpB;AAAA,IACA,kBAAkB,CAAC,SAAS;AAC1B,aAAO,KAAK,SAAS;AAAA,IACvB;AAAA,EACF;AACF;AAaO,MAAM,wBAAwB,MAAuB;AAC1D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,oBAAoB,OAAO,MAAM,YAAY;AAC3C,YAAM,gBAAgB,KAAK,eAAe;AAC1C,YAAM,QAAQ,QAAQ;AAGtB,UAAI,OAAO,kBAAkB,UAAU;AACrC;AAAA,MACF;AAEA,YAAM,SAAS,QAAQ,QAAQ,KAAK,CAAC,OAAO,GAAG,SAAS,aAAa,CAAC;AAGtE,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AAEA,UAAI,CAAC,MAAM,IAAI,aAAa,GAAG;AAC7B,cAAM,IAAI,eAAe,OAAO,KAAK,aAAa,CAAC;AAAA,MACrD;AAEA,YAAM,SAAS,MAAM,MAAM,IAAI,aAAa;AAG5C,UAAI,QAAQ,IAAI;AACd,aAAK,OAAO,IAAI,OAAO;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AACF;AAYO,MAAM,iBAAiB,MAAuB;AACnD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,qBAAqB,OAAO,MAAM,YAAY;AAC5C,YAAM,EAAE,MAAM,iBAAiB,WAAW,IAAI;AAC9C,YAAM,MAAM,KAAK,MAAM;AAGvB,UAAI,OAAO,QAAQ,UAAU;AAC3B;AAAA,MACF;AAGA,UAAI,CAAC,cAAc,CAAC,KAAK,QAAQ;AAC/B;AAAA,MACF;AAEA,YAAM,SAAS,QAAQ,QAAQ,KAAK,CAAC,OAAO,GAAG,SAAS,GAAG,CAAC;AAG5D,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AAGA,UAAI,KAAK,CAAC,MAAM,QAAQ;AAEtB,YAAI,CAAC,gBAAgB,IAAI,GAAG,GAAG;AAC7B,0BAAgB,IAAI,KAAK,OAAO,KAAK,GAAG,CAAC;AAAA,QAC3C;AAEA,cAAM,SAAS,MAAM,gBAAgB,IAAI,GAAG;AAE5C,YAAI,QAAQ,IAAI;AAEd,qBAAW,KAAK,GAAG,EAAE,CAAE,IAAI,OAAO;AAAA,QACpC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAyBO,MAAM,sBAAsB,MAAuB;AACxD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,qBAAqB,CAAC,MAAM,YAAY;AACtC,YAAM,MAAM,KAAK,MAAM;AACvB,YAAM,OAAO,QAAQ;AACrB,YAAM,UAAU,KAAK,YAAY;AAGjC,UAAI,OAAO,QAAQ,YAAY,OAAO,YAAY,YAAY,YAAY,QAAQ,CAAC,WAAW,GAAG,GAAG;AAClG;AAAA,MACF;AAIA,YAAM,WAAW,IAAI,MAAM,GAAG;AAC9B,YAAM,MAAM,SAAS,GAAG,EAAE,KAAK;AAI/B,WAAK,MAAM,IAAK,QAAmC,GAAG,KAAK;AAAA,IAC7D;AAAA,EACF;AACF;AA2BO,MAAM,uBAAuB,MAAuB;AACzD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,oBAAoB,CAAC,MAAM,YAAY;AACrC,YAAM,EAAE,KAAK,IAAI;AAGjB,UAAI,KAAK,WAAW,KAAK,KAAK,CAAC,MAAM,gBAAgB,KAAK,CAAC,MAAM,mBAAmB;AAClF,cAAM,aAAa,eAAe,MAAM,OAAO;AAG/C,YACE,OAAO,eAAe,YACtB,eAAe,QACf,YAAY,cACZ,OAAO,WAAW,QAAQ,MAAM,YAChC,WAAW,QAAQ,EAAE,YAAY,MAAM,WAAW,QAAQ,GAC1D;AACA,qBAAW,QAAQ,IAAI,WAAW,QAAQ,EAAE,YAAY;AAAA,QAC1D;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAQO,MAAM,gBAAgB,MAAuB;AAClD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,qBAAqB,CAAC,MAAM,YAAY;AACtC,YAAM,EAAE,KAAK,IAAI;AAGjB,UAAI,OAAO,KAAK,MAAM,MAAM,YAAY,EAAE,KAAK,CAAC,MAAM,gBAAgB,KAAK,CAAC,MAAM,YAAY;AAE5F,cAAM,iBAAiB,oBAAI,IAAI,CAAC,QAAQ,WAAW,eAAe,SAAS,CAAC;AAE5E,eAAO,KAAK,IAAI,EAAE,QAAQ,CAAC,QAAQ;AACjC,cAAI,CAAC,eAAe,IAAI,GAAG,GAAG;AAC5B,mBAAO,KAAK,GAAG;AAAA,UACjB;AAAA,QACF,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAcO,MAAM,qBAAqB,MAAuB;AACvD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,qBAAqB,CAAC,MAAM,YAAY;AACtC,YAAM,EAAE,KAAK,IAAI;AAGjB,UAAI,KAAK,WAAW,KAAK,KAAK,CAAC,MAAM,WAAW,OAAO,KAAK,CAAC,MAAM,UAAU;AAC3E;AAAA,MACF;AAEA,YAAM,aAAa,KAAK,CAAC;AAGzB,iBAAW,UAAU,cAAc;AACjC,cAAM,YAAY,eAAe,KAAK,MAAM,GAAG,OAAO;AAEtD,YAAI,CAAC,SAAS,SAAS,GAAG;AACxB;AAAA,QACF;AAEA,cAAM,qBACJ,gBAAgB,aAAa,MAAM,QAAQ,UAAU,UAAU,IAAI,UAAU,aAAa,CAAC;AAE7F,cAAM,EAAE,MAAM,gBAAgB,OAAO,eAAe,IAAI,mBAAmB;AAAA,UAIzE,CAAC,KAAK,UAAU;AACd,kBAAM,WAAW,eAAe,OAAO,OAAO;AAE9C,gBAAI,CAAC,SAAS,QAAQ,GAAG;AACvB,qBAAO;AAAA,YACT;AAEA,gBAAI,SAAS,OAAO,QAAQ;AAC1B,kBAAI,KAAK,KAAK,QAAQ;AACtB,qBAAO;AAAA,YACT;AACA,gBAAI,MAAM,KAAK,KAAK;AACpB,mBAAO;AAAA,UACT;AAAA,UACA;AAAA,YACE,MAAM,CAAC;AAAA,YACP,OAAO,CAAC;AAAA,UACV;AAAA,QACF;AAIA,cAAM,mBAAmB,4BAA4B,YAAY,YAAY,cAAc;AAE3F,cAAM,SAAS,CAAC,GAAG,kBAAkB,GAAG,cAAc;AAEtD,YAAI,OAAO,SAAS,GAAG;AACrB,oBAAU,aAAa;AAAA,QACzB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;",
   "names": []
 }

package/package.json

@@ -16,7 +16,7 @@
     "openapi",
     "scalar"
   ],
-  "version": "0.31.0",
+  "version": "0.31.1",
   "engines": {
     "node": ">=18"
   },
@@ -134,13 +134,13 @@
     "vue": "^3.5.26",
     "yaml": "^2.8.0",
     "@scalar/code-highlight": "0.2.3",
+    "@scalar/helpers": "0.2.11",
     "@scalar/json-magic": "0.11.0",
-    "@scalar/object-utils": "1.2.25",
     "@scalar/openapi-upgrader": "0.1.8",
-    "@scalar/helpers": "0.2.11",
-    "@scalar/themes": "0.14.0",
+    "@scalar/snippetz": "0.6.11",
     "@scalar/types": "0.6.2",
-    "@scalar/snippetz": "0.6.11"
+    "@scalar/themes": "0.14.0",
+    "@scalar/object-utils": "1.2.25"
   },
   "devDependencies": {
     "@google-cloud/storage": "7.16.0",

package/dist/mutators/fetch-request-to-har.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fetch-request-to-har.d.ts","sourceRoot":"","sources":["../../src/mutators/fetch-request-to-har.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,KAAK,sBAAsB,GAAG;IAC5B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,iBAAiB,GAAU,uDAMrC,sBAAsB,KAAG,OAAO,CAAC,UAAU,CA+C7C,CAAA"}

package/dist/mutators/fetch-response-to-har.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fetch-response-to-har.d.ts","sourceRoot":"","sources":["../../src/mutators/fetch-response-to-har.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,KAAK,uBAAuB,GAAG;IAC7B,+CAA+C;IAC/C,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,GAAU,wDAKtC,uBAAuB,KAAG,OAAO,CAAC,WAAW,CAwC/C,CAAA;AA4CD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,KAAG,OAoCxD,CAAA"}

package/dist/mutators/har-to-operation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"har-to-operation.d.ts","sourceRoot":"","sources":["../../src/mutators/har-to-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAKpH,KAAK,mBAAmB,GAAG;IACzB,6BAA6B;IAC7B,UAAU,EAAE,UAAU,CAAA;IACtB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC,CAAA;AAyBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GAAI,2DAK5B,mBAAmB,KAAG,eAyHxB,CAAA"}