@scalar/oas-utils 0.2.74 → 0.2.76

package/dist/entities/spec/request-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-examples.d.ts","sourceRoot":"","sources":["../../../src/entities/spec/request-examples.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC,eAAO,MAAM,8BAA8B;;;;;;IAMzC,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUlF,CAAA;AAEF,kFAAkF;AAClF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,uEAQ7B,CAAA;AACV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;YAjCnC,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoDlF,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEzE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;gBAvD/B,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAlF,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAlF,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAlF,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAlF,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuElF,CAAA;AAEF,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAKxE,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB;;;;;;;;;;;;;;;EA8C1D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAiGhB"}
+{"version":3,"file":"request-examples.d.ts","sourceRoot":"","sources":["../../../src/entities/spec/request-examples.ts"],"names":[],"mappings":"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"}

package/dist/entities/spec/request-examples.js

@@ -1,17 +1,24 @@
+import { keysOf } from '@scalar/object-utils/arrays';
 import { z } from 'zod';
 import { schemaModel } from '../../helpers/schema-model.js';
 import { getRequestBodyFromOperation } from '../../spec-getters/getRequestBodyFromOperation.js';
 import { getServerVariableExamples } from '../../spec-getters/getServerVariableExamples.js';
 import { nanoidSchema } from '../shared/utility.js';
 
+// ---------------------------------------------------------------------------
+// Example Parameters
+/**
+ * TODO: Deprecate this.
+ *
+ * The request schema should be stored in the request and any
+ * parameters should be validated against that
+ */
 const requestExampleParametersSchema = z.object({
     key: z.string().default(''),
     value: z.coerce.string().default(''),
     enabled: z.boolean().default(true),
     file: z.any().optional(),
     description: z.string().optional(),
-    /** Params are linked to parents such as path params and global headers/cookies */
-    refUid: nanoidSchema.optional(),
     required: z.boolean().optional(),
     enum: z.array(z.string()).optional(),
     type: z.string().optional(),
@@ -21,6 +28,36 @@ const requestExampleParametersSchema = z.object({
     default: z.any().optional(),
     nullable: z.boolean().optional(),
 });
+/** Convert the array of parameters to an object keyed by the parameter name */
+function parameterArrayToObject(params) {
+    return params.reduce((map, param) => {
+        map[param.key] = param.value;
+        return map;
+    }, {});
+}
+const xScalarFileValueSchema = z
+    .object({
+    url: z.string(),
+    base64: z.string().optional(),
+})
+    .nullable();
+/**
+ * Schema for the OAS serialization of request example parameters
+ *
+ * File values can be optionally fetched on import OR inserted as a base64 encoded string
+ */
+const xScalarFormDataValue = z.union([
+    z.object({
+        type: z.literal('string'),
+        value: z.string(),
+    }),
+    z.object({
+        type: z.literal('file'),
+        file: xScalarFileValueSchema,
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Example Body
 /**
  * Possible encodings for example request bodies when using text formats
  *
@@ -35,6 +72,34 @@ const exampleRequestBodyEncoding = [
     'yaml',
     'edn',
 ];
+const exampleBodyMime = [
+    'application/json',
+    'text/plain',
+    'text/html',
+    'application/javascript',
+    'application/xml',
+    'application/yaml',
+    'application/edn',
+    'application/octet-stream',
+    'application/x-www-form-urlencoded',
+    'multipart/form-data',
+    /** Used for direct files */
+    'binary',
+];
+const contentMapping = {
+    json: 'application/json',
+    text: 'text/plain',
+    html: 'text/html',
+    javascript: 'application/javascript',
+    xml: 'application/xml',
+    yaml: 'application/yaml',
+    edn: 'application/edn',
+};
+/**
+ * TODO: Migrate away from this layout to the format used in the extension
+ *
+ * If a user changes the encoding of the body we expect the content to change as well
+ */
 const exampleRequestBodySchema = z.object({
     raw: z
         .object({
@@ -55,9 +120,23 @@ const exampleRequestBodySchema = z.object({
         .union([z.literal('raw'), z.literal('formData'), z.literal('binary')])
         .default('raw'),
 });
+/** Schema for the OAS serialization of request example bodies */
+const xScalarExampleBodySchema = z.object({
+    encoding: z.enum(exampleBodyMime).default('application/json'),
+    /**
+     * Body content as an object with a separately specified encoding or a simple pre-encoded string value
+     *
+     * Ideally we would convert any objects into the proper encoding on import
+     */
+    content: z.union([z.record(z.string(), z.any()), z.string()]),
+    /** When the encoding is `binary` this will be used to link to the file */
+    file: xScalarFileValueSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// Example Schema
 const requestExampleSchema = z.object({
-    type: z.literal('requestExample').optional().default('requestExample'),
     uid: nanoidSchema,
+    type: z.literal('requestExample').optional().default('requestExample'),
     requestUid: nanoidSchema,
     name: z.string().optional().default('Name'),
     body: exampleRequestBodySchema.optional().default({}),
@@ -70,8 +149,81 @@ const requestExampleSchema = z.object({
     })
         .optional()
         .default({}),
+    /** TODO: Should this be deprecated? */
     serverVariables: z.record(z.string(), z.array(z.string())).optional(),
 });
+/** For OAS serialization we just store the simple key/value pairs */
+const xScalarExampleParameterSchema = z
+    .record(z.string(), z.string())
+    .optional();
+/** Schema for the OAS serialization of request examples */
+const xScalarExampleSchema = z.object({
+    /** TODO: Should this be required? */
+    name: z.string().optional(),
+    body: xScalarExampleBodySchema.optional(),
+    parameters: z.object({
+        path: xScalarExampleParameterSchema,
+        query: xScalarExampleParameterSchema,
+        headers: xScalarExampleParameterSchema,
+        cookies: xScalarExampleParameterSchema,
+    }),
+});
+/**
+ * Convert a request example to the xScalar serialized format
+ *
+ * TODO: The base format should be migrated to align MUCH closer to the serialized format
+ */
+function convertExampleToXScalar(example) {
+    const active = example.body?.activeBody;
+    const xScalarBody = {
+        encoding: 'text/plain',
+        content: '',
+    };
+    if (example.body?.activeBody === 'binary') {
+        xScalarBody.encoding = 'binary';
+        // TODO: Need to allow users to set these properties
+        xScalarBody.file = null;
+    }
+    if (active === 'formData' && example.body?.[active]) {
+        const body = example.body[active];
+        xScalarBody.encoding =
+            body.encoding === 'form-data'
+                ? 'multipart/form-data'
+                : 'application/x-www-form-urlencoded';
+        // TODO: Need to allow users to set these properties
+        xScalarBody.content = body.value.reduce((map, param) => {
+            /** TODO: We need to ensure only file or value is set */
+            map[param.key] = param.file
+                ? {
+                    type: 'file',
+                    file: null,
+                }
+                : {
+                    type: 'string',
+                    value: param.value,
+                };
+            return map;
+        }, {});
+    }
+    if (example.body?.activeBody === 'raw') {
+        xScalarBody.encoding =
+            contentMapping[example.body.raw?.encoding ?? 'text'] ?? 'text/plain';
+        xScalarBody.content = example.body.raw?.value ?? '';
+    }
+    const parameters = {};
+    keysOf(example.parameters ?? {}).forEach((key) => {
+        if (example.parameters?.[key].length) {
+            parameters[key] = parameterArrayToObject(example.parameters[key]);
+        }
+    });
+    return xScalarExampleSchema.parse({
+        /** Only add the body if we have content or the body should be a file */
+        body: xScalarBody.content || xScalarBody.encoding === 'binary'
+            ? xScalarBody
+            : undefined,
+        parameters,
+    });
+}
 // ---------------------------------------------------------------------------
 // Example Helpers
 /** Create new instance parameter from a request parameter */
@@ -198,4 +350,4 @@ function createExampleFromRequest(request, name, server) {
         return example;
 }
 
-export { createExampleFromRequest, createParamInstance, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema };
+export { convertExampleToXScalar, createExampleFromRequest, createParamInstance, exampleBodyMime, exampleRequestBodyEncoding, exampleRequestBodySchema, requestExampleParametersSchema, requestExampleSchema, xScalarExampleBodySchema, xScalarExampleSchema, xScalarFileValueSchema, xScalarFormDataValue };

package/dist/entities/spec/requests.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { RequestExample } from './request-examples.js';
+import { type RequestExample } from './request-examples.js';
 export declare const requestMethods: readonly ["connect", "delete", "get", "head", "options", "patch", "post", "put", "trace"];
 export type RequestMethod = (typeof requestMethods)[number];
 /** A single set of populated values for a sent request */
@@ -90,10 +90,10 @@ export declare const oasRequestSchema: z.ZodObject<{
         in: "path" | "query" | "header" | "cookie";
         deprecated: boolean;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -103,11 +103,11 @@ export declare const oasRequestSchema: z.ZodObject<{
         in: "path" | "query" | "header" | "cookie";
         required?: boolean | undefined;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -129,6 +129,86 @@ export declare const oasRequestSchema: z.ZodObject<{
     deprecated: z.ZodOptional<z.ZodBoolean>;
     /** Response formats */
     responses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /** xScalar examples */
+    'x-scalar-examples': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodObject<{
+            encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+            content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+            file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                url: z.ZodString;
+                base64: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                base64?: string | undefined;
+            }, {
+                url: string;
+                base64?: string | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        }, {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        }>>;
+        parameters: z.ZodObject<{
+            path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cookies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     description?: string | undefined;
     summary?: string | undefined;
@@ -146,10 +226,10 @@ export declare const oasRequestSchema: z.ZodObject<{
         in: "path" | "query" | "header" | "cookie";
         deprecated: boolean;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -157,6 +237,23 @@ export declare const oasRequestSchema: z.ZodObject<{
     }[] | undefined;
     requestBody?: any;
     responses?: Record<string, any> | undefined;
+    'x-scalar-examples'?: Record<string, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }> | undefined;
 }, {
     description?: string | undefined;
     summary?: string | undefined;
@@ -173,11 +270,11 @@ export declare const oasRequestSchema: z.ZodObject<{
         in: "path" | "query" | "header" | "cookie";
         required?: boolean | undefined;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -185,9 +282,26 @@ export declare const oasRequestSchema: z.ZodObject<{
     }[] | undefined;
     requestBody?: any;
     responses?: Record<string, any> | undefined;
+    'x-scalar-examples'?: Record<string, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }> | undefined;
 }>;
 /** Unified request schema for client usage */
-export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
+export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<Omit<{
     /**
      * A list of tags for API documentation control. Tags can be used for logical
      * grouping of operations by resources or any other qualifier.
@@ -249,10 +363,10 @@ export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
         in: "path" | "query" | "header" | "cookie";
         deprecated: boolean;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -262,11 +376,11 @@ export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
         in: "path" | "query" | "header" | "cookie";
         required?: boolean | undefined;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -288,7 +402,87 @@ export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
     deprecated: z.ZodOptional<z.ZodBoolean>;
     /** Response formats */
     responses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-}, {
+    /** xScalar examples */
+    'x-scalar-examples': z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodObject<{
+            encoding: z.ZodDefault<z.ZodEnum<["application/json", "text/plain", "text/html", "application/javascript", "application/xml", "application/yaml", "application/edn", "application/octet-stream", "application/x-www-form-urlencoded", "multipart/form-data", "binary"]>>;
+            content: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+            file: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                url: z.ZodString;
+                base64: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                url: string;
+                base64?: string | undefined;
+            }, {
+                url: string;
+                base64?: string | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        }, {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        }>>;
+        parameters: z.ZodObject<{
+            path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cookies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            encoding: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary";
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+        } | undefined;
+    }, {
+        parameters: {
+            path?: Record<string, string> | undefined;
+            cookies?: Record<string, string> | undefined;
+            query?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        };
+        name?: string | undefined;
+        body?: {
+            content: string | Record<string, any>;
+            file?: {
+                url: string;
+                base64?: string | undefined;
+            } | null | undefined;
+            encoding?: "application/json" | "application/octet-stream" | "application/x-www-form-urlencoded" | "application/xml" | "multipart/form-data" | "text/plain" | "text/html" | "application/javascript" | "application/yaml" | "application/edn" | "binary" | undefined;
+        } | undefined;
+    }>>>;
+}, "x-scalar-examples">, {
     type: z.ZodDefault<z.ZodOptional<z.ZodLiteral<"request">>>;
     uid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     /** Path Key */
@@ -328,10 +522,10 @@ export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
         in: "path" | "query" | "header" | "cookie";
         deprecated: boolean;
         description?: string | undefined;
+        example?: unknown;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;
@@ -363,11 +557,11 @@ export declare const requestSchema: z.ZodObject<z.objectUtil.extendShape<{
         in: "path" | "query" | "header" | "cookie";
         required?: boolean | undefined;
         description?: string | undefined;
+        example?: unknown;
         deprecated?: boolean | undefined;
         schema?: unknown;
         content?: unknown;
         style?: "matrix" | "simple" | "form" | "label" | "spaceDelimited" | "pipeDelimited" | "deepObject" | undefined;
-        example?: unknown;
         examples?: Record<string, {
             value?: unknown;
             summary?: string | undefined;

package/dist/entities/spec/requests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../../src/entities/spec/requests.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAIxD,eAAO,MAAM,cAAc,2FAUjB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;IACzD,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,MAAM,EAAE,aAAa,CAAA;IACrB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAMD,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;;IAEH,kDAAkD;;IAElD,mHAAmH;;IAEnH;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH;;;;;OAKG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH;;OAEG;;;;;;;;;;;;IAGH,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE0B,CAAA;AA0BnD,8CAA8C;AAC9C,eAAO,MAAM,aAAa;IAtExB;;;;;OAKG;;IAEH,kDAAkD;;IAElD,mHAAmH;;IAEnH;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH;;;;;OAKG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH;;OAEG;;;;;;;;;;;;IAGH,uBAAuB;;;;;IAcvB,eAAe;;IAEf,qBAAqB;;IAErB,kDAAkD;;IAElD,oCAAoC;;IAEpC,uDAAuD;;IAEvD,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKS,CAAA;AAC1E,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA"}
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../../src/entities/spec/requests.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvC,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,oBAAoB,CAAA;AAI9E,eAAO,MAAM,cAAc,2FAUjB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;IACzD,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,MAAM,EAAE,aAAa,CAAA;IACrB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAMD,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;;IAEH,kDAAkD;;IAElD,mHAAmH;;IAEnH;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH;;;;;OAKG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH;;OAEG;;;;;;;;;;;;IAGH,uBAAuB;;IAEvB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE0B,CAAA;AA0BnD,8CAA8C;AAC9C,eAAO,MAAM,aAAa;IAxExB;;;;;OAKG;;IAEH,kDAAkD;;IAElD,mHAAmH;;IAEnH;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH;;;;;OAKG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH;;OAEG;;;;;;;;;;;;IAGH,uBAAuB;;IAEvB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcvB,eAAe;;IAEf,qBAAqB;;IAErB,kDAAkD;;IAElD,oCAAoC;;IAEpC,uDAAuD;;IAEvD,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOlC,CAAA;AAE/B,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA"}

package/dist/entities/spec/requests.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { oasParameterSchema } from './parameters.js';
+import { xScalarExampleSchema } from './request-examples.js';
 import { oasSecurityRequirementSchema } from './security.js';
 import { oasExternalDocumentationSchema } from './spec-objects.js';
 import { nanoidSchema } from '../shared/utility.js';
@@ -24,17 +25,17 @@ const oasRequestSchema = z.object({
      *
      * These tags are the openapi spec tag names, not uids
      */
-    tags: z.string().array().optional(),
+    'tags': z.string().array().optional(),
     /** A short summary of what the operation does. */
-    summary: z.string().optional(),
+    'summary': z.string().optional(),
     /** A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. */
-    description: z.string().optional(),
+    '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(),
+    '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
@@ -42,25 +43,27 @@ const oasRequestSchema = z.object({
      * 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(),
+    '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(),
+    'requestBody': requestBodySchema.optional(),
     /**
      * Request parameters
      */
-    parameters: oasParameterSchema.array().optional(),
+    'parameters': oasParameterSchema.array().optional(),
     /**
      * External documentation object
      */
-    externalDocs: oasExternalDocumentationSchema.optional(),
-    deprecated: z.boolean().optional(),
+    'externalDocs': oasExternalDocumentationSchema.optional(),
+    'deprecated': z.boolean().optional(),
     /** Response formats */
-    responses: z.record(z.string(), z.any()).optional(),
+    'responses': z.record(z.string(), z.any()).optional(),
+    /** xScalar examples */
+    'x-scalar-examples': z.record(z.string(), xScalarExampleSchema).optional(),
 });
 /**
  * Extended properties added to the spec definition for client usage
@@ -86,6 +89,8 @@ const extendedRequestSchema = z.object({
     selectedSecuritySchemeUids: nanoidSchema.array().default([]),
 });
 /** Unified request schema for client usage */
-const requestSchema = oasRequestSchema.merge(extendedRequestSchema);
+const requestSchema = oasRequestSchema
+    .omit({ 'x-scalar-examples': true })
+    .merge(extendedRequestSchema);
 
 export { oasRequestSchema, requestMethods, requestSchema };

package/dist/entities/spec/server.d.ts

@@ -37,10 +37,10 @@ export declare const oasServerSchema: z.ZodObject<{
     }> | undefined;
 }, {
     description?: string | undefined;
-    url?: string | undefined;
     variables?: Record<string, Omit<OpenAPIV3_1.ServerVariableObject, "enum"> & {
         enum?: [string, ...string[]];
     }> | undefined;
+    url?: string | undefined;
 }>;
 export declare const serverSchema: z.ZodObject<z.objectUtil.extendShape<{
     /**
@@ -72,10 +72,10 @@ export declare const serverSchema: z.ZodObject<z.objectUtil.extendShape<{
 }, {
     uid?: string | undefined;
     description?: string | undefined;
-    url?: string | undefined;
     variables?: Record<string, Omit<OpenAPIV3_1.ServerVariableObject, "enum"> & {
         enum?: [string, ...string[]];
     }> | undefined;
+    url?: string | undefined;
 }>;
 export type Server = z.infer<typeof serverSchema>;
 export type ServerPayload = z.input<typeof serverSchema>;