specra 0.1.0

package/dist/lib/index.d.ts

@@ -0,0 +1,798 @@
+import { ClassValue } from 'clsx';
+
+interface DocMeta {
+    title: string;
+    description?: string;
+    slug?: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    order?: number;
+    sidebar_position?: number;
+    content?: string;
+    last_updated?: string;
+    draft?: boolean;
+    authors?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    tags?: string[];
+    redirect_from?: string[];
+    reading_time?: number;
+    word_count?: number;
+    icon?: string;
+    tab_group?: string;
+}
+interface Doc {
+    slug: string;
+    filePath: string;
+    title: string;
+    meta: DocMeta;
+    content: string;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+}
+interface TocItem {
+    id: string;
+    title: string;
+    level: number;
+}
+declare function getVersions(): string[];
+declare function getDocBySlug(slug: string, version?: string): Promise<Doc | null>;
+declare function getAllDocs(version?: string): Promise<Doc[]>;
+declare function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): {
+    previous?: Doc;
+    next?: Doc;
+};
+declare function extractTableOfContents(content: string): TocItem[];
+/**
+ * Check if a slug represents a category (has child documents)
+ */
+declare function isCategoryPage(slug: string, allDocs: Doc[]): boolean;
+
+/**
+ * Caching layer for MDX operations to improve development performance
+ *
+ * This module provides in-memory caching for expensive file system operations
+ * that occur during static generation. In development mode, caches are
+ * invalidated automatically when files change.
+ */
+
+/**
+ * Cached version of getVersions()
+ */
+declare function getCachedVersions(): string[];
+/**
+ * Cached version of getAllDocs()
+ */
+declare function getCachedAllDocs(version?: string): Promise<Doc[]>;
+/**
+ * Cached version of getDocBySlug()
+ */
+declare function getCachedDocBySlug(slug: string, version?: string): Promise<Doc | null>;
+/**
+ * Manually clear all caches
+ * Useful for testing or when you want to force a refresh
+ */
+declare function clearAllCaches(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getCacheStats(): {
+    versions: {
+        cached: boolean;
+        age: number;
+    };
+    allDocs: {
+        entries: number;
+        versions: string[];
+    };
+    docBySlug: {
+        entries: number;
+    };
+};
+
+interface TOCItem {
+    id: string;
+    title: string;
+    level: number;
+}
+/**
+ * Extract headings from HTML string for table of contents
+ */
+declare function extractHeadings(html: string): TOCItem[];
+
+/**
+ * Configuration schema for Specra documentation system
+ */
+/**
+ * Site metadata and branding
+ */
+interface SiteConfig {
+    /** The title of the documentation site */
+    title: string;
+    /** Short description of the documentation */
+    description?: string;
+    /** URL where the documentation is hosted */
+    url?: string;
+    /** Base URL path for the documentation (e.g., '/docs') */
+    baseUrl?: string;
+    /** Path to the site logo */
+    logo?: string;
+    /** Path to the favicon */
+    favicon?: string;
+    /** Default language for the documentation */
+    language?: string;
+    /** Organization or author name */
+    organizationName?: string;
+    /** Project name */
+    projectName?: string;
+    /** Active/default version for the documentation */
+    activeVersion?: string;
+}
+/**
+ * Theme and appearance settings
+ */
+interface ThemeConfig {
+    /** Primary color for the theme */
+    primaryColor?: string;
+    /** Default theme mode */
+    defaultMode?: "light" | "dark" | "system";
+    /** Whether to respect system preferences */
+    respectPrefersColorScheme?: boolean;
+    /** Custom CSS file path */
+    customCss?: string;
+}
+/**
+ * Tab group for organizing documentation
+ */
+interface TabGroup {
+    /** Unique identifier for the tab group */
+    id: string;
+    /** Display label for the tab */
+    label: string;
+    /** Optional icon name (lucide-react icon) */
+    icon?: string;
+}
+/**
+ * Navigation and sidebar configuration
+ */
+interface NavigationConfig {
+    /** Whether to show the sidebar by default */
+    showSidebar?: boolean;
+    /** Whether the sidebar is collapsible */
+    collapsibleSidebar?: boolean;
+    /** Whether to show breadcrumbs */
+    showBreadcrumbs?: boolean;
+    /** Whether to show table of contents */
+    showTableOfContents?: boolean;
+    /** Position of table of contents */
+    tocPosition?: "left" | "right";
+    /** Maximum depth for table of contents */
+    tocMaxDepth?: number;
+    /** Tab groups for organizing documentation sections */
+    tabGroups?: TabGroup[];
+}
+/**
+ * Social and external links
+ */
+interface SocialLinks {
+    /** GitHub repository URL */
+    github?: string;
+    /** Twitter/X handle or URL */
+    twitter?: string;
+    /** Discord invite URL */
+    discord?: string;
+    /** LinkedIn profile or company page */
+    linkedin?: string;
+    /** YouTube channel URL */
+    youtube?: string;
+    /** Custom social links */
+    custom?: Array<{
+        label: string;
+        url: string;
+        icon?: string;
+    }>;
+}
+/**
+ * Search configuration
+ */
+interface SearchConfig {
+    /** Enable/disable search functionality */
+    enabled?: boolean;
+    /** Placeholder text for search input */
+    placeholder?: string;
+    /** Search provider type */
+    provider?: "meilisearch" | "algolia" | "local";
+    /** Meilisearch configuration */
+    meilisearch?: {
+        /** Meilisearch server URL */
+        host: string;
+        /** API key for Meilisearch */
+        apiKey?: string;
+        /** Index name */
+        indexName: string;
+    };
+}
+/**
+ * Analytics configuration
+ */
+interface AnalyticsConfig {
+    /** Google Analytics tracking ID */
+    googleAnalytics?: string;
+    /** Google Tag Manager ID */
+    googleTagManager?: string;
+    /** Plausible Analytics domain */
+    plausible?: string;
+    /** Custom analytics scripts */
+    custom?: Array<{
+        src: string;
+        async?: boolean;
+        defer?: boolean;
+    }>;
+}
+/**
+ * Footer configuration
+ */
+interface FooterConfig {
+    /** Copyright text */
+    copyright?: string;
+    /** Footer links organized by columns */
+    links?: Array<{
+        title: string;
+        items: Array<{
+            label: string;
+            href: string;
+        }>;
+    }>;
+    /** Custom footer content */
+    customContent?: string;
+}
+/**
+ * Documentation features
+ */
+interface FeaturesConfig {
+    /** Enable/disable edit this page links */
+    editUrl?: string | false;
+    /** Show last updated timestamp */
+    showLastUpdated?: boolean;
+    /** Show reading time estimate */
+    showReadingTime?: boolean;
+    /** Show author information */
+    showAuthors?: boolean;
+    /** Show tags */
+    showTags?: boolean;
+    /** Enable version dropdown */
+    versioning?: boolean;
+    /** Enable i18n (internationalization) */
+    i18n?: boolean;
+}
+/**
+ * Site-wide banner configuration
+ */
+interface BannerConfig {
+    /** Whether the banner is enabled */
+    enabled?: boolean;
+    /** Banner message */
+    message?: string;
+    /** Banner type */
+    type?: "info" | "warning" | "success" | "error";
+    /** Whether the banner can be dismissed */
+    dismissible?: boolean;
+}
+/**
+ * Environment variables that can be used in documentation
+ * These will be replaced at build time or runtime
+ */
+interface EnvironmentVariables {
+    /** API base URL */
+    API_BASE_URL?: string;
+    /** API version */
+    API_VERSION?: string;
+    /** CDN URL */
+    CDN_URL?: string;
+    /** Custom environment variables */
+    [key: string]: string | undefined;
+}
+/**
+ * Deployment configuration for different hosting scenarios
+ */
+interface DeploymentConfig {
+    /**
+     * Deployment target
+     * - 'vercel': For Vercel or similar Node.js hosting (uses 'standalone' output)
+     * - 'github-pages': For GitHub Pages static hosting (uses 'export' output)
+     * - 'static': For any static hosting like Netlify, Cloudflare Pages, etc.
+     * - 'custom-domain-static': For static hosting with custom domain (no basePath needed)
+     */
+    target?: "vercel" | "github-pages" | "static" | "custom-domain-static";
+    /**
+     * Base path for assets when deploying to GitHub Pages without custom domain
+     * This should be your repository name (e.g., 'my-repo')
+     * Only used when target is 'github-pages' and no custom domain is configured
+     */
+    basePath?: string;
+    /**
+     * Whether a custom domain is configured
+     * When true, basePath will be ignored even for GitHub Pages
+     */
+    customDomain?: boolean;
+}
+/**
+ * Main configuration interface
+ */
+interface SpecraConfig {
+    /** Site metadata and branding */
+    site: SiteConfig;
+    /** Theme and appearance settings */
+    theme?: ThemeConfig;
+    /** Navigation and sidebar configuration */
+    navigation?: NavigationConfig;
+    /** Social and external links */
+    social?: SocialLinks;
+    /** Search configuration */
+    search?: SearchConfig;
+    /** Analytics configuration */
+    analytics?: AnalyticsConfig;
+    /** Footer configuration */
+    footer?: FooterConfig;
+    /** Site-wide banner */
+    banner?: BannerConfig;
+    /** Documentation features */
+    features?: FeaturesConfig;
+    /** Environment variables for use in docs */
+    env?: EnvironmentVariables;
+    /** Deployment configuration */
+    deployment?: DeploymentConfig;
+}
+/**
+ * Default configuration values
+ */
+declare const defaultConfig: SpecraConfig;
+
+/**
+ * Load and parse the Specra configuration file
+ * Falls back to default configuration if file doesn't exist or is invalid
+ */
+declare function loadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+/**
+ * Get a specific configuration value by path (SERVER ONLY)
+ * Example: getConfigValue('site.title') or getConfigValue('theme.defaultMode')
+ */
+declare function getConfigValue<T = any>(path: string, config?: SpecraConfig): T | undefined;
+/**
+ * Replace environment variables in a string (SERVER ONLY)
+ * Supports ${ENV_VAR} and {{ENV_VAR}} syntax
+ */
+declare function replaceEnvVariables(text: string, config?: SpecraConfig): string;
+/**
+ * Process content and replace all environment variables (SERVER ONLY)
+ */
+declare function processContentWithEnv(content: string, config?: SpecraConfig): string;
+/**
+ * Validate configuration (basic validation) (SERVER ONLY)
+ */
+declare function validateConfig(config: SpecraConfig): {
+    valid: boolean;
+    errors: string[];
+};
+declare function initConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+/**
+ * Get the configuration instance (cached) (SERVER ONLY)
+ */
+declare function getConfig(): SpecraConfig;
+/**
+ * Reload the configuration (useful for development) (SERVER ONLY)
+ */
+declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+
+/**
+ * Simple API Documentation Format for Specra
+ * Easy to write, easy to parse
+ */
+interface ApiParam {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: any;
+    example?: any;
+}
+interface ApiHeader {
+    name: string;
+    value: string;
+    description?: string;
+}
+interface ApiResponse$1 {
+    status: number;
+    description?: string;
+    example?: any;
+    schema?: any;
+}
+interface ApiEndpointSpec {
+    title: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    description?: string;
+    pathParams?: ApiParam[];
+    queryParams?: ApiParam[];
+    headers?: ApiHeader[];
+    body?: {
+        description?: string;
+        example?: any;
+        schema?: any;
+    };
+    successResponse?: ApiResponse$1;
+    errorResponses?: ApiResponse$1[];
+    examples?: {
+        title: string;
+        language: string;
+        code: string;
+    }[];
+}
+interface SpecraApiSpec {
+    version?: string;
+    title?: string;
+    description?: string;
+    baseUrl: string;
+    env?: Record<string, string>;
+    globalHeaders?: ApiHeader[];
+    auth?: {
+        type: "bearer" | "apiKey" | "basic";
+        description?: string;
+        headerName?: string;
+        tokenPrefix?: string;
+    };
+    endpoints: ApiEndpointSpec[];
+}
+
+/**
+ * Base interface for all API spec parsers
+ */
+interface ApiSpecParser {
+    /**
+     * Parse the input spec and convert to Specra format
+     */
+    parse(input: any): SpecraApiSpec;
+    /**
+     * Validate if the input is in the expected format
+     */
+    validate(input: any): boolean;
+}
+
+/**
+ * Parser for native Specra API format
+ * This is a pass-through parser since the input is already in the correct format
+ */
+declare class SpecraParser implements ApiSpecParser {
+    validate(input: any): boolean;
+    parse(input: any): SpecraApiSpec;
+}
+
+/**
+ * Parser for OpenAPI 3.0/3.1 specifications
+ */
+declare class OpenApiParser implements ApiSpecParser {
+    validate(input: any): boolean;
+    parse(input: any): SpecraApiSpec;
+    private extractBaseUrl;
+    private extractAuth;
+    private parseOperation;
+    private convertPathParams;
+    private parseParameters;
+    private parseRequestBody;
+    private parseResponses;
+    private generateExample;
+    private resolveRef;
+}
+
+/**
+ * Parser for Postman Collection v2.0/v2.1
+ */
+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;
+}
+
+type ParserType = "auto" | "specra" | "openapi" | "postman";
+/**
+ * Auto-detect the parser type based on the input structure
+ */
+declare function detectParserType(input: any): ParserType;
+/**
+ * Parse an API spec using the specified or auto-detected parser
+ */
+declare function parseApiSpec(input: any, parserType?: ParserType): SpecraApiSpec;
+
+/**
+ * Specra API Documentation Schema
+ * Supports REST, GraphQL, and WebSocket APIs
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+interface ApiParameter {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: any;
+    example?: any;
+    enum?: string[];
+}
+interface ApiResponse {
+    status: number;
+    description: string;
+    schema?: any;
+    example?: any;
+    headers?: Record<string, string>;
+}
+interface ApiExample {
+    title: string;
+    language: string;
+    code: string;
+}
+interface ApiAuthentication {
+    type: "apiKey" | "bearer" | "basic" | "oauth2" | "none";
+    description?: string;
+    location?: "header" | "query" | "cookie";
+    name?: string;
+    scheme?: string;
+}
+interface RestEndpoint {
+    type: "rest";
+    method: HttpMethod;
+    path: string;
+    summary: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    authentication?: ApiAuthentication;
+    pathParams?: ApiParameter[];
+    queryParams?: ApiParameter[];
+    headers?: ApiParameter[];
+    body?: {
+        contentType: string;
+        schema?: any;
+        example?: any;
+        description?: string;
+    };
+    responses: ApiResponse[];
+    examples?: ApiExample[];
+}
+interface GraphQLField {
+    name: string;
+    type: string;
+    description?: string;
+    args?: ApiParameter[];
+    deprecated?: boolean;
+    deprecationReason?: string;
+}
+interface GraphQLType {
+    name: string;
+    kind: "OBJECT" | "INPUT_OBJECT" | "ENUM" | "SCALAR" | "INTERFACE" | "UNION";
+    description?: string;
+    fields?: GraphQLField[];
+    enumValues?: {
+        name: string;
+        description?: string;
+    }[];
+}
+interface GraphQLQuery {
+    type: "graphql";
+    operationType: "query" | "mutation" | "subscription";
+    name: string;
+    description?: string;
+    args?: ApiParameter[];
+    returnType: string;
+    example?: string;
+    response?: any;
+}
+interface GraphQLSchema {
+    queries?: GraphQLQuery[];
+    mutations?: GraphQLQuery[];
+    subscriptions?: GraphQLQuery[];
+    types?: GraphQLType[];
+}
+interface WebSocketEvent {
+    type: "websocket";
+    event: string;
+    direction: "client-to-server" | "server-to-client" | "bidirectional";
+    description?: string;
+    payload?: {
+        schema?: any;
+        example?: any;
+    };
+    response?: {
+        schema?: any;
+        example?: any;
+    };
+}
+interface WebSocketConnection {
+    url: string;
+    authentication?: ApiAuthentication;
+    description?: string;
+    events: WebSocketEvent[];
+}
+interface ApiDocumentation {
+    version: string;
+    title: string;
+    description?: string;
+    baseUrl?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    rest?: {
+        endpoints: RestEndpoint[];
+    };
+    graphql?: GraphQLSchema;
+    websocket?: WebSocketConnection[];
+    authentication?: ApiAuthentication[];
+    headers?: Record<string, string>;
+}
+interface ApiSpecConfig {
+    source: "openapi" | "postman" | "insomnia" | "specra" | "manual";
+    path?: string;
+    spec?: ApiDocumentation;
+    autoGenerate?: boolean;
+    outputDir?: string;
+}
+interface ParsedApiSpec {
+    source: ApiSpecConfig["source"];
+    documentation: ApiDocumentation;
+}
+
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Get the correct asset path based on deployment configuration
+ * Handles different deployment scenarios:
+ * - Vercel/Node.js hosting (standalone build): No basePath needed
+ * - GitHub Pages without custom domain: Uses basePath from config
+ * - Static hosting with custom domain: No basePath needed
+ *
+ * @param path - The asset path (can start with or without '/')
+ * @returns The properly formatted asset path
+ */
+declare function getAssetPath(path: string): string;
+
+/**
+ * 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.
+ */
+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
+ */
+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
+ */
+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
+ */
+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[];
+};
+
+interface CategoryConfig {
+    label?: string;
+    position?: number;
+    sidebar_position?: number;
+    link?: {
+        type: "generated-index" | "doc";
+        slug?: string;
+    };
+    collapsed?: boolean;
+    collapsible?: boolean;
+    icon?: string;
+    tab_group?: string;
+}
+/**
+ * Read category.json from a folder
+ */
+declare function getCategoryConfig(folderPath: string): CategoryConfig | null;
+/**
+ * Get all category configs for a version
+ */
+declare function getAllCategoryConfigs(version: string): Map<string, CategoryConfig>;
+
+interface RedirectMapping {
+    from: string;
+    to: string;
+}
+/**
+ * Build redirect mappings from all docs' redirect_from frontmatter
+ */
+declare function buildRedirectMappings(): Promise<RedirectMapping[]>;
+/**
+ * Find redirect destination for a given path
+ */
+declare function findRedirect(path: string): Promise<string | null>;
+
+/**
+ * Development utilities for debugging and performance monitoring
+ * Only active in development mode
+ */
+/**
+ * Performance timer for measuring operation duration
+ */
+declare class PerfTimer {
+    private startTime;
+    private label;
+    constructor(label: string);
+    end(): void;
+}
+/**
+ * Log file system operations
+ */
+declare function logFsOperation(operation: string, path: string, details?: any): void;
+/**
+ * Log cache operations
+ */
+declare function logCacheOperation(operation: 'hit' | 'miss' | 'invalidate', key: string): void;
+/**
+ * Memory usage reporter
+ */
+declare function logMemoryUsage(label?: string): void;
+/**
+ * Pretty print object for debugging
+ */
+declare function debugLog(label: string, data: any): void;
+
+export { type AnalyticsConfig, type ApiAuthentication, type ApiDocumentation, type ApiEndpointSpec, type ApiExample, type ApiHeader, type ApiParam, type ApiParameter, type ApiResponse, type ApiSpecConfig, type ApiSpecParser, type BannerConfig, type CategoryConfig, type DeploymentConfig, type Doc, type DocMeta, type EnvironmentVariables, type FeaturesConfig, type FooterConfig, type GraphQLField, type GraphQLQuery, type GraphQLSchema, type GraphQLType, type HttpMethod, type NavigationConfig, OpenApiParser, type ParsedApiSpec, type ParserType, PerfTimer, PostmanParser, type RedirectMapping, type RestEndpoint, type SearchConfig, type SidebarGroup, type SiteConfig, type SocialLinks, type ApiResponse$1 as SpecraApiResponse, type SpecraApiSpec, type SpecraConfig, SpecraParser, type TOCItem, type TabGroup, type ThemeConfig, type TocItem, type WebSocketConnection, type WebSocketEvent, buildRedirectMappings, buildSidebarStructure, clearAllCaches, cn, debugLog, defaultConfig, detectParserType, extractHeadings, extractTableOfContents, findRedirect, getAdjacentDocs, getAllCategoryConfigs, getAllDocs, getAssetPath, getCacheStats, getCachedAllDocs, getCachedDocBySlug, getCachedVersions, getCategoryConfig, getConfig, getConfigValue, getDocBySlug, getVersions, initConfig, isCategoryPage, loadConfig, logCacheOperation, logFsOperation, logMemoryUsage, parseApiSpec, processContentWithEnv, reloadConfig, replaceEnvVariables, sortSidebarGroups, sortSidebarItems, validateConfig };