@scalar/oas-utils 0.11.1 → 0.12.0

package/dist/spec-getters/get-request-body-from-operation.js

@@ -1,176 +0,0 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
-import { prettyPrintJson } from '@scalar/helpers/json/pretty-print-json';
-import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { normalizeMimeTypeObject } from '../helpers/normalize-mime-type-object.js';
-import { getExampleFromSchema } from './get-example-from-schema.js';
-import { getParametersFromOperation } from './get-parameters-from-operation.js';
-/**
- * Transform the object into a nested array of objects
- * that represent the key-value pairs of the object.
- */
-function getParamsFromObject(obj, nested = false, field) {
-    return Object.entries(obj).flatMap(([key, value]) => {
-        const name = field ?? key;
-        if (Array.isArray(value) && !nested) {
-            return getParamsFromObject(value, true, key);
-        }
-        if (typeof value === 'object' && !(value instanceof File) && value !== null) {
-            // Nested object inside formData field: no way to represent it, so just serialize to JSON string
-            value = JSON.stringify(value);
-        }
-        return [{ name, value }];
-    });
-}
-// Define preferred standard mime types (order indicates preference)
-const standardMimeTypes = [
-    'application/json',
-    'application/octet-stream',
-    'application/x-www-form-urlencoded',
-    'application/xml',
-    'multipart/form-data',
-    'text/plain',
-];
-/**
- * Get the request body from the operation.
- */
-export function getRequestBodyFromOperation(operation, selectedExampleKey, omitEmptyAndOptionalProperties) {
-    const originalContent = operation.requestBody?.content;
-    const content = normalizeMimeTypeObject(originalContent);
-    // First try to find a standard mime type
-    const mimeType = standardMimeTypes.find((currentMimeType) => !!content?.[currentMimeType]) ??
-        (Object.keys(content ?? {})[0] || 'application/json');
-    // Handle JSON-like content types (e.g., application/vnd.github+json)
-    const isJsonLike = mimeType.includes('json') || mimeType.endsWith('+json');
-    /** Examples */
-    const examples = content?.[mimeType]?.examples ?? content?.['application/json']?.examples;
-    // Let's use the first example
-    const selectedExample = examples?.[selectedExampleKey ?? Object.keys(examples ?? {})[0] ?? ''];
-    if (selectedExample) {
-        return {
-            mimeType,
-            text: prettyPrintJson('value' in selectedExample ? selectedExample.value : selectedExample),
-        };
-    }
-    /**
-     * Body Parameters (Swagger 2.0)
-     *
-     * ”The payload that's appended to the HTTP request. Since there can only be one payload, there can only
-     * be one body parameter. The name of the body parameter has no effect on the parameter itself and is used
-     * for documentation purposes only. Since Form parameters are also in the payload, body and form
-     * parameters cannot exist together for the same operation.”
-     */
-    const bodyParameters = getParametersFromOperation(operation.parameters ?? [], 
-    // TODO: Add path parameters
-    [], // operation.path ?? [],
-    'body', false);
-    if (bodyParameters.length > 0) {
-        return {
-            mimeType: 'application/json',
-            text: prettyPrintJson(bodyParameters[0]?.value ?? ''),
-        };
-    }
-    /**
-     * FormData Parameters (Swagger 2.0)
-     *
-     * ”Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded,
-     * multipart/form-data or both are used as the content type of the request (in Swagger's definition, the
-     * consumes property of an operation). This is the only parameter type that can be used to send files,
-     * thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared
-     * together with a body parameter for the same operation. Form parameters have a different format based on
-     * the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
-     * - application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload.
-     *   For example, foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple
-     *   parameters that are being transferred.
-     * - multipart/form-data - each parameter takes a section in the payload with an internal header.
-     *   For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is
-     *   submit-name. This type of form parameters is more commonly used for file transfers.”
-     */
-    const formDataParameters = getParametersFromOperation(operation.parameters ?? [], 
-    // TODO: Add path parameters
-    [], // operation.path ?? [],
-    'formData', false);
-    if (formDataParameters.length > 0) {
-        return {
-            mimeType: 'application/x-www-form-urlencoded',
-            params: formDataParameters.map((parameter) => ({
-                name: parameter.name,
-                /**
-                 * TODO: This value MUST be a string
-                 * Figure out why this is not always a string
-                 *
-                 * JSON.stringify is a TEMPORARY fix
-                 */
-                value: typeof parameter.value === 'string' ? parameter.value : JSON.stringify(parameter.value),
-            })),
-        };
-    }
-    // If no mime type is supported, exit early
-    if (!mimeType) {
-        return null;
-    }
-    // Get the request body object for the mime type
-    const requestBodyObject = content?.[mimeType];
-    // Get example from operation
-    const example = requestBodyObject?.example ? requestBodyObject?.example : undefined;
-    // Update the JSON handling section
-    if (isJsonLike) {
-        const exampleFromSchema = requestBodyObject?.schema
-            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-                mode: 'write',
-                omitEmptyAndOptionalProperties: omitEmptyAndOptionalProperties ?? false,
-            })
-            : null;
-        const body = example ?? exampleFromSchema;
-        return {
-            mimeType,
-            text: body ? (typeof body === 'string' ? body : JSON.stringify(body, null, 2)) : undefined,
-        };
-    }
-    // XML
-    if (mimeType === 'application/xml') {
-        const exampleFromSchema = requestBodyObject?.schema
-            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-                xml: true,
-                mode: 'write',
-            })
-            : null;
-        return {
-            mimeType,
-            text: example ?? json2xml(exampleFromSchema),
-        };
-    }
-    // Binary data
-    if (mimeType === 'application/octet-stream') {
-        return {
-            mimeType,
-            text: 'BINARY',
-        };
-    }
-    // Plain text
-    if (mimeType === 'text/plain') {
-        const exampleFromSchema = requestBodyObject?.schema
-            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-                xml: true,
-                mode: 'write',
-            })
-            : null;
-        return {
-            mimeType,
-            text: example ?? exampleFromSchema ?? '',
-        };
-    }
-    // URL encoded data
-    if (mimeType === 'multipart/form-data' || mimeType === 'application/x-www-form-urlencoded') {
-        const exampleFromSchema = requestBodyObject?.schema
-            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-                xml: true,
-                mode: 'write',
-            })
-            : null;
-        return {
-            mimeType,
-            params: getParamsFromObject(example ?? exampleFromSchema ?? {}),
-        };
-    }
-    return null;
-}

package/dist/spec-getters/get-server-variable-examples.d.ts

@@ -1,4 +0,0 @@
-import type { Server } from '../entities/spec/server.js';
-/** Retrieve example values for server variables */
-export declare const getServerVariableExamples: (server: Server) => Record<string, string[]>;
-//# sourceMappingURL=get-server-variable-examples.d.ts.map

package/dist/spec-getters/get-server-variable-examples.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"get-server-variable-examples.d.ts","sourceRoot":"","sources":["../../src/spec-getters/get-server-variable-examples.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAEpD,mDAAmD;AACnD,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,6BAUvD,CAAA"}

package/dist/spec-getters/get-server-variable-examples.js

@@ -1,12 +0,0 @@
-/** Retrieve example values for server variables */
-export const getServerVariableExamples = (server) => {
-    const examples = {};
-    if (server.variables) {
-        for (const [key, variable] of Object.entries(server.variables)) {
-            examples[key] = variable.enum?.filter((v) => typeof v === 'string') ?? [
-                variable.default,
-            ];
-        }
-    }
-    return examples;
-};

package/dist/spec-getters/index.d.ts

@@ -1,5 +0,0 @@
-export { getExampleFromSchema } from './get-example-from-schema.js';
-export { getParametersFromOperation } from './get-parameters-from-operation.js';
-export { getRequestBodyFromOperation } from './get-request-body-from-operation.js';
-export { getServerVariableExamples } from './get-server-variable-examples.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/spec-getters/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spec-getters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,OAAO,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAA;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA"}

package/dist/spec-getters/index.js

@@ -1,4 +0,0 @@
-export { getExampleFromSchema } from './get-example-from-schema.js';
-export { getParametersFromOperation } from './get-parameters-from-operation.js';
-export { getRequestBodyFromOperation } from './get-request-body-from-operation.js';
-export { getServerVariableExamples } from './get-server-variable-examples.js';

package/dist/transforms/import-spec.d.ts

@@ -1,64 +0,0 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
-import type { ApiReferenceConfiguration } from '@scalar/types/api-reference';
-import { type SecurityScheme } from '@scalar/types/entities';
-import type { UnknownObject } from '@scalar/types/utils';
-import type { SelectedSecuritySchemeUids } from '../entities/shared/utility.js';
-import { type Collection, type CollectionPayload } from '../entities/spec/collection.js';
-import { type RequestExample } from '../entities/spec/request-examples.js';
-import { type Request } from '../entities/spec/requests.js';
-import { type Server } from '../entities/spec/server.js';
-import { type Tag } from '../entities/spec/spec-objects.js';
-/** Takes a string or object and parses it into an openapi spec compliant schema */
-export declare const parseSchema: (originalDocument: string | UnknownObject | undefined, { shouldLoad, dereferencedDocument, }?: {
-    shouldLoad?: boolean;
-    dereferencedDocument?: OpenAPIV3_1.Document;
-}) => Promise<{
-    /**
-     * Temporary fix for the parser returning an empty array
-     * TODO: remove this once the parser is fixed
-     */
-    schema: OpenAPIV3_1.Document;
-    errors: import("@scalar/openapi-parser").ErrorObject[];
-}>;
-/** Converts selected security requirements to uids */
-export declare const getSelectedSecuritySchemeUids: (securityRequirements: (string | string[])[], preferredSecurityNames: (string | string[])[] | undefined, securitySchemeMap: Record<string, SecurityScheme["uid"]>) => SelectedSecuritySchemeUids;
-/** Create a "uid" from a slug */
-export declare const getSlugUid: (slug: string) => Collection["uid"];
-export type ImportSpecToWorkspaceArgs = Pick<CollectionPayload, 'documentUrl' | 'watchMode'> & Pick<ApiReferenceConfiguration, 'authentication' | 'baseServerURL' | 'servers' | 'slug'> & {
-    /** The dereferenced document */
-    dereferencedDocument?: OpenAPIV3_1.Document;
-    /** Sets the preferred security scheme on the collection instead of the requests */
-    useCollectionSecurity?: boolean;
-    /** Call the load step from the parser */
-    shouldLoad?: boolean;
-};
-/**
- * Imports an OpenAPI document and converts it to workspace entities (Collection, Request, Server, etc.)
- *
- * The imported entities maintain a close mapping to the original OpenAPI specification to enable:
- * - Bi-directional translation between spec and workspace entities
- * - Preservation of specification details and structure
- * - Accurate representation of relationships between components
- *
- * Relationships between entities are maintained through unique identifiers (UIDs) which allow:
- * - Flexible organization at different levels (workspace, collection, request)
- * - Proper linking between related components
- * - Easy lookup and reference of dependent entities
- */
-export declare function importSpecToWorkspace(content: string | UnknownObject | undefined, { 
-/** If a dereferenced document is provided, we will skip the dereferencing step. */
-dereferencedDocument, authentication, baseServerURL, documentUrl, servers: configuredServers, useCollectionSecurity, slug, shouldLoad, watchMode, }?: ImportSpecToWorkspaceArgs): Promise<{
-    error: false;
-    collection: Collection;
-    requests: Request[];
-    schema: OpenAPIV3_1.Document;
-    examples: RequestExample[];
-    servers: Server[];
-    tags: Tag[];
-    securitySchemes: SecurityScheme[];
-} | {
-    error: true;
-    importWarnings: string[];
-    collection: undefined;
-}>;
-//# sourceMappingURL=import-spec.d.ts.map

package/dist/transforms/import-spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"import-spec.d.ts","sourceRoot":"","sources":["../../src/transforms/import-spec.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAE5E,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGxD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAC3E,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAoB,MAAM,4BAA4B,CAAA;AAEtG,OAAO,EAAE,KAAK,cAAc,EAA4B,MAAM,kCAAkC,CAAA;AAChG,OAAO,EAAE,KAAK,OAAO,EAAsC,MAAM,0BAA0B,CAAA;AAC3F,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,KAAK,GAAG,EAAa,MAAM,8BAA8B,CAAA;AA6ClE,mFAAmF;AACnF,eAAO,MAAM,WAAW,GACtB,kBAAkB,MAAM,GAAG,aAAa,GAAG,SAAS,EACpD,wCAIG;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,oBAAoB,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;CAAO;IAkB3E;;;OAGG;YAC8C,WAAW,CAAC,QAAQ;;EAGxE,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,GACxC,sBAAsB,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,EAC3C,wBAAwB,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,YAAK,EAClD,mBAAmB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,KACvD,0BAaF,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAA2B,UAAU,CAAC,KAAK,CAAC,CAAA;AAEnF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,iBAAiB,EAAE,aAAa,GAAG,WAAW,CAAC,GAC1F,IAAI,CAAC,yBAAyB,EAAE,gBAAgB,GAAG,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC,GAAG;IACzF,gCAAgC;IAChC,oBAAoB,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;IAC3C,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,EAC3C;AACE,mFAAmF;AACnF,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,WAAW,EACX,OAAO,EAAE,iBAAiB,EAC1B,qBAA6B,EAC7B,IAAI,EACJ,UAAU,EACV,SAAiB,GAClB,GAAE,yBAA8B,GAChC,OAAO,CACN;IACE,KAAK,EAAE,KAAK,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAA;IAC5B,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,eAAe,EAAE,cAAc,EAAE,CAAA;CAClC,GACD;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,SAAS,CAAA;CAAE,CACnE,CA4WA"}