@ashdev/codex-plugin-sync-anilist 1.10.0

package/README.md

@@ -0,0 +1,218 @@
+# @ashdev/codex-plugin-sync-anilist
+
+A Codex plugin for syncing manga reading progress between Codex and [AniList](https://anilist.co). Supports push/pull of reading status, volumes/chapters read, scores, dates, and notes.
+
+## Features
+
+- Two-way sync of manga reading progress with AniList
+- Push reading status, progress, scores, dates, and notes to AniList
+- Pull updates from AniList back to Codex
+- Configurable progress unit (volumes or chapters)
+- Auto-pause/auto-drop stale series based on reading inactivity
+- Rate limit handling with automatic retry
+- Highest-progress-wins conflict resolution (progress only moves forward)
+- External ID matching via AniList API IDs (`api:anilist`)
+
+## Authentication
+
+This plugin supports two authentication methods:
+
+### OAuth (Recommended)
+
+If your Codex administrator has configured OAuth:
+
+1. Go to **Settings** > **Integrations**
+2. Click **Connect with AniList Sync**
+3. Authorize Codex on AniList
+4. You're connected!
+
+### Personal Access Token
+
+If OAuth is not configured by the admin:
+
+1. Go to [AniList Developer Settings](https://anilist.co/settings/developer)
+2. Click **Create New Client**
+3. Set the redirect URL to `https://anilist.co/api/v2/oauth/pin`
+4. Click **Save**, then **Authorize** your new client
+5. Copy the token shown on the pin page
+6. In Codex, go to **Settings** > **Integrations**
+7. Paste the token in the access token field and click **Save Token**
+
+## Admin Setup
+
+### Adding the Plugin to Codex
+
+1. Log in to Codex as an administrator
+2. Navigate to **Settings** > **Plugins**
+3. Click **Add Plugin**
+4. Fill in the form:
+   - **Name**: `sync-anilist`
+   - **Display Name**: `AniList Sync`
+   - **Command**: `npx`
+   - **Arguments**: `-y @ashdev/codex-plugin-sync-anilist@1.9.3`
+5. Click **Save**
+6. Click **Test Connection** to verify the plugin works
+
+### Configuring OAuth (Optional)
+
+To enable OAuth login for your users:
+
+1. Go to [AniList Developer Settings](https://anilist.co/settings/developer)
+2. Click **Create New Client**
+3. Set the redirect URL to `{your-codex-url}/api/v1/user/plugins/oauth/callback`
+4. Save and copy the **Client ID**
+5. In Codex, go to **Settings** > **Plugins** > click the gear icon on AniList Sync
+6. Go to the **OAuth** tab
+7. Paste the **Client ID** (and optionally the **Client Secret**)
+8. Click **Save Changes**
+
+Without OAuth configured, users can still connect by pasting a personal access token.
+
+### npx Options
+
+| Configuration | Arguments | Description |
+|--------------|-----------|-------------|
+| Latest version | `-y @ashdev/codex-plugin-sync-anilist` | Always uses latest |
+| Pinned version | `-y @ashdev/codex-plugin-sync-anilist@1.9.3` | Recommended for production |
+| Fast startup | `-y --prefer-offline @ashdev/codex-plugin-sync-anilist@1.9.3` | Skips version check if cached |
+
+## Configuration
+
+### Codex Sync Settings
+
+These settings are managed in the **Sync Settings** section of the plugin settings modal. They control which data the Codex server sends to the plugin and are shared across all sync plugins.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Include completed series | On | Include series where all local books are read |
+| Include in-progress series | On | Include series where at least one book has been started |
+| Count partially-read books | Off | Whether partially-read books count toward the progress number |
+| Sync ratings & notes | On | Include user ratings and notes in sync |
+
+### Plugin-Specific Settings
+
+These settings are specific to the AniList plugin and appear under **Plugin Settings** in the settings modal.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Progress Unit | string | `volumes` | Whether each Codex book counts as a "volume" or "chapter" on AniList. Use "volumes" to avoid misleading "Read chapter X" activity on AniList. |
+| Auto-Pause After Days | number | `0` (disabled) | Number of days without reading activity before an in-progress series is set to Paused on AniList |
+| Auto-Drop After Days | number | `0` (disabled) | Number of days without reading activity before an in-progress series is set to Dropped on AniList |
+
+## Using the Plugin
+
+Once connected, the sync plugin works automatically:
+
+1. Go to **Settings** > **Integrations**
+2. Click **Sync Now** to trigger a manual sync
+3. View sync status including pulled/pushed/applied counts
+
+The plugin matches Codex series to AniList entries using external IDs stored in the `series_external_ids` table with the `api:anilist` source.
+
+## Sync Behavior
+
+### Sync Modes
+
+You can configure which direction data flows in **Settings** > **Integrations** > **Settings**:
+
+| Mode | Description |
+|------|-------------|
+| **Pull & Push** (default) | Import progress from AniList, then export Codex progress to AniList |
+| **Pull Only** | Import progress from AniList without writing anything back |
+| **Push Only** | Export Codex progress to AniList without importing |
+
+### How Sync Works
+
+When sync runs in **Pull & Push** mode, it executes two phases in order:
+
+1. **Pull** — Fetches your reading list from AniList, matches entries to Codex series via external IDs, and marks the corresponding books as read in Codex.
+2. **Push** — Reads your current Codex reading progress and sends it to AniList, overwriting the remote entry.
+
+### Conflict Resolution
+
+Codex uses a **highest progress wins** strategy. There is no manual conflict resolution — instead, progress can only move forward:
+
+| Scenario | Result |
+|----------|--------|
+| AniList ahead (e.g., 5 vols read) and Codex behind (3 vols read) | Pull marks books 4–5 as read in Codex. Push sends 5 to AniList. Both agree. |
+| Codex ahead (5 vols read) and AniList behind (3 vols read) | Pull tries to mark first 3 as read — already completed, skipped. Push sends 5 to AniList. **Codex wins.** |
+| Both changed differently | Pull applies remote progress first (additive only), then Push sends local state to AniList. Effectively **Codex wins** because push runs last. |
+
+Key behaviors:
+
+- **Pull is additive only** — it marks unread books as read but never un-reads a book. If you lower your chapter count on AniList, that change is ignored.
+- **Push overwrites the remote** — after pulling, Codex sends its current state to AniList, which may overwrite changes made directly on AniList.
+- **Progress is monotonic** — once a book is marked as read, sync will not undo it. Progress only moves forward.
+
+### Completed Status
+
+The plugin is conservative about marking series as "Completed" on AniList:
+
+- A series is pushed as **Completed** only when all local books are read **and** the series metadata includes a `total_book_count` that matches.
+- Otherwise, the series is pushed as **Reading** — even if all local books are read — because Codex can't be sure the library contains the full series.
+
+### Rating & Notes Sync
+
+When **Sync Ratings & Notes** is enabled in plugin settings:
+
+- **Push**: Codex ratings (1-100 scale) and notes are sent to AniList, converted to the user's chosen AniList score format (auto-detected from their profile).
+- **Pull**: AniList scores and notes are imported into Codex, but only when Codex has **no existing rating** for that series. Existing Codex ratings are never overwritten (**Codex wins**).
+- Notes without a score are skipped on pull (Codex requires a rating to store notes).
+
+### Auto-Pause & Auto-Drop
+
+You can configure automatic status changes for series you haven't read in a while:
+
+| Configuration | Behavior |
+|--------------|----------|
+| Pause=5, Drop=0 | Not read in 5 days -> Paused |
+| Pause=5, Drop=7 | Not read in 5 days -> Paused; not read in 7 days -> Dropped |
+| Pause=5, Drop=3 | Not read in 3 days -> Dropped (drop fires first since threshold is shorter) |
+| Pause=0, Drop=4 | Not read in 4 days -> Dropped (no pause step) |
+| Pause=0, Drop=0 | Disabled (default) |
+
+Key behaviors:
+
+- **Only affects in-progress series** — completed series are never auto-paused or auto-dropped.
+- **Based on last reading activity** — the timer resets every time you read any book in the series.
+- **Drop takes priority** — if both pause and drop thresholds are met, the series is dropped (not paused).
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+## Project Structure
+
+```
+plugins/sync-anilist/
+├── src/
+│   ├── index.ts          # Plugin entry point & staleness logic
+│   ├── index.test.ts     # Staleness logic tests
+│   ├── manifest.ts       # Plugin manifest
+│   ├── anilist.ts        # AniList API client & utility functions
+│   └── anilist.test.ts   # API client & utility tests
+├── dist/
+│   └── index.js          # Built bundle (excluded from git)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## License
+
+MIT