@mintlify/msft-sdk 1.1.67 → 1.1.69

package/README.md

@@ -52,13 +52,93 @@ import { DocsPage } from "@mintlify/msft-sdk";
 
 ## Core Exports
 
+### Documentation Components
 - `DocsPage` - Main documentation page component
+- `ApiPage` - API reference page component
+- `DocsLayout` - Layout with navigation sidebar
 - `MDXRenderer` - Standalone MDX renderer
-- `convertHtmlToMdx` - Convert HTML to MDX
-- `serializeMdx` - Compile MDX to React components
 - `NavTree`, `TableOfContents` - Navigation components
 - `allComponents` - All available MDX components
 
+### Content Processing
+- `convertHtmlToMdx` - Convert HTML to MDX
+- `serializeMdx` - Compile MDX to React components
+
+### OpenAPI Utilities
+- `convertOpenApiSpecToGraph` - Convert OpenAPI spec to schema graph data
+- `convertOpenApiSpecToNav` - Generate navigation structure from OpenAPI spec
+- `convertOpenApiSpecToHrefMap` - Create href-to-endpoint lookup map
+
+## OpenAPI Integration
+
+The SDK provides utilities for working with OpenAPI specifications:
+
+```tsx
+import {
+  convertOpenApiSpecToGraph,
+  convertOpenApiSpecToNav,
+  convertOpenApiSpecToHrefMap,
+  getApiReferenceDataFromGraph,
+  ApiPage,
+} from "@mintlify/msft-sdk";
+import openApiSpec from "./my-openapi-spec.json";
+
+// Convert spec to schema graph (required for API rendering)
+const graphData = convertOpenApiSpecToGraph(openApiSpec, {
+  filename: "my-api.json",
+  originalFileLocation: "my-api.json",
+});
+
+// Generate navigation from OpenAPI spec
+const navData = convertOpenApiSpecToNav(openApiSpec);
+
+// Create href-to-endpoint map for routing
+const hrefMap = convertOpenApiSpecToHrefMap(openApiSpec);
+
+// Get API reference data for a specific endpoint
+const apiReferenceData = getApiReferenceDataFromGraph({
+  metadata: {
+    title: "Create User",
+    description: "Create a new user",
+    openapi: "post /users",
+  },
+  schemaGraphData: graphData,
+});
+
+// Render the API page
+<ApiPage
+  apiReferenceData={apiReferenceData}
+  pageMetadata={metadata}
+  theme="light"
+/>;
+```
+
+## Development
+
+### Running Tests
+
+This project uses [Vitest](https://vitest.dev/) for testing.
+
+```bash
+# Run tests once
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Test Structure
+
+Tests are located in the `tests/` directory and are organized as follows:
+
+- `tests/fixtures/` - Test fixtures including OpenAPI specs and expected outputs
+- `tests/*.test.ts` - Test files for various conversion functions
+
+The test fixtures are kept outside of the `src/` directory to ensure they're not bundled with the package.
+
 ## License
 
 MIT © Mintlify, Inc.

package/dist/api-playground-2/ApiExamples.js

@@ -1,36 +1,34 @@
 import { jsx as e, jsxs as c } from "react/jsx-runtime";
-import { useContext as x, useState as f, useMemo as u } from "react";
+import { useContext as f, useState as x, useMemo as u } from "react";
 import { useDebouncedApiPlaygroundInputs as d } from "./hooks/usePlaygroundInputsStore.js";
-import { CodeExampleLabelContext as E } from "../contexts/CodeExampleLabelContext.js";
+import { CodeExampleLabelContext as h } from "../contexts/CodeExampleLabelContext.js";
 import { ApiReferenceContext2 as g } from "../contexts/ConfigContext.js";
-import D from "../components/Api/ErrorBoundary.js";
-import { clsx as h } from "clsx";
-import { RequestExample as R } from "./components/Example/RequestExample.js";
-import { ResponseExample as A } from "./components/Example/ResponseExample.js";
-import { initialApiPlaygroundInputs as C } from "./constants/index.js";
-const j = ({ className: o, isModal: i = !1, apiReferenceData: a, noInputs: n = !1 }) => {
-  const { apiReferenceData2: m } = x(g), t = a || m, r = d(100), [p, l] = f();
-  console.log("[DEBUG] ApiExamples - Props apiReferenceData:", a), console.log("[DEBUG] ApiExamples - Context apiReferenceData2FromContext:", m), console.log("[DEBUG] ApiExamples - Final apiReferenceData2:", t), console.log("[DEBUG] ApiExamples - noInputs:", n), console.log("[DEBUG] ApiExamples - isModal:", i);
-  const s = u(
-    () => h(
+import R from "../components/Api/ErrorBoundary.js";
+import { clsx as v } from "clsx";
+import { RequestExample as C } from "./components/Example/RequestExample.js";
+import { ResponseExample as D } from "./components/Example/ResponseExample.js";
+import { initialApiPlaygroundInputs as E } from "./constants/index.js";
+const q = ({ className: t, isModal: r = !1, apiReferenceData: m, noInputs: n = !1 }) => {
+  const { apiReferenceData2: a } = f(g), i = m || a, o = d(100), [p, s] = x(), l = u(
+    () => v(
       "mint:w-full mint:xl:w-[28rem] mint:gap-6 mint:grid mint:grid-rows-[repeat(auto-fit,minmax(0,min-content))] mint:grid-rows mint:relative mint:max-h-[calc(100%-32px)] mint:min-h-[18rem]",
-      o
+      t
     ),
-    [o, i]
+    [t, r]
   );
-  return /* @__PURE__ */ e(E.Provider, { value: { selectedLabel: p, setSelectedLabel: l }, children: /* @__PURE__ */ e("div", { className: s, children: /* @__PURE__ */ c(D, { children: [
+  return /* @__PURE__ */ e(h.Provider, { value: { selectedLabel: p, setSelectedLabel: s }, children: /* @__PURE__ */ e("div", { className: l, children: /* @__PURE__ */ c(R, { children: [
     /* @__PURE__ */ e(
-      R,
+      C,
       {
-        apiReferenceData: t,
-        inputs: n ? C : r,
+        apiReferenceData: i,
+        inputs: n ? E : o,
         maxHeight: "mint:max-h-[40vh]"
       }
     ),
-    /* @__PURE__ */ e(A, { apiReferenceData: t, maxHeight: "mint:max-h-[40vh]" })
+    /* @__PURE__ */ e(D, { apiReferenceData: i, maxHeight: "mint:max-h-[40vh]" })
   ] }) }) });
 };
 export {
-  j as ApiExamples,
-  j as default
+  q as ApiExamples,
+  q as default
 };

package/dist/api-playground-2/components/Example/GeneratedRequestExample.js

@@ -1,146 +1,145 @@
-import { jsx as h } from "react/jsx-runtime";
-import { useState as j, useEffect as V } from "react";
-import { generateRequest as S } from "../../generators/generateRequest.js";
-import { generateSnippet as T } from "../../generators/generateSnippet.js";
-import { getFirstExampleValue as g } from "../../schemaGraph/processExamples.js";
-import { CodeGroupSelect as k } from "../../../components/content-components/CodeGroupSelect/index.js";
-import { CodeSnippets as w } from "../../../components/content-components/code-snippets.js";
-import { langToPresetMap as C } from "../../../constants/snippetPresets.js";
-const z = ({
-  baseUrl: r,
+import { jsx as a } from "react/jsx-runtime";
+import { useState as V, useEffect as B } from "react";
+import { generateRequest as w } from "../../generators/generateRequest.js";
+import { generateSnippet as x } from "../../generators/generateSnippet.js";
+import { getFirstExampleValue as C } from "../../schemaGraph/processExamples.js";
+import { CodeGroupSelect as G } from "../../../components/content-components/CodeGroupSelect/index.js";
+import { CodeSnippets as P } from "../../../components/content-components/code-snippets.js";
+import { langToPresetMap as b } from "../../../constants/snippetPresets.js";
+const X = ({
+  baseUrl: s,
   apiReferenceData: t,
-  inputs: e,
-  requestExampleLanguages: n,
-  requiredOnly: p,
-  maxHeight: o,
-  selectedSecurityOptionIndex: c,
-  selectedRequestBodyContentTypeIndex: l
+  inputs: o,
+  requestExampleLanguages: c,
+  requiredOnly: n,
+  maxHeight: r,
+  selectedSecurityOptionIndex: f,
+  selectedRequestBodyContentTypeIndex: p
 }) => {
-  var u, s, G;
-  console.log("[DEBUG] GeneratedRequestExample - baseUrl:", r), console.log("[DEBUG] GeneratedRequestExample - apiReferenceData:", t), console.log("[DEBUG] GeneratedRequestExample - requestExampleLanguages:", n);
-  const m = (u = t.dependencies) == null ? void 0 : u.requestBody;
+  var l, e, j;
+  const m = (l = t.dependencies) == null ? void 0 : l.requestBody;
   if (!m)
-    return console.log("[DEBUG] GeneratedRequestExample - No requestBody, using SingleRequest"), /* @__PURE__ */ h(
-      q,
+    return /* @__PURE__ */ a(
+      k,
       {
         apiReferenceData: t,
-        baseUrl: r,
-        inputs: e,
-        requestExampleLanguages: n,
-        requiredOnly: p,
-        maxHeight: o,
-        selectedSecurityOptionIndex: c
+        baseUrl: s,
+        inputs: o,
+        requestExampleLanguages: c,
+        requiredOnly: n,
+        maxHeight: r,
+        selectedSecurityOptionIndex: f
       }
     );
-  const i = g(
+  const i = C(
     m.content,
-    l
+    p
   );
   if (!i) return null;
-  const a = Object.entries(m.content).map(
-    ([B, x]) => ({
-      contentType: B,
-      examples: x.examples
+  const h = Object.entries(m.content).map(
+    ([S, T]) => ({
+      contentType: S,
+      examples: T.examples
     })
-  ), E = (s = a[l]) == null ? void 0 : s.examples, f = (G = a[l]) == null ? void 0 : G.contentType;
-  return Object.keys(E).length > 1 ? /* @__PURE__ */ h(
-    N,
+  ), M = (e = h[p]) == null ? void 0 : e.examples, u = (j = h[p]) == null ? void 0 : j.contentType;
+  return Object.keys(M).length > 1 ? /* @__PURE__ */ a(
+    v,
     {
       apiReferenceData: t,
-      selectedBodyContentType: f,
-      baseUrl: r,
-      inputs: e,
-      examples: E,
-      requiredOnly: p,
-      maxHeight: o,
-      selectedSecurityOptionIndex: c
+      selectedBodyContentType: u,
+      baseUrl: s,
+      inputs: o,
+      examples: M,
+      requiredOnly: n,
+      maxHeight: r,
+      selectedSecurityOptionIndex: f
     }
-  ) : /* @__PURE__ */ h(
-    q,
+  ) : /* @__PURE__ */ a(
+    k,
     {
       apiReferenceData: t,
-      selectedBodyContentType: f,
-      baseUrl: r,
-      inputs: e,
+      selectedBodyContentType: u,
+      baseUrl: s,
+      inputs: o,
       exampleValue: i,
-      requestExampleLanguages: n,
-      requiredOnly: p,
-      maxHeight: o,
-      selectedSecurityOptionIndex: c
+      requestExampleLanguages: c,
+      requiredOnly: n,
+      maxHeight: r,
+      selectedSecurityOptionIndex: f
     }
   );
-}, q = ({
-  baseUrl: r,
+}, k = ({
+  baseUrl: s,
   apiReferenceData: t,
-  inputs: e,
-  selectedBodyContentType: n,
-  exampleValue: p,
-  requestExampleLanguages: o,
-  requiredOnly: c,
-  maxHeight: l,
+  inputs: o,
+  selectedBodyContentType: c,
+  exampleValue: n,
+  requestExampleLanguages: r,
+  requiredOnly: f,
+  maxHeight: p,
   selectedSecurityOptionIndex: m
 }) => {
-  const i = S({
-    baseUrl: r,
+  const i = w({
+    baseUrl: s,
     apiReferenceData: t,
-    inputs: e,
-    selectedBodyContentType: n,
-    exampleData: p,
-    requiredOnly: c,
+    inputs: o,
+    selectedBodyContentType: c,
+    exampleData: n,
+    requiredOnly: f,
     selectedSecurityOptionIndex: m
-  }), a = o == null ? void 0 : o.reduce((f, u) => {
-    const s = C[u];
-    return s && f.push(s), f;
-  }, []), E = T({
+  }), h = r == null ? void 0 : r.reduce((u, l) => {
+    const e = b[l];
+    return e && u.push(e), u;
+  }, []), M = x({
     apiReferenceData: t,
-    pathInputs: e.path,
+    pathInputs: o.path,
     request: i,
-    snippetPresets: a
+    snippetPresets: h
   });
-  return /* @__PURE__ */ h(w, { snippets: E, dropdown: !0, maxHeight: l, showCopyButton: !1, noMargins: !0 });
-}, N = ({
-  baseUrl: r,
+  return /* @__PURE__ */ a(P, { snippets: M, dropdown: !0, maxHeight: p, showCopyButton: !1, noMargins: !0 });
+}, v = ({
+  baseUrl: s,
   apiReferenceData: t,
-  inputs: e,
-  selectedBodyContentType: n,
-  examples: p,
-  requiredOnly: o,
-  maxHeight: c,
-  selectedSecurityOptionIndex: l
+  inputs: o,
+  selectedBodyContentType: c,
+  examples: n,
+  requiredOnly: r,
+  maxHeight: f,
+  selectedSecurityOptionIndex: p
 }) => {
-  const [m, i] = j({}), [a, E] = j(null);
-  return V(() => {
-    const f = e.path, u = {};
+  const [m, i] = V({}), [h, M] = V(null);
+  return B(() => {
+    const u = o.path, l = {};
     try {
-      for (const [s, { value: G }] of Object.entries(p)) {
-        if (!G) continue;
-        const B = S({
-          baseUrl: r,
+      for (const [e, { value: j }] of Object.entries(n)) {
+        if (!j) continue;
+        const S = w({
+          baseUrl: s,
           apiReferenceData: t,
-          inputs: e,
-          selectedBodyContentType: n,
-          exampleData: G,
-          requiredOnly: o,
-          selectedSecurityOptionIndex: l
+          inputs: o,
+          selectedBodyContentType: c,
+          exampleData: j,
+          requiredOnly: r,
+          selectedSecurityOptionIndex: p
         });
-        T({
+        x({
           apiReferenceData: t,
-          pathInputs: f,
-          request: B,
+          pathInputs: u,
+          request: S,
           isMultipleRequest: !0
-        }).forEach((M) => {
-          u[M.filename] = {
-            ...u[M.filename],
-            [s]: M
+        }).forEach((E) => {
+          l[E.filename] = {
+            ...l[E.filename],
+            [e]: E
           };
         });
       }
-      i(u);
-    } catch (s) {
-      console.error(s), E(s);
+      i(l);
+    } catch (e) {
+      console.error(e), M(e);
     }
-  }, [r, t, e, n, p, o, l]), a || Object.keys(m).length === 0 ? null : /* @__PURE__ */ h(k, { snippets: m, maxHeight: c });
+  }, [s, t, o, c, n, r, p]), h || Object.keys(m).length === 0 ? null : /* @__PURE__ */ a(G, { snippets: m, maxHeight: f });
 };
 export {
-  z as GeneratedRequestExample
+  X as GeneratedRequestExample
 };

package/dist/api-playground-2/components/Example/RequestExample.js

@@ -1,32 +1,32 @@
 import { jsx as r } from "react/jsx-runtime";
 import { memo as O } from "react";
-import { initialApiPlaygroundInputs as T } from "../../constants/index.js";
-import { generateSnippetMap as j } from "../../generators/generateSnippetMap.js";
-import { useSelectedBaseUrl as w } from "../../hooks/useSelectedBaseUrl.js";
-import { useSelectedRequestBodyContentType as G } from "../../hooks/useSelectedRequestBodyContentType.js";
-import { useSelectedSecurityOption as L } from "../../hooks/useSelectedSecurityOption.js";
-import { CodeGroupSelect as U } from "../../../components/content-components/CodeGroupSelect/index.js";
-import { CodeSnippet as k } from "../../../components/content-components/code-snippet.js";
-import { CodeSnippets as P } from "../../../components/content-components/code-snippets.js";
-import { CodeBlock as b } from "../../../components/content-components/code-block.js";
-import { CodeGroup as h } from "../../../components/content-components/code-group.js";
-import { shikiLangToDisplayLang as v } from "../../../constants/snippetPresets.js";
+import { initialApiPlaygroundInputs as j } from "../../constants/index.js";
+import { generateSnippetMap as w } from "../../generators/generateSnippetMap.js";
+import { useSelectedBaseUrl as B } from "../../hooks/useSelectedBaseUrl.js";
+import { useSelectedRequestBodyContentType as L } from "../../hooks/useSelectedRequestBodyContentType.js";
+import { useSelectedSecurityOption as T } from "../../hooks/useSelectedSecurityOption.js";
+import { CodeGroupSelect as k } from "../../../components/content-components/CodeGroupSelect/index.js";
+import { CodeSnippet as P } from "../../../components/content-components/code-snippet.js";
+import { CodeSnippets as v } from "../../../components/content-components/code-snippets.js";
+import { CodeBlock as h } from "../../../components/content-components/code-block.js";
+import { CodeGroup as b } from "../../../components/content-components/code-group.js";
+import { shikiLangToDisplayLang as G } from "../../../constants/snippetPresets.js";
 import { useApiPlaygroundDisplay as I } from "../../../hooks/useApiPlaygroundDisplay.js";
-import { GeneratedRequestExample as B } from "./GeneratedRequestExample.js";
+import { GeneratedRequestExample as E } from "./GeneratedRequestExample.js";
 const N = O(
   ({
     apiReferenceData: e,
-    inputs: p = T,
-    maxHeight: u
+    inputs: u = j,
+    maxHeight: i
   }) => {
-    var g, y, f, S, q, E, x;
-    const n = (g = e.operation) == null ? void 0 : g.requestExamples, { selectedRequestBodyContentTypeIndex: a } = G(), { selectedSecurityOptionIndex: i } = L(), M = I(), m = (y = e.operation) == null ? void 0 : y.requestExampleLanguages, d = (f = e.operation) == null ? void 0 : f.requiredOnlyExamples, { baseUrl: s } = w();
-    switch (console.log("[DEBUG] RequestExample - requestExampleType:", (S = e.operation) == null ? void 0 : S.requestExampleType), console.log("[DEBUG] RequestExample - baseUrl:", s), console.log("[DEBUG] RequestExample - apiReferenceData.operation:", e.operation), (q = e.operation) == null ? void 0 : q.requestExampleType) {
+    var g, f, y, S, q, x;
+    const n = (g = e.operation) == null ? void 0 : g.requestExamples, { selectedRequestBodyContentTypeIndex: p } = L(), { selectedSecurityOptionIndex: a } = T(), M = I(), m = (f = e.operation) == null ? void 0 : f.requestExampleLanguages, d = (y = e.operation) == null ? void 0 : y.requiredOnlyExamples, { baseUrl: s } = B();
+    switch ((S = e.operation) == null ? void 0 : S.requestExampleType) {
       case "mdx":
         if (!n) return null;
         const C = n.some((o) => o.dropdown ?? !1);
-        return /* @__PURE__ */ r(h, { isSmallText: !0, dropdown: C, noMargins: !0, className: u, children: n.map((o, t) => /* @__PURE__ */ r(
-          b,
+        return /* @__PURE__ */ r(b, { isSmallText: !0, dropdown: C, noMargins: !0, className: i, children: n.map((o, t) => /* @__PURE__ */ r(
+          h,
           {
             language: o.language,
             fileName: o.filename,
@@ -35,54 +35,54 @@ const N = O(
           `${o.filename}-${o.language}-${t}`
         )) });
       case "webhook":
-        return (E = n == null ? void 0 : n[0]) != null && E.code ? /* @__PURE__ */ r(h, { isSmallText: !0, noMargins: !0, hideCodeSnippetFeedbackButton: !0, children: /* @__PURE__ */ r(b, { language: "json", filename: "Example Request Body", children: /* @__PURE__ */ r(k, { language: "json", children: (x = n[0]) == null ? void 0 : x.code }) }) }) : null;
+        return (q = n == null ? void 0 : n[0]) != null && q.code ? /* @__PURE__ */ r(b, { isSmallText: !0, noMargins: !0, hideCodeSnippetFeedbackButton: !0, children: /* @__PURE__ */ r(h, { language: "json", filename: "Example Request Body", children: /* @__PURE__ */ r(P, { language: "json", children: (x = n[0]) == null ? void 0 : x.code }) }) }) : null;
       case "codeSamples":
         if (!e.operation.codeSamples) return null;
-        const c = j({
+        const c = w({
           apiReferenceData: e,
           codeSamples: e.operation.codeSamples,
           baseUrl: s,
           apiPlaygroundMode: M,
           requestExampleLanguages: m,
           requiredOnly: d,
-          inputs: p,
-          selectedSecurityOptionIndex: i,
-          selectedRequestBodyContentTypeIndex: a
+          inputs: u,
+          selectedSecurityOptionIndex: a,
+          selectedRequestBodyContentTypeIndex: p
         });
         if (Object.values(c).every((o) => Object.keys(o).length <= 1)) {
           let t = Object.values(c).flatMap((l) => Object.values(l));
           return new Set(t.map((l) => l.filename)).size !== t.length && (t = t.map((l) => ({
             ...l,
-            filename: v[l.language] ?? l.language
-          }))), /* @__PURE__ */ r(P, { snippets: t, noMargins: !0, dropdown: !0 });
+            filename: G[l.language] ?? l.language
+          }))), /* @__PURE__ */ r(v, { snippets: t, noMargins: !0, dropdown: !0 });
         }
-        return /* @__PURE__ */ r(U, { snippets: c });
+        return /* @__PURE__ */ r(k, { snippets: c });
       case "generated":
         return s ? /* @__PURE__ */ r(
-          B,
+          E,
           {
             apiReferenceData: e,
             baseUrl: s,
-            inputs: p,
-            selectedSecurityOptionIndex: i,
+            inputs: u,
+            selectedSecurityOptionIndex: a,
             requestExampleLanguages: m,
             requiredOnly: d,
-            selectedRequestBodyContentTypeIndex: a,
-            maxHeight: u
+            selectedRequestBodyContentTypeIndex: p,
+            maxHeight: i
           }
         ) : null;
       case "examples":
         return !e.operation.prefillPlaygroundExamples || !s ? null : /* @__PURE__ */ r(
-          B,
+          E,
           {
             apiReferenceData: e,
             baseUrl: s,
-            inputs: p,
-            selectedSecurityOptionIndex: i,
+            inputs: u,
+            selectedSecurityOptionIndex: a,
             requestExampleLanguages: m,
             requiredOnly: d,
-            selectedRequestBodyContentTypeIndex: a,
-            maxHeight: u
+            selectedRequestBodyContentTypeIndex: p,
+            maxHeight: i
           }
         );
       default: