@scalar/workspace-store 0.18.0 → 0.19.0

package/dist/helpers/overrides-proxy.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/helpers/overrides-proxy.ts"],
-  "sourcesContent": ["import { isObject } from '@/helpers/general'\n\nconst isOverridesProxy = Symbol('isOverridesProxy')\nexport const getOverridesTarget = Symbol('getOverridesTarget')\n\n/**\n * Recursively makes all properties of a type optional.\n *\n * - If T is an object, recursively applies DeepPartial to each property, making them optional.\n * - Otherwise, T is returned as-is.\n *\n * @template T - The type to make deeply partial (optional).\n * @example\n * type Example = { a: { b: number } }\n * type PartialExample = DeepPartial<Example>\n * // Result: { a?: { b?: number } }\n */\nexport type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T\n\n/**\n * Creates a proxy object that overlays \"overrides\" on top of a target object.\n *\n * - When reading a property, if an override exists, it is returned; otherwise, the original value is returned.\n * - When writing to a property, if an override exists, it is updated; otherwise, the original object is updated.\n * - This works recursively for nested objects, so overrides can be deeply partial.\n * - Special symbols are used to identify the proxy and to access the original target.\n *\n * @template T - The type of the target object.\n * @param target - The original object to proxy.\n * @param overrides - An optional object containing override values (deeply partial).\n * @returns A proxy object that reflects overrides on top of the target.\n *\n * @example\n * const original = { a: 1, b: { c: 2 } }\n * const overrides = { b: { c: 42 } }\n * const proxy = createOverridesProxy(original, { overrides })\n *\n * console.log(proxy.a) // 1 (from original)\n * console.log(proxy.b.c) // 42 (from overrides)\n *\n * proxy.a = 100\n * console.log(original.a) // 100\n *\n * proxy.b.c = 99\n * console.log(overrides.b.c) // 99\n */\nexport const createOverridesProxy = <T extends Record<string, unknown>>(\n  target: T,\n  options?: {\n    overrides?: DeepPartial<T>\n  },\n  args: {\n    cache: WeakMap<object, any>\n  } = {\n    cache: new WeakMap(),\n  },\n): T => {\n  if (!target || typeof target !== 'object') {\n    return target\n  }\n\n  // Return existing proxy for the same target to ensure referential stability\n  if (args.cache.has(target)) {\n    return args.cache.get(target)!\n  }\n\n  const { overrides } = options ?? {}\n\n  // Proxy handler to intercept get/set operations\n  const handler: ProxyHandler<T> = {\n    get(target, prop, receiver) {\n      // Special symbol to identify this as an overrides proxy\n      if (prop === isOverridesProxy) {\n        return true\n      }\n\n      // Special symbol to access the original target object\n      if (prop === getOverridesTarget) {\n        return target\n      }\n\n      const value = Reflect.get(target, prop, receiver)\n\n      // Return early if the value is already an overrides proxy\n      if (isOverridesProxyObject(value)) {\n        return value\n      }\n\n      // If the value is not an object, return the override if it exists, else the original value\n      if (!isObject(value)) {\n        return Reflect.get(overrides ?? {}, prop) ?? value\n      }\n\n      // For nested objects, recursively create a proxy with the corresponding overrides\n      return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args)\n    },\n\n    set(target, prop, value, receiver) {\n      // Prevent setting special symbols\n      if (prop === isOverridesProxy || prop === getOverridesTarget) {\n        return false\n      }\n\n      // If an override exists for this property, update it\n      const hasOverride = overrides && Reflect.has(overrides, prop)\n\n      if (hasOverride && overrides && typeof overrides === 'object') {\n        ;(overrides as any)[prop] = value\n        return true\n      }\n\n      // Otherwise, update the original target\n      return Reflect.set(target, prop, value, receiver)\n    },\n  }\n\n  // Return the proxy object\n  const proxy = new Proxy<T>(target, handler)\n  args.cache.set(target, proxy)\n  return proxy\n}\n\nexport const isOverridesProxyObject = (obj: unknown): boolean => {\n  return typeof obj === 'object' && obj !== null && (obj as { [isOverridesProxy]: boolean })[isOverridesProxy] === true\n}\n\n/**\n * Unpacks an object from the overrides proxy, returning the original (unproxied) target object.\n * If the input is not an overrides proxy, returns the object as-is.\n *\n * @param input - The potentially proxied object\n * @returns The original unproxied target object or the input object\n */\nexport function unpackOverridesProxy<T>(input: T): T {\n  if ((input as T & { [isOverridesProxy]: boolean | undefined })[isOverridesProxy]) {\n    return (input as T & { [getOverridesTarget]: T })[getOverridesTarget]\n  }\n\n  return input\n}\n"],
-  "mappings": "AAAA,SAAS,gBAAgB;AAEzB,MAAM,mBAAmB,OAAO,kBAAkB;AAC3C,MAAM,qBAAqB,OAAO,oBAAoB;AA2CtD,MAAM,uBAAuB,CAClC,QACA,SAGA,OAEI;AAAA,EACF,OAAO,oBAAI,QAAQ;AACrB,MACM;AACN,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,WAAO;AAAA,EACT;AAGA,MAAI,KAAK,MAAM,IAAI,MAAM,GAAG;AAC1B,WAAO,KAAK,MAAM,IAAI,MAAM;AAAA,EAC9B;AAEA,QAAM,EAAE,UAAU,IAAI,WAAW,CAAC;AAGlC,QAAM,UAA2B;AAAA,IAC/B,IAAIA,SAAQ,MAAM,UAAU;AAE1B,UAAI,SAAS,kBAAkB;AAC7B,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,oBAAoB;AAC/B,eAAOA;AAAA,MACT;AAEA,YAAM,QAAQ,QAAQ,IAAIA,SAAQ,MAAM,QAAQ;AAGhD,UAAI,uBAAuB,KAAK,GAAG;AACjC,eAAO;AAAA,MACT;AAGA,UAAI,CAAC,SAAS,KAAK,GAAG;AACpB,eAAO,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,KAAK;AAAA,MAC/C;AAGA,aAAO,qBAAqB,OAAO,EAAE,WAAW,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI;AAAA,IAC5F;AAAA,IAEA,IAAIA,SAAQ,MAAM,OAAO,UAAU;AAEjC,UAAI,SAAS,oBAAoB,SAAS,oBAAoB;AAC5D,eAAO;AAAA,MACT;AAGA,YAAM,cAAc,aAAa,QAAQ,IAAI,WAAW,IAAI;AAE5D,UAAI,eAAe,aAAa,OAAO,cAAc,UAAU;AAC7D;AAAC,QAAC,UAAkB,IAAI,IAAI;AAC5B,eAAO;AAAA,MACT;AAGA,aAAO,QAAQ,IAAIA,SAAQ,MAAM,OAAO,QAAQ;AAAA,IAClD;AAAA,EACF;AAGA,QAAM,QAAQ,IAAI,MAAS,QAAQ,OAAO;AAC1C,OAAK,MAAM,IAAI,QAAQ,KAAK;AAC5B,SAAO;AACT;AAEO,MAAM,yBAAyB,CAAC,QAA0B;AAC/D,SAAO,OAAO,QAAQ,YAAY,QAAQ,QAAS,IAAwC,gBAAgB,MAAM;AACnH;AASO,SAAS,qBAAwB,OAAa;AACnD,MAAK,MAA0D,gBAAgB,GAAG;AAChF,WAAQ,MAA0C,kBAAkB;AAAA,EACtE;AAEA,SAAO;AACT;",
+  "sourcesContent": ["import { isObject } from '@/helpers/general'\n\nconst isOverridesProxy = Symbol('isOverridesProxy')\nexport const getOverridesTarget = Symbol('getOverridesTarget')\n\n/**\n * Recursively makes all properties of a type optional.\n *\n * - If T is an object, recursively applies DeepPartial to each property, making them optional.\n * - Otherwise, T is returned as-is.\n *\n * @template T - The type to make deeply partial (optional).\n * @example\n * type Example = { a: { b: number } }\n * type PartialExample = DeepPartial<Example>\n * // Result: { a?: { b?: number } }\n */\nexport type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T\n\n/**\n * Creates a proxy object that overlays \"overrides\" on top of a target object.\n *\n * - When reading a property, if an override exists, it is returned; otherwise, the original value is returned.\n * - When writing to a property, if an override exists, it is updated; otherwise, the original object is updated.\n * - This works recursively for nested objects, so overrides can be deeply partial.\n * - Special symbols are used to identify the proxy and to access the original target.\n *\n * @template T - The type of the target object.\n * @param target - The original object to proxy.\n * @param overrides - An optional object containing override values (deeply partial).\n * @returns A proxy object that reflects overrides on top of the target.\n *\n * @example\n * const original = { a: 1, b: { c: 2 } }\n * const overrides = { b: { c: 42 } }\n * const proxy = createOverridesProxy(original, { overrides })\n *\n * console.log(proxy.a) // 1 (from original)\n * console.log(proxy.b.c) // 42 (from overrides)\n *\n * proxy.a = 100\n * console.log(original.a) // 100\n *\n * proxy.b.c = 99\n * console.log(overrides.b.c) // 99\n */\nexport const createOverridesProxy = <T extends Record<string, unknown>>(\n  target: T,\n  options?: {\n    overrides?: DeepPartial<T>\n  },\n  args: {\n    cache: WeakMap<object, any>\n  } = {\n    cache: new WeakMap(),\n  },\n): T => {\n  if (!target || typeof target !== 'object') {\n    return target\n  }\n\n  // Return existing proxy for the same target to ensure referential stability\n  if (args.cache.has(target)) {\n    return args.cache.get(target)!\n  }\n\n  const { overrides } = options ?? {}\n\n  // Proxy handler to intercept get/set operations\n  const handler: ProxyHandler<T> = {\n    get(target, prop, receiver) {\n      // Special symbol to identify this as an overrides proxy\n      if (prop === isOverridesProxy) {\n        return true\n      }\n\n      // Special symbol to access the original target object\n      if (prop === getOverridesTarget) {\n        return target\n      }\n\n      const value = Reflect.get(target, prop, receiver)\n\n      // Return early if the value is already an overrides proxy\n      if (isOverridesProxyObject(value)) {\n        return value\n      }\n\n      // If the value is not an object, return the override if it exists, else the original value\n      if (!isObject(value)) {\n        return Reflect.get(overrides ?? {}, prop) ?? value\n      }\n\n      // For nested objects, recursively create a proxy with the corresponding overrides\n      return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args)\n    },\n\n    set(target, prop, value, receiver) {\n      // Prevent setting special symbols\n      if (prop === isOverridesProxy || prop === getOverridesTarget) {\n        return false\n      }\n\n      // If an override exists for this property, update it\n      const hasOverride = overrides && Reflect.has(overrides, prop)\n\n      if (hasOverride && overrides && typeof overrides === 'object') {\n        ;(overrides as any)[prop] = value\n        return true\n      }\n\n      // Otherwise, update the original target\n      return Reflect.set(target, prop, value, receiver)\n    },\n  }\n\n  // Return the proxy object\n  const proxy = new Proxy<T>(target, handler)\n  args.cache.set(target, proxy)\n  return proxy\n}\n\nexport const isOverridesProxyObject = (obj: unknown): boolean => {\n  return typeof obj === 'object' && obj !== null && (obj as { [isOverridesProxy]: boolean })[isOverridesProxy] === true\n}\n\n/**\n * Unpacks an object from the overrides proxy, returning the original (unproxied) target object.\n * If the input is not an overrides proxy, returns the object as-is.\n *\n * @param input - The potentially proxied object\n * @returns The original unproxied target object or the input object\n */\nexport function unpackOverridesProxy<T>(input: T): T {\n  if (\n    typeof input === 'object' &&\n    input !== null &&\n    (input as T & { [isOverridesProxy]: boolean | undefined })[isOverridesProxy]\n  ) {\n    return (input as T & { [getOverridesTarget]: T })[getOverridesTarget]\n  }\n\n  return input\n}\n"],
+  "mappings": "AAAA,SAAS,gBAAgB;AAEzB,MAAM,mBAAmB,OAAO,kBAAkB;AAC3C,MAAM,qBAAqB,OAAO,oBAAoB;AA2CtD,MAAM,uBAAuB,CAClC,QACA,SAGA,OAEI;AAAA,EACF,OAAO,oBAAI,QAAQ;AACrB,MACM;AACN,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,WAAO;AAAA,EACT;AAGA,MAAI,KAAK,MAAM,IAAI,MAAM,GAAG;AAC1B,WAAO,KAAK,MAAM,IAAI,MAAM;AAAA,EAC9B;AAEA,QAAM,EAAE,UAAU,IAAI,WAAW,CAAC;AAGlC,QAAM,UAA2B;AAAA,IAC/B,IAAIA,SAAQ,MAAM,UAAU;AAE1B,UAAI,SAAS,kBAAkB;AAC7B,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,oBAAoB;AAC/B,eAAOA;AAAA,MACT;AAEA,YAAM,QAAQ,QAAQ,IAAIA,SAAQ,MAAM,QAAQ;AAGhD,UAAI,uBAAuB,KAAK,GAAG;AACjC,eAAO;AAAA,MACT;AAGA,UAAI,CAAC,SAAS,KAAK,GAAG;AACpB,eAAO,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,KAAK;AAAA,MAC/C;AAGA,aAAO,qBAAqB,OAAO,EAAE,WAAW,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI;AAAA,IAC5F;AAAA,IAEA,IAAIA,SAAQ,MAAM,OAAO,UAAU;AAEjC,UAAI,SAAS,oBAAoB,SAAS,oBAAoB;AAC5D,eAAO;AAAA,MACT;AAGA,YAAM,cAAc,aAAa,QAAQ,IAAI,WAAW,IAAI;AAE5D,UAAI,eAAe,aAAa,OAAO,cAAc,UAAU;AAC7D;AAAC,QAAC,UAAkB,IAAI,IAAI;AAC5B,eAAO;AAAA,MACT;AAGA,aAAO,QAAQ,IAAIA,SAAQ,MAAM,OAAO,QAAQ;AAAA,IAClD;AAAA,EACF;AAGA,QAAM,QAAQ,IAAI,MAAS,QAAQ,OAAO;AAC1C,OAAK,MAAM,IAAI,QAAQ,KAAK;AAC5B,SAAO;AACT;AAEO,MAAM,yBAAyB,CAAC,QAA0B;AAC/D,SAAO,OAAO,QAAQ,YAAY,QAAQ,QAAS,IAAwC,gBAAgB,MAAM;AACnH;AASO,SAAS,qBAAwB,OAAa;AACnD,MACE,OAAO,UAAU,YACjB,UAAU,QACT,MAA0D,gBAAgB,GAC3E;AACA,WAAQ,MAA0C,kBAAkB;AAAA,EACtE;AAEA,SAAO;AACT;",
   "names": ["target"]
 }

package/dist/helpers/unpack-proxy.d.ts

@@ -2,5 +2,5 @@
  * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,
  * returning the "raw" plain object or array.
  */
-export declare const unpackProxyObject: <T extends object | Array<unknown>>(input: T) => T;
+export declare const unpackProxyObject: <T>(input: T) => T;
 //# sourceMappingURL=unpack-proxy.d.ts.map

package/dist/helpers/unpack-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unpack-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/unpack-proxy.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,KAAG,CACV,CAAA"}
+{"version":3,"file":"unpack-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/unpack-proxy.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CACsB,CAAA"}

package/dist/helpers/unpack-proxy.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/helpers/unpack-proxy.ts"],
-  "sourcesContent": ["import { getRaw } from '@scalar/json-magic/magic-proxy'\nimport { toRaw } from 'vue'\n\nimport { unpackDetectChangesProxy } from '@/helpers/detect-changes-proxy'\nimport { unpackOverridesProxy } from '@/helpers/overrides-proxy'\n\n/**\n * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,\n * returning the \"raw\" plain object or array.\n */\nexport const unpackProxyObject = <T extends object | Array<unknown>>(input: T): T =>\n  unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(input))))\n"],
-  "mappings": "AAAA,SAAS,cAAc;AACvB,SAAS,aAAa;AAEtB,SAAS,gCAAgC;AACzC,SAAS,4BAA4B;AAM9B,MAAM,oBAAoB,CAAoC,UACnE,yBAAyB,MAAM,OAAO,qBAAqB,KAAK,CAAC,CAAC,CAAC;",
+  "sourcesContent": ["import { getRaw } from '@scalar/json-magic/magic-proxy'\nimport { toRaw } from 'vue'\n\nimport { unpackDetectChangesProxy } from '@/helpers/detect-changes-proxy'\nimport { unpackOverridesProxy } from '@/helpers/overrides-proxy'\n\n/**\n * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,\n * returning the \"raw\" plain object or array.\n */\nexport const unpackProxyObject = <T>(input: T): T =>\n  unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(input))))\n"],
+  "mappings": "AAAA,SAAS,cAAc;AACvB,SAAS,aAAa;AAEtB,SAAS,gCAAgC;AACzC,SAAS,4BAA4B;AAM9B,MAAM,oBAAoB,CAAI,UACnC,yBAAyB,MAAM,OAAO,qBAAqB,KAAK,CAAC,CAAC,CAAC;",
   "names": []
 }

package/dist/mutators/auth.d.ts

@@ -0,0 +1,210 @@
+import type { HttpMethod } from '@scalar/helpers/http/http-methods';
+import type { WorkspaceDocument } from '../schemas.js';
+import type { SecurityRequirementObject } from '../schemas/v3.1/strict/security-requirement.js';
+import type { SecuritySchemeObject } from '../schemas/v3.1/strict/security-scheme.js';
+/**
+ * AuthMeta defines the meta information needed to specify whether the authentication operation
+ * is being performed at the document level (entire API), or for a specific operation (specific path and method).
+ *
+ * - If type is 'document', the operation applies to the whole OpenAPI document.
+ * - If type is 'operation', it targets a specific operation, identified by its path and method.
+ */
+export type AuthMeta = {
+    type: 'document';
+} | {
+    type: 'operation';
+    path: string;
+    method: HttpMethod;
+};
+/**
+ * Updates the selected security schemes for either the entire document or a specific operation.
+ * - Adds newly created security schemes (if any) to the workspace document's components.
+ * - Ensures that each new scheme name is unique within the document by using `generateUniqueValue`.
+ * - Updates the `x-scalar-selected-security` property on the target (document or operation) to reflect the new set of selected security schemes.
+ * - Corrects and maintains the selected index so it points to a valid security scheme.
+ *
+ * @param document - The workspace OpenAPI document to mutate (can be null, in which case nothing happens)
+ * @param selectedSecuritySchemes - The current list of selected security scheme objects
+ * @param create - Array of new schemes to create, each with a name and a scheme definition
+ * @param meta - Location to update: whole document or a specific operation (`{ type: 'document' }` or `{ type: 'operation', path, method }`)
+ *
+ * Example usage:
+ * ```
+ * updateSelectedSecuritySchemes({
+ *   document,
+ *   selectedSecuritySchemes: [{ bearerAuth: [] }],
+ *   create: [
+ *     { name: 'ApiKeyAuth', scheme: { type: 'apiKey', in: 'header', name: 'X-API-Key' } }
+ *   ],
+ *   meta: { type: 'document' }
+ * })
+ * ```
+ */
+export declare const updateSelectedSecuritySchemes: ({ document, selectedRequirements, newSchemes, meta, }: {
+    document: WorkspaceDocument | null;
+    selectedRequirements: SecurityRequirementObject[];
+    newSchemes: {
+        name: string;
+        scheme: SecuritySchemeObject;
+    }[];
+    meta: AuthMeta;
+}) => void;
+/**
+ * SecuritySchemeUpdate represents the possible updates that can be made
+ * to an OpenAPI security scheme object via UI interactions.
+ *
+ * - `http`: Updates to HTTP type schemes (e.g. basic, bearer), allowing token, username, and password changes.
+ * - `apiKey`: Updates to API Key type schemes, allowing the key name and its value to be updated.
+ * - `oauth2`: Updates to OAuth2 type schemes for each supported OAuth2 flow.
+ *    - Can set various properties such as auth/token URLs, tokens, PKCE method, client credentials, etc.
+ */
+export type SecuritySchemeUpdate = {
+    type: 'http';
+    payload: Partial<{
+        token: string;
+        username: string;
+        password: string;
+    }>;
+} | {
+    type: 'apiKey';
+    payload: Partial<{
+        name: string;
+        value: string;
+    }>;
+} | {
+    type: 'oauth2';
+    flow: 'implicit' | 'password' | 'clientCredentials' | 'authorizationCode';
+    payload: Partial<{
+        authUrl: string;
+        tokenUrl: string;
+        token: string;
+        redirectUrl: string;
+        clientId: string;
+        clientSecret: string;
+        usePkce: 'no' | 'SHA-256' | 'plain';
+        username: string;
+        password: string;
+    }>;
+};
+/**
+ * Updates a security scheme in the OpenAPI document's components object.
+ * Handles updates for HTTP, API Key, and OAuth2 types, saving secret information and configuration for UI-auth flows.
+ *
+ * @param document - The OpenAPI workspace document (can be null)
+ * @param data - The update information, including type and payload
+ * @param name - The name of the security scheme in document.components.securitySchemes
+ *
+ * Example usage:
+ *
+ * updateSecurityScheme({
+ *   document,
+ *   data: {
+ *     type: 'http',
+ *     payload: {
+ *       username: 'user123',
+ *       password: 'pw123',
+ *       token: 'tokenval'
+ *     }
+ *   },
+ *   name: 'MyHttpAuth',
+ * })
+ */
+export declare const updateSecurityScheme: ({ document, data, name, }: {
+    document: WorkspaceDocument | null;
+    data: SecuritySchemeUpdate;
+    name: string;
+}) => void;
+/**
+ * Sets the selected authentication tab (scheme) index for the given OpenAPI document or operation.
+ * - When on the document level, updates the 'x-selected-index' on the document's x-scalar-selected-security extension.
+ * - When on an operation (endpoint) level, updates the 'x-selected-index' for that operation's x-scalar-selected-security.
+ *
+ * Also initializes the x-scalar-selected-security extension if it does not exist.
+ *
+ * @param document The OpenAPI document object (may be null)
+ * @param index The index to set as selected
+ * @param meta Context where the selection applies ('document' or specific operation)
+ *
+ * @example
+ * // Document-level tab selection
+ * updateSelectedAuthTab({
+ *   document,
+ *   index: 1,
+ *   meta: { type: 'document' }
+ * });
+ *
+ * // Operation-level tab selection (e.g., GET /pets)
+ * updateSelectedAuthTab({
+ *   document,
+ *   index: 0,
+ *   meta: { type: 'operation', path: '/pets', method: 'get' }
+ * });
+ */
+export declare const updateSelectedAuthTab: ({ document, index, meta, }: {
+    document: WorkspaceDocument | null;
+    index: number;
+    meta: AuthMeta;
+}) => void;
+/**
+ * Updates the scopes for a specific security requirement in the selected security schemes of
+ * a document or operation.
+ *
+ * @param document - The OpenAPI WorkspaceDocument to update.
+ * @param id - An array of scheme names that uniquely identifies the target security requirement.
+ *             For example: ['OAuth', 'ApiKeyAuth']
+ * @param name - The security scheme name to update scopes for (e.g., 'OAuth').
+ * @param scopes - The new list of scopes to set. For example: ['read:pets', 'write:pets']
+ * @param meta - The context specifying whether the update is at the document-level or operation-level.
+ *
+ * Example usage:
+ * ```ts
+ * // Suppose your document (or operation) x-scalar-selected-security looks like:
+ * // "x-scalar-selected-security": {
+ * //   "x-selected-index": 0,
+ * //   "x-schemes": [
+ * //     { "OAuth": ["read:pets"] },
+ * //     { "ApiKeyAuth": [] }
+ * //   ]
+ * // }
+ *
+ * updateSelectedScopes({
+ *   document,
+ *   id: ["OAuth"],     // identifies the scheme object: { "OAuth": [...] }
+ *   name: "OAuth",     // scheme name to update within this security requirement
+ *   scopes: ["write:pets"], // new scopes array
+ *   meta: { type: "document" }
+ * })
+ * // After, the first scheme becomes: { "OAuth": ["write:pets"] }
+ * ```
+ */
+export declare const updateSelectedScopes: ({ document, id, name, scopes, meta, }: {
+    document: WorkspaceDocument | null;
+    id: string[];
+    name: string;
+    scopes: string[];
+    meta: AuthMeta;
+}) => void;
+/**
+ * Deletes one or more security schemes from an OpenAPI WorkspaceDocument,
+ * and removes all references to those schemes from selected security, document-level security,
+ * and operation-level security/selected security (e.g., on paths).
+ *
+ * Example usage:
+ *
+ * ```ts
+ * deleteSecurityScheme({
+ *   document,                                // The OpenAPI document to update
+ *   names: ['ApiKeyAuth', 'BearerAuth'],     // The names of security schemes you want to delete
+ * });
+ * ```
+ *
+ * After running this function:
+ * - The named security schemes are removed from the components.securitySchemes section.
+ * - All document-level and operation-level security entries referencing those schemes are removed.
+ * - Any extended x-scalar-selected-security references to those schemes are also removed.
+ */
+export declare const deleteSecurityScheme: ({ document, names }: {
+    document: WorkspaceDocument | null;
+    names: string[];
+}) => void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/mutators/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mutators/auth.ts"],"names":[],"mappings":"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"}

package/dist/mutators/auth.js

@@ -0,0 +1,223 @@
+import { generateUniqueValue } from "../helpers/generate-unique-value.js";
+import { getResolvedRef } from "../helpers/get-resolved-ref.js";
+const updateSelectedSecuritySchemes = ({
+  document,
+  selectedRequirements,
+  newSchemes,
+  meta
+}) => {
+  if (!document) {
+    return;
+  }
+  const getTarget = () => {
+    if (meta.type === "document") {
+      return document;
+    }
+    return getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  };
+  const createdSchemes = newSchemes.map((scheme) => {
+    const name = generateUniqueValue({
+      defaultValue: scheme.name,
+      validation: (value) => !document.components?.securitySchemes?.[value],
+      maxRetries: 100
+    });
+    if (!name) {
+      return;
+    }
+    if (!document.components) {
+      document.components = {};
+    }
+    if (!document.components.securitySchemes) {
+      document.components.securitySchemes = {};
+    }
+    document.components.securitySchemes[name] = scheme.scheme;
+    return {
+      [name]: []
+    };
+  }).filter(Boolean);
+  const target = getTarget();
+  const newSelectedSecuritySchemes = [...selectedRequirements, ...createdSchemes];
+  if (!target) {
+    return;
+  }
+  if (!target["x-scalar-selected-security"]) {
+    target["x-scalar-selected-security"] = {
+      "x-selected-index": -1,
+      "x-schemes": []
+    };
+  }
+  const selectedIndex = target["x-scalar-selected-security"]["x-selected-index"];
+  target["x-scalar-selected-security"]["x-schemes"] = newSelectedSecuritySchemes;
+  if (newSelectedSecuritySchemes.length > 0 && selectedIndex < 0) {
+    target["x-scalar-selected-security"]["x-selected-index"] = 0;
+  }
+  if (selectedIndex >= newSelectedSecuritySchemes.length) {
+    target["x-scalar-selected-security"]["x-selected-index"] = newSelectedSecuritySchemes.length - 1;
+  }
+};
+const updateSecurityScheme = ({
+  document,
+  data,
+  name
+}) => {
+  if (!document) {
+    return;
+  }
+  const target = getResolvedRef(document.components?.securitySchemes?.[name]);
+  if (!target) {
+    return;
+  }
+  if (target.type === "http" && data.type === "http") {
+    if (data.payload.username) {
+      target["x-scalar-secret-username"] = data.payload.username;
+    }
+    if (data.payload.password) {
+      target["x-scalar-secret-password"] = data.payload.password;
+    }
+    if (data.payload.token) {
+      target["x-scalar-secret-token"] = data.payload.token;
+    }
+  } else if (target.type === "apiKey" && data.type === "apiKey") {
+    if (data.payload.name) {
+      target.name = data.payload.name;
+    }
+    if (data.payload.value) {
+      target["x-scalar-secret-token"] = data.payload.value;
+    }
+  } else if (target.type === "oauth2" && data.type === "oauth2") {
+    const flow = target.flows[data.flow];
+    if (!flow) {
+      return;
+    }
+    if (data.payload.authUrl && "authorizationUrl" in flow) {
+      flow.authorizationUrl = data.payload.authUrl;
+    }
+    if (data.payload.tokenUrl && "tokenUrl" in flow) {
+      flow.tokenUrl = data.payload.tokenUrl;
+    }
+    if (data.payload.token && "x-scalar-secret-token" in flow) {
+      flow["x-scalar-secret-token"] = data.payload.token;
+    }
+    if (data.payload.redirectUrl && "x-scalar-secret-redirect-uri" in flow) {
+      flow["x-scalar-secret-redirect-uri"] = data.payload.redirectUrl;
+    }
+    if (data.payload.clientId && "x-scalar-secret-client-id" in flow) {
+      flow["x-scalar-secret-client-id"] = data.payload.clientId;
+    }
+    if (data.payload.clientSecret && "x-scalar-secret-client-secret" in flow) {
+      flow["x-scalar-secret-client-secret"] = data.payload.clientSecret;
+    }
+    if (data.payload.usePkce && "x-usePkce" in flow) {
+      flow["x-usePkce"] = data.payload.usePkce;
+    }
+    if (data.payload.username && "x-scalar-secret-username" in flow) {
+      flow["x-scalar-secret-username"] = data.payload.username;
+    }
+    if (data.payload.password && "x-scalar-secret-password" in flow) {
+      flow["x-scalar-secret-password"] = data.payload.password;
+    }
+  }
+  return;
+};
+const updateSelectedAuthTab = ({
+  document,
+  index,
+  meta
+}) => {
+  if (!document) {
+    return;
+  }
+  const getTarget = () => {
+    if (meta.type === "document") {
+      return document;
+    }
+    return getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  };
+  const target = getTarget();
+  if (!target) {
+    return;
+  }
+  if (!target["x-scalar-selected-security"]) {
+    target["x-scalar-selected-security"] = {
+      "x-selected-index": 0,
+      "x-schemes": []
+    };
+  }
+  target["x-scalar-selected-security"]["x-selected-index"] = index;
+};
+const updateSelectedScopes = ({
+  document,
+  id,
+  name,
+  scopes,
+  meta
+}) => {
+  if (!document) {
+    return;
+  }
+  const getTarget = () => {
+    if (meta.type === "document") {
+      return document;
+    }
+    return getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+  };
+  const target = getTarget();
+  if (!target) {
+    return;
+  }
+  const selectedSchemes = target["x-scalar-selected-security"]?.["x-schemes"];
+  if (!selectedSchemes) {
+    return;
+  }
+  const scheme = selectedSchemes.find((scheme2) => JSON.stringify(Object.keys(scheme2)) === JSON.stringify(id));
+  if (!scheme) {
+    return;
+  }
+  scheme[name] = scopes;
+};
+const deleteSecurityScheme = ({ document, names }) => {
+  if (!document) {
+    return;
+  }
+  const target = getResolvedRef(document.components?.securitySchemes);
+  if (!target) {
+    return;
+  }
+  names.forEach((name) => {
+    delete target[name];
+  });
+  const filterSecuritySchemes = (schemes) => {
+    return schemes.filter((scheme) => !names.some((name) => Object.keys(scheme).includes(name)));
+  };
+  if (document["x-scalar-selected-security"]) {
+    const selectedSecurity = document["x-scalar-selected-security"];
+    selectedSecurity["x-schemes"] = filterSecuritySchemes(selectedSecurity["x-schemes"]);
+  }
+  if (document["security"]) {
+    document["security"] = filterSecuritySchemes(document["security"]);
+  }
+  Object.values(document.paths ?? {}).forEach((path) => {
+    Object.values(path).forEach((operation) => {
+      if (typeof operation !== "object") {
+        return;
+      }
+      const resolvedOperation = getResolvedRef(operation);
+      if ("security" in resolvedOperation && resolvedOperation["security"]) {
+        resolvedOperation["security"] = filterSecuritySchemes(resolvedOperation["security"]);
+      }
+      if ("x-scalar-selected-security" in resolvedOperation && resolvedOperation["x-scalar-selected-security"]) {
+        resolvedOperation["x-scalar-selected-security"]["x-schemes"] = filterSecuritySchemes(
+          resolvedOperation["x-scalar-selected-security"]["x-schemes"]
+        );
+      }
+    });
+  });
+};
+export {
+  deleteSecurityScheme,
+  updateSecurityScheme,
+  updateSelectedAuthTab,
+  updateSelectedScopes,
+  updateSelectedSecuritySchemes
+};
+//# sourceMappingURL=auth.js.map

package/dist/mutators/auth.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/mutators/auth.ts"],
+  "sourcesContent": ["import type { HttpMethod } from '@scalar/helpers/http/http-methods'\n\nimport { generateUniqueValue } from '@/helpers/generate-unique-value'\nimport { getResolvedRef } from '@/helpers/get-resolved-ref'\nimport type { WorkspaceDocument } from '@/schemas'\nimport type { SecurityRequirementObject } from '@/schemas/v3.1/strict/security-requirement'\nimport type { SecuritySchemeObject } from '@/schemas/v3.1/strict/security-scheme'\n\n/**\n * AuthMeta defines the meta information needed to specify whether the authentication operation\n * is being performed at the document level (entire API), or for a specific operation (specific path and method).\n *\n * - If type is 'document', the operation applies to the whole OpenAPI document.\n * - If type is 'operation', it targets a specific operation, identified by its path and method.\n */\nexport type AuthMeta =\n  | {\n      type: 'document'\n    }\n  | {\n      type: 'operation'\n      path: string\n      method: HttpMethod\n    }\n\n/**\n * Updates the selected security schemes for either the entire document or a specific operation.\n * - Adds newly created security schemes (if any) to the workspace document's components.\n * - Ensures that each new scheme name is unique within the document by using `generateUniqueValue`.\n * - Updates the `x-scalar-selected-security` property on the target (document or operation) to reflect the new set of selected security schemes.\n * - Corrects and maintains the selected index so it points to a valid security scheme.\n *\n * @param document - The workspace OpenAPI document to mutate (can be null, in which case nothing happens)\n * @param selectedSecuritySchemes - The current list of selected security scheme objects\n * @param create - Array of new schemes to create, each with a name and a scheme definition\n * @param meta - Location to update: whole document or a specific operation (`{ type: 'document' }` or `{ type: 'operation', path, method }`)\n *\n * Example usage:\n * ```\n * updateSelectedSecuritySchemes({\n *   document,\n *   selectedSecuritySchemes: [{ bearerAuth: [] }],\n *   create: [\n *     { name: 'ApiKeyAuth', scheme: { type: 'apiKey', in: 'header', name: 'X-API-Key' } }\n *   ],\n *   meta: { type: 'document' }\n * })\n * ```\n */\nexport const updateSelectedSecuritySchemes = ({\n  document,\n  selectedRequirements,\n  newSchemes,\n  meta,\n}: {\n  document: WorkspaceDocument | null\n  selectedRequirements: SecurityRequirementObject[]\n  newSchemes: { name: string; scheme: SecuritySchemeObject }[]\n  meta: AuthMeta\n}) => {\n  if (!document) {\n    return\n  }\n\n  // Helper to get the target (whole document or a specific operation)\n  const getTarget = () => {\n    if (meta.type === 'document') {\n      return document\n    }\n\n    return getResolvedRef(document.paths?.[meta.path]?.[meta.method])\n  }\n\n  // Create any new security schemes required, ensuring unique names for the components\n  const createdSchemes = newSchemes\n    .map((scheme) => {\n      const name = generateUniqueValue({\n        defaultValue: scheme.name,\n        validation: (value) => !document.components?.securitySchemes?.[value],\n        maxRetries: 100,\n      })\n\n      if (!name) {\n        return\n      }\n\n      // Ensure components and securitySchemes exist\n      if (!document.components) {\n        document.components = {}\n      }\n      if (!document.components.securitySchemes) {\n        document.components.securitySchemes = {}\n      }\n\n      // Add the new security scheme definition\n      document.components.securitySchemes[name] = scheme.scheme\n\n      // Return an OpenAPI Security Requirement Object for this new scheme (empty scope array)\n      return {\n        [name]: [],\n      }\n    })\n    .filter(Boolean) as SecurityRequirementObject[]\n\n  const target = getTarget()\n\n  const newSelectedSecuritySchemes = [...selectedRequirements, ...createdSchemes]\n\n  // If the target (document/operation) doesn't exist, do nothing\n  if (!target) {\n    return\n  }\n\n  // Ensure the x-scalar-selected-security structure exists on the target\n  if (!target['x-scalar-selected-security']) {\n    target['x-scalar-selected-security'] = {\n      'x-selected-index': -1,\n      'x-schemes': [],\n    }\n  }\n\n  const selectedIndex = target['x-scalar-selected-security']['x-selected-index']\n\n  // Update the schemes array\n  target['x-scalar-selected-security']['x-schemes'] = newSelectedSecuritySchemes\n\n  // Adjust selected index if there are schemes and the index is unset/invalid\n  if (newSelectedSecuritySchemes.length > 0 && selectedIndex < 0) {\n    target['x-scalar-selected-security']['x-selected-index'] = 0\n  }\n\n  // If the selected index is now out of bounds, select the last available\n  if (selectedIndex >= newSelectedSecuritySchemes.length) {\n    target['x-scalar-selected-security']['x-selected-index'] = newSelectedSecuritySchemes.length - 1\n  }\n}\n\n/**\n * SecuritySchemeUpdate represents the possible updates that can be made\n * to an OpenAPI security scheme object via UI interactions.\n *\n * - `http`: Updates to HTTP type schemes (e.g. basic, bearer), allowing token, username, and password changes.\n * - `apiKey`: Updates to API Key type schemes, allowing the key name and its value to be updated.\n * - `oauth2`: Updates to OAuth2 type schemes for each supported OAuth2 flow.\n *    - Can set various properties such as auth/token URLs, tokens, PKCE method, client credentials, etc.\n */\nexport type SecuritySchemeUpdate =\n  | {\n      type: 'http'\n      payload: Partial<{\n        token: string\n        username: string\n        password: string\n      }>\n    }\n  | {\n      type: 'apiKey'\n      payload: Partial<{\n        name: string\n        value: string\n      }>\n    }\n  | {\n      type: 'oauth2'\n      flow: 'implicit' | 'password' | 'clientCredentials' | 'authorizationCode'\n      payload: Partial<{\n        authUrl: string\n        tokenUrl: string\n        token: string\n        redirectUrl: string\n        clientId: string\n        clientSecret: string\n        usePkce: 'no' | 'SHA-256' | 'plain'\n        username: string\n        password: string\n      }>\n    }\n\n/**\n * Updates a security scheme in the OpenAPI document's components object.\n * Handles updates for HTTP, API Key, and OAuth2 types, saving secret information and configuration for UI-auth flows.\n *\n * @param document - The OpenAPI workspace document (can be null)\n * @param data - The update information, including type and payload\n * @param name - The name of the security scheme in document.components.securitySchemes\n *\n * Example usage:\n *\n * updateSecurityScheme({\n *   document,\n *   data: {\n *     type: 'http',\n *     payload: {\n *       username: 'user123',\n *       password: 'pw123',\n *       token: 'tokenval'\n *     }\n *   },\n *   name: 'MyHttpAuth',\n * })\n */\nexport const updateSecurityScheme = ({\n  document,\n  data,\n  name,\n}: {\n  document: WorkspaceDocument | null\n  data: SecuritySchemeUpdate\n  name: string\n}) => {\n  if (!document) {\n    return\n  }\n\n  const target = getResolvedRef(document.components?.securitySchemes?.[name])\n\n  if (!target) {\n    return\n  }\n\n  // Handle HTTP (basic, bearer, etc.)\n  if (target.type === 'http' && data.type === 'http') {\n    if (data.payload.username) {\n      target['x-scalar-secret-username'] = data.payload.username\n    }\n    if (data.payload.password) {\n      target['x-scalar-secret-password'] = data.payload.password\n    }\n    if (data.payload.token) {\n      target['x-scalar-secret-token'] = data.payload.token\n    }\n\n    // Handle API Key\n  } else if (target.type === 'apiKey' && data.type === 'apiKey') {\n    if (data.payload.name) {\n      target.name = data.payload.name\n    }\n    if (data.payload.value) {\n      target['x-scalar-secret-token'] = data.payload.value\n    }\n\n    // Handle OAuth2 (various flows)\n  } else if (target.type === 'oauth2' && data.type === 'oauth2') {\n    const flow = target.flows[data.flow]\n    if (!flow) {\n      // If the flow is not found, do nothing\n      return\n    }\n\n    if (data.payload.authUrl && 'authorizationUrl' in flow) {\n      flow.authorizationUrl = data.payload.authUrl\n    }\n    if (data.payload.tokenUrl && 'tokenUrl' in flow) {\n      flow.tokenUrl = data.payload.tokenUrl\n    }\n    if (data.payload.token && 'x-scalar-secret-token' in flow) {\n      flow['x-scalar-secret-token'] = data.payload.token\n    }\n    if (data.payload.redirectUrl && 'x-scalar-secret-redirect-uri' in flow) {\n      flow['x-scalar-secret-redirect-uri'] = data.payload.redirectUrl\n    }\n    if (data.payload.clientId && 'x-scalar-secret-client-id' in flow) {\n      flow['x-scalar-secret-client-id'] = data.payload.clientId\n    }\n    if (data.payload.clientSecret && 'x-scalar-secret-client-secret' in flow) {\n      flow['x-scalar-secret-client-secret'] = data.payload.clientSecret\n    }\n    if (data.payload.usePkce && 'x-usePkce' in flow) {\n      flow['x-usePkce'] = data.payload.usePkce\n    }\n    if (data.payload.username && 'x-scalar-secret-username' in flow) {\n      flow['x-scalar-secret-username'] = data.payload.username\n    }\n    if (data.payload.password && 'x-scalar-secret-password' in flow) {\n      flow['x-scalar-secret-password'] = data.payload.password\n    }\n  }\n\n  // TODO: handle openid connect type in the future\n\n  return\n}\n\n/**\n * Sets the selected authentication tab (scheme) index for the given OpenAPI document or operation.\n * - When on the document level, updates the 'x-selected-index' on the document's x-scalar-selected-security extension.\n * - When on an operation (endpoint) level, updates the 'x-selected-index' for that operation's x-scalar-selected-security.\n *\n * Also initializes the x-scalar-selected-security extension if it does not exist.\n *\n * @param document The OpenAPI document object (may be null)\n * @param index The index to set as selected\n * @param meta Context where the selection applies ('document' or specific operation)\n *\n * @example\n * // Document-level tab selection\n * updateSelectedAuthTab({\n *   document,\n *   index: 1,\n *   meta: { type: 'document' }\n * });\n *\n * // Operation-level tab selection (e.g., GET /pets)\n * updateSelectedAuthTab({\n *   document,\n *   index: 0,\n *   meta: { type: 'operation', path: '/pets', method: 'get' }\n * });\n */\nexport const updateSelectedAuthTab = ({\n  document,\n  index,\n  meta,\n}: {\n  document: WorkspaceDocument | null\n  index: number\n  meta: AuthMeta\n}) => {\n  if (!document) {\n    return\n  }\n\n  // Determine the target object for setting the auth tab index:\n  // - Document/root level\n  // - Operation/endpoint level (if meta specifies operation)\n  const getTarget = () => {\n    if (meta.type === 'document') {\n      return document\n    }\n    return getResolvedRef(document.paths?.[meta.path]?.[meta.method])\n  }\n\n  const target = getTarget()\n  if (!target) {\n    return\n  }\n\n  // Ensure the 'x-scalar-selected-security' extension exists\n  if (!target['x-scalar-selected-security']) {\n    target['x-scalar-selected-security'] = {\n      'x-selected-index': 0,\n      'x-schemes': [],\n    }\n  }\n\n  // Set the selected auth tab index\n  target['x-scalar-selected-security']['x-selected-index'] = index\n}\n\n/**\n * Updates the scopes for a specific security requirement in the selected security schemes of\n * a document or operation.\n *\n * @param document - The OpenAPI WorkspaceDocument to update.\n * @param id - An array of scheme names that uniquely identifies the target security requirement.\n *             For example: ['OAuth', 'ApiKeyAuth']\n * @param name - The security scheme name to update scopes for (e.g., 'OAuth').\n * @param scopes - The new list of scopes to set. For example: ['read:pets', 'write:pets']\n * @param meta - The context specifying whether the update is at the document-level or operation-level.\n *\n * Example usage:\n * ```ts\n * // Suppose your document (or operation) x-scalar-selected-security looks like:\n * // \"x-scalar-selected-security\": {\n * //   \"x-selected-index\": 0,\n * //   \"x-schemes\": [\n * //     { \"OAuth\": [\"read:pets\"] },\n * //     { \"ApiKeyAuth\": [] }\n * //   ]\n * // }\n *\n * updateSelectedScopes({\n *   document,\n *   id: [\"OAuth\"],     // identifies the scheme object: { \"OAuth\": [...] }\n *   name: \"OAuth\",     // scheme name to update within this security requirement\n *   scopes: [\"write:pets\"], // new scopes array\n *   meta: { type: \"document\" }\n * })\n * // After, the first scheme becomes: { \"OAuth\": [\"write:pets\"] }\n * ```\n */\nexport const updateSelectedScopes = ({\n  document,\n  id,\n  name,\n  scopes,\n  meta,\n}: {\n  document: WorkspaceDocument | null\n  id: string[]\n  name: string\n  scopes: string[]\n  meta: AuthMeta\n}) => {\n  if (!document) {\n    return\n  }\n\n  // Determine the target object (document or the operation)\n  const getTarget = () => {\n    if (meta.type === 'document') {\n      return document\n    }\n    return getResolvedRef(document.paths?.[meta.path]?.[meta.method])\n  }\n\n  const target = getTarget()\n\n  if (!target) {\n    return\n  }\n\n  // Array of security requirement objects under x-scalar-selected-security\n  const selectedSchemes = target['x-scalar-selected-security']?.['x-schemes']\n\n  if (!selectedSchemes) {\n    return\n  }\n\n  // Find the security requirement that matches the given id (scheme key names)\n  // For example: if id = [\"OAuth\"], matches { OAuth: [...] }\n  const scheme = selectedSchemes.find((scheme) => JSON.stringify(Object.keys(scheme)) === JSON.stringify(id))\n\n  if (!scheme) {\n    return\n  }\n\n  // Set the scopes array for the named security scheme within the found security requirement\n  scheme[name] = scopes\n}\n\n/**\n * Deletes one or more security schemes from an OpenAPI WorkspaceDocument,\n * and removes all references to those schemes from selected security, document-level security,\n * and operation-level security/selected security (e.g., on paths).\n *\n * Example usage:\n *\n * ```ts\n * deleteSecurityScheme({\n *   document,                                // The OpenAPI document to update\n *   names: ['ApiKeyAuth', 'BearerAuth'],     // The names of security schemes you want to delete\n * });\n * ```\n *\n * After running this function:\n * - The named security schemes are removed from the components.securitySchemes section.\n * - All document-level and operation-level security entries referencing those schemes are removed.\n * - Any extended x-scalar-selected-security references to those schemes are also removed.\n */\nexport const deleteSecurityScheme = ({ document, names }: { document: WorkspaceDocument | null; names: string[] }) => {\n  if (!document) {\n    // Early exit if there is no document to modify\n    return\n  }\n\n  // Get the mutable reference to securitySchemes in components (may be a proxy/resolved reference)\n  const target = getResolvedRef(document.components?.securitySchemes)\n\n  if (!target) {\n    // If there are no security schemes to delete from, return early\n    return\n  }\n\n  // Remove each named security scheme from the components.securitySchemes object\n  names.forEach((name) => {\n    delete target[name]\n  })\n\n  // Function to remove any security requirement objects that reference given scheme names.\n  const filterSecuritySchemes = (schemes: SecurityRequirementObject[]) => {\n    // Remove schemes whose key is included in the `names` to be deleted.\n    return schemes.filter((scheme) => !names.some((name) => Object.keys(scheme).includes(name)))\n  }\n\n  // -- Remove from document-level `x-scalar-selected-security` extension, if present\n  if (document['x-scalar-selected-security']) {\n    const selectedSecurity = document['x-scalar-selected-security']\n    selectedSecurity['x-schemes'] = filterSecuritySchemes(selectedSecurity['x-schemes'])\n  }\n\n  // -- Remove from document-level `security` property, if present\n  if (document['security']) {\n    document['security'] = filterSecuritySchemes(document['security'])\n  }\n\n  // -- For each path and operation, remove deleted security schemes from operation-level security and custom extension\n  Object.values(document.paths ?? {}).forEach((path) => {\n    Object.values(path).forEach((operation) => {\n      if (typeof operation !== 'object') {\n        // Ignore operations that are not objects (could be undefined)\n        return\n      }\n\n      // Get mutable reference for the operation (could resolve $ref proxies)\n      const resolvedOperation = getResolvedRef(operation)\n\n      // Remove from operation-level security array\n      if ('security' in resolvedOperation && resolvedOperation['security']) {\n        resolvedOperation['security'] = filterSecuritySchemes(resolvedOperation['security'])\n      }\n\n      // Remove from operation-level x-scalar-selected-security array\n      if ('x-scalar-selected-security' in resolvedOperation && resolvedOperation['x-scalar-selected-security']) {\n        resolvedOperation['x-scalar-selected-security']['x-schemes'] = filterSecuritySchemes(\n          resolvedOperation['x-scalar-selected-security']['x-schemes'],\n        )\n      }\n    })\n  })\n}\n"],
+  "mappings": "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",
+  "names": ["scheme"]
+}

package/dist/mutators/environment.d.ts

@@ -1,17 +1,25 @@
-import type { UnknownObject } from '../helpers/general.js';
-import type { XScalarClientConfigEnvironments, xScalarClientConfigEnvironment } from '../schemas/v3.1/strict/client-config-extensions/x-scalar-client-config-environments.js';
+import type { EnvironmentEvents } from '../events/definitions/environment.js';
+import type { Workspace, WorkspaceDocument } from '../schemas.js';
+import { type XScalarEnvVar, type XScalarEnvironment } from '../schemas/extensions/document/x-scalar-environments.js';
 /**
- * Environment mutators for managing client configuration environments in OpenAPI documents.
- * Provides functions to add and delete environments from the document's x-scalar-client-config-environments extension.
+ * Adds OR updates an environment to the document or workspace.
  *
- * @param store - The workspace store containing the documents
- * @param documentName - The name of the document to operate on
- * @returns Object containing addEnvironment and deleteEnvironment functions
+ * @param document - current document if available
+ * @param workspace - current workspace if available
+ * @param environmentName - Name of the environment to add
+ * @param payload - The environment configuration to add
+ * @param oldEnvironmentName - Only needed when renaming the environment
+ * @returns the parsed environment that was added or updated or undefined if the collection is not found
  */
-export declare const environmentMutators: (document?: UnknownObject & {
-    "x-scalar-client-config-environments"?: XScalarClientConfigEnvironments;
-}) => {
-    addEnvironment: (name: string, environment: xScalarClientConfigEnvironment) => boolean;
-    deleteEnvironment: (environmentName: string) => boolean;
-};
+export declare const upsertEnvironment: (document: WorkspaceDocument | null, workspace: Workspace, { environmentName, payload, collectionType, oldEnvironmentName }: EnvironmentEvents["environment:upsert:environment"]) => XScalarEnvironment | undefined;
+/**
+ * Adds OR updates an environment variable to the document or workspace.
+ *
+ * @param collection - Workspace OR document
+ * @param environmentName - Name of the environment to add the variable to
+ * @param variableName - Name of the variable to add
+ * @param value - Value of the variable to add
+ * @returns the parsed variable that was added or updated or undefined if the collection is not found
+ */
+export declare const upsertEnvironmentVariable: (collection: WorkspaceDocument | Workspace | null, { environmentName, variable, index }: EnvironmentEvents["environment:upsert:environment-variable"]) => XScalarEnvVar | undefined;
 //# sourceMappingURL=environment.d.ts.map

package/dist/mutators/environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/mutators/environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EACV,+BAA+B,EAC/B,8BAA8B,EAC/B,MAAM,oFAAoF,CAAA;AAE3F;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,WAAW,aAAa,GAAG;IAAE,qCAAqC,CAAC,EAAE,+BAA+B,CAAA;CAAE;2BAsBxE,MAAM,eAAe,8BAA8B;yCA6BrC,MAAM;CAanD,CAAA"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/mutators/environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAGxB,MAAM,qDAAqD,CAAA;AAG5D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,WAAW,SAAS,EACpB,kEAAkE,iBAAiB,CAAC,gCAAgC,CAAC,KACpH,kBAAkB,GAAG,SAqCvB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACpC,YAAY,iBAAiB,GAAG,SAAS,GAAG,IAAI,EAChD,sCAAsC,iBAAiB,CAAC,yCAAyC,CAAC,KACjG,aAAa,GAAG,SA0BlB,CAAA"}