markdown-notes-engine 1.0.1 → 1.0.2

package/README.md

@@ -26,11 +26,60 @@ A complete, production-ready markdown note-taking engine with GitHub integration
 npm install markdown-notes-engine
 ```
 
+### Module Support
+
+This package supports both **ES Modules (ESM)** and **CommonJS (CJS)**:
+
+**ES Modules (import)**
+```javascript
+import { createNotesRouter, GitHubClient, StorageClient } from 'markdown-notes-engine';
+```
+
+**CommonJS (require)**
+```javascript
+const { createNotesRouter, GitHubClient, StorageClient } = require('markdown-notes-engine');
+```
+
 ### Backend (Express)
 
+<details>
+<summary><b>ES Modules (import)</b></summary>
+
 ```javascript
+import express from 'express';
+import { createNotesRouter } from 'markdown-notes-engine';
+
+const app = express();
+
+const notesRouter = createNotesRouter({
+  github: {
+    token: process.env.GITHUB_TOKEN,
+    owner: process.env.GITHUB_OWNER,
+    repo: process.env.GITHUB_REPO
+  },
+  storage: {
+    type: 'r2',
+    accountId: process.env.R2_ACCOUNT_ID,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucketName: process.env.R2_BUCKET_NAME,
+    publicUrl: process.env.R2_PUBLIC_URL
+  }
+});
+
+app.use('/api', notesRouter);
+```
+</details>
+
+<details>
+<summary><b>CommonJS (require)</b></summary>
+
+```javascript
+const express = require('express');
 const { createNotesRouter } = require('markdown-notes-engine');
 
+const app = express();
+
 const notesRouter = createNotesRouter({
   github: {
     token: process.env.GITHUB_TOKEN,
@@ -49,6 +98,7 @@ const notesRouter = createNotesRouter({
 
 app.use('/api', notesRouter);
 ```
+</details>
 
 ### Frontend (JavaScript)
 
@@ -121,13 +171,16 @@ This repository contains both the package source and a working notes application
 markdown-notes-engine/
 ├── lib/                    # NPM package source
 │   ├── backend/           # Express router and API
+│   │   ├── *.js          # CommonJS modules
+│   │   └── *.mjs         # ES modules
 │   ├── frontend/          # Editor UI component
-│   └── index.js           # Main package entry
+│   ├── index.js           # Main entry (CommonJS)
+│   └── index.mjs          # Main entry (ES modules)
 ├── examples/              # Usage examples
 │   └── express-app/       # Express integration example
 ├── server.js              # Demo server
 ├── public/                # Demo frontend
-└── package.json           # Package configuration
+└── package.json           # Package configuration (dual module support)
 ```
 
 ### Running the Demo

package/lib/README.md

@@ -23,8 +23,63 @@ npm install markdown-notes-engine
 
 ## Quick Start
 
+### Module Support
+
+This package supports both **ES Modules (ESM)** and **CommonJS (CJS)**. Choose the syntax that works for your project:
+
+**ES Modules (import)**
+```javascript
+import { createNotesRouter, GitHubClient, StorageClient, MarkdownRenderer } from 'markdown-notes-engine';
+```
+
+**CommonJS (require)**
+```javascript
+const { createNotesRouter, GitHubClient, StorageClient, MarkdownRenderer } = require('markdown-notes-engine');
+```
+
 ### Backend Setup (Express)
 
+<details open>
+<summary><b>ES Modules (import)</b></summary>
+
+```javascript
+import express from 'express';
+import { createNotesRouter } from 'markdown-notes-engine';
+
+const app = express();
+
+// Create the notes router with your configuration
+const notesRouter = createNotesRouter({
+  github: {
+    token: process.env.GITHUB_TOKEN,
+    owner: process.env.GITHUB_OWNER,
+    repo: process.env.GITHUB_REPO
+  },
+  storage: {
+    type: 'r2', // or 's3'
+    accountId: process.env.R2_ACCOUNT_ID,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucketName: process.env.R2_BUCKET_NAME,
+    publicUrl: process.env.R2_PUBLIC_URL
+  },
+  options: {
+    autoUpdateReadme: true // Auto-update README with note index
+  }
+});
+
+// Mount the router
+app.use('/api', notesRouter);
+
+app.listen(3000, () => {
+  console.log('Notes app running on http://localhost:3000');
+});
+```
+</details>
+
+<details>
+<summary><b>CommonJS (require)</b></summary>
+
 ```javascript
 const express = require('express');
 const { createNotesRouter } = require('markdown-notes-engine');
@@ -58,6 +113,7 @@ app.listen(3000, () => {
   console.log('Notes app running on http://localhost:3000');
 });
 ```
+</details>
 
 ### Frontend Setup (HTML + JavaScript)
 
@@ -191,7 +247,52 @@ When you mount the notes router, it provides these endpoints:
 
 ### Using Individual Components
 
-You can use individual backend components if you need more control:
+You can use individual backend components if you need more control.
+
+<details open>
+<summary><b>ES Modules (import)</b></summary>
+
+```javascript
+import { GitHubClient, StorageClient, MarkdownRenderer } from 'markdown-notes-engine';
+
+// GitHub client
+const github = new GitHubClient({
+  token: 'xxx',
+  owner: 'user',
+  repo: 'repo',
+  branch: 'main'
+});
+
+// Get file structure
+const structure = await github.getFileStructure();
+
+// Get file content
+const file = await github.getFile('path/to/note.md');
+
+// Save file
+await github.saveFile('path/to/note.md', 'content', file.sha);
+
+// Storage client
+const storage = new StorageClient({
+  type: 'r2',
+  accountId: 'xxx',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'xxx',
+  bucketName: 'bucket',
+  publicUrl: 'https://bucket.r2.dev'
+});
+
+// Upload image
+const imageUrl = await storage.uploadImage(buffer, 'image.png', 'folder');
+
+// Markdown renderer
+const renderer = new MarkdownRenderer();
+const html = renderer.render('# Hello World');
+```
+</details>
+
+<details>
+<summary><b>CommonJS (require)</b></summary>
 
 ```javascript
 const { GitHubClient, StorageClient, MarkdownRenderer } = require('markdown-notes-engine');
@@ -200,7 +301,8 @@ const { GitHubClient, StorageClient, MarkdownRenderer } = require('markdown-note
 const github = new GitHubClient({
   token: 'xxx',
   owner: 'user',
-  repo: 'repo'
+  repo: 'repo',
+  branch: 'main'
 });
 
 // Get file structure
@@ -229,6 +331,25 @@ const imageUrl = await storage.uploadImage(buffer, 'image.png', 'folder');
 const renderer = new MarkdownRenderer();
 const html = renderer.render('# Hello World');
 ```
+</details>
+
+### Subpath Imports
+
+You can also import components directly from their subpaths:
+
+**ES Modules**
+```javascript
+import { GitHubClient } from 'markdown-notes-engine/backend/github';
+import { StorageClient } from 'markdown-notes-engine/backend/storage';
+import { MarkdownRenderer } from 'markdown-notes-engine/backend/markdown';
+```
+
+**CommonJS**
+```javascript
+const { GitHubClient } = require('markdown-notes-engine/backend/github');
+const { StorageClient } = require('markdown-notes-engine/backend/storage');
+const { MarkdownRenderer } = require('markdown-notes-engine/backend/markdown');
+```
 
 ### Frontend Callbacks
 

package/lib/backend/github.mjs

@@ -0,0 +1,316 @@
+/**
+ * GitHub Client Wrapper
+ * Handles all GitHub API operations for note management
+ */
+
+import { Octokit } from '@octokit/rest';
+
+export class GitHubClient {
+  constructor({ token, owner, repo, branch = 'main' }) {
+    this.octokit = new Octokit({ auth: token });
+    this.owner = owner;
+    this.repo = repo;
+    this.branch = branch;
+  }
+
+  /**
+   * Get the default branch for the repository
+   * @returns {Promise<string>} Default branch name
+   */
+  async getDefaultBranch() {
+    try {
+      const response = await this.octokit.repos.get({
+        owner: this.owner,
+        repo: this.repo
+      });
+      return response.data.default_branch;
+    } catch (error) {
+      console.error('Failed to get default branch:', error.message);
+      return 'main'; // fallback
+    }
+  }
+
+  /**
+   * Get repository file tree structure
+   * @returns {Promise<Array>} Array of files and folders
+   */
+  async getFileStructure() {
+    try {
+      // Get the entire tree recursively using git API
+      const { data } = await this.octokit.git.getTree({
+        owner: this.owner,
+        repo: this.repo,
+        tree_sha: this.branch,
+        recursive: '1'
+      });
+
+      // Filter to only blob files (not trees)
+      const files = data.tree.filter(item => item.type === 'blob');
+
+      return this._buildStructureFromFiles(files);
+    } catch (error) {
+      if (error.status === 404) {
+        // Branch doesn't exist, try to get default branch
+        try {
+          const defaultBranch = await this.getDefaultBranch();
+          this.branch = defaultBranch; // Update for future calls
+
+          const { data } = await this.octokit.git.getTree({
+            owner: this.owner,
+            repo: this.repo,
+            tree_sha: defaultBranch,
+            recursive: '1'
+          });
+
+          const files = data.tree.filter(item => item.type === 'blob');
+          return this._buildStructureFromFiles(files);
+        } catch (retryError) {
+          // Repository might be empty
+          console.error('Repository appears to be empty or inaccessible:', retryError.message);
+          return []; // Return empty array for empty repos
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get file content
+   * @param {string} path - File path
+   * @returns {Promise<Object>} File content and metadata
+   */
+  async getFile(path) {
+    try {
+      const response = await this.octokit.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: path,
+        ref: this.branch
+      });
+
+      // Check if this is a file (not a directory)
+      if (!response.data.content) {
+        console.error('No content in response - might be a directory');
+        return null;
+      }
+
+      return {
+        content: Buffer.from(response.data.content, 'base64').toString('utf-8'),
+        sha: response.data.sha,
+        path: response.data.path
+      };
+    } catch (error) {
+      if (error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create or update a file
+   * @param {string} path - File path
+   * @param {string} content - File content
+   * @param {string} [sha] - File SHA (required for updates)
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async saveFile(path, content, sha = null) {
+    const params = {
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      message: sha ? `Update ${path}` : `Create ${path}`,
+      content: Buffer.from(content).toString('base64'),
+      branch: this.branch
+    };
+
+    if (sha) {
+      params.sha = sha;
+    }
+
+    const response = await this.octokit.repos.createOrUpdateFileContents(params);
+    return response.data;
+  }
+
+  /**
+   * Delete a file
+   * @param {string} path - File path
+   * @param {string} sha - File SHA
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async deleteFile(path, sha) {
+    const response = await this.octokit.repos.deleteFile({
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      message: `Delete ${path}`,
+      sha: sha,
+      branch: this.branch
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Create a folder (by creating a .gitkeep file)
+   * @param {string} path - Folder path
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async createFolder(path) {
+    const gitkeepPath = `${path}/.gitkeep`;
+    return this.saveFile(gitkeepPath, '', null);
+  }
+
+  /**
+   * Delete a folder (recursively delete all files)
+   * @param {string} path - Folder path
+   * @returns {Promise<Array>} Array of delete responses
+   */
+  async deleteFolder(path) {
+    const files = await this._getFilesInFolder(path);
+    const deletePromises = files.map(file =>
+      this.deleteFile(file.path, file.sha)
+    );
+
+    return Promise.all(deletePromises);
+  }
+
+  /**
+   * Search notes for a query
+   * @param {string} query - Search query
+   * @returns {Promise<Array>} Search results
+   */
+  async searchNotes(query) {
+    const searchQuery = `${query} repo:${this.owner}/${this.repo}`;
+    const response = await this.octokit.search.code({
+      q: searchQuery
+    });
+
+    const results = [];
+
+    for (const item of response.data.items) {
+      if (!item.path.endsWith('.md')) continue;
+
+      const file = await this.getFile(item.path);
+      if (!file) continue;
+
+      const lines = file.content.split('\n');
+      const matches = [];
+
+      lines.forEach((line, index) => {
+        if (line.toLowerCase().includes(query.toLowerCase())) {
+          matches.push({
+            line: index + 1,
+            content: line
+          });
+        }
+      });
+
+      if (matches.length > 0) {
+        results.push({
+          path: item.path,
+          matches: matches
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all files in a folder
+   * @private
+   */
+  async _getFilesInFolder(path) {
+    const response = await this.octokit.repos.getContent({
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      ref: this.branch
+    });
+
+    let files = [];
+
+    for (const item of response.data) {
+      if (item.type === 'file') {
+        files.push(item);
+      } else if (item.type === 'dir') {
+        const subFiles = await this._getFilesInFolder(item.path);
+        files = files.concat(subFiles);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Build hierarchical structure from flat file list
+   * @private
+   */
+  _buildStructureFromFiles(files) {
+    const root = [];
+    const folderMap = new Map();
+
+    // Sort files to ensure consistent ordering
+    files.sort((a, b) => a.path.localeCompare(b.path));
+
+    for (const file of files) {
+      const parts = file.path.split('/');
+      let currentLevel = root;
+      let currentPath = '';
+
+      // Process each part of the path
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        currentPath = currentPath ? `${currentPath}/${part}` : part;
+
+        if (i === parts.length - 1) {
+          // It's a file - skip .gitkeep files
+          if (part === '.gitkeep') {
+            continue;
+          }
+
+          currentLevel.push({
+            name: part,
+            type: 'file',
+            path: file.path,
+            sha: file.sha
+          });
+        } else {
+          // It's a folder
+          let folder = folderMap.get(currentPath);
+
+          if (!folder) {
+            folder = {
+              name: part,
+              type: 'folder',
+              path: currentPath,
+              children: []
+            };
+            folderMap.set(currentPath, folder);
+            currentLevel.push(folder);
+          }
+
+          currentLevel = folder.children;
+        }
+      }
+    }
+
+    // Sort function: folders first, then alphabetically
+    const sortStructure = (items) => {
+      items.sort((a, b) => {
+        if (a.type === b.type) return a.name.localeCompare(b.name);
+        return a.type === 'folder' ? -1 : 1;
+      });
+
+      items.forEach((item) => {
+        if (item.type === 'folder' && item.children) {
+          sortStructure(item.children);
+        }
+      });
+    };
+
+    sortStructure(root);
+    return root;
+  }
+}

package/lib/backend/index.mjs

@@ -0,0 +1,74 @@
+/**
+ * Markdown Notes Engine - Backend Router
+ *
+ * Creates an Express router with all note-taking API endpoints
+ */
+
+import express from 'express';
+import { GitHubClient } from './github.mjs';
+import { StorageClient } from './storage.mjs';
+import { MarkdownRenderer } from './markdown.mjs';
+import notesRoutes from './routes/notes.mjs';
+import uploadRoutes from './routes/upload.mjs';
+import searchRoutes from './routes/search.mjs';
+
+/**
+ * Creates a configured notes router
+ * @param {Object} config - Configuration object
+ * @param {Object} config.github - GitHub configuration
+ * @param {string} config.github.token - GitHub personal access token
+ * @param {string} config.github.owner - Repository owner
+ * @param {string} config.github.repo - Repository name
+ * @param {string} [config.github.branch='main'] - Repository branch (defaults to 'main')
+ * @param {Object} config.storage - Storage configuration (R2 or S3)
+ * @param {string} config.storage.type - 'r2' or 's3'
+ * @param {string} config.storage.accountId - Account ID (R2) or region (S3)
+ * @param {string} config.storage.accessKeyId - Access key ID
+ * @param {string} config.storage.secretAccessKey - Secret access key
+ * @param {string} config.storage.bucketName - Bucket name
+ * @param {string} config.storage.publicUrl - Public URL for accessing files
+ * @param {Object} [config.options] - Optional configuration
+ * @param {boolean} [config.options.autoUpdateReadme=true] - Auto-update README on note save
+ * @returns {express.Router} Configured Express router
+ */
+export function createNotesRouter(config) {
+  if (!config.github || !config.github.token || !config.github.owner || !config.github.repo) {
+    throw new Error('GitHub configuration is required: token, owner, and repo');
+  }
+
+  if (!config.storage) {
+    throw new Error('Storage configuration is required');
+  }
+
+  const router = express.Router();
+
+  // Initialize clients
+  const githubClient = new GitHubClient({
+    token: config.github.token,
+    owner: config.github.owner,
+    repo: config.github.repo,
+    branch: config.github.branch || 'main'
+  });
+
+  const storageClient = new StorageClient(config.storage);
+  const markdownRenderer = new MarkdownRenderer();
+  const options = config.options || {};
+
+  // Middleware to attach clients to request
+  router.use((req, res, next) => {
+    req.notesEngine = {
+      githubClient,
+      storageClient,
+      markdownRenderer,
+      options
+    };
+    next();
+  });
+
+  // Mount route handlers
+  router.use(notesRoutes);
+  router.use(uploadRoutes);
+  router.use(searchRoutes);
+
+  return router;
+}

package/lib/backend/markdown.mjs

@@ -0,0 +1,60 @@
+/**
+ * Markdown Renderer
+ * Renders markdown to HTML with syntax highlighting
+ */
+
+import { marked } from 'marked';
+import { markedHighlight } from 'marked-highlight';
+import hljs from 'highlight.js';
+
+export class MarkdownRenderer {
+  constructor() {
+    // Configure marked with syntax highlighting
+    marked.use(markedHighlight({
+      langPrefix: 'hljs language-',
+      highlight(code, lang) {
+        const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+        return hljs.highlight(code, { language }).value;
+      }
+    }));
+
+    // Custom renderer for links and videos
+    const renderer = new marked.Renderer();
+
+    // Custom link renderer - handles internal markdown links
+    renderer.link = (href, title, text) => {
+      if (href.endsWith('.md')) {
+        return `<a href="#" class="internal-link" data-path="${href}">${text}</a>`;
+      }
+      return `<a href="${href}" ${title ? `title="${title}"` : ''}>${text}</a>`;
+    };
+
+    // Custom image renderer - detects videos and renders video tag
+    renderer.image = (href, title, text) => {
+      // Check if it's a video
+      const videoExtensions = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
+      const isVideo = videoExtensions.some(ext => href.toLowerCase().endsWith(ext)) ||
+                      href.includes('/videos/');
+
+      if (isVideo) {
+        return `<video controls style="max-width: 100%;" ${title ? `title="${title}"` : ''}>
+          <source src="${href}" type="video/mp4">
+          Your browser does not support the video tag.
+        </video>`;
+      }
+
+      return `<img src="${href}" alt="${text}" ${title ? `title="${title}"` : ''} style="max-width: 100%;">`;
+    };
+
+    marked.use({ renderer });
+  }
+
+  /**
+   * Render markdown to HTML
+   * @param {string} markdown - Markdown content
+   * @returns {string} HTML content
+   */
+  render(markdown) {
+    return marked(markdown);
+  }
+}