trakt-tools 1.9.3 → 1.10.0

package/README.md

@@ -25,6 +25,7 @@ Or set `TRAKT_CLI_PATH` environment variable, or configure `cliPath` in plugin s
 | `cliPath` | Path to trakt-cli binary (auto-detected on PATH) |
 | `clientId` | Trakt API client ID (from https://trakt.tv/oauth/applications) |
 | `clientSecret` | Trakt API client secret |
+| `syncEnabled` | Register the opt-in `trakt_sync` tool (default `false`) |
 
 ## Available Tools
 
@@ -36,6 +37,7 @@ Or set `TRAKT_CLI_PATH` environment variable, or configure `cliPath` in plugin s
 | `trakt_watchlist` | View watchlist |
 | `trakt_progress` | Show watch progress for TV shows |
 | `trakt_auth` | Set up Trakt.tv authentication |
+| `trakt_sync` | Opt-in: import from streaming services (only when `syncEnabled`) |
 
 ## License
 

package/dist/index.js

@@ -29,6 +29,16 @@ function whichBinary(name) {
 }
 
 // src/index.ts
+var SYNC_TOOL = {
+  name: "trakt_sync",
+  command: "sync",
+  description: "Import watched items from streaming services (Apple TV Up Next, Netflix, HBO Max, Paramount+) into Trakt history, using the sync config at ~/.config/trakt-cli/sync.yaml. Skips denied titles, items older than the configured window, and anything already in history. Shows not yet in history and all movies are returned in pending_review and NOT written; ask the user before approving any. Use dry_run first to preview.",
+  parameters: Type.Object({
+    dry_run: Type.Optional(
+      Type.Boolean({ description: "Preview what would be added without writing (default false)" })
+    )
+  })
+};
 var TOOLS = [
   {
     name: "trakt_search",
@@ -262,12 +272,13 @@ var index_default = definePluginEntry({
   description: "Track movies and TV shows using trakt.tv",
   register(api) {
     const config = api.pluginConfig;
+    const tools = config?.syncEnabled ? [...TOOLS, SYNC_TOOL] : TOOLS;
     let cliPath;
     try {
       cliPath = resolveCliPath(config);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      for (const tool of TOOLS) {
+      for (const tool of tools) {
         api.registerTool({
           name: tool.name,
           label: tool.name,
@@ -282,7 +293,7 @@ var index_default = definePluginEntry({
       }
       return;
     }
-    for (const tool of TOOLS) {
+    for (const tool of tools) {
       api.registerTool({
         name: tool.name,
         label: tool.name,
@@ -304,7 +315,8 @@ var index_default = definePluginEntry({
           try {
             const args = buildCliArgs(tool.command, tool.subcommand, params, config);
             const { stdout } = await runCli(cliPath, args, {
-              timeout: 12e4,
+              // sync walks several services plus per-show history lookups.
+              timeout: tool.command === "sync" ? 6e5 : 12e4,
               maxBuffer: 4 * 1024 * 1024
             });
             let result;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "trakt-tools",
   "name": "Trakt",
   "description": "Track movies and TV shows using trakt.tv",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "configSchema": {
     "type": "object",
     "properties": {
@@ -18,6 +18,11 @@
       "clientSecret": {
         "type": "string",
         "description": "Trakt API client secret"
+      },
+      "syncEnabled": {
+        "type": "boolean",
+        "description": "Opt in to the trakt_sync tool (imports from streaming services). Off by default.",
+        "default": false
       }
     },
     "additionalProperties": false
@@ -37,6 +42,10 @@
       "label": "Client Secret",
       "help": "Trakt API client secret from https://trakt.tv/oauth/applications",
       "sensitive": true
+    },
+    "syncEnabled": {
+      "label": "Enable streaming sync",
+      "help": "Registers trakt_sync. Also requires ~/.config/trakt-cli/sync.yaml with enabled: true; see `trakt-cli sync --help`."
     }
   },
   "contracts": {
@@ -50,7 +59,8 @@
       "trakt_watchlist_remove",
       "trakt_calendar",
       "trakt_progress",
-      "trakt_auth"
+      "trakt_auth",
+      "trakt_sync"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trakt-tools",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "description": "OpenClaw plugin for Trakt.tv - track movies and TV shows",
   "type": "module",
   "openclaw": {

package/skills/trakt/SKILL.md

@@ -66,13 +66,52 @@ trakt-cli history add "Pluribus" --json
 trakt-cli history add "The Sopranos" "The Wire" --json
 trakt-cli history add --type movie "The Godfather" --json
 trakt-cli history add --watched-at 2025-06-15 "Dark" --json
+trakt-cli history add --rewatch "Severance" --json
 ```
 
 - Searches by name, prefers exact title matches
+- For shows, only episodes that have aired **and** are not yet in your
+  history are added: catching up on a partially watched show never creates
+  duplicate plays, and a fully caught-up show adds nothing
+- Season 0 (specials) is never marked watched, so this agrees with what
+  `progress` reports
+- `--rewatch` deliberately records another play for every aired episode,
+  including ones already watched. Use it only when the user actually means
+  a rewatch; without it a finished show is a no-op
+- Repeated titles (or aliases resolving to the same show) are handled once
+  per call — later matches add nothing and come back with a
+  `duplicate_of` field in `queries` (text output: `duplicate of "<query>"`)
+- Every requested title gets a `queries` entry in JSON output, show or
+  movie alike (`query`, `type`): matched titles carry `matched` (shows
+  also `new_episodes` / `already_watched_episodes`), titles that match
+  nothing have no `matched` field, and a title whose Trakt search failed
+  carries `search_error` — so a failed lookup is distinguishable from
+  "not found"
 - `--type show` (default) or `--type movie`
 - `--watched-at`: RFC3339 or YYYY-MM-DD (defaults to now)
 - Accepts multiple titles in one call
-- JSON output: `{ "added_episodes": N, "added_movies": N, "not_found_movies": N, "not_found_shows": N }`
+- JSON output: `{ "added_episodes": N, "added_movies": N, "not_found_movies": N, "not_found_shows": N, "not_found_seasons": N, "not_found_episodes": N, "queries": [{ "query", "type", "matched", "new_episodes", "already_watched_episodes", "duplicate_of", "search_error" }] }`
+- A show whose pending-episode lookup fails is skipped and reported in an
+  additive `skipped_shows` array; if every lookup fails, nothing is written
+  and the command exits 1 with `{"error": "pending episode lookup failed", "skipped_shows": [...]}`
+- On a Trakt rate limit (429) the command stops immediately, syncs nothing,
+  and exits 1 with `{"error": ..., "retry_after": N}` (marker also on
+  stderr) — wait out `retry_after` before calling any trakt tool again
+
+### Streaming Sync (opt-in)
+
+Only if the user has set up `~/.config/trakt-cli/sync.yaml` (otherwise `sync` reports `"enabled": false` and does nothing).
+
+```bash
+trakt-cli sync --dry-run --json
+trakt-cli sync --json
+trakt-cli sync approve "Title"
+trakt-cli sync deny "Title"
+```
+
+- JSON output: `{ "enabled", "sources": {name: {items, error}}, "planned", "pending_review", "skipped_denied", "skipped_old", "already_watched", "unresolved", "added" }`
+- Confirmed episodes of shows already in history sync automatically; new shows, all movies, and implied episodes (e.g. skipped ones before an Up Next pointer) land in `pending_review` and are NOT written. Ask the user before running `sync approve` for any title; never approve on their behalf
+- Use `sync deny` for titles the user says belong to someone else
 
 ### Search
 

package/src/index.ts

@@ -16,6 +16,8 @@ interface PluginConfig {
 	cliPath?: string;
 	clientId?: string;
 	clientSecret?: string;
+	/** Opt-in: register trakt_sync. Off by default so existing installs are unchanged. */
+	syncEnabled?: boolean;
 }
 
 interface ToolDef {
@@ -26,6 +28,20 @@ interface ToolDef {
 	parameters: ReturnType<typeof Type.Object>;
 }
 
+// Opt-in streaming sync tool. Registered only when pluginConfig.syncEnabled is
+// true; the CLI itself also stays inert without ~/.config/trakt-cli/sync.yaml.
+const SYNC_TOOL: ToolDef = {
+	name: 'trakt_sync',
+	command: 'sync',
+	description:
+		'Import watched items from streaming services (Apple TV Up Next, Netflix, HBO Max, Paramount+) into Trakt history, using the sync config at ~/.config/trakt-cli/sync.yaml. Skips denied titles, items older than the configured window, and anything already in history. Shows not yet in history and all movies are returned in pending_review and NOT written; ask the user before approving any. Use dry_run first to preview.',
+	parameters: Type.Object({
+		dry_run: Type.Optional(
+			Type.Boolean({ description: 'Preview what would be added without writing (default false)' })
+		),
+	}),
+};
+
 // Tool metadata — each maps to a CLI subcommand
 const TOOLS: ToolDef[] = [
 	{
@@ -306,6 +322,7 @@ export default definePluginEntry({
 
 	register(api) {
 		const config = api.pluginConfig as PluginConfig | undefined;
+		const tools = config?.syncEnabled ? [...TOOLS, SYNC_TOOL] : TOOLS;
 
 		let cliPath: string;
 		try {
@@ -314,7 +331,7 @@ export default definePluginEntry({
 			// Defer error to tool execution time — plugin still loads
 			const errorMessage = error instanceof Error ? error.message : String(error);
 
-			for (const tool of TOOLS) {
+			for (const tool of tools) {
 				api.registerTool({
 					name: tool.name,
 					label: tool.name,
@@ -330,7 +347,7 @@ export default definePluginEntry({
 			return;
 		}
 
-		for (const tool of TOOLS) {
+		for (const tool of tools) {
 			api.registerTool({
 				name: tool.name,
 				label: tool.name,
@@ -362,7 +379,8 @@ export default definePluginEntry({
 						// Follow-up: parallelize GetShowProgress loop or add a --filter
 						// flag so per-show progress checks don't hammer 50 API calls.
 						const { stdout } = await runCli(cliPath, args, {
-							timeout: 120_000,
+							// sync walks several services plus per-show history lookups.
+							timeout: tool.command === 'sync' ? 600_000 : 120_000,
 							maxBuffer: 4 * 1024 * 1024,
 						});