Skip to content

Browser Extension Guide

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 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
  • 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

  • Minimal Permissions: Only requests necessary browser permissions
  • 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

The extension is compatible with: - Google Chrome - Microsoft Edge - Chromium-based browsers (Brave, Opera, etc.) - Mozilla Firefox (full support including PDF conversion)

Installation

For End Users

See the Browser Extension README for detailed installation instructions.

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 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

Deployment Options

Option 1: Direct Distribution - Share the browser-extension folder with users - Users load it as an unpacked extension

Option 2: Internal Extension Store - Package the extension as a .zip file - Distribute via internal Chrome Web Store or Firefox Add-ons for Enterprise

Option 3: Public Store (requires additional steps) - Submit to Chrome Web Store - Submit to Firefox Add-ons

Configuration

Extension Settings

Users need to configure two settings:

  1. DocuElevate Server URL (required)
  2. Format: https://docuelevate.example.com
  3. Must be accessible from user's browser

  4. Should not include trailing slashes or API paths

  5. Session Cookie (optional, if auth enabled)

  6. Format: session=cookie_value_here
  7. Obtained by logging into DocuElevate and copying session cookie
  8. Expires when the session expires (users need to update it)

Server Configuration

No server-side configuration is required. The extension uses existing API endpoints:

POST /api/process-url      # For URL mode
POST /api/files/upload     # For clip mode

Ensure these endpoints are: - Accessible from users' browsers - Not blocked by CORS policies (if different domain) - Properly secured with authentication if needed

Usage

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. 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

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:
  5. Clip Full Page: Captures entire page content
  6. Clip Selection: Captures only selected text (select first)
  7. Optionally enter a custom filename
  8. Page is converted to PDF and uploaded
  9. Status message shows success or error

Sending URLs via Context Menu

  1. Right-click on any link or the current page
  2. Select "Send URL to DocuElevate"
  3. A notification appears with the result

Clipping via Context Menu

  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 - Office: https://example.com/report.docx - Spreadsheets: https://example.com/data.xlsx - Text files: https://example.com/notes.txt

Image URLs: - https://example.com/image.jpg - 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    │ /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  │
                        │ (chrome.storage) │
                        └──────────────────┘

Data Flow - URL Mode

  1. User initiates send: Via popup or context menu
  2. Extension gets current URL: From active tab
  3. Extension loads config: Server URL and session cookie from storage
  4. API request sent: POST to /api/process-url with URL and optional filename
  5. DocuElevate processes:
  6. Downloads file from URL
  7. Validates file type and size
  8. Enqueues for processing (OCR, metadata extraction)
  9. Response returned: Task ID and status
  10. User notified: Success or error message displayed

Data Flow - Clip Mode

  1. User initiates clip: Via popup or context menu
  2. Extension captures page:
  3. Content script extracts HTML with styles
  4. For selection: captures only selected range
  5. For full page: captures entire document body
  6. HTML to PDF conversion:
  7. Background script creates temporary tab with HTML
  8. Browser's printToPDF API converts to PDF
  9. Temporary tab is closed
  10. PDF upload:
  11. Extension loads config from storage
  12. FormData created with PDF blob
  13. POST to /api/files/upload with authentication
  14. DocuElevate processes:
  15. Receives PDF file
  16. Validates and stores
  17. Enqueues for OCR and metadata extraction
  18. Response returned: Task ID and status
  19. User notified: Success or error notification

Security Flow

The extension implements several security measures:

  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

Extension Structure

manifest.json: Extension metadata and configuration - 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 with mode toggle - popup.css: Styling with modern UI design - popup.js: Configuration and file sending logic

scripts/: Background functionality - background.js: Service worker for context menu and notifications - content.js: Content script for page interaction (minimal)

icons/: Extension icons in multiple sizes

API Integration

The extension communicates with DocuElevate via two API endpoints:

URL Mode - Request Format:

POST /api/process-url
Content-Type: application/json
Cookie: session=<session_value>  // if auth enabled

{
  "url": "https://example.com/file.pdf",
  "filename": "optional-custom-name.pdf"  // optional
}

URL Mode - Response Format:

{
  "task_id": "abc-123-def",
  "status": "queued",
  "message": "File downloaded from URL and queued for processing",
  "filename": "file.pdf",
  "size": 1024
}

Clip Mode - Request Format:

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:

{
  "task_id": "def-456-ghi",
  "status": "processing",
  "message": "File uploaded and queued for processing",
  "filename": "page-title.pdf"
}

Error Response (both modes):

{
  "detail": "Error message explaining what went wrong"
}

Browser Permissions

The extension requests these permissions:

  • activeTab: Get URL and content of current tab
  • storage: Save configuration (server URL, session cookie)
  • 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.

Troubleshooting

Common Issues

"Failed to connect to DocuElevate server" - Check server URL is correct and accessible - Verify server is running - Check firewall/network settings - Test API directly: curl https://your-server/api/process-url

"Authentication required" (401 error) - User needs to add session cookie - Session may have expired (log in again) - Check AUTH_ENABLED setting in DocuElevate

"Unsupported file type" (400 error) - URL must point to a supported file type - Check file extension and Content-Type header - See DocuElevate supported file types

"File too large" (413 error) - File exceeds MAX_UPLOAD_SIZE setting - Contact admin to increase limit or use smaller file

Extension not appearing - Ensure developer mode is enabled - Reload the extension - Check browser console for errors

Debug Mode

To debug the extension:

  1. Open Extension Console:
  2. Chrome: Right-click extension icon → "Inspect popup"

  3. Or go to chrome://extensions/ → Click "Inspect views: service worker"

  4. Check Console Logs:

  5. Look for error messages
  6. Verify API requests are being sent

  7. Check response status codes

  8. Test API Directly: bash curl -X POST https://your-server/api/process-url \ -H "Content-Type: application/json" \ -H "Cookie: session=your_session" \ -d '{"url": "https://example.com/test.pdf"}'

Best Practices

For Users

  • Keep your session cookie secure and don't share it
  • Verify the DocuElevate server URL is correct before saving
  • Only send files from trusted sources
  • Check file size limits before sending large files

For Administrators

  • Configure HTTPS for production servers
  • Set appropriate MAX_UPLOAD_SIZE limits
  • Enable authentication for security
  • Monitor API usage and set rate limits if needed
  • Provide clear documentation to users on getting session cookies

Future Enhancements

Possible future improvements:

  • OAuth2 authentication instead of session cookies
  • Current session cookie approach has limitations:
    • Session cookies expire and need manual refresh
    • Users must manually copy cookie from browser DevTools
    • No automatic token refresh mechanism
  • OAuth2 would provide:
    • Automatic token refresh
    • Better security with short-lived access tokens
    • Easier user experience (login flow instead of cookie copying)
  • File preview before sending
  • Batch processing multiple URLs
  • Progress indication for large files
  • History of sent files
  • Custom processing options (OCR language, metadata fields, etc.)

For users of the current implementation:

  1. Keep session cookies secure: Never share your session cookie value
  2. Refresh regularly: Session cookies expire; update the extension when you log in again
  3. Use HTTPS: Always use HTTPS for your DocuElevate server
  4. Clear on logout: Remove the session cookie from extension when logging out
  5. Private browsing: Session cookies from private/incognito windows have shorter lifetimes

Support

For issues or questions: - Check the troubleshooting section above - Review the main documentation - Open an issue on GitHub