287 lines
6.7 KiB
Markdown
287 lines
6.7 KiB
Markdown
# 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
|
|
|
|
```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 |