feat: initial open-source project structure

Agent Skill for searching and downloading torrents via TorrentClaw. Includes SKILL.md with OpenClaw metadata, bash scripts for torrent client detection, CONTRIBUTING.md, CHANGELOG.md, CI/CD with GitHub Actions (shellcheck + conventional commits), lefthook git hooks, Makefile, and .editorconfig.
2026-02-13 18:40:25 +01:00 · 2026-02-13 18:40:25 +01:00 · 98c550feb0
commit 98c550feb0
parent b0c4fc2e21
14 changed files with 1096 additions and 0 deletions
--- a/references/api-reference.md
+++ b/references/api-reference.md
@ -0,0 +1,165 @@
+# TorrentClaw API Reference
+
+## Search Response Schema
+
+```json
+{
+  "total": 42,
+  "page": 1,
+  "pageSize": 20,
+  "results": [
+    {
+      "id": 1,
+      "imdbId": "tt1375666",
+      "tmdbId": "27205",
+      "contentType": "movie",
+      "title": "Inception",
+      "titleOriginal": "Inception",
+      "year": 2010,
+      "overview": "A thief who steals corporate secrets...",
+      "posterUrl": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
+      "genres": ["Action", "Science Fiction", "Adventure"],
+      "ratingImdb": "8.8",
+      "ratingTmdb": "8.4",
+      "contentUrl": "/movies/inception-2010-1",
+      "hasTorrents": true,
+      "maxSeeders": 847,
+      "torrents": [
+        {
+          "infoHash": "aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
+          "magnetUrl": "magnet:?xt=urn:btih:aaf1e71c...&dn=Inception+2010+1080p&tr=udp://tracker.opentrackr.org:1337/announce&tr=...",
+          "torrentUrl": "/api/v1/torrent/aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
+          "quality": "1080p",
+          "codec": "x265",
+          "sourceType": "BluRay",
+          "sizeBytes": "2147483648",
+          "seeders": 847,
+          "leechers": 23,
+          "source": "yts",
+          "qualityScore": 85,
+          "scrapedAt": "2026-02-13T10:30:00Z",
+          "uploadedAt": "2024-03-15T12:00:00Z",
+          "languages": ["en"],
+          "audioCodec": "AAC",
+          "hdrType": null,
+          "releaseGroup": "YTS",
+          "season": null,
+          "episode": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Allowed Genres
+
+Action, Adventure, Animation, Comedy, Crime, Documentary, Drama, Family, Fantasy, History, Horror, Music, Mystery, Romance, Science Fiction, Thriller, War, Western, Reality, Talk, News, Soap, Kids, TV Movie, Action & Adventure, Sci-Fi & Fantasy, War & Politics
+
+## API Key Authentication
+
+**Request Headers:**
+```
+Authorization: Bearer tc_live_xxxxx
+```
+
+Or via query parameter:
+```
+?api_key=tc_live_xxxxx
+```
+
+**Response Headers:**
+```
+X-RateLimit-Tier: free
+X-RateLimit-Remaining: 115
+X-Api-Key-Id: tc_live_abc1
+```
+
+**Rate Limit Tiers:**
+- **Anonymous**: 30 req/min (no key)
+- **Free**: 120 req/min, 1,000 req/day (with API key)
+- **Pro**: 1,000 req/min, 10,000 req/day (with API key)
+- **Internal**: Unlimited (with API key)
+
+## New Query Parameters
+
+**Season & Episode Filtering:**
+- `season=1` — Filter by TV show season number
+- `episode=5` — Filter by episode number
+- Note: Also supports parsing from query text (e.g., `q=breaking+bad+S01E05`)
+
+**Localization:**
+- `locale=es` — Get titles in Spanish (also: fr, de, pt, it, ja, ko, zh, ru, ar)
+
+## New Response Fields
+
+**Content fields:**
+- `hasTorrents` (boolean) — Whether content has associated torrents
+- `maxSeeders` (number) — Highest seeder count across all torrents for this content
+
+**Torrent fields:**
+- `scrapedAt` (string, ISO 8601) — Timestamp of last tracker scrape for real-time seeder/leecher counts
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Invalid parameters (missing q, bad genre, etc.) |
+| 404 | Torrent file not found (torrent endpoint only) |
+| 429 | Rate limited |
+| 500 | Internal server error |
+
+## Rate Limits
+
+| Endpoint | Limit |
+|----------|-------|
+| /api/v1/search | 30/min |
+| /api/v1/autocomplete | 60/min |
+| /api/v1/stats | 10/min |
+| /api/v1/torrent | 20/min |
+
+## Torrent Download Integration
+
+### Using magnetUrl with Transmission
+
+```bash
+# Search and add best torrent to Transmission
+RESULT=$(curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=inception&type=movie&sort=seeders&limit=1")
+MAGNET=$(echo "$RESULT" | jq -r '.results[0].torrents[0].magnetUrl')
+transmission-remote -a "$MAGNET"
+```
+
+### Using magnetUrl with aria2
+
+```bash
+RESULT=$(curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=inception&sort=seeders&limit=1")
+MAGNET=$(echo "$RESULT" | jq -r '.results[0].torrents[0].magnetUrl')
+aria2c "$MAGNET" --dir=~/Downloads
+```
+
+### Downloading .torrent files
+
+```bash
+# Get info hash from search result
+INFO_HASH=$(echo "$RESULT" | jq -r '.results[0].torrents[0].infoHash')
+
+# Download .torrent file
+curl -o "movie.torrent" "https://torrentclaw.com/api/v1/torrent/$INFO_HASH"
+
+# The file includes a descriptive filename in Content-Disposition header:
+# TorrentClaw.com-Inception-1080p-EN.torrent
+```
+
+## Data Sources
+
+| Source | Content | Notes |
+|--------|---------|-------|
+| YTS | Movies | High quality, IMDb IDs |
+| EZTV | TV Shows | Episode torrents, IMDb IDs |
+| Knaben | Mixed | Meta-search aggregator |
+| Prowlarr | Mixed | Indexer aggregator |
+| Bitmagnet | Mixed | DHT discovery |
+| Torrentio | Mixed | Stremio ecosystem |
+| DonTorrent | Mixed | Spanish content |
+| Torrents.csv | Mixed | Open dataset |
+| TMDB | Metadata | Posters, genres, translations |