specra 0.1.14 → 0.2.1

package/LICENSE.MD

@@ -1,6 +1,6 @@
-MIT License
+MIT License with Branding Requirement
 
-Copyright (c) 2025 dalmasonto, arthur-kamau
+Copyright (c) 2025-2026 dalmasonto, arthur-kamau
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,8 +9,29 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. BRANDING / WATERMARK REQUIREMENT: All documentation sites generated using
+   this Software MUST display the "Powered by Specra" watermark in a visible
+   location (footer or equivalent) on every public-facing page. This watermark
+   must include the text "Powered by Specra" and link to https://specra-docs.com.
+
+   The watermark MUST NOT be removed, hidden, obscured, or made invisible by
+   any means (including but not limited to CSS, JavaScript, DOM manipulation,
+   or build-time stripping) unless the user holds an active paid subscription
+   (Starter tier or above) on the Specra platform (https://specra-docs.com)
+   that explicitly grants the right to remove Specra branding.
+
+   Removal, hiding, or circumvention of the watermark without a valid paid
+   subscription constitutes a COPYRIGHT VIOLATION and a breach of this license,
+   and may result in legal action.
+
+3. Users with an active paid subscription (Starter, Pro, or Enterprise) on the
+   Specra platform may remove the watermark by setting the appropriate
+   configuration option. This right is non-transferable and applies only while
+   the subscription remains active. If a subscription lapses or is cancelled,
+   the watermark must be restored.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

package/README.md

@@ -1,20 +1,20 @@
 # Specra
 
-A modern documentation library for Next.js that makes it easy to create beautiful, feature-rich documentation sites.
-To view the docs, visit [Specra Docs](https://specra.vercel.app).
+A modern documentation library built on SvelteKit that makes it easy to create beautiful, feature-rich documentation sites.
+To view the docs, visit [Specra Docs](https://specra-docs.com).
 
 ## Features
 
-- 📝 **MDX Support** - Write documentation in Markdown with React components
-- 📚 **Multi-Version Docs** - Support multiple documentation versions seamlessly
-- 🔌 **API Reference Generation** - Auto-generate API docs from OpenAPI, Postman, or Specra formats
-- 🔍 **Full-Text Search** - Integrated MeiliSearch support for fast search
-- 🎯 **Tab Groups** - Organize content into multiple navigation tabs
-- 🌓 **Dark Mode** - Built-in theme switching with system preference detection
-- 🎨 **Customizable** - Highly configurable with Tailwind CSS
-- ⚡ **Fast** - Built on Next.js with optimized performance
-- 📱 **Responsive** - Mobile-friendly design out of the box
-- 🔥 **Hot Reload** - Instant updates during development
+- **MDX Support** - Write documentation in Markdown with Svelte components
+- **Multi-Version Docs** - Support multiple documentation versions seamlessly
+- **API Reference Generation** - Auto-generate API docs from OpenAPI, Postman, or Specra formats
+- **Full-Text Search** - Integrated MeiliSearch support for fast search
+- **Tab Groups** - Organize content into multiple navigation tabs
+- **Dark Mode** - Built-in theme switching with system preference detection
+- **Customizable** - Highly configurable with Tailwind CSS
+- **Fast** - Built on SvelteKit with optimized performance
+- **Responsive** - Mobile-friendly design out of the box
+- **Hot Reload** - Instant updates during development
 
 ## Installation
 
@@ -28,58 +28,47 @@ pnpm add specra
 
 ## Quick Start
 
-### 1. Create a new Next.js app (if you don't have one)
+### 1. Create a new SvelteKit app (if you don't have one)
 
 ```bash
-npx create-next-app@latest my-docs
+npx create-specra my-docs
 cd my-docs
 ```
 
-### 2. Install Specra
+Or manually with SvelteKit:
 
 ```bash
+npx sv create my-docs
+cd my-docs
 npm install specra
 ```
 
-### 3. Set up your app structure
+### 2. Set up your project structure
 
 ```
 my-docs/
-├── app/
-│   ├── layout.tsx          # Re-export from Specra
-│   ├── page.tsx            # Your landing page
-│   └── docs/
-│       └── [version]/
-│           └── [...slug]/
-│               └── page.tsx  # Re-export from Specra
-├── docs/                   # Your MDX content
+├── src/
+│   ├── routes/
+│   │   ├── +layout.svelte       # Root layout with Specra components
+│   │   ├── +layout.ts           # Load config
+│   │   ├── +page.svelte         # Your landing page
+│   │   └── docs/
+│   │       └── [version]/
+│   │           └── [...slug]/
+│   │               ├── +page.svelte   # Doc page
+│   │               └── +page.ts       # Load doc data
+│   └── app.html
+├── docs/                         # Your MDX content
 │   └── v1.0.0/
 │       └── getting-started.mdx
-├── public/
+├── static/
 │   └── logo.png
-└── specra.config.json      # Specra configuration
-```
-
-### 4. Configure app/layout.tsx
-
-```typescript
-// app/layout.tsx
-export { default } from 'specra/app/layout'
-export { generateMetadata } from 'specra/app/layout'
-```
-
-### 5. Configure app/docs/[version]/[...slug]/page.tsx
-
-```typescript
-// app/docs/[version]/[...slug]/page.tsx
-export { default } from 'specra/app/docs-page'
-export {
-  generateStaticParams,
-  generateMetadata
-} from 'specra/app/docs-page'
+├── specra.config.json            # Specra configuration
+├── svelte.config.js
+└── vite.config.ts
 ```
 
-### 6. Create specra.config.json
+### 3. Configure specra.config.json
 
 ```json
 {
@@ -87,20 +76,28 @@ export {
     "title": "My Documentation",
     "description": "Awesome docs built with Specra",
     "url": "https://docs.example.com",
-    "logo": "/logo.png"
+    "activeVersion": "v1.0.0"
   },
   "theme": {
     "defaultMode": "system",
-    "primaryColor": "#0070f3"
+    "respectPrefersColorScheme": true
   },
   "navigation": {
-    "sidebar": true,
-    "breadcrumbs": true
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "sidebarStyle": "card"
+  },
+  "features": {
+    "versioning": true,
+    "showVersionBadge": false,
+    "showReadingTime": true
   }
 }
 ```
 
-### 7. Create your first doc
+### 4. Create your first doc
 
 ```mdx
 ---
@@ -113,9 +110,9 @@ description: Learn how to get started with our platform
 Welcome to the documentation!
 ```
 
-### 8. Import globals.css
+### 5. Import globals.css
 
-Add to your `app/globals.css`:
+Add to your root stylesheet:
 
 ```css
 @import 'specra/styles';
@@ -123,17 +120,17 @@ Add to your `app/globals.css`:
 /* Your custom styles */
 ```
 
-### 9. Run development server
+### 6. Run development server
 
 ```bash
 npm run dev
 ```
 
-Visit `http://localhost:3000/docs/v1.0.0/getting-started` to see your docs!
+Visit `http://localhost:5173/docs/v1.0.0/getting-started` to see your docs!
 
 ## Configuration
 
-See [Configuration Guide](https://docs.specra.dev/configuration) for full documentation.
+See [Configuration Guide](https://specra-docs.com/docs) for full documentation.
 
 ## Upgrading
 
@@ -145,14 +142,26 @@ npm update specra
 
 Your content and configuration stay the same - only the SDK updates!
 
+## Specra SaaS
+
+The official documentation site ([specra-docs](https://specra-docs.com)) also serves as a SaaS platform with paid tiers (Starter, Pro, Enterprise). It includes:
+- Authentication (Auth.js with GitHub OAuth + email/password)
+- Subscription billing via Stripe (USD) and M-Pesa Daraja (KES)
+- User dashboard with plan management and billing history
+- PostgreSQL database via Prisma v7
+
+The SaaS layer is implemented entirely within specra-docs and does not affect the SDK itself. Users of the SDK can build free, self-hosted documentation sites without any billing features.
+
 ## Why Specra?
 
 Specra is designed to be the easiest way to create documentation for your projects. It handles all the complex parts (versioning, search, API references) while letting you focus on writing great content.
 
 ## License
 
-MIT
+MIT with Branding Requirement — see [LICENSE.MD](LICENSE.MD).
+
+All documentation sites built with Specra must display the "Powered by Specra" watermark. Removing the watermark requires an active paid subscription (Starter tier or above) at [specra-docs.com](https://specra-docs.com). Unauthorized removal of the watermark is a copyright violation.
 
 ## Authors
 
-dalmasonto, arthur-kamau
+dalmasonto, arthur-kamau

package/config/specra.config.schema.json

@@ -164,6 +164,10 @@
           "description": "Show tags",
           "type": "boolean"
         },
+        "showVersionBadge": {
+          "description": "Show version badge in the sidebar",
+          "type": "boolean"
+        },
         "versioning": {
           "description": "Enable version dropdown",
           "type": "boolean"
@@ -322,6 +326,14 @@
           "description": "Whether to show table of contents",
           "type": "boolean"
         },
+        "sidebarStyle": {
+          "description": "Sidebar visual style: \"card\" (rounded container) or \"flush\" (attached to screen edge)",
+          "enum": [
+            "card",
+            "flush"
+          ],
+          "type": "string"
+        },
         "tabGroups": {
           "description": "Tab groups for organizing documentation sections",
           "items": {
@@ -451,6 +463,10 @@
           "description": "Organization or author name",
           "type": "string"
         },
+        "projectId": {
+          "description": "Project ID to tie this doc site to a Specra project for visitor tracking",
+          "type": "string"
+        },
         "projectName": {
           "description": "Project name",
           "type": "string"

package/config/svelte-config.js

@@ -0,0 +1,63 @@
+/**
+ * Specra SvelteKit Configuration
+ *
+ * Provides a function that returns SvelteKit-compatible configuration
+ * with mdsvex preprocessor and all required remark/rehype plugins.
+ *
+ * Usage in svelte.config.js:
+ * ```js
+ * import { specraConfig } from 'specra/svelte-config'
+ * const config = specraConfig()
+ * export default config
+ * ```
+ */
+import { mdsvex } from 'mdsvex'
+import remarkGfm from 'remark-gfm'
+import remarkMath from 'remark-math'
+import rehypeSlug from 'rehype-slug'
+import rehypeKatex from 'rehype-katex'
+import rehypeRaw from 'rehype-raw'
+
+/**
+ * Get mdsvex preprocessor config with all Specra remark/rehype plugins
+ */
+export function specraMdsvexConfig(options = {}) {
+  return {
+    extensions: ['.md', '.svx', '.mdx'],
+    remarkPlugins: [
+      remarkGfm,
+      remarkMath,
+      ...(options.remarkPlugins || [])
+    ],
+    rehypePlugins: [
+      rehypeSlug,
+      rehypeKatex,
+      rehypeRaw,
+      ...(options.rehypePlugins || [])
+    ],
+    smartypants: {
+      dashes: 'oldschool'
+    },
+    ...options
+  }
+}
+
+/**
+ * Create a full SvelteKit config with Specra defaults
+ */
+export function specraConfig(options = {}) {
+  const { vitePreprocess } = options.vitePreprocess || {}
+
+  return {
+    extensions: ['.svelte', '.md', '.svx', '.mdx'],
+    preprocess: [
+      ...(vitePreprocess ? [vitePreprocess()] : []),
+      mdsvex(specraMdsvexConfig(options.mdsvex || {}))
+    ],
+    kit: {
+      ...(options.kit || {})
+    }
+  }
+}
+
+export default specraConfig

package/dist/api-parser.types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Simple API Documentation Format for Specra
+ * Easy to write, easy to parse
+ */
+export interface ApiParam {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: any;
+    example?: any;
+}
+export interface ApiHeader {
+    name: string;
+    value: string;
+    description?: string;
+}
+export interface ApiResponse {
+    status: number;
+    description?: string;
+    example?: any;
+    schema?: any;
+}
+export 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;
+    errorResponses?: ApiResponse[];
+    examples?: {
+        title: string;
+        language: string;
+        code: string;
+    }[];
+}
+export 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[];
+}

package/dist/api-parser.types.js

@@ -0,0 +1,5 @@
+/**
+ * Simple API Documentation Format for Specra
+ * Easy to write, easy to parse
+ */
+export {};

package/dist/api.types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Specra API Documentation Schema
+ * Supports REST, GraphQL, and WebSocket APIs
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export interface ApiParameter {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: any;
+    example?: any;
+    enum?: string[];
+}
+export interface ApiResponse {
+    status: number;
+    description: string;
+    schema?: any;
+    example?: any;
+    headers?: Record<string, string>;
+}
+export interface ApiExample {
+    title: string;
+    language: string;
+    code: string;
+}
+export interface ApiAuthentication {
+    type: "apiKey" | "bearer" | "basic" | "oauth2" | "none";
+    description?: string;
+    location?: "header" | "query" | "cookie";
+    name?: string;
+    scheme?: string;
+}
+export 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[];
+}
+export interface GraphQLField {
+    name: string;
+    type: string;
+    description?: string;
+    args?: ApiParameter[];
+    deprecated?: boolean;
+    deprecationReason?: string;
+}
+export interface GraphQLType {
+    name: string;
+    kind: "OBJECT" | "INPUT_OBJECT" | "ENUM" | "SCALAR" | "INTERFACE" | "UNION";
+    description?: string;
+    fields?: GraphQLField[];
+    enumValues?: {
+        name: string;
+        description?: string;
+    }[];
+}
+export interface GraphQLQuery {
+    type: "graphql";
+    operationType: "query" | "mutation" | "subscription";
+    name: string;
+    description?: string;
+    args?: ApiParameter[];
+    returnType: string;
+    example?: string;
+    response?: any;
+}
+export interface GraphQLSchema {
+    queries?: GraphQLQuery[];
+    mutations?: GraphQLQuery[];
+    subscriptions?: GraphQLQuery[];
+    types?: GraphQLType[];
+}
+export 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;
+    };
+}
+export interface WebSocketConnection {
+    url: string;
+    authentication?: ApiAuthentication;
+    description?: string;
+    events: WebSocketEvent[];
+}
+export 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>;
+}
+export interface ApiSpecConfig {
+    source: "openapi" | "postman" | "insomnia" | "specra" | "manual";
+    path?: string;
+    spec?: ApiDocumentation;
+    autoGenerate?: boolean;
+    outputDir?: string;
+}
+export interface ParsedApiSpec {
+    source: ApiSpecConfig["source"];
+    documentation: ApiDocumentation;
+}

package/dist/api.types.js

@@ -0,0 +1,5 @@
+/**
+ * Specra API Documentation Schema
+ * Supports REST, GraphQL, and WebSocket APIs
+ */
+export {};

package/dist/category.d.ts

@@ -0,0 +1,21 @@
+export 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
+ */
+export declare function getCategoryConfig(folderPath: string): CategoryConfig | null;
+/**
+ * Get all category configs for a version
+ */
+export declare function getAllCategoryConfigs(version: string): Map<string, CategoryConfig>;

package/dist/category.js

@@ -0,0 +1,48 @@
+// Note: This file uses server-only APIs (fs, path) and should only be imported in Server Components
+import fs from "fs";
+import path from "path";
+const DOCS_DIR = path.join(process.cwd(), "docs");
+/**
+ * Read category.json from a folder
+ */
+export function getCategoryConfig(folderPath) {
+    try {
+        const categoryPath = path.join(folderPath, "_category_.json");
+        if (!fs.existsSync(categoryPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(categoryPath, "utf8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        console.error(`Error reading category config from ${folderPath}:`, error);
+        return null;
+    }
+}
+/**
+ * Get all category configs for a version
+ */
+export function getAllCategoryConfigs(version) {
+    const configs = new Map();
+    const versionDir = path.join(DOCS_DIR, version);
+    if (!fs.existsSync(versionDir)) {
+        return configs;
+    }
+    function scanDirectory(dir, relativePath = "") {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const fullPath = path.join(dir, entry.name);
+                const relPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                const config = getCategoryConfig(fullPath);
+                if (config) {
+                    configs.set(relPath, config);
+                }
+                // Recursively scan subdirectories
+                scanDirectory(fullPath, relPath);
+            }
+        }
+    }
+    scanDirectory(versionDir);
+    return configs;
+}

package/dist/components/ConfigProvider.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { setConfigContext } from '../stores/config.js';
+  import type { SpecraConfig } from '../config.types.js';
+
+  interface Props {
+    config: SpecraConfig;
+  }
+
+  let { config }: Props = $props();
+  setConfigContext(config);
+</script>
+
+<slot />

package/dist/components/ConfigProvider.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { SpecraConfig } from '../config.types.js';
+interface Props {
+    config: SpecraConfig;
+}
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+type $$__sveltets_2_PropsWithChildren<Props, Slots> = Props & (Slots extends {
+    default: any;
+} ? Props extends Record<string, never> ? any : {
+    children?: any;
+} : {});
+declare const ConfigProvider: $$__sveltets_2_IsomorphicComponent<$$__sveltets_2_PropsWithChildren<Props, {
+    default: {};
+}>, {
+    [evt: string]: CustomEvent<any>;
+}, {
+    default: {};
+}, {}, "">;
+type ConfigProvider = InstanceType<typeof ConfigProvider>;
+export default ConfigProvider;