docorbit 0.1.0 → 0.1.2

package/dist/packages/normalizer/src/html.js

@@ -0,0 +1,221 @@
+function unescapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCharCode(parseInt(code, 16)));
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, '')
+        .replace(/[\s_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Deterministically normalizes HTML documentation into clean Markdown,
+ * preserving code fences, language tags, headings, tables, callouts, and links.
+ */
+export function normalizeHtmlToMarkdown(html, baseUrl) {
+    const headings = [];
+    const links = [];
+    const codeExamples = [];
+    let title = '';
+    // 1. Extract title from <title> tag if present
+    const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (titleMatch) {
+        title = unescapeHtml(titleMatch[1]).replace(/\s+/g, ' ').trim();
+        title = title.split(/\s+[|–—-]\s+/)[0].trim();
+    }
+    // 2. Remove non-content / boilerplate tags
+    let cleaned = html
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, '')
+        .replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, '')
+        .replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, '')
+        .replace(/<nav\b[^>]*>[\s\S]*?<\/nav>/gi, '')
+        .replace(/<header\b[^>]*>[\s\S]*?<\/header>/gi, '')
+        .replace(/<footer\b[^>]*>[\s\S]*?<\/footer>/gi, '')
+        .replace(/<div\b[^>]*(?:class|id)=["'][^"']*\b(?:sidebar|nav|menu|navbar|footer|cookie-banner|breadcrumbs)\b[^"']*["'][^>]*>[\s\S]*?<\/div>/gi, '');
+    // 3. Extract and preserve code blocks
+    const codeBlockPlaceholders = [];
+    cleaned = cleaned.replace(/<pre\b[^>]*>(?:<code\b([^>]*)>)?([\s\S]*?)(?:<\/code>)?<\/pre>/gi, (_, codeAttrs, codeBody) => {
+        let lang = '';
+        if (codeAttrs) {
+            const langMatch = codeAttrs.match(/\b(?:class|data-language)=["'][^"']*\b(?:language-|lang-)?([a-zA-Z0-9_-]+)\b[^"']*["']/i);
+            if (langMatch && !['hljs', 'code'].includes(langMatch[1].toLowerCase())) {
+                lang = langMatch[1].toLowerCase();
+            }
+        }
+        const rawCode = unescapeHtml(codeBody.replace(/<[^>]+>/g, '')).trim();
+        if (!rawCode)
+            return '';
+        const exampleId = `code_${codeExamples.length + 1}`;
+        codeExamples.push({
+            id: exampleId,
+            language: lang || 'text',
+            code: rawCode,
+        });
+        const placeholder = `__DOCORBIT_CODE_BLOCK_${codeBlockPlaceholders.length}__`;
+        codeBlockPlaceholders.push(`\n\`\`\`${lang}\n${rawCode}\n\`\`\`\n`);
+        return placeholder;
+    });
+    // 4. Extract Headings and build anchors
+    cleaned = cleaned.replace(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi, (_, levelStr, attrs, innerText) => {
+        const level = parseInt(levelStr, 10);
+        const plainText = unescapeHtml(innerText.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+        if (!plainText)
+            return '';
+        let anchor = '';
+        const idMatch = attrs.match(/\bid=["']([^"']+)["']/i);
+        if (idMatch) {
+            anchor = idMatch[1];
+        }
+        else {
+            anchor = slugify(plainText);
+        }
+        headings.push({ level, text: plainText, anchor });
+        const hashes = '#'.repeat(level);
+        return `\n\n${hashes} ${plainText}\n\n`;
+    });
+    // Prefer first H1 as title, otherwise fallback to HTML title, then first heading
+    const h1 = headings.find(h => h.level === 1);
+    if (h1) {
+        title = h1.text;
+    }
+    else if (!title && headings.length > 0) {
+        title = headings[0].text;
+    }
+    if (!title) {
+        title = 'Documentation Page';
+    }
+    // 5. Extract and normalize Links
+    cleaned = cleaned.replace(/<a\b[^>]*\bhref=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, linkText) => {
+        const text = unescapeHtml(linkText.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+        if (!text || href.startsWith('#') || href.startsWith('javascript:'))
+            return text;
+        let absoluteUrl = href;
+        let isExternal = false;
+        try {
+            const resolved = new URL(href, baseUrl);
+            absoluteUrl = resolved.href;
+            const baseHost = new URL(baseUrl).hostname;
+            isExternal = resolved.hostname !== baseHost;
+        }
+        catch {
+            // Keep raw href
+        }
+        links.push({
+            text,
+            url: absoluteUrl,
+            isExternal,
+        });
+        return `[${text}](${absoluteUrl})`;
+    });
+    // 6. Handle Callouts & Blockquotes
+    cleaned = cleaned.replace(/<blockquote\b[^>]*>([\s\S]*?)<\/blockquote>/gi, (_, inner) => {
+        const blockText = inner
+            .replace(/<p\b[^>]*>/gi, '')
+            .replace(/<\/p>/gi, '\n')
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<[^>]+>/g, '');
+        const cleanLines = unescapeHtml(blockText)
+            .split('\n')
+            .map(l => l.trim())
+            .filter(Boolean)
+            .map(l => `> ${l}`)
+            .join('\n');
+        return `\n\n${cleanLines}\n\n`;
+    });
+    cleaned = cleaned.replace(/<div\b[^>]*\bclass=["'][^"']*\b(?:alert|callout|admonition|tip|warning|note|info)\b[^"']*["'][^>]*>([\s\S]*?)<\/div>/gi, (_, inner) => {
+        const alertText = unescapeHtml(inner.replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim();
+        if (!alertText)
+            return '';
+        return `\n\n> [!NOTE]\n> ${alertText}\n\n`;
+    });
+    // 7. Handle Tables
+    cleaned = cleaned.replace(/<table\b[^>]*>([\s\S]*?)<\/table>/gi, (_, tableContent) => {
+        const rows = [];
+        const rowMatches = tableContent.matchAll(/<tr\b[^>]*>([\s\S]*?)<\/tr>/gi);
+        for (const rMatch of rowMatches) {
+            const rowContent = rMatch[1];
+            const cells = [];
+            const cellMatches = rowContent.matchAll(/<t[hd]\b[^>]*>([\s\S]*?)<\/t[hd]>/gi);
+            for (const cMatch of cellMatches) {
+                const cellText = unescapeHtml(cMatch[1].replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+                cells.push(cellText);
+            }
+            if (cells.length > 0) {
+                rows.push(cells);
+            }
+        }
+        if (rows.length === 0)
+            return '';
+        const colCount = Math.max(...rows.map(r => r.length));
+        const headerRow = rows[0].map(c => c || '-');
+        while (headerRow.length < colCount)
+            headerRow.push('-');
+        const delimiterRow = Array(colCount).fill('---');
+        const tableLines = [
+            `| ${headerRow.join(' | ')} |`,
+            `| ${delimiterRow.join(' | ')} |`,
+        ];
+        for (let i = 1; i < rows.length; i++) {
+            const dataRow = rows[i].map(c => c || '');
+            while (dataRow.length < colCount)
+                dataRow.push('');
+            tableLines.push(`| ${dataRow.join(' | ')} |`);
+        }
+        return `\n\n${tableLines.join('\n')}\n\n`;
+    });
+    // 8. Handle Lists
+    cleaned = cleaned
+        .replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_, inner) => {
+        const text = unescapeHtml(inner.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
+        return `\n- ${text}`;
+    })
+        .replace(/<\/?(?:ul|ol)\b[^>]*>/gi, '\n');
+    // 9. Handle Inline elements
+    cleaned = cleaned
+        .replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, (_, inner) => {
+        const text = unescapeHtml(inner.replace(/<[^>]+>/g, '')).trim();
+        return text ? `\`${text}\`` : '';
+    })
+        .replace(/<(?:strong|b)\b[^>]*>([\s\S]*?)<\/(?:strong|b)>/gi, (_, inner) => {
+        const text = inner.trim();
+        return text ? `**${text}**` : '';
+    })
+        .replace(/<(?:em|i)\b[^>]*>([\s\S]*?)<\/(?:em|i)>/gi, (_, inner) => {
+        const text = inner.trim();
+        return text ? `*${text}*` : '';
+    })
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/?(?:p|div|section|article|main)\b[^>]*>/gi, '\n\n');
+    // 10. Strip all remaining HTML tags
+    cleaned = cleaned.replace(/<[^>]+>/g, '');
+    // 11. Restore preserved code blocks
+    for (let i = 0; i < codeBlockPlaceholders.length; i++) {
+        cleaned = cleaned.replace(`__DOCORBIT_CODE_BLOCK_${i}__`, codeBlockPlaceholders[i]);
+    }
+    // 12. Normalize whitespace
+    cleaned = unescapeHtml(cleaned)
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n\s+\n/g, '\n\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return {
+        title,
+        markdown: cleaned,
+        headings,
+        links,
+        codeExamples,
+    };
+}

package/{packages/normalizer/src/index.ts → dist/packages/normalizer/src/index.d.ts}

@@ -5,4 +5,3 @@ export * from './page.ts';
 export * from './slicer.ts';
 export * from './example-indexer.ts';
 export * from './pitfall-extractor.ts';
-

package/dist/packages/normalizer/src/index.js

@@ -0,0 +1,7 @@
+export * from "./html.js";
+export * from "./llms.js";
+export * from "./openapi.js";
+export * from "./page.js";
+export * from "./slicer.js";
+export * from "./example-indexer.js";
+export * from "./pitfall-extractor.js";

package/dist/packages/normalizer/src/llms.d.ts

@@ -0,0 +1,3 @@
+import type { LlmsDocument } from '../../shared/src/index.ts';
+export declare function parseLlmsTxt(content: string, baseUrl: string): LlmsDocument;
+export declare function isValidLlmsTxt(content: string): boolean;

package/dist/packages/normalizer/src/llms.js

@@ -0,0 +1,71 @@
+export function parseLlmsTxt(content, baseUrl) {
+    const lines = content.split('\n');
+    let title;
+    let summary;
+    const sections = [];
+    let currentSection = { name: 'Overview', links: [] };
+    const summaryLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        const rawLine = lines[i];
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (line.startsWith('# ') && !title) {
+            title = line.slice(2).trim();
+            continue;
+        }
+        if (line.startsWith('>')) {
+            const text = line.replace(/^>\s*/, '').trim();
+            if (text)
+                summaryLines.push(text);
+            continue;
+        }
+        if (line.startsWith('## ')) {
+            if (currentSection.links.length > 0 || currentSection.name !== 'Overview') {
+                sections.push(currentSection);
+            }
+            currentSection = {
+                name: line.slice(3).trim(),
+                links: [],
+            };
+            continue;
+        }
+        const linkMatch = line.match(/^[-*]\s+\[([^\]]+)\]\(([^)]+)\)(?::\s*(.*))?$/);
+        if (linkMatch) {
+            const linkTitle = linkMatch[1].trim();
+            let rawHref = linkMatch[2].trim();
+            const description = linkMatch[3] ? linkMatch[3].trim() : undefined;
+            try {
+                rawHref = new URL(rawHref, baseUrl).href;
+            }
+            catch {
+                // Keep raw
+            }
+            const linkItem = {
+                title: linkTitle,
+                url: rawHref,
+                ...(description ? { description } : {}),
+            };
+            currentSection.links.push(linkItem);
+        }
+    }
+    if (currentSection.links.length > 0 || sections.length === 0) {
+        sections.push(currentSection);
+    }
+    if (summaryLines.length > 0) {
+        summary = summaryLines.join(' ');
+    }
+    return {
+        title,
+        summary,
+        sections,
+        rawContent: content,
+    };
+}
+export function isValidLlmsTxt(content) {
+    if (!content || typeof content !== 'string')
+        return false;
+    const hasH1 = /^#\s+.+/m.test(content);
+    const hasLink = /^[-*]\s+\[.+\]\(.+\)/m.test(content);
+    return hasH1 && hasLink;
+}

package/dist/packages/normalizer/src/openapi/endpoint-parser.d.ts

@@ -0,0 +1,11 @@
+import type { OpenApiSummary, ApiEndpoint } from '../../../shared/src/index.ts';
+/**
+ * Detects if a document content is an OpenAPI or Swagger specification.
+ */
+export declare function detectOpenApiSpec(content: string, sourceUrl: string): OpenApiSummary | null;
+/**
+ * Parses all API endpoints from an OpenAPI 3.x or Swagger 2.0 specification.
+ * Fully deterministic with internal $ref resolution, schema normalization,
+ * pagination heuristics, and error detection.
+ */
+export declare function parseOpenApiEndpoints(rawSpec: string | Record<string, unknown>, pageId: string, snapshotId: string, sourceUrl?: string, docVersion?: string): ApiEndpoint[];

package/dist/packages/normalizer/src/openapi/endpoint-parser.js

@@ -0,0 +1,357 @@
+import { createHash } from 'node:crypto';
+import { resolveJsonPointer, normalizeSchema } from "./schema-resolver.js";
+/**
+ * Detects if a document content is an OpenAPI or Swagger specification.
+ */
+export function detectOpenApiSpec(content, sourceUrl) {
+    if (!content || typeof content !== 'string')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const openapiVer = typeof parsed.openapi === 'string' ? parsed.openapi : undefined;
+    const swaggerVer = typeof parsed.swagger === 'string' ? parsed.swagger : undefined;
+    const specVersion = openapiVer || swaggerVer;
+    if (!specVersion)
+        return null;
+    const info = (typeof parsed.info === 'object' && parsed.info !== null)
+        ? parsed.info
+        : {};
+    const title = typeof info.title === 'string' ? info.title : 'Untitled API';
+    const description = typeof info.description === 'string' ? info.description : undefined;
+    const servers = [];
+    if (Array.isArray(parsed.servers)) {
+        for (const server of parsed.servers) {
+            if (server && typeof server === 'object' && typeof server.url === 'string') {
+                servers.push(server.url);
+            }
+        }
+    }
+    else if (typeof parsed.host === 'string') {
+        const basePath = typeof parsed.basePath === 'string' ? parsed.basePath : '';
+        const schemes = Array.isArray(parsed.schemes) ? parsed.schemes : ['https'];
+        servers.push(`${schemes[0]}://${parsed.host}${basePath}`);
+    }
+    let pathCount = 0;
+    if (typeof parsed.paths === 'object' && parsed.paths !== null) {
+        pathCount = Object.keys(parsed.paths).length;
+    }
+    return {
+        specVersion,
+        title,
+        description,
+        servers,
+        pathCount,
+        sourceUrl,
+        rawJson: parsed,
+    };
+}
+/**
+ * Parses all API endpoints from an OpenAPI 3.x or Swagger 2.0 specification.
+ * Fully deterministic with internal $ref resolution, schema normalization,
+ * pagination heuristics, and error detection.
+ */
+export function parseOpenApiEndpoints(rawSpec, pageId, snapshotId, sourceUrl, docVersion) {
+    let root;
+    if (typeof rawSpec === 'string') {
+        try {
+            root = JSON.parse(rawSpec);
+        }
+        catch {
+            return [];
+        }
+    }
+    else {
+        root = rawSpec;
+    }
+    if (!root || typeof root !== 'object')
+        return [];
+    const isOpenApi3 = typeof root.openapi === 'string';
+    const isSwagger2 = typeof root.swagger === 'string';
+    if (!isOpenApi3 && !isSwagger2)
+        return [];
+    const paths = (typeof root.paths === 'object' && root.paths !== null)
+        ? root.paths
+        : {};
+    const endpoints = [];
+    const supportedMethods = new Set(['get', 'post', 'put', 'delete', 'patch', 'head', 'options']);
+    // Extract root-level security schemes
+    const securitySchemesMap = new Map();
+    if (isOpenApi3 && root.components && typeof root.components === 'object') {
+        const comps = root.components;
+        if (typeof comps.securitySchemes === 'object' && comps.securitySchemes !== null) {
+            for (const [name, schemeRaw] of Object.entries(comps.securitySchemes)) {
+                if (typeof schemeRaw === 'object' && schemeRaw !== null) {
+                    const s = schemeRaw;
+                    securitySchemesMap.set(name, {
+                        type: s.type || 'http',
+                        name: typeof s.name === 'string' ? s.name : name,
+                        in: s.in,
+                        scheme: typeof s.scheme === 'string' ? s.scheme : undefined,
+                        bearerFormat: typeof s.bearerFormat === 'string' ? s.bearerFormat : undefined,
+                        description: typeof s.description === 'string' ? s.description : undefined,
+                    });
+                }
+            }
+        }
+    }
+    else if (isSwagger2 && typeof root.securityDefinitions === 'object' && root.securityDefinitions !== null) {
+        for (const [name, schemeRaw] of Object.entries(root.securityDefinitions)) {
+            if (typeof schemeRaw === 'object' && schemeRaw !== null) {
+                const s = schemeRaw;
+                const rawType = typeof s.type === 'string' ? s.type : 'apiKey';
+                let mappedType = 'apiKey';
+                let mappedScheme = undefined;
+                if (rawType === 'basic') {
+                    mappedType = 'http';
+                    mappedScheme = 'basic';
+                }
+                else if (rawType === 'oauth2') {
+                    mappedType = 'oauth2';
+                }
+                securitySchemesMap.set(name, {
+                    type: mappedType,
+                    name: typeof s.name === 'string' ? s.name : name,
+                    in: s.in,
+                    scheme: mappedScheme,
+                    description: typeof s.description === 'string' ? s.description : undefined,
+                });
+            }
+        }
+    }
+    // Root security fallback
+    const rootSecurityReqs = Array.isArray(root.security)
+        ? root.security
+        : [];
+    const nowIso = new Date().toISOString();
+    for (const [pathStr, pathItemRaw] of Object.entries(paths)) {
+        if (!pathItemRaw || typeof pathItemRaw !== 'object')
+            continue;
+        const pathItem = pathItemRaw;
+        // Common path-level parameters
+        const pathCommonParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+        for (const [methodKey, operationRaw] of Object.entries(pathItem)) {
+            const method = methodKey.toLowerCase();
+            if (!supportedMethods.has(method))
+                continue;
+            if (!operationRaw || typeof operationRaw !== 'object')
+                continue;
+            const op = operationRaw;
+            // Summary & Description
+            const summary = typeof op.summary === 'string' ? op.summary : undefined;
+            const description = typeof op.description === 'string' ? op.description : undefined;
+            const operationId = typeof op.operationId === 'string' ? op.operationId : undefined;
+            const deprecated = Boolean(op.deprecated || pathItem.deprecated);
+            // Parameters
+            const rawParams = [...pathCommonParams, ...(Array.isArray(op.parameters) ? op.parameters : [])];
+            const parameters = [];
+            let swaggerBodySchema = undefined;
+            for (const pRaw of rawParams) {
+                let p = pRaw;
+                if (typeof p.$ref === 'string') {
+                    const resolved = resolveJsonPointer(root, p.$ref);
+                    if (typeof resolved === 'object' && resolved !== null) {
+                        p = resolved;
+                    }
+                }
+                if (isSwagger2 && p.in === 'body') {
+                    swaggerBodySchema = p.schema;
+                    continue;
+                }
+                const name = typeof p.name === 'string' ? p.name : '';
+                const paramIn = (typeof p.in === 'string' ? p.in : 'query');
+                const required = paramIn === 'path' ? true : Boolean(p.required);
+                const pDesc = typeof p.description === 'string' ? p.description : undefined;
+                const pDefault = p.default !== undefined ? p.default : (p.schema && typeof p.schema === 'object' ? p.schema.default : undefined);
+                const pExample = p.example !== undefined ? p.example : (p.schema && typeof p.schema === 'object' ? p.schema.example : undefined);
+                let pType = typeof p.type === 'string' ? p.type : undefined;
+                let pSchema = undefined;
+                if (p.schema && typeof p.schema === 'object') {
+                    pSchema = p.schema;
+                    if (!pType && typeof pSchema.type === 'string') {
+                        pType = pSchema.type;
+                    }
+                }
+                parameters.push({
+                    name,
+                    in: paramIn,
+                    required,
+                    type: pType,
+                    description: pDesc,
+                    default: pDefault,
+                    schema: pSchema,
+                    example: pExample,
+                });
+            }
+            // Request Body
+            let requestSchema = undefined;
+            if (isOpenApi3 && op.requestBody && typeof op.requestBody === 'object') {
+                let rb = op.requestBody;
+                if (typeof rb.$ref === 'string') {
+                    const resolved = resolveJsonPointer(root, rb.$ref);
+                    if (typeof resolved === 'object' && resolved !== null) {
+                        rb = resolved;
+                    }
+                }
+                if (typeof rb.content === 'object' && rb.content !== null) {
+                    const content = rb.content;
+                    // Prefer application/json, fallback to first media type
+                    const mediaTypeObj = (content['application/json'] || Object.values(content)[0]);
+                    if (mediaTypeObj && mediaTypeObj.schema) {
+                        requestSchema = normalizeSchema(mediaTypeObj.schema, root);
+                    }
+                }
+            }
+            else if (isSwagger2 && swaggerBodySchema) {
+                requestSchema = normalizeSchema(swaggerBodySchema, root);
+            }
+            // Responses & Errors
+            const responseSchema = {};
+            const errors = [];
+            if (typeof op.responses === 'object' && op.responses !== null) {
+                for (const [statusCode, resRaw] of Object.entries(op.responses)) {
+                    let res = resRaw;
+                    if (typeof res.$ref === 'string') {
+                        const resolved = resolveJsonPointer(root, res.$ref);
+                        if (typeof resolved === 'object' && resolved !== null) {
+                            res = resolved;
+                        }
+                    }
+                    const resDesc = typeof res.description === 'string' ? res.description : '';
+                    let contentType = undefined;
+                    let resSchemaObj = undefined;
+                    let resExample = undefined;
+                    if (isOpenApi3 && typeof res.content === 'object' && res.content !== null) {
+                        const content = res.content;
+                        const ctKey = content['application/json'] ? 'application/json' : Object.keys(content)[0];
+                        contentType = ctKey;
+                        const mediaObj = content[ctKey];
+                        if (mediaObj) {
+                            resSchemaObj = mediaObj.schema;
+                            resExample = mediaObj.example || (mediaObj.examples ? Object.values(mediaObj.examples)[0] : undefined);
+                        }
+                    }
+                    else if (isSwagger2) {
+                        resSchemaObj = res.schema;
+                        contentType = 'application/json';
+                        resExample = res.examples ? Object.values(res.examples)[0] : undefined;
+                    }
+                    const normalizedResSchema = normalizeSchema(resSchemaObj, root);
+                    const apiResponse = {
+                        statusCode,
+                        description: resDesc,
+                        contentType,
+                        schema: normalizedResSchema,
+                        example: resExample,
+                    };
+                    responseSchema[statusCode] = apiResponse;
+                    // Detect errors
+                    const isErrorCode = statusCode.startsWith('4') || statusCode.startsWith('5') || statusCode === 'default';
+                    if (isErrorCode) {
+                        errors.push({
+                            statusCode,
+                            description: resDesc,
+                            schema: normalizedResSchema,
+                            example: resExample,
+                        });
+                    }
+                }
+            }
+            // Authentication Schemes
+            const auth = [];
+            const opSecurityReqs = Array.isArray(op.security)
+                ? op.security
+                : rootSecurityReqs;
+            for (const req of opSecurityReqs) {
+                if (typeof req !== 'object' || req === null)
+                    continue;
+                for (const schemeName of Object.keys(req)) {
+                    const found = securitySchemesMap.get(schemeName);
+                    if (found) {
+                        // Avoid duplicate schemes
+                        if (!auth.some(a => a.name === found.name && a.type === found.type)) {
+                            auth.push(found);
+                        }
+                    }
+                    else {
+                        auth.push({
+                            type: 'apiKey',
+                            name: schemeName,
+                        });
+                    }
+                }
+            }
+            // Pagination Heuristics
+            let pagination = undefined;
+            const paramNames = parameters.map(p => p.name.toLowerCase());
+            const cursorParams = paramNames.filter(n => ['starting_after', 'ending_before', 'cursor', 'next_cursor', 'after', 'before'].includes(n));
+            const offsetParams = paramNames.filter(n => ['offset', 'skip', 'start'].includes(n));
+            const pageParams = paramNames.filter(n => ['page', 'page_number', 'pagenumber'].includes(n));
+            const limitParams = paramNames.filter(n => ['limit', 'per_page', 'page_size', 'pagesize', 'count', 'max'].includes(n));
+            // Inspect response properties for pagination clues
+            const okResponse = responseSchema['200'] || responseSchema['201'];
+            const responseProps = okResponse?.schema?.properties ? Object.keys(okResponse.schema.properties) : [];
+            const detectedResponseFields = responseProps.filter(prop => ['has_more', 'next_cursor', 'cursor', 'next_page', 'page_info', 'total_count', 'data', 'items', 'results'].includes(prop.toLowerCase()));
+            if (cursorParams.length > 0) {
+                pagination = {
+                    type: 'cursor',
+                    parameters: [...cursorParams, ...limitParams],
+                    responseFields: detectedResponseFields,
+                };
+            }
+            else if (offsetParams.length > 0) {
+                pagination = {
+                    type: 'offset',
+                    parameters: [...offsetParams, ...limitParams],
+                    responseFields: detectedResponseFields,
+                };
+            }
+            else if (pageParams.length > 0) {
+                pagination = {
+                    type: 'page',
+                    parameters: [...pageParams, ...limitParams],
+                    responseFields: detectedResponseFields,
+                };
+            }
+            // Deterministic Endpoint ID
+            const endpointId = createHash('sha256')
+                .update(`${pageId}:${method}:${pathStr}`)
+                .digest('hex')
+                .substring(0, 16);
+            const provenance = sourceUrl
+                ? {
+                    sourceUrl,
+                    retrievedAt: nowIso,
+                    sourceAuthority: 'official',
+                }
+                : undefined;
+            endpoints.push({
+                id: endpointId,
+                pageId,
+                snapshotId,
+                method: method,
+                path: pathStr,
+                summary,
+                description,
+                operationId,
+                parameters,
+                requestSchema,
+                responseSchema,
+                auth,
+                errors,
+                pagination,
+                deprecated,
+                docVersion,
+                provenance,
+                createdAt: nowIso,
+            });
+        }
+    }
+    return endpoints;
+}