trakt-readonly

# Trakt (OpenClaw) — Read-only

Use this skill to query Trakt.tv user data via the API (read-only). Default to **read-only**; do not implement write operations unless the user explicitly asks for OAuth support.

## Requirements

- Env vars:
  - `TRAKT_CLIENT_ID` (Trakt API Client ID)
  - `TRAKT_USERNAME` (Trakt username or user slug)
  - `TRAKT_ACCESS_TOKEN` (OAuth Bearer token, required for playback)
  - `TRAKT_CLIENT_SECRET` (required for device token exchange)
- Binaries: `curl`, `jq`

## Commands (script)

Use `{baseDir}/scripts/trakt-api.sh`.

- `watching` — current movie/episode being watched
- `recent [limit]` — recent episode history (default 10, max 100)
- `watched-shows` — recently watched shows list
- `profile` — user profile
- `stats` — user stats
- `playback <type> <start_at> <end_at>` — playback progress (OAuth required)

Examples:

```
TRAKT_CLIENT_ID=xxx TRAKT_USERNAME=user {baseDir}/scripts/trakt-api.sh watching
TRAKT_CLIENT_ID=xxx TRAKT_USERNAME=user {baseDir}/scripts/trakt-api.sh recent 5
TRAKT_CLIENT_ID=xxx TRAKT_ACCESS_TOKEN=yyy {baseDir}/scripts/trakt-api.sh playback movies 2016-06-01T00:00:00.000Z 2016-07-01T23:59:59.000Z
TRAKT_CLIENT_ID=xxx {baseDir}/scripts/trakt-api.sh device-code
TRAKT_CLIENT_ID=xxx TRAKT_CLIENT_SECRET=zzz {baseDir}/scripts/trakt-api.sh device-token <device_code>
```

## Guardrails

- Never log or expose API keys or access tokens.
- Only call `https://api.trakt.tv`.
- Read-only endpoints only; playback uses OAuth token read access.
- Device OAuth flow is read-only; do not request write scopes.
- Validate `recent` limit is numeric and between 1–100.
- Handle empty/404 responses gracefully (public profile required).

## References

- Read `references/trakt-api.md` for endpoints, headers, and auth notes.

# Trakt Read-only Skill

A secure OpenClaw skill for querying Trakt.tv user data (read-only): current watching, recent episode history, watched shows, stats, and profile.

## Features

- **Watching**: Current movie or episode
- **Recent Episodes**: Recent episode history
- **Watched Shows**: Recently watched shows list
- **Stats**: User stats
- **Profile**: User profile info

## Prerequisites

- `jq` (for JSON parsing)
- `curl`

Install on Ubuntu/Debian:

```
sudo apt-get update && sudo apt-get install -y jq curl
```

## Setup

### Get a Trakt Client ID

1. Go to https://trakt.tv/oauth/applications
2. Click **New Application**
3. Fill in the form (any name). For redirect URI, you can use `urn:ietf:wg:oauth:2.0:oob`.
4. Save and copy the **Client ID**

### Configure OpenClaw

Add to `~/.openclaw/openclaw.json`:

```json5
{
  skills: {
    entries: {
      "trakt-readonly": {
        enabled: true,
        apiKey: "YOUR_TRAKT_CLIENT_ID", // convenience for TRAKT_CLIENT_ID
        env: {
          TRAKT_CLIENT_ID: "YOUR_TRAKT_CLIENT_ID",
          TRAKT_USERNAME: "YOUR_TRAKT_USERNAME",
          TRAKT_ACCESS_TOKEN: "YOUR_TRAKT_OAUTH_TOKEN", // required for playback
          TRAKT_CLIENT_SECRET: "YOUR_TRAKT_CLIENT_SECRET" // required for device token exchange
        }
      }
    }
  }
}
```

**Note:** OpenClaw injects these env vars at runtime (not globally). Never commit secrets to git. If you run the agent in a sandboxed session, set env vars under `agents.defaults.sandbox.docker.env`.

## Usage

### Read-only Commands (No OAuth Required)

**Read-only endpoints require only `TRAKT_CLIENT_ID` + `TRAKT_USERNAME`.**

| Command | Description | Example |
|---------|-------------|---------|
| `watching` | Current watching | `/trakt-readonly watching` |
| `recent [limit]` | Recent episodes | `/trakt-readonly recent 5` |
| `watched-shows` | Watched shows list | `/trakt-readonly watched-shows` |
| `stats` | User stats | `/trakt-readonly stats` |
| `profile` | User profile |...