specra 0.1.13 → 0.2.0

package/dist/parsers/openapi-parser.js

@@ -0,0 +1,209 @@
+/**
+ * Parser for OpenAPI 3.0/3.1 specifications
+ */
+export class OpenApiParser {
+    validate(input) {
+        return (typeof input === "object" &&
+            input !== null &&
+            ("openapi" in input || "swagger" in input) &&
+            "paths" in input);
+    }
+    parse(input) {
+        if (!this.validate(input)) {
+            throw new Error("Invalid OpenAPI spec format");
+        }
+        const baseUrl = this.extractBaseUrl(input);
+        const endpoints = [];
+        // Parse paths
+        for (const [path, pathItem] of Object.entries(input.paths || {})) {
+            const methods = ["get", "post", "put", "patch", "delete"];
+            for (const method of methods) {
+                const operation = pathItem[method];
+                if (!operation)
+                    continue;
+                const endpoint = this.parseOperation(path, method.toUpperCase(), operation, input);
+                endpoints.push(endpoint);
+            }
+        }
+        return {
+            version: input.info?.version,
+            title: input.info?.title,
+            description: input.info?.description,
+            baseUrl,
+            auth: this.extractAuth(input),
+            endpoints,
+        };
+    }
+    extractBaseUrl(spec) {
+        // OpenAPI 3.x servers
+        if (spec.servers && spec.servers.length > 0) {
+            return spec.servers[0].url;
+        }
+        // Swagger 2.0
+        if (spec.host) {
+            const scheme = spec.schemes?.[0] || "https";
+            const basePath = spec.basePath || "";
+            return `${scheme}://${spec.host}${basePath}`;
+        }
+        return "";
+    }
+    extractAuth(spec) {
+        const securitySchemes = spec.components?.securitySchemes || spec.securityDefinitions;
+        if (!securitySchemes)
+            return undefined;
+        // Get the first security scheme
+        const firstScheme = Object.values(securitySchemes)[0];
+        if (!firstScheme)
+            return undefined;
+        if (firstScheme.type === "http" && firstScheme.scheme === "bearer") {
+            return {
+                type: "bearer",
+                description: firstScheme.description,
+                tokenPrefix: "Bearer",
+            };
+        }
+        if (firstScheme.type === "apiKey") {
+            return {
+                type: "apiKey",
+                description: firstScheme.description,
+                headerName: firstScheme.name || "X-API-Key",
+            };
+        }
+        if (firstScheme.type === "http" && firstScheme.scheme === "basic") {
+            return {
+                type: "basic",
+                description: firstScheme.description,
+            };
+        }
+        return undefined;
+    }
+    parseOperation(path, method, operation, spec) {
+        const endpoint = {
+            title: operation.summary || operation.operationId || `${method} ${path}`,
+            method,
+            path: this.convertPathParams(path),
+            description: operation.description,
+        };
+        // Parse parameters
+        const params = this.parseParameters(operation.parameters || [], spec);
+        if (params.path.length > 0)
+            endpoint.pathParams = params.path;
+        if (params.query.length > 0)
+            endpoint.queryParams = params.query;
+        if (params.header.length > 0) {
+            endpoint.headers = params.header.map((p) => ({
+                name: p.name,
+                value: p.example || "",
+                description: p.description,
+            }));
+        }
+        // Parse request body
+        if (operation.requestBody) {
+            endpoint.body = this.parseRequestBody(operation.requestBody, spec);
+        }
+        // Parse responses
+        const responses = this.parseResponses(operation.responses || {}, spec);
+        if (responses.success)
+            endpoint.successResponse = responses.success;
+        if (responses.errors.length > 0)
+            endpoint.errorResponses = responses.errors;
+        return endpoint;
+    }
+    convertPathParams(path) {
+        // Convert OpenAPI {param} to :param
+        return path.replace(/\{([^}]+)\}/g, ":$1");
+    }
+    parseParameters(parameters, spec) {
+        const result = { path: [], query: [], header: [] };
+        for (const param of parameters) {
+            // Resolve $ref if present
+            const resolved = param.$ref ? this.resolveRef(param.$ref, spec) : param;
+            const apiParam = {
+                name: resolved.name,
+                type: resolved.schema?.type || resolved.type || "string",
+                required: resolved.required,
+                description: resolved.description,
+                example: resolved.example || resolved.schema?.example,
+            };
+            if (resolved.in === "path")
+                result.path.push(apiParam);
+            else if (resolved.in === "query")
+                result.query.push(apiParam);
+            else if (resolved.in === "header")
+                result.header.push(apiParam);
+        }
+        return result;
+    }
+    parseRequestBody(requestBody, spec) {
+        const content = requestBody.content?.["application/json"];
+        if (!content)
+            return undefined;
+        return {
+            description: requestBody.description,
+            example: content.example || this.generateExample(content.schema, spec),
+            schema: content.schema,
+        };
+    }
+    parseResponses(responses, spec) {
+        const result = { errors: [] };
+        for (const [statusCode, response] of Object.entries(responses)) {
+            const status = parseInt(statusCode);
+            if (isNaN(status))
+                continue;
+            const resolved = response.$ref ? this.resolveRef(response.$ref, spec) : response;
+            const content = resolved.content?.["application/json"];
+            const apiResponse = {
+                status,
+                description: resolved.description,
+                example: content?.example || this.generateExample(content?.schema, spec),
+                schema: content?.schema,
+            };
+            if (status >= 200 && status < 300) {
+                result.success = apiResponse;
+            }
+            else {
+                result.errors.push(apiResponse);
+            }
+        }
+        return result;
+    }
+    generateExample(schema, spec) {
+        if (!schema)
+            return undefined;
+        if (schema.$ref)
+            schema = this.resolveRef(schema.$ref, spec);
+        if (schema.example)
+            return schema.example;
+        // Simple example generation based on schema type
+        if (schema.type === "object" && schema.properties) {
+            const example = {};
+            for (const [key, prop] of Object.entries(schema.properties)) {
+                example[key] = this.generateExample(prop, spec);
+            }
+            return example;
+        }
+        if (schema.type === "array" && schema.items) {
+            return [this.generateExample(schema.items, spec)];
+        }
+        // Default values by type
+        const defaults = {
+            string: "string",
+            number: 0,
+            integer: 0,
+            boolean: false,
+            object: {},
+            array: [],
+        };
+        return defaults[schema.type] || null;
+    }
+    resolveRef(ref, spec) {
+        const path = ref.replace(/^#\//, "").split("/");
+        let current = spec;
+        for (const segment of path) {
+            current = current[segment];
+            if (!current)
+                return {};
+        }
+        return current;
+    }
+}

package/dist/parsers/postman-parser.d.ts

@@ -0,0 +1,20 @@
+import type { SpecraApiSpec } from "../api-parser.types";
+import type { ApiSpecParser } from "./base-parser";
+/**
+ * Parser for Postman Collection v2.0/v2.1
+ */
+export declare class PostmanParser implements ApiSpecParser {
+    validate(input: any): boolean;
+    parse(input: any): SpecraApiSpec;
+    private extractBaseUrl;
+    private findFirstRequest;
+    private extractAuth;
+    private extractGlobalHeaders;
+    private parseItems;
+    private parseRequest;
+    private parseUrl;
+    private buildPath;
+    private parseUrlParams;
+    private parseBody;
+    private parseResponses;
+}

package/dist/parsers/postman-parser.js

@@ -0,0 +1,260 @@
+/**
+ * Parser for Postman Collection v2.0/v2.1
+ */
+export class PostmanParser {
+    validate(input) {
+        return (typeof input === "object" &&
+            input !== null &&
+            "info" in input &&
+            input.info?.schema?.includes("v2"));
+    }
+    parse(input) {
+        if (!this.validate(input)) {
+            throw new Error("Invalid Postman Collection format (requires v2.0 or v2.1)");
+        }
+        const baseUrl = this.extractBaseUrl(input);
+        const endpoints = [];
+        // Parse items (can be nested in folders)
+        this.parseItems(input.item || [], endpoints, baseUrl, input);
+        return {
+            version: input.info?.version,
+            title: input.info?.name,
+            description: input.info?.description,
+            baseUrl,
+            auth: this.extractAuth(input.auth),
+            globalHeaders: this.extractGlobalHeaders(input),
+            endpoints,
+        };
+    }
+    extractBaseUrl(collection) {
+        // Try to get from variables
+        const baseUrlVar = collection.variable?.find((v) => v.key === "baseUrl" || v.key === "base_url" || v.key === "url");
+        if (baseUrlVar)
+            return baseUrlVar.value;
+        // Try to extract from first request
+        if (collection.item && collection.item.length > 0) {
+            const firstRequest = this.findFirstRequest(collection.item);
+            if (firstRequest?.request?.url) {
+                const url = this.parseUrl(firstRequest.request.url);
+                if (url.host) {
+                    return `${url.protocol}://${url.host.join(".")}`;
+                }
+            }
+        }
+        return "";
+    }
+    findFirstRequest(items) {
+        for (const item of items) {
+            if (item.request)
+                return item;
+            if (item.item) {
+                const found = this.findFirstRequest(item.item);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    extractAuth(auth) {
+        if (!auth)
+            return undefined;
+        if (auth.type === "bearer") {
+            return {
+                type: "bearer",
+                tokenPrefix: "Bearer",
+            };
+        }
+        if (auth.type === "apikey") {
+            const keyData = auth.apikey?.find((a) => a.key === "key");
+            const keyName = keyData?.value || "X-API-Key";
+            return {
+                type: "apiKey",
+                headerName: keyName,
+            };
+        }
+        if (auth.type === "basic") {
+            return {
+                type: "basic",
+            };
+        }
+        return undefined;
+    }
+    extractGlobalHeaders(collection) {
+        // Postman doesn't have global headers in the same way, but we can check for common patterns
+        return [];
+    }
+    parseItems(items, endpoints, baseUrl, collection) {
+        for (const item of items) {
+            // If it's a folder, recurse
+            if (item.item && Array.isArray(item.item)) {
+                this.parseItems(item.item, endpoints, baseUrl, collection);
+            }
+            // If it's a request
+            else if (item.request) {
+                const endpoint = this.parseRequest(item, baseUrl, collection);
+                endpoints.push(endpoint);
+            }
+        }
+    }
+    parseRequest(item, baseUrl, collection) {
+        const request = item.request;
+        const url = this.parseUrl(request.url);
+        const endpoint = {
+            title: item.name,
+            method: request.method.toUpperCase(),
+            path: this.buildPath(url, baseUrl),
+            description: item.request.description || item.description,
+        };
+        // Parse URL parameters (path and query)
+        const params = this.parseUrlParams(url);
+        if (params.path.length > 0)
+            endpoint.pathParams = params.path;
+        if (params.query.length > 0)
+            endpoint.queryParams = params.query;
+        // Parse headers
+        if (request.header && request.header.length > 0) {
+            endpoint.headers = request.header
+                .filter((h) => !h.disabled)
+                .map((h) => ({
+                name: h.key,
+                value: h.value || "",
+                description: h.description,
+            }));
+        }
+        // Parse request body
+        if (request.body) {
+            endpoint.body = this.parseBody(request.body);
+        }
+        // Parse response examples
+        const responses = this.parseResponses(item.response || []);
+        if (responses.success)
+            endpoint.successResponse = responses.success;
+        if (responses.errors.length > 0)
+            endpoint.errorResponses = responses.errors;
+        return endpoint;
+    }
+    parseUrl(url) {
+        if (typeof url === "string") {
+            // Parse string URL
+            const urlObj = new URL(url);
+            return {
+                protocol: urlObj.protocol.replace(":", ""),
+                host: urlObj.hostname.split("."),
+                path: urlObj.pathname.split("/").filter(Boolean),
+                query: [],
+                variable: [],
+            };
+        }
+        return {
+            protocol: url.protocol || "https",
+            host: url.host || [],
+            path: url.path || [],
+            query: url.query || [],
+            variable: url.variable || [],
+        };
+    }
+    buildPath(url, baseUrl) {
+        let path = "/";
+        if (url.path && url.path.length > 0) {
+            path += url.path.join("/");
+        }
+        // Convert Postman :param to our :param format (they're the same!)
+        // But we need to handle {{variable}} syntax
+        path = path.replace(/\{\{([^}]+)\}\}/g, ":$1");
+        return path;
+    }
+    parseUrlParams(url) {
+        const result = { path: [], query: [] };
+        // Path parameters from variables
+        if (url.variable && url.variable.length > 0) {
+            for (const v of url.variable) {
+                result.path.push({
+                    name: v.key,
+                    type: v.type || "string",
+                    description: v.description,
+                    example: v.value,
+                });
+            }
+        }
+        // Extract path params from the path itself
+        if (url.path && url.path.length > 0) {
+            for (const segment of url.path) {
+                if (segment.startsWith(":")) {
+                    const paramName = segment.slice(1);
+                    // Only add if not already added from variables
+                    if (!result.path.find((p) => p.name === paramName)) {
+                        result.path.push({
+                            name: paramName,
+                            type: "string",
+                        });
+                    }
+                }
+            }
+        }
+        // Query parameters
+        if (url.query && url.query.length > 0) {
+            for (const q of url.query) {
+                if (q.disabled)
+                    continue;
+                result.query.push({
+                    name: q.key,
+                    type: "string",
+                    description: q.description,
+                    example: q.value,
+                });
+            }
+        }
+        return result;
+    }
+    parseBody(body) {
+        if (!body)
+            return undefined;
+        let example;
+        let description = body.description;
+        if (body.mode === "raw") {
+            try {
+                example = JSON.parse(body.raw);
+            }
+            catch {
+                example = body.raw;
+            }
+        }
+        else if (body.mode === "formdata" || body.mode === "urlencoded") {
+            example = {};
+            for (const item of body[body.mode] || []) {
+                if (!item.disabled) {
+                    example[item.key] = item.value;
+                }
+            }
+        }
+        return {
+            description,
+            example,
+        };
+    }
+    parseResponses(responses) {
+        const result = { errors: [] };
+        for (const response of responses) {
+            let example;
+            try {
+                example = JSON.parse(response.body);
+            }
+            catch {
+                example = response.body;
+            }
+            const apiResponse = {
+                status: response.code || 200,
+                description: response.name,
+                example,
+            };
+            if (apiResponse.status >= 200 && apiResponse.status < 300) {
+                if (!result.success)
+                    result.success = apiResponse;
+            }
+            else {
+                result.errors.push(apiResponse);
+            }
+        }
+        return result;
+    }
+}

package/dist/parsers/specra-parser.d.ts

@@ -0,0 +1,10 @@
+import type { SpecraApiSpec } from "../api-parser.types";
+import type { ApiSpecParser } from "./base-parser";
+/**
+ * Parser for native Specra API format
+ * This is a pass-through parser since the input is already in the correct format
+ */
+export declare class SpecraParser implements ApiSpecParser {
+    validate(input: any): boolean;
+    parse(input: any): SpecraApiSpec;
+}

package/dist/parsers/specra-parser.js

@@ -0,0 +1,18 @@
+/**
+ * Parser for native Specra API format
+ * This is a pass-through parser since the input is already in the correct format
+ */
+export class SpecraParser {
+    validate(input) {
+        return (typeof input === "object" &&
+            input !== null &&
+            "endpoints" in input &&
+            Array.isArray(input.endpoints));
+    }
+    parse(input) {
+        if (!this.validate(input)) {
+            throw new Error("Invalid Specra API spec format");
+        }
+        return input;
+    }
+}

package/dist/redirects.d.ts

@@ -0,0 +1,12 @@
+export interface RedirectMapping {
+    from: string;
+    to: string;
+}
+/**
+ * Build redirect mappings from all docs' redirect_from frontmatter
+ */
+export declare function buildRedirectMappings(): Promise<RedirectMapping[]>;
+/**
+ * Find redirect destination for a given path
+ */
+export declare function findRedirect(path: string): Promise<string | null>;

package/dist/redirects.js

@@ -0,0 +1,30 @@
+import { getAllDocs, getVersions } from "./mdx";
+/**
+ * Build redirect mappings from all docs' redirect_from frontmatter
+ */
+export async function buildRedirectMappings() {
+    const versions = getVersions();
+    const redirects = [];
+    for (const version of versions) {
+        const docs = await getAllDocs(version);
+        for (const doc of docs) {
+            if (doc.meta.redirect_from && Array.isArray(doc.meta.redirect_from)) {
+                for (const oldPath of doc.meta.redirect_from) {
+                    redirects.push({
+                        from: oldPath,
+                        to: `/docs/${version}/${doc.slug}`,
+                    });
+                }
+            }
+        }
+    }
+    return redirects;
+}
+/**
+ * Find redirect destination for a given path
+ */
+export async function findRedirect(path) {
+    const redirects = await buildRedirectMappings();
+    const redirect = redirects.find((r) => r.from === path);
+    return redirect ? redirect.to : null;
+}

package/dist/remark-code-meta.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Remark plugin to extract code block meta strings and pass them as props
+ * Converts: ```js filename.js
+ * Into props: { language: 'js', meta: 'filename.js' }
+ */
+export declare function remarkCodeMeta(): (tree: any) => void;

package/dist/remark-code-meta.js

@@ -0,0 +1,21 @@
+/**
+ * Remark plugin to extract code block meta strings and pass them as props
+ * Converts: ```js filename.js
+ * Into props: { language: 'js', meta: 'filename.js' }
+ */
+export function remarkCodeMeta() {
+    return (tree) => {
+        const visit = (node) => {
+            if (node.type === 'code' && node.meta) {
+                // Store the meta string in the node's data
+                node.data = node.data || {};
+                node.data.hProperties = node.data.hProperties || {};
+                node.data.hProperties.meta = node.meta;
+            }
+            if (node.children) {
+                node.children.forEach(visit);
+            }
+        };
+        visit(tree);
+    };
+}

package/dist/sidebar-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Unified sidebar sorting and structure building utilities
+ * This module provides consistent sidebar logic across the application
+ * to ensure ordering is handled the same way everywhere.
+ */
+export interface SidebarGroup {
+    label: string;
+    path: string;
+    icon?: string;
+    items: any[];
+    position: number;
+    collapsible: boolean;
+    defaultCollapsed: boolean;
+    children: Record<string, SidebarGroup>;
+}
+/**
+ * Sort sidebar items by their position.
+ * Items with explicit sidebar_position come first (sorted numerically),
+ * followed by items without position (sorted by their original order).
+ *
+ * @param items - Array of items with optional sidebar_position
+ * @returns Sorted array of items
+ */
+export declare function sortSidebarItems<T extends {
+    sidebar_position?: number;
+    meta?: any;
+}>(items: T[]): T[];
+/**
+ * Sort sidebar groups by their position.
+ * Groups with explicit position come first (sorted numerically),
+ * followed by groups without position at the end (sorted by their original order).
+ *
+ * @param groups - Record of group key to group object with position
+ * @returns Sorted array of [key, group] tuples
+ */
+export declare function sortSidebarGroups<T extends {
+    position: number;
+}>(groups: Record<string, T>): [string, T][];
+/**
+ * Build hierarchical sidebar structure from flat list of documents
+ * This is the single source of truth for sidebar structure used by both
+ * the sidebar component and navigation (prev/next) links.
+ *
+ * @param docs - Array of documents with metadata
+ * @returns Object containing root groups and standalone items
+ */
+export declare function buildSidebarStructure<T extends {
+    filePath: string;
+    slug: string;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryIcon?: string;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    meta: any;
+}>(docs: T[]): {
+    rootGroups: Record<string, SidebarGroup>;
+    standalone: T[];
+};