@fydemy/cms 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,431 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+interface MarkdownData {
+    content: string;
+    data: Record<string, any>;
+}
+/**
+ * Parse markdown content with frontmatter
+ * @param rawContent - Raw markdown content to parse
+ * @returns Parsed markdown data with frontmatter and content
+ */
+declare function parseMarkdown(rawContent: string): MarkdownData;
+/**
+ * Convert data and content back to markdown with frontmatter
+ */
+declare function stringifyMarkdown(data: Record<string, any>, content: string): string;
+/**
+ * Read and parse a markdown file
+ * @param filePath - Path to the markdown file
+ * @returns Parsed markdown data
+ * @throws Error if file path is invalid or file is too large
+ */
+declare function getMarkdownContent(filePath: string): Promise<MarkdownData>;
+/**
+ * Write markdown file with frontmatter
+ * @param filePath - Path to the markdown file
+ * @param data - Frontmatter data object
+ * @param content - Markdown content
+ * @throws Error if file path is invalid or content is too large
+ */
+declare function saveMarkdownContent(filePath: string, data: Record<string, any>, content: string): Promise<void>;
+/**
+ * Delete a markdown file
+ * @param filePath - Path to the markdown file
+ * @throws Error if file path is invalid
+ */
+declare function deleteMarkdownContent(filePath: string): Promise<void>;
+/**
+ * List all markdown files in a directory
+ * @param directory - Directory path (optional, defaults to root)
+ * @returns Array of file paths
+ * @throws Error if directory path is invalid
+ */
+declare function listMarkdownFiles(directory?: string): Promise<string[]>;
+/**
+ * Check if a markdown file exists
+ * @param filePath - Path to the markdown file
+ * @returns True if file exists, false otherwise
+ * @throws Error if file path is invalid
+ */
+declare function markdownFileExists(filePath: string): Promise<boolean>;
+
+/**
+ * Represents a file or directory entry
+ */
+interface FileEntry {
+    /** Relative path from base content directory */
+    path: string;
+    /** File or directory name */
+    name: string;
+    /** Type of entry */
+    type: "file" | "directory";
+}
+/**
+ * Interface for file storage operations
+ */
+interface StorageProvider {
+    /** Read file content as string */
+    readFile(filePath: string): Promise<string>;
+    /** Write content to file, creating parent directories if needed */
+    writeFile(filePath: string, content: string): Promise<void>;
+    /** Delete a file */
+    deleteFile(filePath: string): Promise<void>;
+    /** List files in a directory */
+    listFiles(directory: string): Promise<FileEntry[]>;
+    /** Check if a file exists */
+    exists(filePath: string): Promise<boolean>;
+    /** Upload a binary file */
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * Local file system storage (for development)
+ */
+declare class LocalStorage implements StorageProvider {
+    private baseDir;
+    constructor(baseDir?: string);
+    private getFullPath;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    listFiles(directory: string): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * GitHub storage (for production)
+ */
+declare class GitHubStorage implements StorageProvider {
+    private octokit;
+    private owner;
+    private repo;
+    private branch;
+    private baseDir;
+    constructor();
+    private getGitHubPath;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    listFiles(directory: string): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * Get the appropriate storage provider based on environment
+ */
+declare function getStorageProvider(): StorageProvider;
+
+/**
+ * List all files and directories in a directory
+ * @param directory - Relative path to the directory (default: root)
+ * @returns Array of file entries (files and directories)
+ */
+declare function listDirectory(directory?: string): Promise<FileEntry[]>;
+
+/**
+ * Base interface for collection items with flexible frontmatter
+ */
+interface CollectionItem<T = Record<string, any>> {
+    /** The markdown content body */
+    content: string;
+    /** Frontmatter data with dynamic fields */
+    data: T;
+    /** File slug (filename without extension) */
+    slug: string;
+}
+/**
+ * Fetch all markdown files from a specific folder/collection
+ * @param folderName - The folder name under public/content (e.g., "blog", "pages")
+ * @returns Array of collection items with parsed frontmatter and content
+ *
+ * @example
+ * ```ts
+ * // Fetch all blog posts
+ * const posts = await getCollectionItems("blog");
+ * posts.forEach(post => {
+ *   console.log(post.data.title); // Access any frontmatter field
+ *   console.log(post.slug);       // Filename without .md
+ * });
+ *
+ * // With type inference for known fields
+ * interface BlogPost {
+ *   title: string;
+ *   date: string;
+ *   author?: string;
+ *   [key: string]: any; // Allow any other fields
+ * }
+ * const typedPosts = await getCollectionItems<BlogPost>("blog");
+ * ```
+ */
+declare function getCollectionItems<T = Record<string, any>>(folderName: string): Promise<CollectionItem<T>[]>;
+/**
+ * Fetch a single item from a collection by slug
+ * @param folderName - The folder name under public/content
+ * @param slug - The filename without .md extension
+ * @returns Single collection item or null if not found
+ *
+ * @example
+ * ```ts
+ * // Fetch a specific blog post
+ * const post = await getCollectionItem("blog", "my-first-post");
+ * if (post) {
+ *   console.log(post.data.title);
+ * }
+ * ```
+ */
+declare function getCollectionItem<T = Record<string, any>>(folderName: string, slug: string): Promise<CollectionItem<T> | null>;
+/**
+ * Get all unique folder names (collections) in the content directory
+ * @param baseDir - Base directory to scan (default: "")
+ * @returns Array of folder names
+ *
+ * @example
+ * ```ts
+ * const collections = await getCollections();
+ * // Returns: ["blog", "pages", "docs", ...]
+ * ```
+ */
+declare function getCollections(baseDir?: string): Promise<string[]>;
+
+/**
+ * Upload a file and return its public URL
+ * @param fileName - Original filename
+ * @param buffer - File content buffer
+ * @returns Public URL path to the uploaded file
+ */
+declare function uploadFile(fileName: string, buffer: Buffer): Promise<string>;
+
+/**
+ * Session payload structure for JWT
+ */
+interface SessionPayload {
+    /** Username of the authenticated user */
+    username: string;
+    /** Expiration timestamp (Unix time) */
+    exp: number;
+}
+/**
+ * Create a new session token for the given username
+ * @param username - The username to create a session for
+ * @returns Signed JWT string
+ */
+declare function createSession(username: string): Promise<string>;
+/**
+ * Verify and decode a session token
+ * @param token - The JWT token to verify
+ * @returns Decoded payload if valid, null otherwise
+ */
+declare function verifySession(token: string): Promise<SessionPayload | null>;
+/**
+ * Get session from Next.js request cookies
+ */
+declare function getSessionFromCookies(): Promise<SessionPayload | null>;
+/**
+ * Set session cookie
+ */
+declare function setSessionCookie(token: string): Promise<void>;
+/**
+ * Clear session cookie
+ */
+declare function clearSessionCookie(): Promise<void>;
+
+/**
+ * Validate username and password against environment variables using timing-safe comparison
+ * @param username - Username to validate
+ * @param password - Password to validate
+ * @returns True if credentials are valid, false otherwise
+ * @throws Error if environment variables are not configured
+ */
+declare function validateCredentials(username: string, password: string): boolean;
+
+/**
+ * Login endpoint with rate limiting
+ */
+declare function handleLogin(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Logout endpoint
+ */
+declare function handleLogout(): Promise<NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Get content endpoint
+ */
+declare function handleGetContent(_request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<MarkdownData>>;
+/**
+ * Save content endpoint
+ */
+declare function handleSaveContent(request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Delete content endpoint
+ */
+declare function handleDeleteContent(_request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * List files endpoint
+ */
+declare function handleListFiles(directory?: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    entries: FileEntry[];
+}>>;
+/**
+ * Create API route handlers for Next.js App Router
+ */
+declare function createContentApiHandlers(): {
+    GET(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<MarkdownData>>;
+    POST(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        success: boolean;
+    }>>;
+    DELETE(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        success: boolean;
+    }>>;
+};
+/**
+ * Create list API handlers
+ */
+declare function createListApiHandlers(): {
+    GET(_request: NextRequest, { params }: {
+        params: {
+            path?: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        entries: FileEntry[];
+    }>>;
+};
+
+/**
+ * Handle file upload
+ */
+declare function handleUpload(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    url: string;
+    filename: string;
+}>>;
+
+/**
+ * Create middleware to protect admin routes
+ */
+declare function createAuthMiddleware(options?: {
+    loginPath?: string;
+    protectedPaths?: string[];
+}): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+interface InitCMSConfig {
+    /** Directory where content is stored (default: "public/content") */
+    contentDir?: string;
+}
+/**
+ * Initialize CMS in a Next.js project
+ * Creates the content directory and an example markdown file.
+ * @param config - Configuration options
+ */
+declare function initCMS(config?: InitCMSConfig): Promise<void>;
+
+/**
+ * Maximum username length (prevents DoS)
+ */
+declare const MAX_USERNAME_LENGTH = 100;
+/**
+ * Maximum password length (prevents DoS)
+ */
+declare const MAX_PASSWORD_LENGTH = 1000;
+/**
+ * Maximum file size in bytes (10MB)
+ */
+declare const MAX_FILE_SIZE: number;
+/**
+ * Validate and sanitize file path to prevent directory traversal
+ * @param filePath - The file path to validate
+ * @returns Sanitized file path
+ * @throws Error if path is invalid or attempts directory traversal
+ */
+declare function validateFilePath(filePath: string): string;
+/**
+ * Validate username input
+ * @param username - The username to validate
+ * @returns True if valid
+ * @throws Error if invalid
+ */
+declare function validateUsername(username: string): boolean;
+/**
+ * Validate password input
+ * @param password - The password to validate
+ * @returns True if valid
+ * @throws Error if invalid
+ */
+declare function validatePassword(password: string): boolean;
+/**
+ * Validate file size
+ * @param size - File size in bytes
+ * @returns True if valid
+ * @throws Error if too large
+ */
+declare function validateFileSize(size: number): boolean;
+/**
+ * Sanitize frontmatter data to prevent injection
+ * @param data - The data object to sanitize
+ * @returns Sanitized data
+ */
+declare function sanitizeFrontmatter(data: Record<string, any>): Record<string, any>;
+
+/**
+ * Simple in-memory rate limiter for login attempts
+ */
+/**
+ * Check if IP/identifier is rate limited
+ * @param identifier - IP address or other unique identifier
+ * @returns Object with isLimited and remaining attempts
+ */
+declare function checkRateLimit(identifier: string): {
+    isLimited: boolean;
+    remaining: number;
+    resetTime: number;
+};
+/**
+ * Increment rate limit counter for identifier
+ * @param identifier - IP address or other unique identifier
+ */
+declare function incrementRateLimit(identifier: string): void;
+/**
+ * Reset rate limit for identifier (use after successful login)
+ * @param identifier - IP address or other unique identifier
+ */
+declare function resetRateLimit(identifier: string): void;
+
+export { type CollectionItem, type FileEntry, GitHubStorage, type InitCMSConfig, LocalStorage, MAX_FILE_SIZE, MAX_PASSWORD_LENGTH, MAX_USERNAME_LENGTH, type MarkdownData, type StorageProvider, checkRateLimit, clearSessionCookie, createAuthMiddleware, createContentApiHandlers, createListApiHandlers, createSession, deleteMarkdownContent, getCollectionItem, getCollectionItems, getCollections, getMarkdownContent, getSessionFromCookies, getStorageProvider, handleDeleteContent, handleGetContent, handleListFiles, handleLogin, handleLogout, handleSaveContent, handleUpload, incrementRateLimit, initCMS, listDirectory, listMarkdownFiles, markdownFileExists, parseMarkdown, resetRateLimit, sanitizeFrontmatter, saveMarkdownContent, setSessionCookie, stringifyMarkdown, uploadFile, validateCredentials, validateFilePath, validateFileSize, validatePassword, validateUsername, verifySession };