@scalar/api-reference 1.41.1 → 1.43.0

package/dist/helpers/storage.d.ts

@@ -0,0 +1,347 @@
+import { type XScalarSelectedSecurity } from '@scalar/workspace-store/schemas/extensions/security/x-scalar-selected-security';
+import { type SecuritySchemes } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+/**
+ * Provides an interface to store and retrieve the selected client value
+ * in local storage.
+ */
+export declare const clientStorage: () => {
+    /**
+     * Gets the stored selected client from local storage.
+     */
+    get: () => string | null;
+    /**
+     * Stores the selected client value in local storage.
+     * @param value The value to store
+     */
+    set: (value: string) => void;
+};
+/**
+ * Provides an interface to store and retrieve authentication scheme
+ * information in local storage, including both the available schemes and
+ * the user's selected schemes.
+ */
+export declare const authStorage: () => {
+    /**
+     * Retrieves and coerces the authentication schemes stored in local storage.
+     */
+    getSchemas: () => {
+        [x: string]: ({
+            description?: string | undefined;
+        } & {
+            'x-scalar-secret-token': string;
+        } & {
+            type: "apiKey";
+            name: string;
+            in: "header" | "query" | "cookie";
+        }) | ({
+            description?: string | undefined;
+        } & {
+            'x-scalar-secret-token': string;
+        } & {
+            'x-scalar-secret-username': string;
+            'x-scalar-secret-password': string;
+        } & {
+            bearerFormat?: string | undefined;
+            type: "http";
+            scheme: "basic" | "bearer";
+        }) | ({
+            description?: string | undefined;
+        } & {
+            type: "oauth2";
+            flows: {
+                password?: ({
+                    refreshUrl: string;
+                    scopes: {
+                        [x: string]: string;
+                    };
+                } & {
+                    'x-scalar-secret-client-id': string;
+                } & {
+                    'x-scalar-secret-token': string;
+                } & {
+                    'x-scalar-security-query'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-scalar-security-body'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-tokenName'?: string | undefined;
+                } & {
+                    'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                } & {
+                    tokenUrl: string;
+                } & {
+                    'x-scalar-secret-username': string;
+                    'x-scalar-secret-password': string;
+                } & {
+                    'x-scalar-secret-client-secret': string;
+                }) | undefined;
+                implicit?: ({
+                    refreshUrl: string;
+                    scopes: {
+                        [x: string]: string;
+                    };
+                } & {
+                    'x-scalar-secret-client-id': string;
+                } & {
+                    'x-scalar-secret-token': string;
+                } & {
+                    'x-scalar-security-query'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-scalar-security-body'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-tokenName'?: string | undefined;
+                } & {
+                    'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                } & {
+                    authorizationUrl: string;
+                } & {
+                    'x-scalar-secret-redirect-uri': string;
+                }) | undefined;
+                clientCredentials?: ({
+                    refreshUrl: string;
+                    scopes: {
+                        [x: string]: string;
+                    };
+                } & {
+                    'x-scalar-secret-client-id': string;
+                } & {
+                    'x-scalar-secret-token': string;
+                } & {
+                    'x-scalar-security-query'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-scalar-security-body'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-tokenName'?: string | undefined;
+                } & {
+                    'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                } & {
+                    tokenUrl: string;
+                } & {
+                    'x-scalar-secret-client-secret': string;
+                }) | undefined;
+                authorizationCode?: ({
+                    refreshUrl: string;
+                    scopes: {
+                        [x: string]: string;
+                    };
+                } & {
+                    'x-scalar-secret-client-id': string;
+                } & {
+                    'x-scalar-secret-token': string;
+                } & {
+                    'x-scalar-security-query'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-scalar-security-body'?: {
+                        [x: string]: string;
+                    } | undefined;
+                } & {
+                    'x-tokenName'?: string | undefined;
+                } & {
+                    'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                } & {
+                    authorizationUrl: string;
+                    tokenUrl: string;
+                } & {
+                    'x-scalar-secret-client-secret': string;
+                } & {
+                    'x-scalar-secret-redirect-uri': string;
+                } & {
+                    'x-usePkce': "SHA-256" | "plain" | "no";
+                }) | undefined;
+            };
+        } & {
+            'x-default-scopes'?: string[] | undefined;
+        }) | ({
+            description?: string | undefined;
+        } & {
+            type: "openIdConnect";
+            openIdConnectUrl: string;
+        }) | ({
+            summary?: string | undefined;
+            description?: string | undefined;
+            $ref: string;
+        } & {
+            $status?: "loading" | "error" | undefined;
+            $global?: boolean | undefined;
+        } & {
+            '$ref-value': ({
+                description?: string | undefined;
+            } & {
+                'x-scalar-secret-token': string;
+            } & {
+                type: "apiKey";
+                name: string;
+                in: "header" | "query" | "cookie";
+            }) | ({
+                description?: string | undefined;
+            } & {
+                'x-scalar-secret-token': string;
+            } & {
+                'x-scalar-secret-username': string;
+                'x-scalar-secret-password': string;
+            } & {
+                bearerFormat?: string | undefined;
+                type: "http";
+                scheme: "basic" | "bearer";
+            }) | ({
+                description?: string | undefined;
+            } & {
+                type: "oauth2";
+                flows: {
+                    password?: ({
+                        refreshUrl: string;
+                        scopes: {
+                            [x: string]: string;
+                        };
+                    } & {
+                        'x-scalar-secret-client-id': string;
+                    } & {
+                        'x-scalar-secret-token': string;
+                    } & {
+                        'x-scalar-security-query'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-scalar-security-body'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-tokenName'?: string | undefined;
+                    } & {
+                        'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                    } & {
+                        tokenUrl: string;
+                    } & {
+                        'x-scalar-secret-username': string;
+                        'x-scalar-secret-password': string;
+                    } & {
+                        'x-scalar-secret-client-secret': string;
+                    }) | undefined;
+                    implicit?: ({
+                        refreshUrl: string;
+                        scopes: {
+                            [x: string]: string;
+                        };
+                    } & {
+                        'x-scalar-secret-client-id': string;
+                    } & {
+                        'x-scalar-secret-token': string;
+                    } & {
+                        'x-scalar-security-query'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-scalar-security-body'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-tokenName'?: string | undefined;
+                    } & {
+                        'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                    } & {
+                        authorizationUrl: string;
+                    } & {
+                        'x-scalar-secret-redirect-uri': string;
+                    }) | undefined;
+                    clientCredentials?: ({
+                        refreshUrl: string;
+                        scopes: {
+                            [x: string]: string;
+                        };
+                    } & {
+                        'x-scalar-secret-client-id': string;
+                    } & {
+                        'x-scalar-secret-token': string;
+                    } & {
+                        'x-scalar-security-query'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-scalar-security-body'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-tokenName'?: string | undefined;
+                    } & {
+                        'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                    } & {
+                        tokenUrl: string;
+                    } & {
+                        'x-scalar-secret-client-secret': string;
+                    }) | undefined;
+                    authorizationCode?: ({
+                        refreshUrl: string;
+                        scopes: {
+                            [x: string]: string;
+                        };
+                    } & {
+                        'x-scalar-secret-client-id': string;
+                    } & {
+                        'x-scalar-secret-token': string;
+                    } & {
+                        'x-scalar-security-query'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-scalar-security-body'?: {
+                            [x: string]: string;
+                        } | undefined;
+                    } & {
+                        'x-tokenName'?: string | undefined;
+                    } & {
+                        'x-scalar-credentials-location'?: "body" | "header" | undefined;
+                    } & {
+                        authorizationUrl: string;
+                        tokenUrl: string;
+                    } & {
+                        'x-scalar-secret-client-secret': string;
+                    } & {
+                        'x-scalar-secret-redirect-uri': string;
+                    } & {
+                        'x-usePkce': "SHA-256" | "plain" | "no";
+                    }) | undefined;
+                };
+            } & {
+                'x-default-scopes'?: string[] | undefined;
+            }) | ({
+                description?: string | undefined;
+            } & {
+                type: "openIdConnect";
+                openIdConnectUrl: string;
+            });
+        });
+    };
+    /**
+     * Stores the authentication schemes in local storage.
+     * @param value The SecuritySchemes object to stringify and store.
+     */
+    setSchemas: (prefix: string, value: SecuritySchemes) => void;
+    /**
+     * Retrieves and coerces the selected authentication schemes stored in local storage.
+     */
+    getSelectedSchemes: () => {
+        'x-scalar-selected-security'?: {
+            selectedIndex: number;
+            selectedSchemes: unknown[];
+        } | undefined;
+    };
+    /**
+     * Stores the user's selected authentication schemes in local storage.
+     * @param value The XScalarSelectedSecurity object to stringify and store.
+     */
+    setSelectedSchemes: (prefix: string, value: XScalarSelectedSecurity) => void;
+};
+//# sourceMappingURL=storage.d.ts.map

package/dist/helpers/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/helpers/storage.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,gFAAgF,CAAA;AAEvF,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,8DAA8D,CAAA;AAKrE;;;GAGG;AACH,eAAO,MAAM,aAAa;IAGtB;;OAEG;;IAIH;;;OAGG;iBACU,MAAM;CAItB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW;IAIpB;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAKH;;;OAGG;yBACkB,MAAM,SAAS,eAAe;IAGnD;;OAEG;;;;;;;IAKH;;;OAGG;iCAC0B,MAAM,SAAS,uBAAuB;CAItE,CAAA"}

package/dist/helpers/storage.js

@@ -0,0 +1,61 @@
+import { REFERENCE_LS_KEYS, safeLocalStorage } from "@scalar/helpers/object/local-storage";
+import { XScalarSelectedSecuritySchema } from "@scalar/workspace-store/schemas/extensions/security/x-scalar-selected-security";
+import { coerceValue } from "@scalar/workspace-store/schemas/typebox-coerce";
+import { SecuritySchemesSchema } from "@scalar/workspace-store/schemas/v3.1/strict/openapi-document";
+const storage = safeLocalStorage();
+const clientStorage = () => {
+  const key = REFERENCE_LS_KEYS.SELECTED_CLIENT;
+  return {
+    /**
+     * Gets the stored selected client from local storage.
+     */
+    get: () => {
+      return storage.getItem(key);
+    },
+    /**
+     * Stores the selected client value in local storage.
+     * @param value The value to store
+     */
+    set: (value) => {
+      storage.setItem(key, value);
+    }
+  };
+};
+const authStorage = () => {
+  const schemasKey = REFERENCE_LS_KEYS.AUTH_SCHEMES;
+  const selectedSchemesKey = REFERENCE_LS_KEYS.SELECTED_AUTH_SCHEMES;
+  return {
+    /**
+     * Retrieves and coerces the authentication schemes stored in local storage.
+     */
+    getSchemas: () => {
+      const parsed = JSON.parse(storage.getItem(schemasKey) ?? "{}");
+      return coerceValue(SecuritySchemesSchema, parsed);
+    },
+    /**
+     * Stores the authentication schemes in local storage.
+     * @param value The SecuritySchemes object to stringify and store.
+     */
+    setSchemas: (prefix, value) => {
+      storage.setItem(`${prefix}-schemasKey`, JSON.stringify(value));
+    },
+    /**
+     * Retrieves and coerces the selected authentication schemes stored in local storage.
+     */
+    getSelectedSchemes: () => {
+      const parsed = JSON.parse(storage.getItem(selectedSchemesKey) ?? "{}");
+      return coerceValue(XScalarSelectedSecuritySchema, parsed);
+    },
+    /**
+     * Stores the user's selected authentication schemes in local storage.
+     * @param value The XScalarSelectedSecurity object to stringify and store.
+     */
+    setSelectedSchemes: (prefix, value) => {
+      storage.setItem(`${prefix}-selectedSchemesKey`, JSON.stringify(value));
+    }
+  };
+};
+export {
+  authStorage,
+  clientStorage
+};

package/dist/hooks/index.d.ts

@@ -1,4 +1,2 @@
 export { useIntersection } from './use-intersection.js';
-export { useLegacyStoreEvents } from './use-legacy-store-events.js';
-export { useWorkspaceStoreEvents } from './use-workspace-store-events.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/hooks/index.js

@@ -1,8 +1,4 @@
 import { useIntersection } from "./use-intersection.js";
-import { useLegacyStoreEvents } from "./use-legacy-store-events.js";
-import { useWorkspaceStoreEvents } from "./use-workspace-store-events.js";
 export {
-  useIntersection,
-  useLegacyStoreEvents,
-  useWorkspaceStoreEvents
+  useIntersection
 };

package/dist/index.d.ts

@@ -4,7 +4,6 @@ export { default as ApiReference } from './components/ApiReference.vue.js';
 export { default as GettingStarted } from './components/GettingStarted.vue.js';
 export { SearchButton, SearchModal } from './features/Search';
 export { createEmptySpecification } from './helpers/openapi.js';
-export { useWorkspaceStoreEvents } from './hooks/use-workspace-store-events.js';
 export { createApiReference } from './standalone/lib/html-api.js';
 export type ReferenceProps = {
     configuration?: AnyApiReferenceConfiguration;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAE/E,YAAY,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAE5E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAC3E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAA;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,CAAC,EAAE,4BAA4B,CAAA;CAC7C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAE/E,YAAY,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAE5E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAC3E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,CAAC,EAAE,4BAA4B,CAAA;CAC7C,CAAA"}

package/dist/index.js

@@ -1,7 +1,6 @@
 import { default as default2 } from "./components/ApiReference.vue.js";
 import { default as default3 } from "./components/GettingStarted.vue.js";
 import { createEmptySpecification } from "./helpers/openapi.js";
-import { useWorkspaceStoreEvents } from "./hooks/use-workspace-store-events.js";
 import { createApiReference } from "./standalone/lib/html-api.js";
 import { default as default4 } from "./features/Search/components/SearchButton.vue.js";
 import { default as default5 } from "./features/Search/components/SearchModal.vue.js";
@@ -11,6 +10,5 @@ export {
   default4 as SearchButton,
   default5 as SearchModal,
   createApiReference,
-  createEmptySpecification,
-  useWorkspaceStoreEvents
+  createEmptySpecification
 };

package/dist/plugins/persistance-plugin.d.ts

@@ -0,0 +1,16 @@
+import type { WorkspacePlugin } from '@scalar/workspace-store/workspace-plugin';
+/**
+ * Plugin to persist workspace state changes with debounced writes.
+ */
+export declare const persistencePlugin: ({ debounceDelay, maxWait, prefix, }: {
+    debounceDelay?: number;
+    /** Maximum time in milliseconds to wait before forcing execution, even with continuous calls. */
+    maxWait?: number;
+    /**
+     * Prefix to use for local storage keys.
+     * This can be a string or a function returning a string.
+     * For example, to persist data per document, use the document name as the prefix.
+     */
+    prefix?: string | (() => string);
+}) => WorkspacePlugin;
+//# sourceMappingURL=persistance-plugin.d.ts.map

package/dist/plugins/persistance-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistance-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/persistance-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAI/E;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,qCAI/B;IACD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;CACjC,KAAG,eA8DH,CAAA"}

package/dist/plugins/persistance-plugin.js

@@ -0,0 +1,54 @@
+import { debounce } from "@scalar/helpers/general/debounce";
+import { authStorage, clientStorage } from "../helpers/storage.js";
+const persistencePlugin = ({
+  debounceDelay = 500,
+  maxWait = 1e4,
+  prefix = ""
+}) => {
+  const { execute } = debounce({ delay: debounceDelay, maxWait });
+  const authPersistence = authStorage();
+  const clientPersistence = clientStorage();
+  const getPrefix = () => {
+    if (typeof prefix === "string") {
+      return prefix;
+    }
+    return prefix();
+  };
+  return {
+    hooks: {
+      /**
+       * Handles all workspace state change events.
+       * Each write is debounced by a key to prevent frequent writes for the same entity.
+       */
+      onWorkspaceStateChanges(event) {
+        if (event.type === "meta") {
+          const defaultClient = event.value["x-scalar-default-client"];
+          if (defaultClient !== void 0) {
+            execute("x-scalar-default-client", () => clientPersistence.set(defaultClient));
+          }
+          return;
+        }
+        if (event.type === "documents") {
+          const { path, value: document } = event;
+          const { securitySchemes = {} } = document.components ?? {};
+          if (path[0] === "components" && path[1] === "securitySchemes") {
+            execute("x-scalar-security-schemes", () => authPersistence.setSchemas(getPrefix(), securitySchemes));
+          }
+          const selectedSecurity = document["x-scalar-selected-security"];
+          if (path[0] === "x-scalar-selected-security" && selectedSecurity) {
+            execute(
+              "x-scalar-selected-security-schemes",
+              () => authPersistence.setSelectedSchemes(getPrefix(), {
+                "x-scalar-selected-security": selectedSecurity
+              })
+            );
+          }
+        }
+        return;
+      }
+    }
+  };
+};
+export {
+  persistencePlugin
+};