myworkspace/LinkSyncExtension

LinkSyncExtension

A Firefox browser extension for bookmark synchronization with LinkSyncServer.

Overview

LinkSyncExtension syncs bookmarks between Firefox and LinkSyncServer, supporting:

• Firefox-Compatible Fields - All bookmark attributes natively
• Multiple Sync Modes - Bi-directional, browser authoritative, server authoritative
• Collection Management - View and manage collections
• Query Builder - Build and execute complex queries
• Conflict Resolution - Handle sync conflicts gracefully

Features

Synchronization

Mode	Description
Bi-directional	Add/update bookmarks both ways; optional deletions
Browser Authoritative	Browser is source of truth; overwrites server
Server Authoritative	Download from server only; overwrite on conflict

Bookmarks (Links)

All Firefox bookmark attributes:

• url - Bookmark URL
• title - Display title
• description - Optional description
• notes - User notes
• tags - Array of tag names
• favicon_url - Icon URL
• path - Folder structure
• created_at, updated_at - Timestamps
• visit_count, is_bookmarked - Status fields

Collections

Two types:

1. Static Collections - Explicit set of bookmark IDs
2. Dynamic Collections - Query expression evaluated on access

Query Builder

Build queries with:

• Term lists: ('term1', 'term2', 'term3') → OR
• Tag filters: tagA, tagB
• Field filters: url:example.com
• Set operations: AND, OR, XOR

Example:

('work', 'dev') OR tag:work XOR url:internal.com

Sync Status

Monitor sync state:

• Last sync time
• Pending changes count
• Conflict indicators
• Manual sync trigger

Installation

Step 1: Load Extension

1. Open Firefox and navigate to about:addons
2. Click the "Gear" icon → "Debug Add-ons"
3. Click "Load Temporary Add-on..."
4. Navigate to LinkSyncExtension folder
5. Select manifest.json

Or upload a .zip file via "Install Temporary Add-on from File..."

Step 2: Configure

1. Click the extension icon
2. Click "Settings" button
3. Configure:
   • Server URL - LinkSyncServer address (e.g., https://links.example.com)
   • API Key - Generate from server admin panel
   • Collection Name - Name to map this browser
4. Click "Save Settings"

Step 3: Start Syncing

• Extension runs in background
• Click icon to view status
• Add bookmarks via popup
• Sync automatically or manually

Usage

Adding Bookmarks

Click the extension icon to open the popup:

• URL - Auto-filled with current page (or manual entry)
• Title - Auto-filled from page title
• Description - Auto-filled from meta description
• Notes - Your notes
• Tags - Comma-separated tag names
• Folder - Folder structure path
• Click "Add Bookmark"

Viewing Collections

Click the extension icon:

• All Links - View all synced bookmarks
• Collections - View your collections
• Search - Search across all links
• Query Builder - Build custom queries

Syncing

Click the extension icon → "Sync Now"

• Manual sync triggers
• Automatic sync on page load (optional)

Managing Settings

Click the extension icon → "Settings"

Change:

• Server URL
• API Key
• Collection mapping
• Sync mode
• Auto-sync settings

File Structure

LinkSyncExtension/
├── manifest.json              # Extension manifest v2
├── popup.html                 # Bookmark add/edit UI
├── popup.css                  # Popup styling
├── popup.js                   # Popup logic
├── background.html            # Settings page
├── background.js              # Service worker
├── content/
│   └── content.js             # Content script (optional)
└── utils/
    ├── bookmark.js           # Bookmark manipulation
    ├── collection.js         # Collection management
    ├── query-engine.js       # Query parsing/execution
    └── sync.js               # Sync logic

API

The extension communicates with LinkSyncServer via REST API:

Endpoint	Method	Description
/api/auth/login/	POST	Authenticate, get API token
/api/links/	GET	List bookmarks
/api/links/	POST	Create bookmark
/api/links/{id}/	PUT	Update bookmark
/api/links/{id}/	DELETE	Delete bookmark
/api/collections/	GET	List collections
/api/collections/{id}/	GET	Get collection
/api/collections/{id}/query/	POST	Execute query
/api/sync/	POST	Sync bookmarks

Headers:

Authorization: Token <your-api-key>
Content-Type: application/json

Configuration

manifest.json

{
    "manifest_version": 2,
    "name": "LinkSync",
    "version": "1.0.0",
    "description": "Sync bookmarks with LinkSyncServer",
    "permissions": [
        "bookmarks",
        "storage",
        "activeTab"
    ],
    "browser_action": {
        "default_icon": {
            "48": "icons/icon-48.png",
            "96": "icons/icon-96.png"
        },
        "default_title": "LinkSync"
    },
    "background": {
        "page": "background.html"
    },
    "browser_specific_settings": {
        "gecko": {
            "id": "linksync@example.com",
            "strict_min_version": "109.0"
        }
    }
}

Sync Modes

Bi-directional

• Bookmarks added/updated in browser → pushed to server
• Bookmarks added/updated on server → pushed to browser
• Optional: Enable deletions

Browser Authoritative

• Browser is source of truth
• Server data overwritten on conflict
• Only additions/updates pushed

Server Authoritative

• Download bookmarks from server
• Overwrite local data on conflict
• No push to server

Collection Mapping

Map browser profile to collection:

• Each collection has a unique name
• Extension stores collection name in settings
• Server uses name to identify collection
• Multiple extensions per profile supported

Security

• API keys stored in browser storage (encrypted)
• Never expose keys in code
• Validate all server responses
• HTTPS-only connections preferred

Troubleshooting

Extension not loading

• Check browser console for errors
• Verify manifest.json is valid
• Ensure all files present

Cannot connect to server

• Verify server URL is correct
• Check API key is valid
• Ensure HTTPS or server allows HTTP

Sync not working

• Check sync mode settings
• Verify collection exists on server
• Check browser console for errors

Conflicts

• Conflict detected when same URL exists in different locations
• Review conflict in popup
• Choose which version to keep

License

MIT License

Support

For issues and questions, open an issue on the LinkSyncServer repository.

---

Version: 1.0.0
Last Updated: 2026-05-11