@scalar/oas-utils 0.10.8 → 0.10.10

package/dist/entities/spec/requests.js

@@ -1,91 +1,109 @@
-import {
-  XCodeSamplesSchema,
-  XPostResponseSchema
-} from "@scalar/openapi-types/schemas/extensions";
-import { oasSecurityRequirementSchema } from "@scalar/types/entities";
-import { XScalarStability } from "@scalar/types/legacy";
-import { nanoidSchema } from "@scalar/types/utils";
-import { z } from "zod";
-import { selectedSecuritySchemeUidSchema } from "../../entities/shared/utility.js";
-import { oasParameterSchema } from "./parameters.js";
-import { xScalarExampleSchema } from "./request-examples.js";
-import { oasExternalDocumentationSchema } from "./spec-objects.js";
-const requestMethods = ["delete", "get", "head", "options", "patch", "post", "put", "trace"];
+import { XCodeSamplesSchema, XPostResponseSchema, } from '@scalar/openapi-types/schemas/extensions';
+import { oasSecurityRequirementSchema } from '@scalar/types/entities';
+import { XScalarStability } from '@scalar/types/legacy';
+import { nanoidSchema } from '@scalar/types/utils';
+import { z } from 'zod';
+import { selectedSecuritySchemeUidSchema } from '../../entities/shared/utility.js';
+import { oasParameterSchema } from './parameters.js';
+import { xScalarExampleSchema } from './request-examples.js';
+import { oasExternalDocumentationSchema } from './spec-objects.js';
+const requestMethods = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'];
 const requestBodySchema = z.any();
+/** Open API Compliant Request Validator */
 const oasRequestSchema = z.object({
-  /**
-   * A list of tags for API documentation control. Tags can be used for logical
-   * grouping of operations by resources or any other qualifier.
-   *
-   * These tags are the openapi spec tag names, not uids
-   */
-  "tags": z.string().array().optional(),
-  /** A short summary of what the operation does. */
-  "summary": z.string().optional(),
-  /** A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. */
-  "description": z.string().optional(),
-  /**
-   * Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
-   * The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an
-   * operation, therefore, it is RECOMMENDED to follow bin common programming naming conventions./
-   */
-  "operationId": z.string().optional(),
-  /**
-   * A declaration of which security mechanisms can be used across the API. The list of
-   * values includes alternative security requirement objects that can be used. Only
-   * one of the security requirement objects need to be satisfied to authorize a request.
-   * Individual operations can override this definition. To make security optional, an empty
-   * security requirement ({}) can be included in the array.
-   */
-  "security": z.array(oasSecurityRequirementSchema).optional(),
-  /**
-   * The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the
-   * HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the
-   * HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined
-   * semantics and SHOULD be avoided if possible.
-   */
-  "requestBody": requestBodySchema.optional(),
-  /**
-   * Request parameters
-   */
-  "parameters": oasParameterSchema.array().optional(),
-  /**
-   * External documentation object
-   */
-  "externalDocs": oasExternalDocumentationSchema.optional(),
-  "deprecated": z.boolean().optional(),
-  /** Response formats */
-  "responses": z.record(z.string(), z.any()).optional(),
-  /** Callbacks */
-  "callbacks": z.record(z.string(), z.record(z.string(), z.record(z.string(), z.any()))).optional(),
-  /** xScalar examples */
-  "x-scalar-examples": z.record(z.string(), xScalarExampleSchema).optional(),
-  /** Hide operations */
-  "x-internal": z.boolean().optional(),
-  /** Ignore operations */
-  "x-scalar-ignore": z.boolean().optional()
+    /**
+     * A list of tags for API documentation control. Tags can be used for logical
+     * grouping of operations by resources or any other qualifier.
+     *
+     * These tags are the openapi spec tag names, not uids
+     */
+    'tags': z.string().array().optional(),
+    /** A short summary of what the operation does. */
+    'summary': z.string().optional(),
+    /** A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. */
+    'description': z.string().optional(),
+    /**
+     * Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
+     * The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an
+     * operation, therefore, it is RECOMMENDED to follow bin common programming naming conventions./
+     */
+    'operationId': z.string().optional(),
+    /**
+     * A declaration of which security mechanisms can be used across the API. The list of
+     * values includes alternative security requirement objects that can be used. Only
+     * one of the security requirement objects need to be satisfied to authorize a request.
+     * Individual operations can override this definition. To make security optional, an empty
+     * security requirement ({}) can be included in the array.
+     */
+    'security': z.array(oasSecurityRequirementSchema).optional(),
+    /**
+     * The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the
+     * HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the
+     * HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined
+     * semantics and SHOULD be avoided if possible.
+     */
+    'requestBody': requestBodySchema.optional(),
+    /**
+     * Request parameters
+     */
+    'parameters': oasParameterSchema.array().optional(),
+    /**
+     * External documentation object
+     */
+    'externalDocs': oasExternalDocumentationSchema.optional(),
+    'deprecated': z.boolean().optional(),
+    /** Response formats */
+    'responses': z.record(z.string(), z.any()).optional(),
+    /** Callbacks */
+    'callbacks': z.record(z.string(), z.record(z.string(), z.record(z.string(), z.any()))).optional(),
+    /** xScalar examples */
+    'x-scalar-examples': z.record(z.string(), xScalarExampleSchema).optional(),
+    /** Hide operations */
+    'x-internal': z.boolean().optional(),
+    /** Ignore operations */
+    'x-scalar-ignore': z.boolean().optional(),
 });
+/**
+ * An OpenAPI extension to indicate the stability of the operation
+ *
+ * @example
+ * ```yaml
+ * x-scalar-stability: deprecated
+ * ```
+ */
 const ScalarStabilitySchema = z.object({
-  "x-scalar-stability": z.enum([XScalarStability.Deprecated, XScalarStability.Experimental, XScalarStability.Stable]).optional().catch(void 0)
+    'x-scalar-stability': z
+        .enum([XScalarStability.Deprecated, XScalarStability.Experimental, XScalarStability.Stable])
+        .optional()
+        .catch(undefined),
 });
+/**
+ * Extended properties added to the spec definition for client usage
+ *
+ * WARNING: DO NOT ADD PROPERTIES THAT SHARE A NAME WITH OAS OPERATION ENTITIES
+ *
+ * This object is directly converted to a spec operation during saving
+ */
 const extendedRequestSchema = z.object({
-  type: z.literal("request").optional().default("request"),
-  uid: nanoidSchema.brand(),
-  /** Path Key */
-  path: z.string().optional().default(""),
-  /** Request Method */
-  method: z.enum(requestMethods).default("get"),
-  /** List of server UIDs specific to the request */
-  servers: z.string().brand().array().default([]),
-  /** The currently selected server */
-  selectedServerUid: z.string().brand().optional().nullable().default(null),
-  /** List of example UIDs associated with the request */
-  examples: z.string().brand().array().default([]),
-  /** List of security scheme UIDs associated with the request */
-  selectedSecuritySchemeUids: selectedSecuritySchemeUidSchema
+    type: z.literal('request').optional().default('request'),
+    uid: nanoidSchema.brand(),
+    /** Path Key */
+    path: z.string().optional().default(''),
+    /** Request Method */
+    method: z.enum(requestMethods).default('get'),
+    /** List of server UIDs specific to the request */
+    servers: z.string().brand().array().default([]),
+    /** The currently selected server */
+    selectedServerUid: z.string().brand().optional().nullable().default(null),
+    /** List of example UIDs associated with the request */
+    examples: z.string().brand().array().default([]),
+    /** List of security scheme UIDs associated with the request */
+    selectedSecuritySchemeUids: selectedSecuritySchemeUidSchema,
 });
-const requestSchema = oasRequestSchema.omit({ "x-scalar-examples": true }).merge(XCodeSamplesSchema).merge(ScalarStabilitySchema).merge(extendedRequestSchema).merge(XPostResponseSchema);
-export {
-  requestSchema
-};
-//# sourceMappingURL=requests.js.map
+/** Unified request schema for client usage */
+export const requestSchema = oasRequestSchema
+    .omit({ 'x-scalar-examples': true })
+    .merge(XCodeSamplesSchema)
+    .merge(ScalarStabilitySchema)
+    .merge(extendedRequestSchema)
+    .merge(XPostResponseSchema);

package/dist/entities/spec/server.js

@@ -1,52 +1,67 @@
-import { nanoidSchema } from "@scalar/types/utils";
-import { z } from "zod";
+import { nanoidSchema } from '@scalar/types/utils';
+import { z } from 'zod';
+/**
+ * Server Variable Object
+ *
+ * An object representing a Server Variable for server URL template substitution.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#server-variable-object
+ */
 const oasServerVariableSchema = z.object({
-  /**
-   * An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.
-   */
-  enum: z.array(z.string()).optional(),
-  /**
-   * REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied.
-   * Note this behavior is different than the Schema Object's treatment of default values, because in those cases
-   * parameter values are optional. If the enum is defined, the value MUST exist in the enum's values.
-   */
-  default: z.string().optional(),
-  /**
-   * An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
-   */
-  description: z.string().optional()
+    /**
+     * An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.
+     */
+    enum: z.array(z.string()).optional(),
+    /**
+     * REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied.
+     * Note this behavior is different than the Schema Object's treatment of default values, because in those cases
+     * parameter values are optional. If the enum is defined, the value MUST exist in the enum's values.
+     */
+    default: z.string().optional(),
+    /**
+     * An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+     */
+    description: z.string().optional(),
 });
-const extendedServerVariableSchema = oasServerVariableSchema.extend({
-  /** The value of the variable */
-  value: z.string().optional()
-}).refine((data) => {
-  if (Array.isArray(data.enum) && !data.enum.includes(data.default ?? "") && data.enum.length > 0) {
-    data.default = data.enum[0];
-  }
-  if (Array.isArray(data.enum) && data.enum.length === 0) {
-    delete data.enum;
-  }
-  return true;
+/** Extended schema for server variables */
+const extendedServerVariableSchema = oasServerVariableSchema
+    .extend({
+    /** The value of the variable */
+    value: z.string().optional(),
+})
+    .refine((data) => {
+    // Set default to the first enum value if invalid
+    if (Array.isArray(data.enum) && !data.enum.includes(data.default ?? '') && data.enum.length > 0) {
+        data.default = data.enum[0];
+    }
+    if (Array.isArray(data.enum) && data.enum.length === 0) {
+        delete data.enum;
+    }
+    // Always return true since we've modified the data to be valid
+    return true;
 });
+/**
+ * Server Object
+ *
+ * An object representing a Server.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#server-object
+ */
 const oasServerSchema = z.object({
-  /**
-   * REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that
-   * the host location is relative to the location where the OpenAPI document is being served. Variable substitutions
-   * will be made when a variable is named in {brackets}.
-   */
-  url: z.string(),
-  /**
-   * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text
-   * representation.
-   */
-  description: z.string().optional(),
-  /** A map between a variable name and its value. The value is used for substitution in the server's URL template. */
-  variables: z.record(z.string(), extendedServerVariableSchema).optional()
+    /**
+     * REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that
+     * the host location is relative to the location where the OpenAPI document is being served. Variable substitutions
+     * will be made when a variable is named in {brackets}.
+     */
+    url: z.string(),
+    /**
+     * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text
+     * representation.
+     */
+    description: z.string().optional(),
+    /** A map between a variable name and its value. The value is used for substitution in the server's URL template. */
+    variables: z.record(z.string(), extendedServerVariableSchema).optional(),
 });
-const serverSchema = oasServerSchema.extend({
-  uid: nanoidSchema.brand()
+export const serverSchema = oasServerSchema.extend({
+    uid: nanoidSchema.brand(),
 });
-export {
-  serverSchema
-};
-//# sourceMappingURL=server.js.map

package/dist/entities/spec/spec-objects.js

@@ -1,79 +1,124 @@
-import { omitUndefinedValues } from "@scalar/helpers/object/omit-undefined-values";
-import { XScalarSdkInstallationSchema } from "@scalar/openapi-types/schemas/extensions";
-import { nanoidSchema } from "@scalar/types/utils";
-import { z } from "zod";
-const oasLicenseSchema = z.object({
-  /** REQUIRED. The license name used for the API. */
-  name: z.string().optional().nullable().catch(null),
-  /** An SPDX license expression for the API. The identifier field is mutually exclusive of the url field. */
-  identifier: z.string().optional().catch(void 0),
-  /**
-   * A URI for the license used for the API. This MUST be in the form of a URI. The url field is mutually exclusive of the identifier field.
-   */
-  url: z.string().url().optional().catch(void 0)
-}).transform(omitUndefinedValues);
-const oasContactSchema = z.object({
-  /** The identifying name of the contact person/organization. */
-  name: z.string().optional(),
-  /** The URL pointing to the contact information. This MUST be in the form of a URL. */
-  url: z.string().url().optional().catch(void 0),
-  /** The email address of the contact person/organization. This MUST be in the form of an email address. */
-  email: z.string().optional().catch(void 0)
-}).transform(omitUndefinedValues);
-const oasInfoSchema = z.object({
-  /** REQUIRED. The title of the API. */
-  title: z.string().catch("API"),
-  /** A short summary of the API. */
-  summary: z.string().optional().catch(void 0),
-  /** A description of the API. CommonMark syntax MAY be used for rich text representation. */
-  description: z.string().optional().catch(void 0),
-  /** A URL to the Terms of Service for the API. This MUST be in the form of a URL. */
-  termsOfService: z.string().url().optional().catch(void 0),
-  /** The contact information for the exposed API. */
-  contact: oasContactSchema.optional().catch(void 0),
-  /** The license information for the exposed API. */
-  license: oasLicenseSchema.optional().catch(void 0),
-  /**
-   * REQUIRED. The version of the OpenAPI Document (which is distinct from the OpenAPI Specification version or the
-   * version of the API being described or the version of the OpenAPI Description).
-   */
-  version: z.string().catch("1.0")
-}).merge(XScalarSdkInstallationSchema).transform(omitUndefinedValues);
-const oasExternalDocumentationSchema = z.object({
-  /** A description of the target documentation. CommonMark syntax MAY be used for rich text representation. */
-  description: z.string().optional().catch(void 0),
-  /** REQUIRED. The URL for the target documentation. This MUST be in the form of a URL. */
-  url: z.string()
-}).transform(omitUndefinedValues);
-const xScalarNestedSchema = z.object({
-  tagName: z.string()
-}).array();
+import { omitUndefinedValues } from '@scalar/helpers/object/omit-undefined-values';
+import { XScalarSdkInstallationSchema } from '@scalar/openapi-types/schemas/extensions';
+import { nanoidSchema } from '@scalar/types/utils';
+import { z } from 'zod';
+/**
+ * License Object
+ *
+ * License information for the exposed API.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#license-object
+ */
+export const oasLicenseSchema = z
+    .object({
+    /** REQUIRED. The license name used for the API. */
+    name: z.string().optional().nullable().catch(null),
+    /** An SPDX license expression for the API. The identifier field is mutually exclusive of the url field. */
+    identifier: z.string().optional().catch(undefined),
+    /**
+     * A URI for the license used for the API. This MUST be in the form of a URI. The url field is mutually exclusive of the identifier field.
+     */
+    url: z.string().url().optional().catch(undefined),
+})
+    .transform(omitUndefinedValues);
+/**
+ * Contact Object
+ *
+ * Contact information for the exposed API.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#contact-object
+ */
+export const oasContactSchema = z
+    .object({
+    /** The identifying name of the contact person/organization. */
+    name: z.string().optional(),
+    /** The URL pointing to the contact information. This MUST be in the form of a URL. */
+    url: z.string().url().optional().catch(undefined),
+    /** The email address of the contact person/organization. This MUST be in the form of an email address. */
+    email: z.string().optional().catch(undefined),
+})
+    .transform(omitUndefinedValues);
+/**
+ * Info Object
+ *
+ * The object provides metadata about the API. The metadata MAY be used by the clients if needed,
+ * and MAY be presented in editing or documentation generation tools for convenience.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#info-object
+ */
+export const oasInfoSchema = z
+    .object({
+    /** REQUIRED. The title of the API. */
+    title: z.string().catch('API'),
+    /** A short summary of the API. */
+    summary: z.string().optional().catch(undefined),
+    /** A description of the API. CommonMark syntax MAY be used for rich text representation. */
+    description: z.string().optional().catch(undefined),
+    /** A URL to the Terms of Service for the API. This MUST be in the form of a URL. */
+    termsOfService: z.string().url().optional().catch(undefined),
+    /** The contact information for the exposed API. */
+    contact: oasContactSchema.optional().catch(undefined),
+    /** The license information for the exposed API. */
+    license: oasLicenseSchema.optional().catch(undefined),
+    /**
+     * REQUIRED. The version of the OpenAPI Document (which is distinct from the OpenAPI Specification version or the
+     * version of the API being described or the version of the OpenAPI Description).
+     */
+    version: z.string().catch('1.0'),
+})
+    .merge(XScalarSdkInstallationSchema)
+    .transform(omitUndefinedValues);
+/**
+ * External Documentation Object
+ *
+ * Allows referencing an external resource for extended documentation.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#external-documentation-object
+ */
+export const oasExternalDocumentationSchema = z
+    .object({
+    /** A description of the target documentation. CommonMark syntax MAY be used for rich text representation. */
+    description: z.string().optional().catch(undefined),
+    /** REQUIRED. The URL for the target documentation. This MUST be in the form of a URL. */
+    url: z.string(),
+})
+    .transform(omitUndefinedValues);
+// not used but kept for consistency
+// export type ExternalDocumentation = z.infer<typeof oasExternalDocumentationSchema>
+const xScalarNestedSchema = z
+    .object({
+    tagName: z.string(),
+})
+    .array();
+/**
+ * Tag Object
+ *
+ * Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag
+ * defined in the Operation Object instances.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#tag-object
+ */
 const oasTagSchema = z.object({
-  // TODO: Remove
-  /**
-   * @deprecated Needs to be remove as it is not a spec property
-   */
-  "type": z.literal("tag").optional().default("tag"),
-  /** REQUIRED. The name of the tag. */
-  "name": z.string(),
-  /** A description for the tag. CommonMark syntax MAY be used for rich text representation. */
-  "description": z.string().optional().catch(void 0),
-  /** Additional external documentation for this tag. */
-  "externalDocs": oasExternalDocumentationSchema.optional(),
-  "x-scalar-children": xScalarNestedSchema.default([]).optional(),
-  /** Hide collections */
-  "x-internal": z.boolean().optional(),
-  "x-scalar-ignore": z.boolean().optional()
+    // TODO: Remove
+    /**
+     * @deprecated Needs to be remove as it is not a spec property
+     */
+    'type': z.literal('tag').optional().default('tag'),
+    /** REQUIRED. The name of the tag. */
+    'name': z.string(),
+    /** A description for the tag. CommonMark syntax MAY be used for rich text representation. */
+    'description': z.string().optional().catch(undefined),
+    /** Additional external documentation for this tag. */
+    'externalDocs': oasExternalDocumentationSchema.optional(),
+    'x-scalar-children': xScalarNestedSchema.default([]).optional(),
+    /** Hide collections */
+    'x-internal': z.boolean().optional(),
+    'x-scalar-ignore': z.boolean().optional(),
 });
-const tagSchema = oasTagSchema.extend({
-  uid: nanoidSchema.brand(),
-  children: z.union([z.string().brand(), z.string().brand()]).array().default([])
+export const tagSchema = oasTagSchema.extend({
+    uid: nanoidSchema.brand(),
+    children: z
+        .union([z.string().brand(), z.string().brand()])
+        .array()
+        .default([]),
 });
-export {
-  oasContactSchema,
-  oasExternalDocumentationSchema,
-  oasInfoSchema,
-  oasLicenseSchema,
-  tagSchema
-};
-//# sourceMappingURL=spec-objects.js.map

package/dist/entities/spec/x-scalar-environments.js

@@ -1,24 +1,22 @@
-import { z } from "zod";
+import { z } from 'zod';
 const xScalarEnvVarSchema = z.union([
-  z.object({
-    description: z.string().optional(),
-    default: z.string().default("")
-  }),
-  z.string()
+    z.object({
+        description: z.string().optional(),
+        default: z.string().default(''),
+    }),
+    z.string(),
 ]);
+// not used but kept for consistency
+// export type XScalarEnvVar = z.infer<typeof xScalarEnvVarSchema>
 const xScalarEnvironmentSchema = z.object({
-  description: z.string().optional(),
-  color: z.string().optional(),
-  /** A map of variables by name */
-  variables: z.record(z.string(), xScalarEnvVarSchema)
+    description: z.string().optional(),
+    color: z.string().optional(),
+    /** A map of variables by name */
+    variables: z.record(z.string(), xScalarEnvVarSchema),
 });
-const xScalarEnvironmentsSchema = z.record(
-  /** Name */
-  z.string(),
-  /** Environment definition */
-  xScalarEnvironmentSchema
-);
-export {
-  xScalarEnvironmentsSchema
-};
-//# sourceMappingURL=x-scalar-environments.js.map
+/** A map of environments by name */
+export const xScalarEnvironmentsSchema = z.record(
+/** Name */
+z.string(), 
+/** Environment definition */
+xScalarEnvironmentSchema);

package/dist/entities/spec/x-scalar-secrets.js

@@ -1,10 +1,8 @@
-import { z } from "zod";
+import { z } from 'zod';
 const xScalarSecretVarSchema = z.object({
-  description: z.string().optional(),
-  example: z.string().optional()
+    description: z.string().optional(),
+    example: z.string().optional(),
 });
-const xScalarSecretsSchema = z.record(z.string(), xScalarSecretVarSchema);
-export {
-  xScalarSecretsSchema
-};
-//# sourceMappingURL=x-scalar-secrets.js.map
+export const xScalarSecretsSchema = z.record(z.string(), xScalarSecretVarSchema);
+// not used but kept for consistency
+// export type XScalarSecrets = z.infer<typeof xScalarSecretsSchema>

package/dist/entities/workspace/index.js

@@ -1,7 +1 @@
-import {
-  workspaceSchema
-} from "./workspace.js";
-export {
-  workspaceSchema
-};
-//# sourceMappingURL=index.js.map
+export { workspaceSchema, } from './workspace.js';