reading-list

# reading-list skill

reading-list is a personal read-it-later app. It fetches article content using Mozilla Readability and stores clean, extracted text in SQLite. Articles can be tagged, filtered by status, searched by full text, and delivered as a daily email digest.

## Environment

```
PORT=3000
DB_PATH=./data/reading-list.db
SESSION_SECRET=<random string>
AUTH_PASSWORD=<bcrypt hash>    # generate: node -e "require('bcryptjs').hash('mypassword',10).then(console.log)"
FETCH_TIMEOUT_MS=10000
# Optional: digest email
DIGEST_SMTP_HOST=smtp.example.com
DIGEST_SMTP_PORT=587
DIGEST_SMTP_USER=you@example.com
DIGEST_SMTP_PASS=<password>
DIGEST_FROM=reading-list@example.com
NODE_ENV=production
```

## Starting

```bash
pnpm install
pnpm dev          # hot reload
pnpm build && pnpm start
docker compose up  # production
```

## Saving articles

```bash
# Save a URL (triggers async fetch + extraction)
curl -X POST http://localhost:3000/api/articles \
  -H 'Content-Type: application/json' \
  -b 'session=...' \
  -d '{"url": "https://blog.golang.org/structured-concurrency"}'

# Poll until status != 'pending'
curl http://localhost:3000/api/articles/:id
```

Extraction is asynchronous. The article starts with `status='pending'` and transitions to `status='unread'` when complete or `status='failed'` if the fetch fails.

## Listing and filtering articles

```bash
# All articles
curl http://localhost:3000/api/articles

# Unread only
curl "http://localhost:3000/api/articles?status=unread"

# Filter by tag
curl "http://localhost:3000/api/articles?tag=golang"

# Unread + sorted by newest
curl "http://localhost:3000/api/articles?status=unread&sort=created_at&order=desc"

# Unread, not archived
curl "http://localhost:3000/api/articles?status=unread&archived=0"

# Full-text search
curl "http://localhost:3000/api/articles?q=goroutines+concurrency"
```

## Updating article state

```bash
# Mark as read
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"status": "read"}'

# Update read progress (0-100)
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"read_pct": 65}'

# Star an article
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"starred": 1}'

# Archive
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"archived": 1}'

# Unarchive
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"archived": 0}'
```

## Retrying failed articles

```bash
curl -X POST http://localhost:3000/api/articles/:id/refetch
```

## Deleting articles

```bash
curl -X DELETE http://localhost:3000/api/articles/:id
```

## Tags

```bash
# List tags
curl http://localhost:3000/api/tags

# Create a tag
curl -X POST http://localhost:3000/api/tags \
  -H 'Content-Type: application/json' \
  -d '{"name": "golang", "color": "#00ACD7"}'

# Rename a tag
curl -X PATCH http://localhost:3000/api/tags/:id \
  -H 'Content-Type: application/json' \
  -d '{"name": "go"}'

# Delete a tag (removes from all articles)
curl -X DELETE http://localhost:3000/api/tags/:id

# Add tag to article
curl -X POST http://localhost:3000/api/articles/:id/tags \
  -H 'Content-Type: application/json' \
  -d '{"tagId": "tag_xyz"}'

# Remove tag from article
curl -X DELETE http://localhost:3000/api/articles/:articleId/tags/:tagId
```

## Full-text search

```bash
# Search all fields (title, excerpt, content)
curl "http://localhost:3000/api/search?q=goroutines"

# Search returns highlighted snippets
curl "http://localhost:3000/api/search?q=structured+concurrency"
```

The search endpoint uses SQLite FTS5. Queries support:
- Simple words: `concurrency`
- Phrases: `"structured concurrency"` (URL-encode as `%22structured+concurrency%22`)
- Prefix: `gorout*`

## Import bookmarks

```bash
# Import Netscape HTML (browser export)
curl -X POST http://localhost:3000/api/import \
  -F 'file=@bookmarks.html'

# Import JSON array of URLs
curl -X POST http://localhost:3000/api/import \
  -H 'Content-Type: application/json' \
  -d '[
    {"url": "https://example.com/article1", "title": "Article 1"},
    {"url": "https://example.com/article2"}
  ]'
```

All imported articles are queued for async extraction.

## Export

```bash
# Export all articles as JSON
curl http://localhost:3000/api/export > reading-list-backup.json

# Export with article content included
curl "http://localhost:3000/api/export?includeContent=1" > full-backup.json
```

## Authentication

reading-list uses a single-password auth model. To get a session:

```bash
# Get CSRF token first
CSRF=$(curl -s http://localhost:3000/api/csrf | jq -r '.token')

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -H "X-CSRF-Token: $CSRF" \
  -c cookies.txt \
  -d '{"password": "mypassword"}'

# Use session cookie in subsequent requests
curl http://localhost:3000/api/articles -b cookies.txt
```

## Bookmarklet

The bookmarklet JavaScript is available from the settings page at `GET /api/settings/bookmarklet`. Paste it as the URL of a browser bookmark to enable one-click saving.