diff --git a/browser-extension/README.md b/browser-extension/README.md index c454b01b..25e9a6dc 100644 --- a/browser-extension/README.md +++ b/browser-extension/README.md @@ -1,11 +1,14 @@ # DocuElevate Browser Extension -Send files from your browser directly to DocuElevate for processing with a single click. +Clip web pages and send files from your browser directly to DocuElevate for processing with a single click. ## Features +- **Web Page Clipping**: Clip full pages or selected content as PDF documents - **One-Click File Sending**: Send file URLs from your browser to DocuElevate -- **Context Menu Integration**: Right-click on links or pages to send them to DocuElevate +- **Context Menu Integration**: Right-click on links or pages to send or clip them +- **Dual Mode Interface**: Toggle between "Send URL" and "Clip Page" modes +- **PDF Conversion**: Automatically converts clipped pages to PDF format - **Secure Configuration**: Store your DocuElevate server URL and authentication in the extension - **Cross-Browser Support**: Compatible with Chrome, Firefox, Edge, and other Chromium-based browsers - **Minimal Permissions**: Only requests necessary permissions for functionality @@ -50,24 +53,49 @@ Send files from your browser directly to DocuElevate for processing with a singl - If authentication is enabled, enter your session cookie (optional) - Click "Save Configuration" -**Note**: For permanent installation in Firefox, you'll need to sign the extension through Mozilla's add-on portal. +**Note**: For permanent installation in Firefox, you'll need to sign the extension through Mozilla's add-on portal. Firefox supports the same Chrome API for PDF conversion (tabs.printToPDF). ## Usage -### Method 1: Extension Popup +### Method 1: Extension Popup (Send URL Mode) 1. Navigate to a page with a file URL (e.g., a PDF, DOCX, image) 2. Click the DocuElevate extension icon -3. Optionally, enter a custom filename -4. Click "Send to DocuElevate" -5. Wait for confirmation that the file was sent +3. Select "Send URL" mode (default) +4. Optionally, enter a custom filename +5. Click "Send to DocuElevate" +6. Wait for confirmation that the file was sent -### Method 2: Context Menu +### Method 2: Extension Popup (Clip Page Mode) + +1. Navigate to any web page you want to clip +2. Click the DocuElevate extension icon +3. Select "Clip Page" mode +4. Choose either: + - **Clip Full Page**: Captures the entire page content + - **Clip Selection**: Captures only the selected text/content (select text first) +5. Optionally, enter a custom filename +6. The page will be converted to PDF and sent to DocuElevate + +### Method 3: Context Menu - Send URL 1. Right-click on a link or the current page -2. Select "Send to DocuElevate" from the context menu +2. Select "Send URL to DocuElevate" from the context menu 3. A notification will confirm the file was sent or show an error +### Method 4: Context Menu - Clip Page + +1. Right-click on any page +2. Select "Clip Full Page to DocuElevate" from the context menu +3. The entire page will be clipped as PDF and sent + +### Method 5: Context Menu - Clip Selection + +1. Select text or content on the page +2. Right-click on the selection +3. Select "Clip Selection to DocuElevate" from the context menu +4. Only the selected content will be clipped as PDF and sent + ## Configuration ### Server URL @@ -75,7 +103,8 @@ Send files from your browser directly to DocuElevate for processing with a singl The DocuElevate server URL should point to your DocuElevate instance: - Format: `https://your-domain.com` or `http://localhost:8000` - Do not include trailing slashes or API paths -- The extension will automatically append `/api/process-url` +- For URL mode: Extension appends `/api/process-url` +- For clip mode: Extension appends `/api/files/upload` ### Session Cookie (Optional) @@ -95,13 +124,19 @@ If your DocuElevate instance has authentication enabled, you need to provide a s **Security Note**: Your session cookie is stored securely in the browser's extension storage. Never share your session cookie with others. -## Supported File Types +## Supported Content +### URL Mode The extension can send any URL, but DocuElevate will only process supported file types: - - **Documents**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, RTF - **Images**: JPG, PNG, GIF, BMP, TIFF, WebP, SVG +### Clip Mode +Any web page can be clipped. The extension will: +- Capture HTML content with styles +- Convert to PDF format using browser's print API +- Upload to DocuElevate for processing + ## Troubleshooting ### "Failed to connect to DocuElevate server" @@ -123,21 +158,40 @@ The extension can send any URL, but DocuElevate will only process supported file - Enter the session cookie in the extension settings - Ensure your session hasn't expired (log in again if needed) -### "Unsupported file type" +### "No content selected" (Clip Selection) + +**Cause**: No text or content is selected on the page. + +**Solution**: +- Select text or content on the page before clicking "Clip Selection" +- Use "Clip Full Page" to capture the entire page without selection + +### "Failed to convert to PDF" + +**Cause**: The browser's PDF conversion API failed. + +**Solutions**: +- Ensure you're using a modern version of Chrome/Edge/Firefox +- Check browser console for detailed error messages +- Try clipping a simpler page to test +- Ensure the page has finished loading + +### "Unsupported file type" (URL Mode) **Cause**: The URL doesn't point to a supported file type. **Solution**: - Verify the URL ends with a supported file extension - Check that the Content-Type header is set correctly by the server +- Use "Clip Page" mode instead to capture web content ### "File too large" -**Cause**: The file exceeds the maximum upload size configured in DocuElevate. +**Cause**: The file/PDF exceeds the maximum upload size configured in DocuElevate. **Solutions**: - Check your DocuElevate `MAX_UPLOAD_SIZE` configuration -- Try a smaller file +- Try a smaller file or clip a smaller selection - Contact your DocuElevate administrator to increase the limit ## Privacy & Security @@ -146,10 +200,12 @@ The extension can send any URL, but DocuElevate will only process supported file The extension requests minimal permissions: -- **activeTab**: To get the URL of the current tab +- **activeTab**: To get the URL and content of the current tab - **storage**: To save your server URL and session cookie configuration -- **contextMenus**: To add the "Send to DocuElevate" option to right-click menus +- **contextMenus**: To add context menu options for sending/clipping - **notifications**: To show success/error notifications +- **scripting**: To inject content capture code into web pages +- **host_permissions**: To access page content for clipping (restricted to active tab) ### Data Handling @@ -157,6 +213,7 @@ The extension requests minimal permissions: - **Local Configuration**: Your server URL and session cookie are stored locally in your browser - **Direct Communication**: All API requests go directly from your browser to your DocuElevate server - **No Third Parties**: No data is sent to third-party services +- **Page Content**: When clipping, page HTML is captured temporarily in memory and converted to PDF locally in your browser before upload ## Development @@ -175,12 +232,13 @@ browser-extension/ │ ├── icon48.png │ └── icon128.png ├── popup/ # Extension popup UI -│ ├── popup.html -│ ├── popup.css -│ └── popup.js +│ ├── popup.html # Popup interface with mode toggle +│ ├── popup.css # Styling for popup +│ └── popup.js # Popup logic for URL and clip modes └── scripts/ # Background and content scripts - ├── background.js # Service worker for background tasks - └── content.js # Content script for page interaction + ├── background.js # Service worker with PDF conversion + ├── content.js # Content script for page capture + └── capture.js # Utility functions for web clipping ``` ### Testing @@ -230,7 +288,15 @@ For issues, questions, or feature requests: ## Version History -### 1.0.0 (Current) +### 1.1.0 (Current) +- **Web Page Clipping**: Clip full pages or selected content as PDF +- **Dual Mode Interface**: Toggle between "Send URL" and "Clip Page" modes +- **PDF Conversion**: Browser-based PDF generation using printToPDF API +- **Enhanced Context Menus**: Separate options for URL sending and page clipping +- **Selection Clipping**: Clip only selected text/content from pages +- Cross-browser compatibility (Chrome, Firefox, Edge) + +### 1.0.0 - Initial release - Basic URL sending functionality - Configuration management diff --git a/docs/BrowserExtension.md b/docs/BrowserExtension.md index 31cbe1d0..7c395d87 100644 --- a/docs/BrowserExtension.md +++ b/docs/BrowserExtension.md @@ -1,18 +1,21 @@ # Browser Extension Guide -The DocuElevate Browser Extension enables users to send files from their web browser directly to DocuElevate for processing. +The DocuElevate Browser Extension enables users to clip web pages and send files from their web browser directly to DocuElevate for processing. ## Overview -The browser extension provides a seamless way to process files without manually downloading them first. Users can send file URLs with a single click, and DocuElevate will download and process the files automatically. +The browser extension provides a seamless way to process files and capture web content without manually downloading or copying them first. Users can send file URLs or clip entire web pages with a single click, and DocuElevate will process them automatically. ## Features ### Core Functionality +- **Web Page Clipping**: Capture full pages or selected content as PDF documents - **One-Click File Sending**: Send file URLs from the browser to DocuElevate -- **Context Menu Integration**: Right-click on links or pages to send them -- **Popup Interface**: Simple configuration and file submission UI +- **Dual Mode Interface**: Toggle between "Send URL" and "Clip Page" modes +- **Context Menu Integration**: Right-click on links, pages, or selections for quick actions +- **PDF Conversion**: Automatic conversion of clipped pages to PDF format +- **Popup Interface**: Simple configuration and file/page submission UI - **Status Notifications**: Immediate feedback on submission success or failure ### Security Features @@ -21,6 +24,7 @@ The browser extension provides a seamless way to process files without manually - **Secure Storage**: Configuration stored locally in browser extension storage - **Direct Communication**: All requests go directly to your DocuElevate server - **Session-Based Auth**: Supports DocuElevate authentication via session cookies +- **Local PDF Generation**: Pages converted to PDF in your browser before upload ### Cross-Browser Support @@ -28,7 +32,7 @@ The extension is compatible with: - Google Chrome - Microsoft Edge - Chromium-based browsers (Brave, Opera, etc.) -- Mozilla Firefox (with minor adjustments) +- Mozilla Firefox (full support including PDF conversion) ## Installation @@ -40,13 +44,14 @@ Quick steps: 1. Load the extension from the `browser-extension` folder 2. Configure your DocuElevate server URL 3. Optionally add authentication (session cookie) -4. Start sending files! +4. Start sending files or clipping pages! ### For Administrators #### Prerequisites - DocuElevate server running with URL upload API enabled +- File upload API accessible at `/api/files/upload` - Server accessible from users' browsers (not blocked by firewall/CORS) - Optional: Authentication configured if required @@ -82,36 +87,65 @@ Users need to configure two settings: ### Server Configuration -No server-side configuration is required. The extension uses the existing URL upload API endpoint: +No server-side configuration is required. The extension uses existing API endpoints: ``` -POST /api/process-url +POST /api/process-url # For URL mode +POST /api/files/upload # For clip mode ``` -Ensure this endpoint is: +Ensure these endpoints are: - Accessible from users' browsers - Not blocked by CORS policies (if different domain) - Properly secured with authentication if needed ## Usage -### Sending Files via Popup +### Mode Selection + +The extension has two modes accessible via the popup: + +1. **Send URL Mode** (default): Send file URLs to DocuElevate +2. **Clip Page Mode**: Capture and convert web pages to PDF + +Toggle between modes by clicking the mode buttons in the popup. + +### Sending Files via Popup (URL Mode) 1. Click the DocuElevate extension icon -2. The current page URL is displayed -3. Optionally enter a custom filename -4. Click "Send to DocuElevate" -5. Status message shows success or error +2. Select "Send URL" mode +3. The current page URL is displayed +4. Optionally enter a custom filename +5. Click "Send to DocuElevate" +6. Status message shows success or error -### Sending Files via Context Menu +### Clipping Pages via Popup (Clip Mode) + +1. Click the DocuElevate extension icon +2. Select "Clip Page" mode +3. The current page title is displayed +4. Choose one of: + - **Clip Full Page**: Captures entire page content + - **Clip Selection**: Captures only selected text (select first) +5. Optionally enter a custom filename +6. Page is converted to PDF and uploaded +7. Status message shows success or error + +### Sending URLs via Context Menu 1. Right-click on any link or the current page -2. Select "Send to DocuElevate" +2. Select "Send URL to DocuElevate" 3. A notification appears with the result -### Supported URLs +### Clipping via Context Menu -The extension can send any URL, but DocuElevate will only process: +1. **Full Page**: Right-click on any page and select "Clip Full Page to DocuElevate" +2. **Selection**: Select text, right-click, and select "Clip Selection to DocuElevate" +3. A notification appears with the result + +### Supported Content + +**URL Mode** - DocuElevate will process these file types: **Document URLs**: - PDFs: `https://example.com/document.pdf` @@ -124,18 +158,39 @@ The extension can send any URL, but DocuElevate will only process: - `https://example.com/scan.png` - `https://example.com/diagram.svg` +**Clip Mode** - Any web page can be clipped: +- Articles, blogs, documentation +- Forms, receipts, confirmations +- Social media posts, comments +- Any HTML content with styling + ## How It Works ### Architecture ``` + URL Mode ┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ │ Browser │ │ Browser Ext. │ │ DocuElevate │ │ Tab │────────▶│ (popup.js) │────────▶│ Server │ -│ │ URL │ │ API │ │ -└─────────────┘ └──────────────────┘ Request └──────────────┘ - │ - │ Stores config in +│ │ URL │ │ API │ /process-url │ +└─────────────┘ └──────────────────┘ └──────────────┘ + + Clip Mode +┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ Browser │ Capture │ Browser Ext. │ Convert │ Browser │ +│ Tab │────────▶│ (content.js) │────────▶│ printToPDF() │ +│ (HTML) │ │ │ │ │ +└─────────────┘ └──────────────────┘ └──────────────┘ + │ │ + │ │ PDF + ▼ ▼ + ┌──────────────────┐ ┌──────────────┐ + │ background.js │────────▶│ DocuElevate │ + │ │ Upload │ Server │ + └──────────────────┘ │ /files/upload│ + │ └──────────────┘ + │ Stores config ▼ ┌──────────────────┐ │ Browser Storage │ @@ -143,7 +198,7 @@ The extension can send any URL, but DocuElevate will only process: └──────────────────┘ ``` -### Data Flow +### Data Flow - URL Mode 1. **User initiates send**: Via popup or context menu 2. **Extension gets current URL**: From active tab @@ -156,15 +211,39 @@ The extension can send any URL, but DocuElevate will only process: 6. **Response returned**: Task ID and status 7. **User notified**: Success or error message displayed +### Data Flow - Clip Mode + +1. **User initiates clip**: Via popup or context menu +2. **Extension captures page**: + - Content script extracts HTML with styles + - For selection: captures only selected range + - For full page: captures entire document body +3. **HTML to PDF conversion**: + - Background script creates temporary tab with HTML + - Browser's printToPDF API converts to PDF + - Temporary tab is closed +4. **PDF upload**: + - Extension loads config from storage + - FormData created with PDF blob + - POST to `/api/files/upload` with authentication +5. **DocuElevate processes**: + - Receives PDF file + - Validates and stores + - Enqueues for OCR and metadata extraction +6. **Response returned**: Task ID and status +7. **User notified**: Success or error notification + ### Security Flow The extension implements several security measures: -1. **No direct file access**: Extension only sends URLs, not file contents -2. **User-controlled config**: Server URL and auth stored per-user -3. **HTTPS recommended**: Encourages secure communication -4. **Minimal permissions**: Only requests necessary browser APIs -5. **Server-side validation**: DocuElevate validates all URLs (SSRF protection) +1. **No direct file access**: Extension only sends URLs or generated PDFs +2. **Local PDF generation**: Pages converted to PDF in user's browser, not server-side +3. **User-controlled config**: Server URL and auth stored per-user +4. **HTTPS recommended**: Encourages secure communication +5. **Minimal permissions**: Only requests necessary browser APIs +6. **Server-side validation**: DocuElevate validates all uploads +7. **Content isolation**: Captured HTML processed in isolated context ## Technical Details @@ -174,9 +253,10 @@ The extension implements several security measures: - Manifest v3 format (latest standard) - Minimal permissions requested - Compatible with Chrome, Edge, and Firefox +- Version 1.1.0 with web clipping support **popup/**: User interface files -- `popup.html`: Extension popup interface +- `popup.html`: Extension popup interface with mode toggle - `popup.css`: Styling with modern UI design - `popup.js`: Configuration and file sending logic @@ -188,9 +268,9 @@ The extension implements several security measures: ### API Integration -The extension communicates with DocuElevate via the URL upload API: +The extension communicates with DocuElevate via two API endpoints: -**Request Format**: +**URL Mode - Request Format**: ```javascript POST /api/process-url Content-Type: application/json @@ -202,7 +282,7 @@ Cookie: session= // if auth enabled } ``` -**Response Format**: +**URL Mode - Response Format**: ```javascript { "task_id": "abc-123-def", @@ -213,7 +293,27 @@ Cookie: session= // if auth enabled } ``` -**Error Response**: +**Clip Mode - Request Format**: +```javascript +POST /api/files/upload +Content-Type: multipart/form-data +Cookie: session= // if auth enabled + +FormData: + file: (page-title.pdf) +``` + +**Clip Mode - Response Format**: +```javascript +{ + "task_id": "def-456-ghi", + "status": "processing", + "message": "File uploaded and queued for processing", + "filename": "page-title.pdf" +} +``` + +**Error Response** (both modes): ```javascript { "detail": "Error message explaining what went wrong" @@ -224,10 +324,12 @@ Cookie: session= // if auth enabled The extension requests these permissions: -- **activeTab**: Get URL of current tab +- **activeTab**: Get URL and content of current tab - **storage**: Save configuration (server URL, session cookie) -- **contextMenus**: Add "Send to DocuElevate" to right-click menu +- **contextMenus**: Add context menu options for sending/clipping - **notifications**: Show success/error notifications +- **scripting**: Inject content capture code into web pages +- **host_permissions**: Access page content for clipping (restricted to active tab) All permissions are used only for stated purposes. No data is collected or transmitted to third parties.