Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation

2026-05-11 17:37:10 -05:00
parent ad0b12b452
commit aed69afdfd
691 changed files with 181874 additions and 28 deletions
--- a/LinkSyncExtension/README.md
+++ b/LinkSyncExtension/README.md
@@ -0,0 +1,287 @@
+# 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