@mintlify/common 1.0.1262 → 1.0.1264

package/dist/index.d.ts

@@ -45,3 +45,5 @@ export * from './live-preview.js';
 export * from './paths/isEqualIgnoringLeadingSlash.js';
 export * from './sdk/index.js';
 export * from './seo/resolveSeoMetatags.js';
+export * from './mintExportAssets.js';
+export * from './snippetPresets.js';

package/dist/index.js

@@ -45,3 +45,5 @@ export * from './live-preview.js';
 export * from './paths/isEqualIgnoringLeadingSlash.js';
 export * from './sdk/index.js';
 export * from './seo/resolveSeoMetatags.js';
+export * from './mintExportAssets.js';
+export * from './snippetPresets.js';

package/dist/mdx/plugins/rehype/rehypeMdxExtractEndpoint/index.js

@@ -80,7 +80,9 @@ export const rehypeMdxExtractEndpoint = (metadata, config, mdxExtracts) => {
         });
         const content = endpoint.request.body[requestContentType];
         if (content) {
-            content.examples['example'] = { value: generateExampleFromSchema(content.schemaArray[0]) };
+            content.examples['example'] = {
+                value: generateExampleFromSchema(content.schemaArray[0], 0, 'request'),
+            };
         }
         const response = (_a = endpoint.response['200']) === null || _a === void 0 ? void 0 : _a['application/json'];
         if (response) {

package/dist/mintExportAssets.d.ts

@@ -0,0 +1,3 @@
+export declare const MINT_EXPORT_ASSETS_PREFIX = "/_mintlify/export-assets";
+export declare const toMintExportAssetPath: (url: string, extension?: string) => string;
+export declare const fromMintExportAssetPath: (assetPath: string) => string | undefined;

package/dist/mintExportAssets.js

@@ -0,0 +1,58 @@
+export const MINT_EXPORT_ASSETS_PREFIX = '/_mintlify/export-assets';
+const QUERY_SEGMENT = '_q';
+const HTTP_SEGMENT = '_http';
+const PORT_SEPARATOR = '~';
+const toBase64Url = (value) => btoa(String.fromCharCode(...new TextEncoder().encode(value)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+const fromBase64Url = (value) => {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+};
+export const toMintExportAssetPath = (url, extension) => {
+    var _a, _b;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (_c) {
+        return url;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return url;
+    const scheme = parsed.protocol === 'http:' ? `${HTTP_SEGMENT}/` : '';
+    const host = parsed.port ? `${parsed.hostname}${PORT_SEPARATOR}${parsed.port}` : parsed.hostname;
+    const base = `${MINT_EXPORT_ASSETS_PREFIX}/${scheme}${host}${parsed.pathname}`;
+    if (!parsed.search)
+        return base;
+    const resolvedExtension = extension !== null && extension !== void 0 ? extension : (_b = (_a = /\.([a-z0-9]+)$/i.exec(parsed.pathname)) === null || _a === void 0 ? void 0 : _a[1]) === null || _b === void 0 ? void 0 : _b.toLowerCase();
+    const suffix = resolvedExtension ? `.${resolvedExtension}` : '';
+    return `${base.replace(/\/$/, '')}/${QUERY_SEGMENT}/${toBase64Url(parsed.search.slice(1))}${suffix}`;
+};
+export const fromMintExportAssetPath = (assetPath) => {
+    if (!assetPath.startsWith(`${MINT_EXPORT_ASSETS_PREFIX}/`))
+        return undefined;
+    const unprefixed = assetPath.slice(MINT_EXPORT_ASSETS_PREFIX.length + 1);
+    const isHttp = unprefixed.startsWith(`${HTTP_SEGMENT}/`);
+    const protocol = isHttp ? 'http' : 'https';
+    const rest = isHttp ? unprefixed.slice(HTTP_SEGMENT.length + 1) : unprefixed;
+    const slashIndex = rest.indexOf('/');
+    const encodedHost = slashIndex === -1 ? rest : rest.slice(0, slashIndex);
+    const pathname = slashIndex === -1 ? '/' : rest.slice(slashIndex);
+    if (!encodedHost || encodedHost.startsWith('.') || encodedHost.includes('..'))
+        return undefined;
+    const host = encodedHost.replace(PORT_SEPARATOR, ':');
+    const queryMarker = `/${QUERY_SEGMENT}/`;
+    const queryIndex = pathname.lastIndexOf(queryMarker);
+    if (queryIndex === -1)
+        return `${protocol}://${host}${pathname}`;
+    const encodedQuery = pathname.slice(queryIndex + queryMarker.length).replace(/\.[a-z0-9]+$/i, '');
+    try {
+        return `${protocol}://${host}${pathname.slice(0, queryIndex)}?${fromBase64Url(encodedQuery)}`;
+    }
+    catch (_a) {
+        return undefined;
+    }
+};

package/dist/mintExportAssets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mintExportAssets.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { fromMintExportAssetPath, toMintExportAssetPath } from './mintExportAssets.js';
+describe('toMintExportAssetPath', () => {
+    it('maps an absolute url to a local asset path', () => {
+        expect(toMintExportAssetPath('https://d3gk2c5xim1je2.cloudfront.net/fontawesome/v7.2.0/regular/house.svg')).toBe('/_mintlify/export-assets/d3gk2c5xim1je2.cloudfront.net/fontawesome/v7.2.0/regular/house.svg');
+    });
+    it('encodes the query string into the path with the given extension', () => {
+        const assetPath = toMintExportAssetPath('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,400;1,700&display=swap', 'css');
+        expect(assetPath).toMatch(/^\/_mintlify\/export-assets\/fonts\.googleapis\.com\/css2\/_q\/[\w-]+\.css$/);
+    });
+    it('keeps the source extension for urls with a query', () => {
+        expect(toMintExportAssetPath('https://cdn.example.com/style.css?v=1')).toMatch(/^\/_mintlify\/export-assets\/cdn\.example\.com\/style\.css\/_q\/[\w-]+\.css$/);
+    });
+    it('encodes ports without a colon so the path is valid on every file system', () => {
+        expect(toMintExportAssetPath('https://fonts.example.com:8443/custom.woff2')).toBe('/_mintlify/export-assets/fonts.example.com~8443/custom.woff2');
+    });
+    it('keeps plain http assets distinct from https ones', () => {
+        expect(toMintExportAssetPath('http://example.com/a.woff2')).toBe('/_mintlify/export-assets/_http/example.com/a.woff2');
+    });
+    it('leaves relative and non-http urls untouched', () => {
+        expect(toMintExportAssetPath('/images/logo.svg')).toBe('/images/logo.svg');
+        expect(toMintExportAssetPath('data:image/svg+xml,abc')).toBe('data:image/svg+xml,abc');
+    });
+});
+describe('fromMintExportAssetPath', () => {
+    it.each([
+        'https://d3gk2c5xim1je2.cloudfront.net/flags/US.svg',
+        'https://cdn.jsdelivr.net/npm/@fontsource/inter@5/files/inter-latin-400-normal.woff2',
+        'https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,400;1,700&display=swap',
+        'https://example.com/font.woff2?v=1&name=%C3%BC',
+        'http://fonts.example.com/inter.woff2',
+        'http://example.com/style.css?v=2',
+        'https://example.com/font.WOFF2?v=1',
+        'https://fonts.example.com:8443/custom.woff2',
+        'http://localhost:8080/a.css?v=1',
+    ])('round-trips %s', (url) => {
+        expect(fromMintExportAssetPath(toMintExportAssetPath(url, 'css'))).toBe(url);
+    });
+    it('rejects paths outside the asset prefix or with traversal hosts', () => {
+        expect(fromMintExportAssetPath('/images/logo.svg')).toBeUndefined();
+        expect(fromMintExportAssetPath('/_mintlify/export-assets/../etc/passwd')).toBeUndefined();
+    });
+});

package/dist/server-only/ssrf.d.ts

@@ -0,0 +1,8 @@
+import dns from 'dns';
+export declare class PrivateIPError extends Error {
+    readonly hostname: string;
+    readonly ip: string;
+    constructor(hostname: string, ip: string);
+}
+export declare function isPrivateIP(ip: string): boolean;
+export declare function safeLookup(hostname: string, options: dns.LookupOptions, callback: (err: NodeJS.ErrnoException | null, address: string | dns.LookupAddress[], family?: number) => void): void;

package/dist/server-only/ssrf.js

@@ -0,0 +1,108 @@
+import dns from 'dns';
+import { BlockList, isIP } from 'net';
+export class PrivateIPError extends Error {
+    constructor(hostname, ip) {
+        super(`Blocked: ${hostname} resolves to private IP ${ip}`);
+        this.hostname = hostname;
+        this.ip = ip;
+        this.name = 'PrivateIPError';
+    }
+}
+const privateIPBlockList = new BlockList();
+for (const [network, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+]) {
+    privateIPBlockList.addSubnet(network, prefix, 'ipv4');
+}
+// ::/96 covers ::, ::1 and the deprecated IPv4-compatible ::a.b.c.d form; the NAT64 and
+// 6to4 prefixes embed an arbitrary IPv4 address, so they are blocked wholesale rather
+// than unwrapped - they are transition mechanisms, never a legitimate API destination
+for (const [network, prefix] of [
+    ['::', 96],
+    ['64:ff9b::', 96],
+    ['64:ff9b:1::', 48],
+    ['100::', 64],
+    ['2001::', 32],
+    ['2001:2::', 48],
+    ['2001:10::', 28],
+    ['2001:20::', 28],
+    ['2001:db8::', 32],
+    ['2002::', 16],
+    ['3fff::', 20],
+    ['5f00::', 16],
+    ['fc00::', 7],
+    ['fe80::', 10],
+    ['fec0::', 10],
+    ['ff00::', 8],
+]) {
+    privateIPBlockList.addSubnet(network, prefix, 'ipv6');
+}
+export function isPrivateIP(ip) {
+    const ipType = isIP(ip);
+    if (ipType === 0)
+        return true;
+    // handle IPv4-mapped IPv6 (::ffff:x.x.x.x) - extract IPv4 and check that
+    const lower = ip.toLowerCase();
+    if (lower.startsWith('::ffff:') && ip.includes('.')) {
+        const ipv4 = ip.slice(7);
+        if (isIP(ipv4) === 4) {
+            return privateIPBlockList.check(ipv4, 'ipv4');
+        }
+        return true; // malformed IPv4 part = block
+    }
+    return privateIPBlockList.check(ip, ipType === 4 ? 'ipv4' : 'ipv6');
+}
+// custom lookup that validates resolved IPs before returning them
+// the IP returned here is the EXACT IP the socket will connect to (no TOCTOU)
+// resolves all addresses so dual-stack fallback keeps working; rejects if any is private
+export function safeLookup(hostname, options, callback) {
+    dns.lookup(hostname, Object.assign(Object.assign({}, options), { all: true }), (err, addresses) => {
+        const fail = (e) => {
+            if (options.all) {
+                callback(e, []);
+            }
+            else {
+                callback(e, '', 0);
+            }
+        };
+        if (err) {
+            fail(err);
+            return;
+        }
+        if (!Array.isArray(addresses)) {
+            fail(new Error('unexpected DNS lookup result'));
+            return;
+        }
+        const [first] = addresses;
+        if (!first) {
+            fail(new Error('unexpected DNS lookup result'));
+            return;
+        }
+        for (const { address } of addresses) {
+            if (typeof address !== 'string' || isPrivateIP(address)) {
+                fail(new PrivateIPError(hostname, address));
+                return;
+            }
+        }
+        if (options.all) {
+            callback(null, addresses);
+        }
+        else {
+            callback(null, first.address, first.family);
+        }
+    });
+}

package/dist/snippetPresets.d.ts

@@ -0,0 +1,26 @@
+export declare const MINTLIFY_ICONS_CDN_URL = "https://d3gk2c5xim1je2.cloudfront.net";
+export type SnippetPreset = {
+    /** Canonical identifier (e.g., 'python', 'bash') */
+    key: string;
+    /** Alternative names that map to this preset (e.g., ['py'] for python) */
+    aliases?: string[];
+    /** Human-readable name (e.g., "Python", "cURL") */
+    displayName: string;
+    /** Devicon SVG name if different from key (e.g., 'dot-net' for '.NET') */
+    iconKey?: string;
+    /** Shiki language for syntax highlighting */
+    shikiLanguage: string;
+    /** httpsnippet config for code generation */
+    httpSnippet: {
+        target: string;
+        client?: string;
+    };
+};
+/**
+ * Central config for API playground language options.
+ * Each preset defines: display info, icon, syntax highlighting, and code generation.
+ */
+export declare const SNIPPET_PRESETS: SnippetPreset[];
+export declare const getPreset: (lang: string) => SnippetPreset | undefined;
+export declare const getIconKey: (lang: string) => string | undefined;
+export declare const getLanguageIconUrl: (language: string) => string | null;

package/dist/snippetPresets.js

@@ -0,0 +1,149 @@
+var _a;
+export const MINTLIFY_ICONS_CDN_URL = 'https://d3gk2c5xim1je2.cloudfront.net';
+/**
+ * Central config for API playground language options.
+ * Each preset defines: display info, icon, syntax highlighting, and code generation.
+ */
+export const SNIPPET_PRESETS = [
+    {
+        key: 'bash',
+        aliases: ['curl', 'sh', 'shell'],
+        displayName: 'cURL',
+        shikiLanguage: 'bash',
+        httpSnippet: { target: 'shell' },
+    },
+    {
+        key: 'python',
+        aliases: ['py'],
+        displayName: 'Python',
+        shikiLanguage: 'python',
+        httpSnippet: { target: 'python', client: 'requests' },
+    },
+    {
+        key: 'javascript',
+        aliases: ['js'],
+        displayName: 'JavaScript',
+        shikiLanguage: 'javascript',
+        httpSnippet: { target: 'javascript', client: 'fetch' },
+    },
+    {
+        key: 'node',
+        aliases: ['nodejs', 'node.js'],
+        displayName: 'Node.js',
+        iconKey: 'node',
+        shikiLanguage: 'javascript',
+        httpSnippet: { target: 'node', client: 'fetch' },
+    },
+    {
+        key: 'php',
+        displayName: 'PHP',
+        shikiLanguage: 'php',
+        httpSnippet: { target: 'php', client: 'curl' },
+    },
+    {
+        key: 'go',
+        aliases: ['golang'],
+        displayName: 'Go',
+        shikiLanguage: 'go',
+        httpSnippet: { target: 'go' },
+    },
+    {
+        key: 'java',
+        displayName: 'Java',
+        shikiLanguage: 'java',
+        httpSnippet: { target: 'java' },
+    },
+    {
+        key: 'ruby',
+        aliases: ['rb'],
+        displayName: 'Ruby',
+        shikiLanguage: 'ruby',
+        httpSnippet: { target: 'ruby' },
+    },
+    {
+        key: 'powershell',
+        displayName: 'PowerShell',
+        shikiLanguage: 'bash', // shiki doesn't have powershell in our LANGS
+        httpSnippet: { target: 'powershell' },
+    },
+    {
+        key: 'swift',
+        displayName: 'Swift',
+        shikiLanguage: 'swift',
+        httpSnippet: { target: 'swift' },
+    },
+    {
+        key: 'csharp',
+        aliases: ['c#'],
+        displayName: 'C#',
+        shikiLanguage: 'csharp',
+        httpSnippet: { target: 'csharp', client: 'restsharp' },
+    },
+    {
+        key: 'dotnet',
+        aliases: ['.net', '.NET', 'dotnet', 'dot-net'],
+        displayName: '.NET',
+        iconKey: 'dot-net',
+        shikiLanguage: 'csharp',
+        httpSnippet: { target: 'csharp', client: 'restsharp' },
+    },
+    {
+        key: 'typescript',
+        aliases: ['ts'],
+        displayName: 'TypeScript',
+        shikiLanguage: 'typescript',
+        httpSnippet: { target: 'javascript', client: 'fetch' },
+    },
+    {
+        key: 'c',
+        displayName: 'C',
+        shikiLanguage: 'c',
+        httpSnippet: { target: 'c' },
+    },
+    {
+        key: 'c++',
+        aliases: ['cpp'],
+        displayName: 'C++',
+        shikiLanguage: 'c++',
+        iconKey: 'cplusplus',
+        httpSnippet: { target: 'c' },
+    },
+    {
+        key: 'kotlin',
+        aliases: ['kt'],
+        displayName: 'Kotlin',
+        shikiLanguage: 'kotlin',
+        httpSnippet: { target: 'kotlin' },
+    },
+    {
+        key: 'rust',
+        aliases: ['rs'],
+        displayName: 'Rust',
+        shikiLanguage: 'rust',
+        httpSnippet: { target: 'rust' },
+    },
+    {
+        key: 'dart',
+        aliases: ['flutter'],
+        displayName: 'Dart',
+        shikiLanguage: 'dart',
+        httpSnippet: { target: 'dart' },
+    },
+];
+const presetLookup = new Map();
+for (const preset of SNIPPET_PRESETS) {
+    presetLookup.set(preset.key.toLowerCase(), preset);
+    for (const alias of (_a = preset.aliases) !== null && _a !== void 0 ? _a : []) {
+        presetLookup.set(alias.toLowerCase(), preset);
+    }
+}
+export const getPreset = (lang) => presetLookup.get(lang.toLowerCase());
+export const getIconKey = (lang) => {
+    var _a;
+    const preset = getPreset(lang);
+    return preset ? ((_a = preset.iconKey) !== null && _a !== void 0 ? _a : preset.key) : lang.toLowerCase();
+};
+export const getLanguageIconUrl = (language) => {
+    const iconKey = getIconKey(language);
+    return iconKey ? `${MINTLIFY_ICONS_CDN_URL}/devicon/${iconKey}.svg` : null;
+};