gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update browser extension documentation for web clipping

Browse Source 
- Updated browser-extension/README.md with web clipping features
- Updated docs/BrowserExtension.md with dual-mode architecture
- Added documentation for clip mode data flow and API endpoints
- Updated permissions explanation for new clipping capabilities
- Added troubleshooting for clip-specific issues
- Documented version 1.1.0 features and changes

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-13 23:24:10 +00:00
parent f7280be523
commit 5380c6de6c
2 changed files with 226 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
browser-extension/README.md
+89 -23
View File
@@ -1,11 +1,14 @@
# DocuElevate Browser Extension # 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 ## 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 - **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 - **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 - **Cross-Browser Support**: Compatible with Chrome, Firefox, Edge, and other Chromium-based browsers
- **Minimal Permissions**: Only requests necessary permissions for functionality - **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) - If authentication is enabled, enter your session cookie (optional)
- Click "Save Configuration" - 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 ## 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) 1. Navigate to a page with a file URL (e.g., a PDF, DOCX, image)
2. Click the DocuElevate extension icon 2. Click the DocuElevate extension icon
3. Optionally, enter a custom filename 3. Select "Send URL" mode (default)
4. Click "Send to DocuElevate" 4. Optionally, enter a custom filename
5. Wait for confirmation that the file was sent 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 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 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 ## Configuration
### Server URL ### 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: The DocuElevate server URL should point to your DocuElevate instance:
- Format: `https://your-domain.com` or `http://localhost:8000` - Format: `https://your-domain.com` or `http://localhost:8000`
- Do not include trailing slashes or API paths - 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) ### 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. **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: 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 - **Documents**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, RTF
- **Images**: JPG, PNG, GIF, BMP, TIFF, WebP, SVG - **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 ## Troubleshooting
### "Failed to connect to DocuElevate server" ### "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 - Enter the session cookie in the extension settings
- Ensure your session hasn't expired (log in again if needed) - 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. **Cause**: The URL doesn't point to a supported file type.
**Solution**: **Solution**:
- Verify the URL ends with a supported file extension - Verify the URL ends with a supported file extension
- Check that the Content-Type header is set correctly by the server - Check that the Content-Type header is set correctly by the server
- Use "Clip Page" mode instead to capture web content
### "File too large" ### "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**: **Solutions**:
- Check your DocuElevate `MAX_UPLOAD_SIZE` configuration - 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 - Contact your DocuElevate administrator to increase the limit
## Privacy & Security ## Privacy & Security
@@ -146,10 +200,12 @@ The extension can send any URL, but DocuElevate will only process supported file
The extension requests minimal permissions: 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 - **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 - **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 ### 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 - **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 - **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 - **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 ## Development
@@ -175,12 +232,13 @@ browser-extension/
│ ├── icon48.png │ ├── icon48.png
│ └── icon128.png │ └── icon128.png
├── popup/ # Extension popup UI ├── popup/ # Extension popup UI
│ ├── popup.html │ ├── popup.html # Popup interface with mode toggle
│ ├── popup.css │ ├── popup.css # Styling for popup
│ └── popup.js │ └── popup.js # Popup logic for URL and clip modes
└── scripts/ # Background and content scripts └── scripts/ # Background and content scripts
├── background.js # Service worker for background tasks ├── background.js # Service worker with PDF conversion
└── content.js # Content script for page interaction ├── content.js # Content script for page capture
└── capture.js # Utility functions for web clipping
``` ```
### Testing ### Testing
@@ -230,7 +288,15 @@ For issues, questions, or feature requests:
## Version History ## 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 - Initial release
- Basic URL sending functionality - Basic URL sending functionality
- Configuration management - Configuration management
docs/BrowserExtension.md
+137 -35
View File
@@ -1,18 +1,21 @@
# Browser Extension Guide # 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 ## 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 ## Features
### Core Functionality ### 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 - **One-Click File Sending**: Send file URLs from the browser to DocuElevate
- **Context Menu Integration**: Right-click on links or pages to send them - **Dual Mode Interface**: Toggle between "Send URL" and "Clip Page" modes
- **Popup Interface**: Simple configuration and file submission UI - **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 - **Status Notifications**: Immediate feedback on submission success or failure
### Security Features ### 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 - **Secure Storage**: Configuration stored locally in browser extension storage
- **Direct Communication**: All requests go directly to your DocuElevate server - **Direct Communication**: All requests go directly to your DocuElevate server
- **Session-Based Auth**: Supports DocuElevate authentication via session cookies - **Session-Based Auth**: Supports DocuElevate authentication via session cookies
- **Local PDF Generation**: Pages converted to PDF in your browser before upload
### Cross-Browser Support ### Cross-Browser Support
@@ -28,7 +32,7 @@ The extension is compatible with:
- Google Chrome - Google Chrome
- Microsoft Edge - Microsoft Edge
- Chromium-based browsers (Brave, Opera, etc.) - Chromium-based browsers (Brave, Opera, etc.)
- Mozilla Firefox (with minor adjustments) - Mozilla Firefox (full support including PDF conversion)
## Installation ## Installation
@@ -40,13 +44,14 @@ Quick steps:
1. Load the extension from the `browser-extension` folder 1. Load the extension from the `browser-extension` folder
2. Configure your DocuElevate server URL 2. Configure your DocuElevate server URL
3. Optionally add authentication (session cookie) 3. Optionally add authentication (session cookie)
4. Start sending files! 4. Start sending files or clipping pages!
### For Administrators ### For Administrators
#### Prerequisites #### Prerequisites
- DocuElevate server running with URL upload API enabled - 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) - Server accessible from users' browsers (not blocked by firewall/CORS)
- Optional: Authentication configured if required - Optional: Authentication configured if required
@@ -82,36 +87,65 @@ Users need to configure two settings:
### Server Configuration ### 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 - Accessible from users' browsers
- Not blocked by CORS policies (if different domain) - Not blocked by CORS policies (if different domain)
- Properly secured with authentication if needed - Properly secured with authentication if needed
## Usage ## 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 1. Click the DocuElevate extension icon
2. The current page URL is displayed 2. Select "Send URL" mode
3. Optionally enter a custom filename 3. The current page URL is displayed
4. Click "Send to DocuElevate" 4. Optionally enter a custom filename
5. Status message shows success or error 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 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 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**: **Document URLs**:
- PDFs: `https://example.com/document.pdf` - 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/scan.png`
- `https://example.com/diagram.svg` - `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 ## How It Works
### Architecture ### Architecture
``` ```
URL Mode
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Browser │ │ Browser Ext. │ │ DocuElevate │ │ Browser │ │ Browser Ext. │ │ DocuElevate │
│ Tab │────────▶│ (popup.js) │────────▶│ Server │ │ Tab │────────▶│ (popup.js) │────────▶│ Server │
│ │ URL │ │ API │ │ │ │ URL │ │ API │ /process-url │
└─────────────┘ └──────────────────┘ Request └──────────────┘ └─────────────┘ └──────────────────┘ └──────────────┘
│
│ Stores config in 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 │ │ 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 1. **User initiates send**: Via popup or context menu
2. **Extension gets current URL**: From active tab 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 6. **Response returned**: Task ID and status
7. **User notified**: Success or error message displayed 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 ### Security Flow
The extension implements several security measures: The extension implements several security measures:
1. **No direct file access**: Extension only sends URLs, not file contents 1. **No direct file access**: Extension only sends URLs or generated PDFs
2. **User-controlled config**: Server URL and auth stored per-user 2. **Local PDF generation**: Pages converted to PDF in user's browser, not server-side
3. **HTTPS recommended**: Encourages secure communication 3. **User-controlled config**: Server URL and auth stored per-user
4. **Minimal permissions**: Only requests necessary browser APIs 4. **HTTPS recommended**: Encourages secure communication
5. **Server-side validation**: DocuElevate validates all URLs (SSRF protection) 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 ## Technical Details
@@ -174,9 +253,10 @@ The extension implements several security measures:
- Manifest v3 format (latest standard) - Manifest v3 format (latest standard)
- Minimal permissions requested - Minimal permissions requested
- Compatible with Chrome, Edge, and Firefox - Compatible with Chrome, Edge, and Firefox
- Version 1.1.0 with web clipping support
**popup/**: User interface files **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.css`: Styling with modern UI design
- `popup.js`: Configuration and file sending logic - `popup.js`: Configuration and file sending logic
@@ -188,9 +268,9 @@ The extension implements several security measures:
### API Integration ### 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 ```javascript
POST /api/process-url POST /api/process-url
Content-Type: application/json Content-Type: application/json
@@ -202,7 +282,7 @@ Cookie: session=<session_value> // if auth enabled
} }
``` ```
**Response Format**: **URL Mode - Response Format**:
```javascript ```javascript
{ {
"task_id": "abc-123-def", "task_id": "abc-123-def",
@@ -213,7 +293,27 @@ Cookie: session=<session_value> // if auth enabled
} }
``` ```
**Error Response**: **Clip Mode - Request Format**:
```javascript
POST /api/files/upload
Content-Type: multipart/form-data
Cookie: session=<session_value> // if auth enabled
FormData:
file: <PDF Blob> (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 ```javascript
{ {
"detail": "Error message explaining what went wrong" "detail": "Error message explaining what went wrong"
@@ -224,10 +324,12 @@ Cookie: session=<session_value> // if auth enabled
The extension requests these permissions: 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) - **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 - **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. All permissions are used only for stated purposes. No data is collected or transmitted to third parties.