@scalar/types 0.0.36 → 0.0.39

package/dist/api-reference/api-reference-configuration.js

@@ -0,0 +1,335 @@
+import { z } from 'zod';
+import { migrateThemeVariables } from './helpers/migrate-theme-variables.js';
+
+/** Available theme presets for the API reference */
+const themeIdEnum = z.enum([
+    'alternate',
+    'default',
+    'moon',
+    'purple',
+    'solarized',
+    'bluePlanet',
+    'deepSpace',
+    'saturn',
+    'kepler',
+    'elysiajs',
+    'fastify',
+    'mars',
+    'none',
+]);
+/** Valid keys that can be used with CTRL/CMD to open the search modal */
+const searchHotKeyEnum = z.enum([
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+    'g',
+    'h',
+    'i',
+    'j',
+    'k',
+    'l',
+    'm',
+    'n',
+    'o',
+    'p',
+    'q',
+    'r',
+    's',
+    't',
+    'u',
+    'v',
+    'w',
+    'x',
+    'y',
+    'z',
+]);
+/** Supported integration types */
+const integrationEnum = z
+    .enum([
+    'adonisjs',
+    'docusaurus',
+    'dotnet',
+    'elysiajs',
+    'express',
+    'fastapi',
+    'fastify',
+    'go',
+    'hono',
+    'html',
+    'laravel',
+    'litestar',
+    'nestjs',
+    'nextjs',
+    'nitro',
+    'nuxt',
+    'platformatic',
+    'react',
+    'rust',
+    'vue',
+])
+    .nullable();
+/** Configuration for the OpenAPI/Swagger specification */
+const specConfigurationSchema = z.object({
+    /** URL to an OpenAPI/Swagger document */
+    url: z.string().optional(),
+    /**
+     * Directly embed the OpenAPI document.
+     * Can be a string, object, function returning an object, or null.
+     * @remarks It's recommended to pass a URL instead of content.
+     */
+    content: z.union([z.string(), z.record(z.any()), z.function().returns(z.record(z.any())), z.null()]).optional(),
+});
+/** Configuration for path-based routing */
+const pathRoutingSchema = z.object({
+    /** Base path for the API reference */
+    basePath: z.string(),
+});
+/** Configuration for the Api Client */
+const apiClientConfigurationSchema = z.object({
+    /** Prefill authentication */
+    authentication: z.any().optional(), // Temp until we bring in the new auth
+    /** Base URL for the API server */
+    baseServerURL: z.string().optional(),
+    /**
+     * Whether to hide the client button
+     * @default false
+     */
+    hideClientButton: z.boolean().optional().default(false).catch(false),
+    /** URL to a request proxy for the API client */
+    proxyUrl: z.string().optional(),
+    /** Key used with CTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k) */
+    searchHotKey: searchHotKeyEnum.optional(),
+    /** List of OpenAPI server objects */
+    servers: z.array(z.any()).optional(), // Using any for OpenAPIV3_1.ServerObject
+    /**
+     * Whether to show the sidebar
+     * @default true
+     */
+    showSidebar: z.boolean().optional().default(true).catch(true),
+    /** The Swagger/OpenAPI spec to render */
+    spec: specConfigurationSchema.optional(),
+    /** A string to use one of the color presets */
+    theme: themeIdEnum.optional().default('default').catch('default'),
+    /** Integration type identifier */
+    _integration: integrationEnum.optional(),
+});
+const OLD_PROXY_URL = 'https://api.scalar.com/request-proxy';
+const NEW_PROXY_URL = 'https://proxy.scalar.com';
+/** Configuration for the Api Reference */
+const apiReferenceConfigurationSchema = apiClientConfigurationSchema
+    .merge(z.object({
+    /**
+     * The layout to use for the references
+     * @default 'modern'
+     */
+    layout: z.enum(['modern', 'classic']).optional().default('modern').catch('modern'),
+    /**
+     * URL to a request proxy for the API client
+     * @deprecated Use proxyUrl instead
+     */
+    proxy: z.string().optional(),
+    /**
+     * Whether the spec input should show
+     * @default false
+     */
+    isEditable: z.boolean().optional().default(false).catch(false),
+    /**
+     * Whether to show models in the sidebar, search, and content.
+     * @default false
+     */
+    hideModels: z.boolean().optional().default(false).catch(false),
+    /**
+     * Whether to show the "Download OpenAPI Document" button
+     * @default false
+     */
+    hideDownloadButton: z.boolean().optional().default(false).catch(false),
+    /**
+     * Whether to show the "Test Request" button
+     * @default false
+     */
+    hideTestRequestButton: z.boolean().optional().default(false).catch(false),
+    /**
+     * Whether to show the sidebar search bar
+     * @default false
+     */
+    hideSearch: z.boolean().optional().default(false).catch(false),
+    /** Whether dark mode is on or off initially (light mode) */
+    darkMode: z.boolean().optional(),
+    /** forceDarkModeState makes it always this state no matter what */
+    forceDarkModeState: z.enum(['dark', 'light']).optional(),
+    /**
+     * Whether to show the dark mode toggle
+     * @default false
+     */
+    hideDarkModeToggle: z.boolean().optional().default(false).catch(false),
+    /**
+     * If used, passed data will be added to the HTML header
+     * @see https://unhead.unjs.io/usage/composables/use-seo-meta
+     */
+    metaData: z.any().optional(), // Using any for UseSeoMetaInput since it's an external type
+    /**
+     * Path to a favicon image
+     * @default undefined
+     * @example '/favicon.svg'
+     */
+    favicon: z.string().optional(),
+    /**
+     * List of httpsnippet clients to hide from the clients menu
+     * By default hides Unirest, pass `[]` to show all clients
+     */
+    hiddenClients: z
+        .union([z.record(z.union([z.boolean(), z.array(z.string())])), z.array(z.string()), z.literal(true)])
+        .optional(),
+    /** Determine the HTTP client that's selected by default */
+    defaultHttpClient: z
+        .object({
+        targetKey: z.custom(),
+        clientKey: z.string(),
+    })
+        .optional(),
+    /** Custom CSS to be added to the page */
+    customCss: z.string().optional(),
+    /** onSpecUpdate is fired on spec/swagger content change */
+    onSpecUpdate: z.function().args(z.string()).returns(z.void()).optional(),
+    /** onServerChange is fired on selected server change */
+    onServerChange: z.function().args(z.string()).returns(z.void()).optional(),
+    /**
+     * Route using paths instead of hashes, your server MUST support this
+     * @example '/standalone-api-reference/:custom(.*)?'
+     * @experimental
+     * @default undefined
+     */
+    pathRouting: pathRoutingSchema.optional(),
+    /**
+     * Customize the heading portion of the hash
+     * @param heading - The heading object
+     * @returns A string ID used to generate the URL hash
+     * @default (heading) => `#description/${heading.slug}`
+     */
+    generateHeadingSlug: z
+        .function()
+        .args(z.object({ slug: z.string().default('headingSlug') }))
+        .returns(z.string())
+        .optional(),
+    /**
+     * Customize the model portion of the hash
+     * @param model - The model object with a name property
+     * @returns A string ID used to generate the URL hash
+     * @default (model) => slug(model.name)
+     */
+    generateModelSlug: z
+        .function()
+        .args(z.object({ name: z.string().default('modelName') }))
+        .returns(z.string())
+        .optional(),
+    /**
+     * Customize the tag portion of the hash
+     * @param tag - The tag object
+     * @returns A string ID used to generate the URL hash
+     * @default (tag) => slug(tag.name)
+     */
+    generateTagSlug: z
+        .function()
+        .args(z.object({ name: z.string().default('tagName') }))
+        .returns(z.string())
+        .optional(),
+    /**
+     * Customize the operation portion of the hash
+     * @param operation - The operation object
+     * @returns A string ID used to generate the URL hash
+     * @default (operation) => `${operation.method}${operation.path}`
+     */
+    generateOperationSlug: z
+        .function()
+        .args(z.object({
+        path: z.string(),
+        operationId: z.string().optional(),
+        method: z.string(),
+        summary: z.string().optional(),
+    }))
+        .returns(z.string())
+        .optional(),
+    /**
+     * Customize the webhook portion of the hash
+     * @param webhook - The webhook object
+     * @returns A string ID used to generate the URL hash
+     * @default (webhook) => slug(webhook.name)
+     */
+    generateWebhookSlug: z
+        .function()
+        .args(z.object({
+        name: z.string(),
+        method: z.string().optional(),
+    }))
+        .returns(z.string())
+        .optional(),
+    /** Callback fired when the reference is fully loaded */
+    onLoaded: z.union([z.function().returns(z.void()), z.undefined()]).optional(),
+    /**
+     * To handle redirects, pass a function that will recieve:
+     * - The current path with hash if pathRouting is enabled
+     * - The current hash if hashRouting (default)
+     * And then passes that to history.replaceState
+     *
+     * @example hashRouting (default)
+     * ```ts
+     * redirect: (hash: string) => hash.replace('#v1/old-path', '#v2/new-path')
+     * ```
+     * @example pathRouting
+     * ```ts
+     * redirect: (pathWithHash: string) => {
+     *   if (pathWithHash.includes('#')) {
+     *     return pathWithHash.replace('/v1/tags/user#operation/get-user', '/v1/tags/user/operation/get-user')
+     *   }
+     *   return null
+     * }
+     * ```
+     */
+    redirect: z.function().args(z.string()).returns(z.string().nullable().optional()).optional(),
+    /**
+     * Whether to include default fonts
+     * @default true
+     */
+    withDefaultFonts: z.boolean().optional().default(true).catch(true),
+    /** Whether to expand all tags by default */
+    defaultOpenAllTags: z.boolean().optional(),
+    /**
+     * Function to sort tags
+     * @default 'alpha' for alphabetical sorting
+     */
+    tagsSorter: z.union([z.literal('alpha'), z.function().args(z.any(), z.any()).returns(z.number())]).optional(),
+    /**
+     * Function to sort operations
+     * @default 'alpha' for alphabetical sorting
+     */
+    operationsSorter: z
+        .union([z.literal('alpha'), z.literal('method'), z.function().args(z.any(), z.any()).returns(z.number())])
+        .optional(),
+}))
+    .transform((_configuration) => {
+    const configuration = { ..._configuration };
+    // Migrate legacy theme variables
+    if (configuration.customCss) {
+        configuration.customCss = migrateThemeVariables(configuration.customCss);
+    }
+    // Migrate proxy URL
+    if (configuration.proxy) {
+        console.warn(`[DEPRECATED] You’re using the deprecated 'proxy' attribute, rename it to 'proxyUrl' or update the package.`);
+        if (!configuration.proxyUrl) {
+            configuration.proxyUrl = configuration.proxy;
+        }
+        delete configuration.proxy;
+    }
+    if (configuration.proxyUrl === OLD_PROXY_URL) {
+        console.warn(`[DEPRECATED] Warning: configuration.proxyUrl points to our old proxy (${OLD_PROXY_URL}).`);
+        console.warn(`[DEPRECATED] We are overwriting the value and use the new proxy URL (${NEW_PROXY_URL}) instead.`);
+        console.warn(`[DEPRECATED] Action Required: You should manually update your configuration to use the new URL (${NEW_PROXY_URL}). Read more: https://github.com/scalar/scalar`);
+        configuration.proxyUrl = NEW_PROXY_URL;
+    }
+    return configuration;
+});
+
+export { apiClientConfigurationSchema, apiReferenceConfigurationSchema };

package/dist/api-reference/api-reference-configuration.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-reference-configuration.test-d.d.ts.map

package/dist/api-reference/api-reference-configuration.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-reference-configuration.test-d.d.ts","sourceRoot":"","sources":["../../src/api-reference/api-reference-configuration.test-d.ts"],"names":[],"mappings":""}

package/dist/api-reference/helpers/migrate-theme-variables.d.ts

@@ -0,0 +1,10 @@
+/** The legacy -> updated CSS variable prefix pairs */
+export declare const PREFIX_MIGRATIONS: readonly [readonly ["--theme-", "--scalar-"], readonly ["--sidebar-", "--scalar-sidebar-"]];
+export declare const LEGACY_PREFIXES: ("--theme-" | "--sidebar-")[];
+/**
+ * Checks a style string for legacy theme variables and updated them to the new theme variables
+ *
+ * @param styles the style string to be checked for legacy theme variables and updated
+ */
+export declare function migrateThemeVariables(styles: string): string;
+//# sourceMappingURL=migrate-theme-variables.d.ts.map

package/dist/api-reference/helpers/migrate-theme-variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-theme-variables.d.ts","sourceRoot":"","sources":["../../../src/api-reference/helpers/migrate-theme-variables.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,6FAGpB,CAAA;AAEV,eAAO,MAAM,eAAe,+BAA8C,CAAA;AAE1E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/dist/api-reference/helpers/migrate-theme-variables.js

@@ -0,0 +1,21 @@
+/** The legacy -> updated CSS variable prefix pairs */
+const PREFIX_MIGRATIONS = [
+    ['--theme-', '--scalar-'],
+    ['--sidebar-', '--scalar-sidebar-'],
+];
+const LEGACY_PREFIXES = PREFIX_MIGRATIONS.map(([legacy]) => legacy);
+/**
+ * Checks a style string for legacy theme variables and updated them to the new theme variables
+ *
+ * @param styles the style string to be checked for legacy theme variables and updated
+ */
+function migrateThemeVariables(styles) {
+    const hasLegacyPrefixes = LEGACY_PREFIXES.some((p) => styles.includes(p));
+    if (!hasLegacyPrefixes)
+        return styles;
+    console.warn(`DEPRECATION WARNING: It looks like you're using legacy CSS variables in your custom CSS string. Please migrate them to use the updated prefixes. See https://github.com/scalar/scalar/blob/main/documentation/themes.md#theme-prefix-changes`);
+    // Replaces each old variable in the prefix migrations
+    return PREFIX_MIGRATIONS.reduce((s, [o, n]) => s.replaceAll(o, n), styles);
+}
+
+export { LEGACY_PREFIXES, PREFIX_MIGRATIONS, migrateThemeVariables };

package/dist/api-reference/html-rendering-configuration.d.ts

@@ -0,0 +1,34 @@
+import type { ApiReferenceConfiguration } from '../api-reference/api-reference-configuration.ts';
+import { z } from 'zod';
+/**
+ * Zod schema for HTML rendering configuration
+ */
+export declare const htmlRenderingConfigurationSchema: z.ZodObject<{
+    /**
+     * The URL to the Scalar API Reference JS CDN.
+     *
+     * Use this to pin a specific version of the Scalar API Reference.
+     *
+     * @default https://cdn.jsdelivr.net/npm/@scalar/api-reference
+     *
+     * @example https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.122
+     */
+    cdn: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    /**
+     * The title of the page.
+     */
+    pageTitle: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    cdn: string;
+    pageTitle: string;
+}, {
+    cdn?: string | undefined;
+    pageTitle?: string | undefined;
+}>;
+/**
+ * The configuration for the static HTML rendering using the CDN.
+ *
+ * It’s the ApiReferenceConfiguration, but extended with the `pageTitle` and `cdn` options.
+ */
+export type HtmlRenderingConfiguration = ApiReferenceConfiguration & z.infer<typeof htmlRenderingConfigurationSchema>;
+//# sourceMappingURL=html-rendering-configuration.d.ts.map

package/dist/api-reference/html-rendering-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-rendering-configuration.d.ts","sourceRoot":"","sources":["../../src/api-reference/html-rendering-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gDAAgD,CAAA;AAC/F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;GAEG;AACH,eAAO,MAAM,gCAAgC;IAC3C;;;;;;;;OAQG;;IAEH;;OAEG;;;;;;;;EAEH,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAA"}

package/dist/api-reference/html-rendering-configuration.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for HTML rendering configuration
+ */
+const htmlRenderingConfigurationSchema = z.object({
+    /**
+     * The URL to the Scalar API Reference JS CDN.
+     *
+     * Use this to pin a specific version of the Scalar API Reference.
+     *
+     * @default https://cdn.jsdelivr.net/npm/@scalar/api-reference
+     *
+     * @example https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.122
+     */
+    cdn: z.string().optional().default('https://cdn.jsdelivr.net/npm/@scalar/api-reference'),
+    /**
+     * The title of the page.
+     */
+    pageTitle: z.string().optional().default('Scalar API Reference'),
+});
+
+export { htmlRenderingConfigurationSchema };

package/dist/api-reference/index.d.ts

@@ -0,0 +1,4 @@
+export * from './api-reference-configuration.ts';
+export * from './html-rendering-configuration.ts';
+export { migrateThemeVariables } from './helpers/migrate-theme-variables.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/api-reference/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api-reference/index.ts"],"names":[],"mappings":"AAAA,cAAc,kCAAkC,CAAA;AAChD,cAAc,mCAAmC,CAAA;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAA"}

package/dist/api-reference/index.js

@@ -0,0 +1,3 @@
+export { apiClientConfigurationSchema, apiReferenceConfigurationSchema } from './api-reference-configuration.js';
+export { htmlRenderingConfigurationSchema } from './html-rendering-configuration.js';
+export { migrateThemeVariables } from './helpers/migrate-theme-variables.js';