# 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