@mintlify/common 1.0.1202 → 1.0.1203

package/dist/openapi/additionalOperations.d.ts

@@ -0,0 +1,5 @@
+import { type OpenAPIV3_2 } from '@mintlify/validation';
+import type { OpenApiValidateError } from './validate.js';
+type PathItemSources = Partial<Pick<OpenAPIV3_2.Document, 'paths' | 'webhooks' | 'components'>>;
+export declare const validateAdditionalOperations: (document: PathItemSources) => OpenApiValidateError[];
+export {};

package/dist/openapi/additionalOperations.js

@@ -0,0 +1,63 @@
+import { getPathItemOperations, isAdditionalHttpMethod, isFixedHttpMethod, } from '@mintlify/validation';
+const escapePointer = (segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1');
+const callbackPathItemsOf = (location, pathItem) => {
+    if (!pathItem || '$ref' in pathItem)
+        return [];
+    return getPathItemOperations(pathItem).flatMap(([method, operation]) => {
+        const callbacks = operation.callbacks;
+        if (!callbacks)
+            return [];
+        const operationPointer = isFixedHttpMethod(method)
+            ? escapePointer(method)
+            : `additionalOperations/${escapePointer(method)}`;
+        return Object.entries(callbacks).flatMap(([name, callback]) => {
+            if (!callback || '$ref' in callback)
+                return [];
+            return Object.entries(callback).flatMap(([expression, item]) => {
+                const itemLocation = `${location}/${operationPointer}/callbacks/${escapePointer(name)}/${escapePointer(expression)}`;
+                const entry = [itemLocation, item];
+                return [entry, ...callbackPathItemsOf(itemLocation, item)];
+            });
+        });
+    });
+};
+const pathItemsOf = (document) => {
+    var _a, _b, _c, _d, _e, _f;
+    const roots = [
+        ...Object.entries((_a = document.paths) !== null && _a !== void 0 ? _a : {}).map(([path, item]) => [`/paths/${escapePointer(path)}`, item]),
+        ...Object.entries((_b = document.webhooks) !== null && _b !== void 0 ? _b : {}).map(([name, item]) => [
+            `/webhooks/${escapePointer(name)}`,
+            item,
+        ]),
+        ...Object.entries((_d = (_c = document.components) === null || _c === void 0 ? void 0 : _c.pathItems) !== null && _d !== void 0 ? _d : {}).map(([name, item]) => [
+            `/components/pathItems/${escapePointer(name)}`,
+            item,
+        ]),
+        ...Object.entries((_f = (_e = document.components) === null || _e === void 0 ? void 0 : _e.callbacks) !== null && _f !== void 0 ? _f : {}).flatMap(([name, callback]) => {
+            if (!callback || '$ref' in callback)
+                return [];
+            return Object.entries(callback).map(([expression, item]) => [
+                `/components/callbacks/${escapePointer(name)}/${escapePointer(expression)}`,
+                item,
+            ]);
+        }),
+    ];
+    return roots.flatMap((root) => [root, ...callbackPathItemsOf(root[0], root[1])]);
+};
+export const validateAdditionalOperations = (document) => {
+    const errors = [];
+    for (const [location, pathItem] of pathItemsOf(document)) {
+        if (!pathItem || !('additionalOperations' in pathItem) || !pathItem.additionalOperations) {
+            continue;
+        }
+        for (const method of Object.keys(pathItem.additionalOperations)) {
+            if (!isAdditionalHttpMethod(method)) {
+                errors.push({
+                    path: `${location}/additionalOperations/${method}`,
+                    message: 'additionalOperations methods must be uppercase, must not duplicate a fixed method, and cannot be WEBHOOK',
+                });
+            }
+        }
+    }
+    return errors;
+};

package/dist/openapi/filenameUtils.d.ts

@@ -1,3 +1,3 @@
 import { NavigationEntry } from '@mintlify/models';
 export declare const prepareStringToBeValidFilename: (str?: string) => string | undefined;
-export declare const generateUniqueFilenameWithoutExtension: (pages: NavigationEntry[], base: string) => string;
+export declare const generateUniqueFilenameWithoutExtension: (pages: NavigationEntry[] | Readonly<Record<string, unknown>>, base: string) => string;

package/dist/openapi/filenameUtils.js

@@ -9,11 +9,17 @@ export const prepareStringToBeValidFilename = (str) => str
         .toLowerCase()
     : undefined;
 export const generateUniqueFilenameWithoutExtension = (pages, base) => {
+    const hasFilename = (filename) => {
+        const candidate = filename.toLowerCase();
+        return Array.isArray(pages)
+            ? pages.includes(candidate)
+            : Object.prototype.hasOwnProperty.call(pages, candidate);
+    };
     let filename = base;
-    if (pages.includes(filename)) {
+    if (hasFilename(filename)) {
         let extension = 1;
         filename = `${base}-${extension}`;
-        while (pages.includes(filename)) {
+        while (hasFilename(filename)) {
             extension += 1;
             filename = `${base}-${extension}`;
         }

package/dist/openapi/findNavGroup.d.ts

@@ -1,5 +1,5 @@
-import { DecoratedGroupsConfig, DecoratedPagesConfig, GroupsConfig, PagesConfig } from '@mintlify/validation';
+import { DecoratedPagesConfig, PagesConfig } from '@mintlify/validation';
 export declare const DEFAULT_API_GROUP_NAME = "API Reference";
 export declare const DEFAULT_WEBSOCKETS_GROUP_NAME = "Websockets";
-export declare function findNavGroup(nav: GroupsConfig, groupName?: string): PagesConfig;
-export declare function findNavGroup(nav: DecoratedGroupsConfig, groupName?: string): DecoratedPagesConfig;
+export declare function findNavGroup(nav: PagesConfig, groupName?: string, tagKey?: string): PagesConfig;
+export declare function findNavGroup(nav: DecoratedPagesConfig, groupName?: string, tagKey?: string): DecoratedPagesConfig;

package/dist/openapi/findNavGroup.js

@@ -1,12 +1,18 @@
 export const DEFAULT_API_GROUP_NAME = 'API Reference';
 export const DEFAULT_WEBSOCKETS_GROUP_NAME = 'Websockets';
-export function findNavGroup(nav, groupName = DEFAULT_API_GROUP_NAME) {
-    const group = nav.find((fileOrGroup) => typeof fileOrGroup === 'object' && 'group' in fileOrGroup && fileOrGroup.group === groupName);
-    if (group === undefined || !('pages' in group)) {
+const tagKeys = new WeakMap();
+export function findNavGroup(nav, groupName = DEFAULT_API_GROUP_NAME, tagKey) {
+    const group = nav.find((fileOrGroup) => typeof fileOrGroup === 'object' &&
+        'group' in fileOrGroup &&
+        fileOrGroup.group === groupName &&
+        (tagKey === undefined || tagKeys.get(fileOrGroup) === tagKey));
+    if (group === undefined || typeof group !== 'object' || !('pages' in group)) {
         const newGroup = {
             group: groupName,
             pages: [],
         };
+        if (tagKey !== undefined)
+            tagKeys.set(newGroup, tagKey);
         nav.push(newGroup);
         return newGroup.pages;
     }

package/dist/openapi/generateOpenApiPages.d.ts

@@ -4,7 +4,8 @@
  * but without Node.js dependencies (fs, path, etc.).
  */
 import type { PageMetaTags } from '@mintlify/models';
-import { OpenAPIV3 } from 'openapi-types';
+import { type DocumentV3 } from '@mintlify/validation';
+import { type OpenApiTagGroup } from './tagHierarchy.js';
 /**
  * Build MDX content string matching what createOpenApiFrontmatter produces in prebuild.
  * Includes title, description, openapi tag, version, deprecated, and all x-mint metadata
@@ -28,6 +29,7 @@ export type GeneratedApiPage = {
     path: string;
     /** Operation tag (used for sub-grouping) */
     tag?: string;
+    tagPath?: OpenApiTagGroup[];
     /** Whether the operation is x-hidden */
     hidden?: boolean;
     /** Whether this is a webhook */
@@ -41,7 +43,7 @@ export type GeneratedApiPage = {
 };
 export type GenerateOpenApiPagesOptions = {
     /** Parsed OpenAPI v3 document */
-    spec: OpenAPIV3.Document;
+    spec: DocumentV3;
     /** File path of the spec, e.g. "api-reference/openapi.json" */
     specFilePath: string;
     /** Output directory for slug generation, defaults to "api-reference" */

package/dist/openapi/generateOpenApiPages.js

@@ -1,12 +1,12 @@
+import { getPathItemOperations } from '@mintlify/validation';
 import jsYaml from 'js-yaml';
-import { OpenAPIV3 } from 'openapi-types';
 import { optionallyAddLeadingSlash } from '../fs/optionallySlash.js';
 import { mergePageGroups } from '../navigation/groupAccess.js';
 import { slugToTitle } from '../slug/slugToTitle.js';
 import { buildOpenApiMetaTag } from './buildOpenApiMetaTag.js';
 import { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, } from './filenameUtils.js';
 import { getOpenApiTitleAndDescription } from './getOpenApiTitleAndDescription.js';
-import { getTagDisplayName } from './getTagDisplayName.js';
+import { createOpenApiBadgeResolver, createOpenApiTagResolver, isOpenApi32, } from './tagHierarchy.js';
 /**
  * Build MDX content string matching what createOpenApiFrontmatter produces in prebuild.
  * Includes title, description, openapi tag, version, deprecated, and all x-mint metadata
@@ -73,11 +73,14 @@ function getXMintGroups(pathObject, operationObject) {
     return groups;
 }
 export function generateOpenApiPages(opts) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
     const { spec, specFilePath, outputDirectory } = opts;
     const outDir = outputDirectory !== null && outputDirectory !== void 0 ? outputDirectory : DEFAULT_OUTPUT_DIR;
     const openApiFilePathFromRoot = optionallyAddLeadingSlash(specFilePath);
     const pages = [];
+    const resolveTags = createOpenApiTagResolver(spec);
+    const nestedTags = isOpenApi32(spec);
+    const resolveBadge = createOpenApiBadgeResolver(spec);
     // Track used filenames for uniqueness (mirrors the nav array in processOpenApiPath)
     const usedFilenames = [];
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -89,26 +92,23 @@ export function generateOpenApiPages(opts) {
         },
     ];
     // Process paths
-    for (const [apiPath, pathItemObject] of Object.entries(spec.paths)) {
+    for (const [apiPath, pathItemObject] of Object.entries((_b = spec.paths) !== null && _b !== void 0 ? _b : {})) {
         if (!pathItemObject || typeof pathItemObject !== 'object')
             continue;
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         const pathItem = pathItemObject;
-        for (const method of Object.values(OpenAPIV3.HttpMethods)) {
-            if (!(method in pathItem))
-                continue;
+        for (const [method, pathOperation] of getPathItemOperations(pathItem)) {
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-            const operation = pathItem[method];
-            if (!operation)
-                continue;
+            const operation = pathOperation;
             if (operation['x-excluded'])
                 continue;
             const xMint = operation['x-mint'];
             const xMintGroups = getXMintGroups(pathItem, operation);
-            const tagName = (_b = operation.tags) === null || _b === void 0 ? void 0 : _b[0];
-            const groupName = getTagDisplayName(tagName, spec);
-            let title = (_c = prepareStringToBeValidFilename(operation.summary)) !== null && _c !== void 0 ? _c : `${method}-${prepareStringToBeValidFilename(apiPath)}`;
-            let folder = (_d = prepareStringToBeValidFilename(tagName)) !== null && _d !== void 0 ? _d : '';
+            const tagPath = resolveTags(operation.tags);
+            const tagName = (_c = tagPath.at(-1)) === null || _c === void 0 ? void 0 : _c.name;
+            const groupName = (_d = tagPath.at(-1)) === null || _d === void 0 ? void 0 : _d.label;
+            let title = (_e = prepareStringToBeValidFilename(operation.summary)) !== null && _e !== void 0 ? _e : `${method.toLowerCase()}-${prepareStringToBeValidFilename(apiPath)}`;
+            let folder = (_f = prepareStringToBeValidFilename(tagName)) !== null && _f !== void 0 ? _f : '';
             let base = posixJoin(outDir, folder, title);
             if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                 const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -129,20 +129,11 @@ export function generateOpenApiPages(opts) {
             if (xMintGroups.length > 0) {
                 xMintMetadata = Object.assign(Object.assign({}, xMintMetadata), { groups: mergePageGroups(xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.groups, xMintGroups) });
             }
-            const page = {
-                title: (_f = (_e = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _e !== void 0 ? _e : titleTag) !== null && _f !== void 0 ? _f : slugToTitle(filenameWithoutExtension),
-                description: (_g = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _g !== void 0 ? _g : description,
-                deprecated: (_h = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _h !== void 0 ? _h : operation.deprecated,
-                openapi: openapiMetaTag,
-                href: posixResolve('/', filenameWithoutExtension),
-                method,
-                path: apiPath,
-                tag: groupName,
-                hidden: operation['x-hidden'] === true,
-                xMintMetadata,
-                xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content,
-                version: opts.version,
-            };
+            const badge = resolveBadge(operation.tags);
+            if (badge !== undefined && (xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.tag) === undefined) {
+                xMintMetadata = Object.assign(Object.assign({}, xMintMetadata), { tag: badge });
+            }
+            const page = Object.assign(Object.assign({ title: (_h = (_g = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _g !== void 0 ? _g : titleTag) !== null && _h !== void 0 ? _h : slugToTitle(filenameWithoutExtension), description: (_j = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _j !== void 0 ? _j : description, deprecated: (_k = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _k !== void 0 ? _k : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method, path: apiPath, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
             pages.push(page);
         }
     }
@@ -157,20 +148,17 @@ export function generateOpenApiPages(opts) {
                 continue;
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
             const pathItem = webhookObject;
-            for (const method of Object.values(OpenAPIV3.HttpMethods)) {
-                if (!(method in pathItem))
-                    continue;
+            for (const [, pathOperation] of getPathItemOperations(pathItem)) {
                 // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-                const operation = pathItem[method];
-                if (!operation)
-                    continue;
+                const operation = pathOperation;
                 if (operation['x-excluded'])
                     continue;
                 const xMint = operation['x-mint'];
-                const tagName = (_j = operation.tags) === null || _j === void 0 ? void 0 : _j[0];
-                const groupName = getTagDisplayName(tagName, spec);
-                let title = (_k = prepareStringToBeValidFilename(operation.summary)) !== null && _k !== void 0 ? _k : `${prepareStringToBeValidFilename(webhook)}`;
-                let folder = (_l = prepareStringToBeValidFilename(tagName)) !== null && _l !== void 0 ? _l : '';
+                const tagPath = resolveTags(operation.tags);
+                const tagName = (_l = tagPath.at(-1)) === null || _l === void 0 ? void 0 : _l.name;
+                const groupName = (_m = tagPath.at(-1)) === null || _m === void 0 ? void 0 : _m.label;
+                let title = (_o = prepareStringToBeValidFilename(operation.summary)) !== null && _o !== void 0 ? _o : `${prepareStringToBeValidFilename(webhook)}`;
+                let folder = (_p = prepareStringToBeValidFilename(tagName)) !== null && _p !== void 0 ? _p : '';
                 let base = posixJoin(outDir, folder, title);
                 if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                     const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -186,21 +174,10 @@ export function generateOpenApiPages(opts) {
                     method: 'webhook',
                     path: webhook,
                 });
-                const page = {
-                    title: (_o = (_m = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _m === void 0 ? void 0 : _m.title) !== null && _o !== void 0 ? _o : slugToTitle(filenameWithoutExtension),
-                    description: (_q = (_p = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _p === void 0 ? void 0 : _p.description) !== null && _q !== void 0 ? _q : operation.description,
-                    deprecated: (_s = (_r = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _r === void 0 ? void 0 : _r.deprecated) !== null && _s !== void 0 ? _s : operation.deprecated,
-                    openapi: openapiMetaTag,
-                    href: posixResolve('/', filenameWithoutExtension),
-                    method: 'webhook',
-                    path: webhook,
-                    tag: groupName,
-                    hidden: operation['x-hidden'] === true,
-                    isWebhook: true,
-                    xMintMetadata: xMint === null || xMint === void 0 ? void 0 : xMint.metadata,
-                    xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content,
-                    version: opts.version,
-                };
+                const badge = resolveBadge(operation.tags);
+                const xMintMetadata = badge !== undefined && ((_q = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _q === void 0 ? void 0 : _q.tag) === undefined
+                    ? Object.assign(Object.assign({}, xMint === null || xMint === void 0 ? void 0 : xMint.metadata), { tag: badge }) : xMint === null || xMint === void 0 ? void 0 : xMint.metadata;
+                const page = Object.assign(Object.assign({ title: (_s = (_r = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _r === void 0 ? void 0 : _r.title) !== null && _s !== void 0 ? _s : slugToTitle(filenameWithoutExtension), description: (_u = (_t = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _t === void 0 ? void 0 : _t.description) !== null && _u !== void 0 ? _u : operation.description, deprecated: (_w = (_v = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _v === void 0 ? void 0 : _v.deprecated) !== null && _w !== void 0 ? _w : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method: 'webhook', path: webhook, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, isWebhook: true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
                 pages.push(page);
             }
         }

package/dist/openapi/getOpenApiOperationMethodAndEndpoint.js

@@ -1,3 +1,4 @@
+import { httpMethods, isFixedHttpMethod, parseHttpMethod } from '@mintlify/validation';
 import { findOpenApiPath } from './findOpenApiPath.js';
 import { potentiallyParseOpenApiString } from './parseOpenApiString.js';
 export const getOpenApiOperationMethodAndEndpoint = (endpointStr, openApiFiles) => {
@@ -35,24 +36,28 @@ export const getOpenApiOperationMethodAndEndpoint = (endpointStr, openApiFiles)
     };
 };
 const getOperation = (method, pathObject) => {
-    const methods = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+    var _a;
     if (method !== undefined) {
-        const lowerMethod = method.toLowerCase();
-        if (methods.includes(lowerMethod) && lowerMethod in pathObject) {
-            return {
-                method: lowerMethod,
-                operation: pathObject[lowerMethod],
-            };
+        const parsed = parseHttpMethod(method);
+        if (parsed === undefined)
+            return undefined;
+        if (isFixedHttpMethod(parsed)) {
+            return parsed in pathObject
+                ? {
+                    method: parsed,
+                    operation: pathObject[parsed],
+                }
+                : undefined;
         }
+        const operation = 'additionalOperations' in pathObject ? (_a = pathObject.additionalOperations) === null || _a === void 0 ? void 0 : _a[parsed] : undefined;
+        return operation ? { method: parsed, operation } : undefined;
     }
-    else {
-        for (const method of methods) {
-            if (method in pathObject) {
-                return {
-                    method,
-                    operation: pathObject[method],
-                };
-            }
+    for (const fixedMethod of httpMethods) {
+        if (fixedMethod in pathObject) {
+            return {
+                method: fixedMethod,
+                operation: pathObject[fixedMethod],
+            };
         }
     }
     return undefined;

package/dist/openapi/getTagDisplayName.d.ts

@@ -2,4 +2,4 @@ import { OpenAPI } from 'openapi-types';
 /**
  * Resolves the display name for a tag. Prioritizes x-group extension, falls back to tag name.
  */
-export declare const getTagDisplayName: (tagName: string | undefined, schema: OpenAPI.Document) => string | undefined;
+export declare const getTagDisplayName: (tagName: string | undefined, schema: Pick<OpenAPI.Document, "tags">) => string | undefined;

package/dist/openapi/index.d.ts

@@ -18,3 +18,4 @@ export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension,
 export { findNavGroup, DEFAULT_API_GROUP_NAME, DEFAULT_WEBSOCKETS_GROUP_NAME, } from './findNavGroup.js';
 export { generateOpenApiPages, buildGeneratedMdxContent, type GeneratedApiPage, type GenerateOpenApiPagesOptions, } from './generateOpenApiPages.js';
 export { getTagDisplayName } from './getTagDisplayName.js';
+export { createOpenApiBadgeResolver, createOpenApiTagResolver, findOpenApiNavGroup, isOpenApi32, validateOpenApiTagTree, type OpenApiTag, type OpenApiTagGroup, } from './tagHierarchy.js';

package/dist/openapi/index.js

@@ -18,3 +18,4 @@ export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension,
 export { findNavGroup, DEFAULT_API_GROUP_NAME, DEFAULT_WEBSOCKETS_GROUP_NAME, } from './findNavGroup.js';
 export { generateOpenApiPages, buildGeneratedMdxContent, } from './generateOpenApiPages.js';
 export { getTagDisplayName } from './getTagDisplayName.js';
+export { createOpenApiBadgeResolver, createOpenApiTagResolver, findOpenApiNavGroup, isOpenApi32, validateOpenApiTagTree, } from './tagHierarchy.js';

package/dist/openapi/parseApiString.js

@@ -1,4 +1,4 @@
-import { OpenAPIV3 } from 'openapi-types';
+import { isFixedHttpMethod, parseHttpMethod, } from '@mintlify/validation';
 import { isAbsoluteUrl } from '../isAbsoluteUrl.js';
 import { isDocsConfig } from '../isDocsConfig.js';
 export const parseApiString = (apiString, config) => {
@@ -6,21 +6,19 @@ export const parseApiString = (apiString, config) => {
     if (!components[0] || !components[1] || components.length > 2) {
         throw new Error('improperly formatted api string');
     }
-    const upperMethod = components[0];
+    const method = parseHttpMethod(components[0]);
     const endpointStr = components[1];
-    const method = upperMethod.toLowerCase();
-    if (!VALID_METHODS.includes(method)) {
+    if (method === undefined || (!isFixedHttpMethod(method) && method !== components[0])) {
         throw new Error('invalid http method');
     }
     const { origin, path } = parseEndpoint(endpointStr);
     const servers = origin ? [{ url: origin }] : parseServers(config);
     return {
         path,
-        method: method,
+        method,
         servers,
     };
 };
-const VALID_METHODS = Object.values(OpenAPIV3.HttpMethods);
 const parseEndpoint = (endpoint) => {
     if (!isAbsoluteUrl(endpoint)) {
         return {

package/dist/openapi/parseOpenApiString.d.ts

@@ -1,4 +1,5 @@
-import { OpenAPIV3 } from 'openapi-types';
+import { type HttpMethod } from '@mintlify/validation';
+export type OpenApiStringMethod = HttpMethod | 'webhook';
 /**
  *
  * @param str either the openapi or api string defined in the frontmatter
@@ -8,7 +9,7 @@ import { OpenAPIV3 } from 'openapi-types';
  *          returns undefined for any of the values (fails silently)
  */
 export declare const potentiallyParseOpenApiString: (str: string) => {
-    method: OpenAPIV3.HttpMethods;
+    method: OpenApiStringMethod;
     endpoint: string;
     filename?: string;
 } | undefined;
@@ -20,7 +21,7 @@ export declare const potentiallyParseOpenApiString: (str: string) => {
  *          filename: filename of the openapi file (if applicable)
  */
 export declare const parseOpenApiString: (str: string) => {
-    method: OpenAPIV3.HttpMethods;
+    method: OpenApiStringMethod;
     endpoint: string;
     filename?: string;
 };

package/dist/openapi/parseOpenApiString.js

@@ -1,5 +1,5 @@
-import { OpenAPIV3 } from 'openapi-types';
-const VALID_METHODS = Object.values(OpenAPIV3.HttpMethods).concat('webhook');
+import { isFixedHttpMethod, parseHttpMethod } from '@mintlify/validation';
+const parseMethod = (method) => method.toLowerCase() === 'webhook' ? 'webhook' : parseHttpMethod(method);
 /**
  *
  * @param str either the openapi or api string defined in the frontmatter
@@ -11,34 +11,36 @@ const VALID_METHODS = Object.values(OpenAPIV3.HttpMethods).concat('webhook');
 export const potentiallyParseOpenApiString = (str) => {
     const components = str.trim().split(/\s+/);
     let filename;
-    let method;
+    let rawMethod;
     let endpoint;
     if (components.length > 3) {
         // improperly formatted openapi string
         return undefined;
     }
     else if (components[0] && components[1] && components[2]) {
-        [filename, method, endpoint] = components;
+        [filename, rawMethod, endpoint] = components;
     }
     else if (components[0] && components[1]) {
-        [method, endpoint] = components;
+        [rawMethod, endpoint] = components;
     }
     else {
         // improperly formatted openapi string
         return undefined;
     }
-    if (method) {
-        method = method.toLowerCase();
-        if (!VALID_METHODS.includes(method)) {
-            // invalid http method
-            return undefined;
-        }
+    const method = parseMethod(rawMethod);
+    if (method === undefined) {
+        // invalid http method
+        return undefined;
     }
-    return {
-        method: method,
-        endpoint,
-        filename,
-    };
+    if (!isFixedHttpMethod(method) &&
+        method !== 'webhook' &&
+        (rawMethod !== method || !endpoint.startsWith('/'))) {
+        return undefined;
+    }
+    if (method === 'query' && !endpoint.startsWith('/')) {
+        return undefined;
+    }
+    return { method, endpoint, filename };
 };
 /**
  *
@@ -50,29 +52,25 @@ export const potentiallyParseOpenApiString = (str) => {
 export const parseOpenApiString = (str) => {
     const components = str.trim().split(/\s+/);
     let filename;
-    let method;
+    let rawMethod;
     let endpoint;
     if (components.length > 3) {
         throw new Error('improperly formatted openapi string');
     }
     else if (components[0] && components[1] && components[2]) {
-        [filename, method, endpoint] = components;
+        [filename, rawMethod, endpoint] = components;
     }
     else if (components[0] && components[1]) {
-        [method, endpoint] = components;
+        [rawMethod, endpoint] = components;
     }
     else {
         throw new Error('improperly formatted openapi string');
     }
-    method = method.toLowerCase();
-    if (!VALID_METHODS.includes(method)) {
+    const method = parseMethod(rawMethod);
+    if (method === undefined) {
         throw new Error('invalid http method');
     }
-    return {
-        method: method,
-        endpoint,
-        filename,
-    };
+    return { method, endpoint, filename };
 };
 /**
  * same as above, but for openapi-schema frontmatter

package/dist/openapi/querystringParameters.d.ts

@@ -0,0 +1,5 @@
+import { type OpenAPIV3_2 } from '@mintlify/validation';
+import type { OpenApiValidateError } from './validate.js';
+type PathItemSources = Partial<Pick<OpenAPIV3_2.Document, 'paths' | 'webhooks' | 'components'>>;
+export declare const validateQuerystringParameters: (document: PathItemSources) => OpenApiValidateError[];
+export {};

package/dist/openapi/querystringParameters.js

@@ -0,0 +1,81 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { getPathItemOperations, isFixedHttpMethod } from '@mintlify/validation';
+const escapePointer = (segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1');
+const componentName = (ref, section) => { var _a; return (_a = new RegExp(`^#/components/${section}/(.+)$`).exec(ref)) === null || _a === void 0 ? void 0 : _a[1]; };
+const resolveParameter = (parameter, components, seen = new Set()) => {
+    var _a;
+    if (!('$ref' in parameter))
+        return parameter;
+    const name = componentName(parameter.$ref, 'parameters');
+    if (name === undefined || seen.has(name))
+        return undefined;
+    const resolved = (_a = components === null || components === void 0 ? void 0 : components.parameters) === null || _a === void 0 ? void 0 : _a[name];
+    return resolved ? resolveParameter(resolved, components, seen.add(name)) : undefined;
+};
+const parameterLocation = (parameter, components) => { var _a; return (_a = resolveParameter(parameter, components)) === null || _a === void 0 ? void 0 : _a.in; };
+const querystringNames = (parameters, components) => new Set(parameters.flatMap((parameter) => {
+    const resolved = resolveParameter(parameter, components);
+    return (resolved === null || resolved === void 0 ? void 0 : resolved.in) === 'querystring' ? [resolved.name] : [];
+}));
+const resolvePathItem = (pathItem, components, seen = new Set()) => {
+    var _a;
+    if (!('$ref' in pathItem) || typeof pathItem.$ref !== 'string')
+        return pathItem;
+    const { $ref, summary, description } = pathItem, siblings = __rest(pathItem, ["$ref", "summary", "description"]);
+    const name = componentName($ref, 'pathItems');
+    const target = name !== undefined && !seen.has(name) ? (_a = components === null || components === void 0 ? void 0 : components.pathItems) === null || _a === void 0 ? void 0 : _a[name] : undefined;
+    const resolvedTarget = target && name !== undefined ? resolvePathItem(target, components, seen.add(name)) : {};
+    return Object.assign(Object.assign(Object.assign({}, resolvedTarget), siblings), { summary, description });
+};
+export const validateQuerystringParameters = (document) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const errors = [];
+    const pathItems = [
+        ...Object.entries((_a = document.paths) !== null && _a !== void 0 ? _a : {}).map(([path, item]) => [`/paths/${escapePointer(path)}`, item]),
+        ...Object.entries((_b = document.webhooks) !== null && _b !== void 0 ? _b : {}).map(([name, item]) => [
+            `/webhooks/${escapePointer(name)}`,
+            item,
+        ]),
+        ...Object.entries((_d = (_c = document.components) === null || _c === void 0 ? void 0 : _c.pathItems) !== null && _d !== void 0 ? _d : {}).map(([name, item]) => [
+            `/components/pathItems/${escapePointer(name)}`,
+            item,
+        ]),
+    ];
+    for (const [location, rawPathItem] of pathItems) {
+        if (!rawPathItem)
+            continue;
+        const pathItem = resolvePathItem(rawPathItem, document.components);
+        const pathLocations = ((_e = pathItem.parameters) !== null && _e !== void 0 ? _e : []).map((parameter) => parameterLocation(parameter, document.components));
+        for (const [method, operation] of getPathItemOperations(pathItem)) {
+            const operationLocations = ((_f = operation.parameters) !== null && _f !== void 0 ? _f : []).map((parameter) => parameterLocation(parameter, document.components));
+            const locations = [...pathLocations, ...operationLocations];
+            const operationPointer = isFixedHttpMethod(method)
+                ? escapePointer(method)
+                : `additionalOperations/${escapePointer(method)}`;
+            if (locations.includes('querystring') && locations.includes('query')) {
+                errors.push({
+                    path: `${location}/${operationPointer}/parameters`,
+                    message: 'in: querystring cannot be combined with in: query parameters on the same operation',
+                });
+            }
+            const names = querystringNames([...((_g = pathItem.parameters) !== null && _g !== void 0 ? _g : []), ...((_h = operation.parameters) !== null && _h !== void 0 ? _h : [])], document.components);
+            if (names.size > 1) {
+                errors.push({
+                    path: `${location}/${operationPointer}/parameters`,
+                    message: `Only one in: querystring parameter may apply to an operation; found ${[...names].join(', ')}`,
+                });
+            }
+        }
+    }
+    return errors;
+};

package/dist/openapi/tagHierarchy.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentV3, OpenAPIV3_2 } from '@mintlify/validation';
+import type { OpenAPI } from 'openapi-types';
+export type OpenApiTag = OpenAPIV3_2.TagObject & {
+    'x-group'?: string;
+};
+export type OpenApiTagGroup = {
+    name: string;
+    label: string;
+    key?: string;
+};
+export declare const isOpenApi32: (schema: OpenAPI.Document | DocumentV3) => boolean;
+export declare function validateOpenApiTagTree(tags?: readonly OpenApiTag[]): string[];
+export declare function createOpenApiTagResolver(schema: OpenAPI.Document | DocumentV3): (operationTags?: readonly string[]) => OpenApiTagGroup[];
+export declare function createOpenApiBadgeResolver(schema: OpenAPI.Document | DocumentV3): (operationTags?: readonly string[]) => string | undefined;
+export declare function findOpenApiNavGroup<T>(nav: T, tagPath: readonly OpenApiTagGroup[], findGroup: (nav: T, name?: string, key?: string) => T): T;