@mintlify/scraping 4.0.137 → 4.0.138

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/scraping",
-  "version": "4.0.137",
+  "version": "4.0.138",
   "description": "Scrape documentation frameworks to Mintlify docs",
   "engines": {
     "node": ">=18.0.0"
@@ -38,7 +38,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@mintlify/common": "1.0.291",
+    "@mintlify/common": "1.0.292",
     "@mintlify/openapi-parser": "^0.0.7",
     "fs-extra": "^11.1.1",
     "hast-util-to-mdast": "^10.1.0",
@@ -61,7 +61,7 @@
     "@mintlify/models": "0.0.175",
     "@mintlify/prettier-config": "1.0.4",
     "@mintlify/ts-config": "2.0.2",
-    "@mintlify/validation": "0.1.310",
+    "@mintlify/validation": "0.1.311",
     "@trivago/prettier-plugin-sort-imports": "^4.2.1",
     "@tsconfig/recommended": "1.x",
     "@types/hast": "^3.0.4",
@@ -78,5 +78,5 @@
     "typescript": "^5.5.3",
     "vitest": "^2.0.4"
   },
-  "gitHead": "4f3cc5724e880a693746426e868f9ec83ecfb3a0"
+  "gitHead": "4bf57edd57b4b660cc718b2751518b055a61a903"
 }

package/src/openapi/common.ts

@@ -166,3 +166,61 @@ export function processOpenApiPath<N, DN>(
 }
 
 export const DEFAULT_API_GROUP_NAME = 'API Reference';
+export const DEFAULT_WEBHOOK_GROUP_NAME = 'Webhooks';
+
+export function processOpenApiWebhook<N, DN>(
+  webhook: string,
+  webhookObject: OpenAPIV3.PathItemObject,
+  _schema: OpenAPI.Document,
+  nav: N,
+  decoratedNav: DN,
+  writePromises: Promise<void>[],
+  pagesAcc: Record<string, DecoratedNavigationPage>,
+  options: GenerateOpenApiPagesOptions,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  findNavGroup: (nav: any, groupName?: string) => any
+) {
+  const openApiFilePathFromRoot = options.openApiFilePath
+    ? optionallyAddLeadingSlash(options.openApiFilePath)
+    : undefined;
+
+  Object.values(OpenAPIV3.HttpMethods).forEach((method) => {
+    if (method in webhookObject) {
+      const operation = webhookObject[method];
+      const groupName = operation?.tags?.[0] ?? DEFAULT_WEBHOOK_GROUP_NAME;
+      const title =
+        prepareStringToBeValidFilename(operation?.summary) ??
+        `${prepareStringToBeValidFilename(webhook)}`;
+      const folder = prepareStringToBeValidFilename(groupName) ?? '';
+      const base = join(options.outDir ?? '', folder, title);
+
+      const navGroup = findNavGroup(nav, groupName);
+      const decoratedNavGroup = findNavGroup(decoratedNav, groupName);
+
+      const filenameWithoutExtension = generateUniqueFilenameWithoutExtension(navGroup, base);
+
+      const openapiMetaTag = `${
+        openApiFilePathFromRoot ? `${openApiFilePathFromRoot} ` : ''
+      }webhook ${webhook}`;
+
+      const description = operation?.description;
+
+      navGroup.push(filenameWithoutExtension);
+      const page: DecoratedNavigationPage = {
+        openapi: openapiMetaTag,
+        href: resolve('/', filenameWithoutExtension),
+        title: slugToTitle(filenameWithoutExtension),
+        description,
+        version: options.version,
+      };
+      decoratedNavGroup.push(page);
+      pagesAcc[filenameWithoutExtension] = page;
+      const targetPath = options.outDirBasePath
+        ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
+        : `${filenameWithoutExtension}.mdx`;
+      if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
+        writePromises.push(createOpenApiFrontmatter(targetPath, openapiMetaTag, options.version));
+      }
+    }
+  });
+}

package/src/openapi/generateOpenApiPages.ts

@@ -14,6 +14,7 @@ import {
   OpenApiPageGenerationResult,
   processOpenApiPath,
   DEFAULT_API_GROUP_NAME,
+  processOpenApiWebhook,
 } from './common.js';
 
 export async function generateOpenApiPages(
@@ -23,8 +24,17 @@ export async function generateOpenApiPages(
   const { document, isUrl } = await getOpenApiDefinition(pathOrDocumentOrUrl);
   const { schema } = await validate(document);
 
-  if (schema?.paths === undefined || Object.keys(schema.paths).length === 0) {
+  if (
+    schema?.openapi === '3.0.0' &&
+    (schema.paths === undefined || Object.keys(schema.paths).length === 0)
+  ) {
     throw new Error('No paths defined.');
+  } else if (
+    schema?.openapi === '3.1.0' &&
+    (schema.paths === undefined || Object.keys(schema.paths).length === 0) &&
+    (schema.webhooks === undefined || Object.keys(schema.webhooks).length === 0)
+  ) {
+    throw new Error('No paths or webhooks defined.');
   }
 
   const nav: Navigation = [];
@@ -32,22 +42,43 @@ export async function generateOpenApiPages(
   const writePromises: Promise<void>[] = [];
   const pagesAcc: Record<string, DecoratedNavigationPage> = {};
 
-  Object.entries(schema.paths).forEach(([path, pathItemObject]) => {
-    if (!pathItemObject || typeof pathItemObject !== 'object') {
-      return;
-    }
-    processOpenApiPath<Navigation, DecoratedNavigation>(
-      path,
-      pathItemObject,
-      schema as OpenAPI.Document,
-      nav,
-      decoratedNav,
-      writePromises,
-      pagesAcc,
-      opts ?? {},
-      findNavGroup
-    );
-  });
+  if (schema?.paths) {
+    Object.entries(schema.paths).forEach(([path, pathItemObject]) => {
+      if (!pathItemObject || typeof pathItemObject !== 'object') {
+        return;
+      }
+      processOpenApiPath<Navigation, DecoratedNavigation>(
+        path,
+        pathItemObject,
+        schema as OpenAPI.Document,
+        nav,
+        decoratedNav,
+        writePromises,
+        pagesAcc,
+        opts ?? {},
+        findNavGroup
+      );
+    });
+  }
+
+  if (schema?.webhooks) {
+    Object.entries(schema.webhooks).forEach(([webhook, webhookObject]) => {
+      if (!webhookObject || typeof webhookObject !== 'object') {
+        return;
+      }
+      processOpenApiWebhook<Navigation, DecoratedNavigation>(
+        webhook,
+        webhookObject,
+        schema as OpenAPI.Document,
+        nav,
+        decoratedNav,
+        writePromises,
+        pagesAcc,
+        opts ?? {},
+        findNavGroup
+      );
+    });
+  }
 
   await Promise.all(writePromises);
 
@@ -59,6 +90,7 @@ export async function generateOpenApiPages(
     isUrl,
   };
 }
+
 const findNavGroup = <T extends NavigationGroup | DecoratedNavigationGroup>(
   nav: T['pages'][number][],
   groupName: string = DEFAULT_API_GROUP_NAME

package/src/openapi/generateOpenApiPagesForDocsConfig.ts

@@ -14,6 +14,7 @@ import {
   OpenApiPageGenerationResult,
   processOpenApiPath,
   DEFAULT_API_GROUP_NAME,
+  processOpenApiWebhook,
 } from './common.js';
 
 export async function generateOpenApiPagesForDocsConfig(
@@ -23,8 +24,17 @@ export async function generateOpenApiPagesForDocsConfig(
   const { document, isUrl } = await getOpenApiDefinition(pathOrDocumentOrUrl);
   const { schema } = await validate(document);
 
-  if (schema?.paths === undefined || Object.keys(schema.paths).length === 0) {
+  if (
+    schema?.openapi === '3.0.0' &&
+    (schema.paths === undefined || Object.keys(schema.paths).length === 0)
+  ) {
     throw new Error('No paths defined.');
+  } else if (
+    schema?.openapi === '3.1.0' &&
+    (schema.paths === undefined || Object.keys(schema.paths).length === 0) &&
+    (schema.webhooks === undefined || Object.keys(schema.webhooks).length === 0)
+  ) {
+    throw new Error('No paths or webhooks defined.');
   }
 
   const nav: GroupsConfig = [];
@@ -32,22 +42,43 @@ export async function generateOpenApiPagesForDocsConfig(
   const writePromises: Promise<void>[] = [];
   const pagesAcc: Record<string, DecoratedNavigationPage> = {};
 
-  Object.entries(schema.paths).forEach(([path, pathItemObject]) => {
-    if (!pathItemObject || typeof pathItemObject !== 'object') {
-      return;
-    }
-    processOpenApiPath<GroupsConfig, DecoratedGroupsConfig>(
-      path,
-      pathItemObject,
-      schema as OpenAPI.Document,
-      nav,
-      decoratedNav,
-      writePromises,
-      pagesAcc,
-      opts ?? {},
-      findNavGroup
-    );
-  });
+  if (schema?.paths) {
+    Object.entries(schema.paths).forEach(([path, pathItemObject]) => {
+      if (!pathItemObject || typeof pathItemObject !== 'object') {
+        return;
+      }
+      processOpenApiPath<GroupsConfig, DecoratedGroupsConfig>(
+        path,
+        pathItemObject,
+        schema as OpenAPI.Document,
+        nav,
+        decoratedNav,
+        writePromises,
+        pagesAcc,
+        opts ?? {},
+        findNavGroup
+      );
+    });
+  }
+
+  if (schema?.webhooks) {
+    Object.entries(schema.webhooks).forEach(([webhook, webhookObject]) => {
+      if (!webhookObject || typeof webhookObject !== 'object') {
+        return;
+      }
+      processOpenApiWebhook<GroupsConfig, DecoratedGroupsConfig>(
+        webhook,
+        webhookObject,
+        schema as OpenAPI.Document,
+        nav,
+        decoratedNav,
+        writePromises,
+        pagesAcc,
+        opts ?? {},
+        findNavGroup
+      );
+    });
+  }
 
   await Promise.all(writePromises);