@scalar/schemas 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @scalar/schemas
 
+## 0.4.0
+
+### Minor Changes
+
+- [#9398](https://github.com/scalar/scalar/pull/9398): feat: read code samples from x-readme, x-stainless and x-scalar extensions
+
+  In addition to `x-codeSamples`, the code sample picker now reads custom samples from `x-scalar-examples`, `x-stainless-snippets`, `x-stainless-examples`, and `x-readme.code-samples`. When more than one is present on an operation, the highest-priority source is used (x-scalar-examples > x-stainless-snippets > x-stainless-examples > x-readme > x-codeSamples).
+
+- [#9422](https://github.com/scalar/scalar/pull/9422): Add a `nonce` option for Content Security Policy support.
+
+  When you pass a `nonce`, the rendered HTML stamps it onto the inline `<script>` and the CDN `<script>` tag (and Scalar's own `<style>` tags, plus a matching `<meta property="csp-nonce">`). This lets the API Reference run under a strict `script-src` with no `unsafe-inline` and no `unsafe-eval`.
+
+  ```ts
+  ApiReference({
+    url: '/openapi.json',
+    // Match this value in your `script-src` CSP directive.
+    nonce: 'r4nd0m',
+  })
+  ```
+
+  Note: `style-src` still needs `'unsafe-inline'`. The reference renders inline `style="…"` attributes, which a CSP nonce can never authorize (nonces only apply to `<script>`, `<style>` and `<link>` elements), so a nonce-only `style-src` is not possible. The win is a fully strict `script-src`.
+
+- [#9400](https://github.com/scalar/scalar/pull/9400): feat(api-reference): add `expandAllSchemaProperties` config option.
+
+  When enabled, nested schema properties are expanded by default while keeping the
+  "Show/Hide Child Attributes" button available for manual collapsing. Expansion
+  is cycle-safe: every finite branch is expanded fully, and self-referential
+  ($ref or inline) schemas stop at the point they would otherwise recurse forever.
+
+- [#9399](https://github.com/scalar/scalar/pull/9399): Show custom SDK installation instructions from `x-scalar-sdk-installation` in the introduction card, falling back to the client selector when there are none. Each entry takes a `lang` and a Markdown `description`, so a single tab can render rich instructions with syntax-highlighted code blocks (for example Maven and Gradle for Java)
+
 ## 0.3.3
 
 ### Patch Changes

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

@@ -139,6 +139,7 @@ export declare const apiReferenceConfigurationSchema: import("@scalar/validation
     defaultOpenAllTags: import("@scalar/validation").BooleanSchema;
     expandAllModelSections: import("@scalar/validation").BooleanSchema;
     expandAllResponses: import("@scalar/validation").BooleanSchema;
+    expandAllSchemaProperties: import("@scalar/validation").BooleanSchema;
     tagsSorter: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").LiteralSchema<"alpha">, import("@scalar/validation").FunctionSchema<(a: any, b: any) => number>]>>;
     operationsSorter: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").LiteralSchema<"alpha">, import("@scalar/validation").LiteralSchema<"method">, import("@scalar/validation").FunctionSchema<(a: any, b: any) => number>]>>;
     orderSchemaPropertiesBy: import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").LiteralSchema<"alpha">, import("@scalar/validation").LiteralSchema<"preserve">]>;
@@ -201,6 +202,7 @@ export declare const apiReferenceConfigurationWithSourceSchema: (rawInput: unkno
     defaultOpenAllTags: boolean;
     expandAllModelSections: boolean;
     expandAllResponses: boolean;
+    expandAllSchemaProperties: boolean;
     orderSchemaPropertiesBy: "alpha" | "preserve";
     orderRequiredPropertiesFirst: boolean;
 } & {

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

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

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

@@ -163,6 +163,10 @@ export const apiReferenceConfigurationSchema = intersection([
             default: false,
             typeComment: 'Whether to expand all responses by default. Warning: this can cause performance issues on big documents',
         }),
+        expandAllSchemaProperties: boolean({
+            default: false,
+            typeComment: 'Whether to expand all nested schema properties by default. The Show/Hide Child Attributes toggle remains available so nested sections can still be collapsed manually. Warning: this can cause performance issues on big documents',
+        }),
         tagsSorter: optional(union([literal('alpha'), fn()]), {
             typeComment: 'Function to sort tags',
         }),

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

@@ -10,5 +10,12 @@ export declare const htmlRenderingConfigurationSchema: import("@scalar/validatio
      */
     cdn: import("@scalar/validation").StringSchema;
     pageTitle: import("@scalar/validation").StringSchema;
+    /**
+     * A Content Security Policy (CSP) nonce to apply to the generated inline `<script>` and `<style>`
+     * tags so the API Reference can render under a strict CSP without `unsafe-inline`.
+     *
+     * Generate a fresh value per request and match it in your `script-src` and `style-src` directives.
+     */
+    nonce: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
 }>;
 //# sourceMappingURL=html-rendering-configuration.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"html-rendering-configuration.d.ts","sourceRoot":"","sources":["../../src/api-reference/html-rendering-configuration.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gCAAgC;IAC3C;;;;;;;;OAQG;;;EAOH,CAAA"}
+{"version":3,"file":"html-rendering-configuration.d.ts","sourceRoot":"","sources":["../../src/api-reference/html-rendering-configuration.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gCAAgC;IAC3C;;;;;;;;OAQG;;;IAOH;;;;;OAKG;;EAEH,CAAA"}

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

@@ -1,4 +1,4 @@
-import { object, string } from '@scalar/validation';
+import { object, optional, string } from '@scalar/validation';
 export const htmlRenderingConfigurationSchema = object({
     /**
      * The URL to the Scalar API Reference JS CDN.
@@ -15,4 +15,11 @@ export const htmlRenderingConfigurationSchema = object({
     pageTitle: string({
         default: 'Scalar API Reference',
     }),
+    /**
+     * A Content Security Policy (CSP) nonce to apply to the generated inline `<script>` and `<style>`
+     * tags so the API Reference can render under a strict CSP without `unsafe-inline`.
+     *
+     * Generate a fresh value per request and match it in your `script-src` and `style-src` directives.
+     */
+    nonce: optional(string()),
 });

package/dist/extensions/document/x-scalar-sdk-installation.d.ts

@@ -1,7 +1,6 @@
 export declare const XScalarSdkInstallation: import("@scalar/validation").ObjectSchema<{
     'x-scalar-sdk-installation': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
         lang: import("@scalar/validation").StringSchema;
-        source: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
         description: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
     }>>>;
 }>;

package/dist/extensions/document/x-scalar-sdk-installation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x-scalar-sdk-installation.d.ts","sourceRoot":"","sources":["../../../src/extensions/document/x-scalar-sdk-installation.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,sBAAsB;;;;;;EAiBlC,CAAA"}
+{"version":3,"file":"x-scalar-sdk-installation.d.ts","sourceRoot":"","sources":["../../../src/extensions/document/x-scalar-sdk-installation.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,sBAAsB;;;;;EAiBlC,CAAA"}

package/dist/extensions/document/x-scalar-sdk-installation.js

@@ -1,9 +1,8 @@
 import { array, object, optional, string } from '@scalar/validation';
 import { typeCommentWithExample } from '../type-comment.js';
 const XScalarSdkInstallationItem = object({
-    lang: string({ typeComment: 'Programming language or platform (for example `shell`, `javascript`)' }),
-    source: optional(string({ typeComment: 'Installation command or snippet source' })),
-    description: optional(string({ typeComment: 'Human-readable description of this installation option' })),
+    lang: string({ typeComment: 'Programming language or platform (for example `TypeScript`, `Java`, `Python`)' }),
+    description: optional(string({ typeComment: 'Installation instructions in Markdown (supports fenced code blocks)' })),
 }, {
     typeName: 'XScalarSdkInstallationItem',
     typeComment: 'One SDK installation instruction block',
@@ -17,7 +16,7 @@ export const XScalarSdkInstallation = object({
     typeComment: typeCommentWithExample('Scalar SDK installation instructions for the API description.', {
         language: 'yaml',
         body: `x-scalar-sdk-installation:
-  - lang: shell
-    source: npm install @scalar/api-client`,
+  - lang: TypeScript
+    description: Install our SDK from npm with \`npm install @scalar/sdk\``,
     }),
 });

package/dist/extensions/operation/x-code-samples.d.ts

@@ -19,5 +19,30 @@ export declare const XCodeSamples: import("@scalar/validation").ObjectSchema<{
         label: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
         source: import("@scalar/validation").StringSchema;
     }>>>;
+    'x-readme': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ObjectSchema<{
+        'code-samples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+            language: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            code: import("@scalar/validation").StringSchema;
+            name: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            install: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            correspondingExample: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        }>>>;
+        'samples-languages': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").StringSchema>>;
+    }>>;
+    'x-stainless-snippets': import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+    'x-stainless-examples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").ObjectSchema<{
+        title: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        request: import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+        response: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnknownSchema>;
+    }>, import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+        title: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        request: import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+        response: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnknownSchema>;
+    }>>]>>;
+    'x-scalar-examples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+        lang: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        label: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        source: import("@scalar/validation").StringSchema;
+    }>>>;
 }>;
 //# sourceMappingURL=x-code-samples.d.ts.map

package/dist/extensions/operation/x-code-samples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x-code-samples.d.ts","sourceRoot":"","sources":["../../../src/extensions/operation/x-code-samples.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW;;;;EAUvB,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;EAmBxB,CAAA"}
+{"version":3,"file":"x-code-samples.d.ts","sourceRoot":"","sources":["../../../src/extensions/operation/x-code-samples.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW;;;;EAUvB,CAAA;AA0CD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BxB,CAAA"}

package/dist/extensions/operation/x-code-samples.js

@@ -1,4 +1,4 @@
-import { array, object, optional, string } from '@scalar/validation';
+import { array, object, optional, record, string, union, unknown } from '@scalar/validation';
 import { typeCommentInlineCode, typeCommentWithExample } from '../type-comment.js';
 export const XCodeSample = object({
     lang: optional(string({ typeComment: 'Programming language for syntax highlighting' })),
@@ -8,13 +8,44 @@ export const XCodeSample = object({
     typeName: 'XCodeSample',
     typeComment: 'A single code sample for documentation or examples',
 });
+const XReadmeCodeSample = object({
+    language: optional(string({ typeComment: 'Programming language for syntax highlighting' })),
+    code: string({ typeComment: 'Source code for the sample' }),
+    name: optional(string({ typeComment: 'Label shown in the code sample picker' })),
+    install: optional(string({ typeComment: 'Installation instructions for the sample' })),
+    correspondingExample: optional(string({ typeComment: 'Name of the response example this sample maps to' })),
+}, {
+    typeName: 'XReadmeCodeSample',
+    typeComment: 'A single ReadMe custom code sample',
+});
+const XReadme = object({
+    'code-samples': optional(array(XReadmeCodeSample, { typeComment: 'ReadMe custom code samples' })),
+    'samples-languages': optional(array(string(), { typeComment: 'Languages to generate code samples for' })),
+}, {
+    typeName: 'XReadme',
+    typeComment: 'ReadMe extension object. Only code-samples carries source code.',
+});
+const XLanguageExample = object({
+    title: optional(string({ typeComment: 'Label shown in the code sample picker' })),
+    request: optional(record(string(), string(), { typeComment: 'Source code keyed by programming language' })),
+    response: optional(unknown({ typeComment: 'Example response for the request' })),
+}, {
+    typeName: 'XLanguageExample',
+    typeComment: 'Per-language request snippets with an optional title and response',
+});
+/** A single example or an array of examples, as used by x-stainless-examples and x-scalar-examples. */
+const XLanguageExamples = union([XLanguageExample, array(XLanguageExample)]);
 export const XCodeSamples = object({
     'x-codeSamples': optional(array(XCodeSample, { typeComment: 'Code samples (camelCase spelling)' })),
     'x-code-samples': optional(array(XCodeSample, { typeComment: 'Code samples (kebab-case spelling)' })),
     'x-custom-examples': optional(array(XCodeSample, { typeComment: 'Custom code examples for the operation' })),
+    'x-readme': optional(XReadme),
+    'x-stainless-snippets': optional(record(string(), string(), { typeComment: 'Stainless snippets, source code keyed by language' })),
+    'x-stainless-examples': optional(XLanguageExamples),
+    'x-scalar-examples': optional(array(XCodeSample, { typeComment: 'Scalar code samples (same shape as x-codeSamples)' })),
 }, {
     typeName: 'XCodeSamples',
-    typeComment: typeCommentWithExample(`Code samples attached to an operation. Supports ${typeCommentInlineCode('x-codeSamples')}, ${typeCommentInlineCode('x-code-samples')}, and ${typeCommentInlineCode('x-custom-examples')}.`, {
+    typeComment: typeCommentWithExample(`Code samples attached to an operation. Supports ${typeCommentInlineCode('x-codeSamples')}, ${typeCommentInlineCode('x-code-samples')}, ${typeCommentInlineCode('x-custom-examples')}, ${typeCommentInlineCode('x-readme')}, ${typeCommentInlineCode('x-stainless-snippets')}, ${typeCommentInlineCode('x-stainless-examples')}, and ${typeCommentInlineCode('x-scalar-examples')}.`, {
         language: 'yaml',
         body: `x-code-samples:
   - lang: curl

package/dist/openapi/3.1/document.d.ts

@@ -19,7 +19,6 @@ export declare const openApiSchema: import("@scalar/validation").IntersectionSch
     }>, import("@scalar/validation").ObjectSchema<{
         'x-scalar-sdk-installation': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
             lang: import("@scalar/validation").StringSchema;
-            source: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
             description: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
         }>>>;
     }>]>;

package/dist/openapi/3.1/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/document.ts"],"names":[],"mappings":"AA2GA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAGxB,CAAA"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/document.ts"],"names":[],"mappings":"AA2GA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAGxB,CAAA"}

package/dist/openapi/3.1/info.d.ts

@@ -17,7 +17,6 @@ export declare const info: import("@scalar/validation").IntersectionSchema<reado
 }>, import("@scalar/validation").ObjectSchema<{
     'x-scalar-sdk-installation': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
         lang: import("@scalar/validation").StringSchema;
-        source: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
         description: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
     }>>>;
 }>]>;

package/dist/openapi/3.1/info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/info.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;IAuBhB,CAAA"}
+{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/info.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;IAuBhB,CAAA"}

package/dist/openapi/3.1/operation.d.ts

@@ -48,6 +48,31 @@ export declare const operation: import("@scalar/validation").IntersectionSchema<
         label: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
         source: import("@scalar/validation").StringSchema;
     }>>>;
+    'x-readme': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ObjectSchema<{
+        'code-samples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+            language: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            code: import("@scalar/validation").StringSchema;
+            name: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            install: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+            correspondingExample: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        }>>>;
+        'samples-languages': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").StringSchema>>;
+    }>>;
+    'x-stainless-snippets': import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+    'x-stainless-examples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").ObjectSchema<{
+        title: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        request: import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+        response: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnknownSchema>;
+    }>, import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+        title: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        request: import("@scalar/validation").OptionalSchema<import("@scalar/validation").RecordSchema<import("@scalar/validation").StringSchema, import("@scalar/validation").StringSchema>>;
+        response: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnknownSchema>;
+    }>>]>>;
+    'x-scalar-examples': import("@scalar/validation").OptionalSchema<import("@scalar/validation").ArraySchema<import("@scalar/validation").ObjectSchema<{
+        lang: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        label: import("@scalar/validation").OptionalSchema<import("@scalar/validation").StringSchema>;
+        source: import("@scalar/validation").StringSchema;
+    }>>>;
 }>, import("@scalar/validation").ObjectSchema<{
     'x-scalar-stability': import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [import("@scalar/validation").LiteralSchema<"deprecated">, import("@scalar/validation").LiteralSchema<"experimental">, import("@scalar/validation").LiteralSchema<"stable">]>>;
 }>, import("@scalar/validation").ObjectSchema<{

package/dist/openapi/3.1/operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/operation.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiDrB,CAAA"}
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../../src/openapi/3.1/operation.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiDrB,CAAA"}

package/package.json

@@ -14,7 +14,7 @@
     "schemas",
     "scalar"
   ],
-  "version": "0.3.3",
+  "version": "0.4.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,12 +41,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/helpers": "0.8.1",
-    "@scalar/validation": "0.6.0"
+    "@scalar/validation": "0.6.0",
+    "@scalar/helpers": "0.8.1"
   },
   "devDependencies": {
     "vitest": "4.1.0",
-    "@scalar/types": "0.12.3"
+    "@scalar/types": "0.13.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",