[Trakt Manager] Add AI tools that update the account and read ratings

[princeberenger]

Description

Adds write and ratings AI tools on top of the read-only set from #31154. Raycast AI can add/remove watchlist items, mark movies/shows/episodes watched, remove history, and rate or unrate a title. Every write shows a confirmation that names the item Trakt holds for that ID.

Writes report Trakt's added / existing / deleted / not_found counts: HTTP 201 is not treated as a write when nothing was stored. Lookups refuse overlapping movie/show IDs without a type, and a year in the query (Dune 1989) is parsed as a year without breaking titles like Blade Runner 2049.

Lists stay out of this PR.

Screencast

N/A — AI tools only; existing grid commands are unchanged.

Checklist

• I read the extension guidelines
• I read the documentation about publishing
• I ran npm run build and tested this distribution build in Raycast
• I checked that files in the assets folder are used by the extension itself
• I checked that assets used by the README are placed outside of the metadata folder

[raycastbot]

Thank you for your contribution! 🎉

🔔 @thesobercoder @vishalbalaji3 @burhanrashid52 you might want to have a look.

You can use this guide to learn how to check out the Pull Request locally in order to test it.

📋 Quick checkout commands

BRANCH="ext/trakt-manager"
FORK_URL="https://github.com/princeberenger/raycast-extensions.git"
EXTENSION_NAME="trakt-manager"
REPO_NAME="raycast-extensions"

git clone -n --depth=1 --filter=tree:0 -b $BRANCH $FORK_URL
cd $REPO_NAME
git sparse-checkout set --no-cone "extensions/$EXTENSION_NAME"
git checkout
cd "extensions/$EXTENSION_NAME"
npm install && npm run dev

We're currently experiencing a high volume of incoming requests. As a result, the initial review may take up to 15 business days.

[greptile-apps]

Confidence Score: 4/5

The PR is not ready to merge because the changelog breaks an explicit repository rule.

Findings

1.  get-ratings can return a season rating, and package.json still says remove-rating supports seasons. This changed input rejects season , so the assistant has no way to remove that rating even though removeMediaRating already supports a seasons body. Add a safe season confirmation path, or stop advertising season removal. ▶
2.  Keep the merge-date placeholder ▶

Fix with agent prompt

### Issue 1
extensions/trakt-manager/src/tools/remove-rating.ts:9-12
`get-ratings` can return a season rating, and `package.json` still says `remove-rating` supports seasons. This changed input rejects `season`, so the assistant has no way to remove that rating even though `removeMediaRating` already supports a `seasons` body. Add a safe season confirmation path, or stop advertising season removal.

### Issue 2
extensions/trakt-manager/CHANGELOG.md:3
This title must keep the `{PR_MERGE_DATE}` placeholder. The fixed date stops the release flow from filling in the real merge date. Change it back to `## [Update] - {PR_MERGE_DATE}`.

```suggestion
## [Update] - {PR_MERGE_DATE}
```

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Raycast AI can now read Trakt ratings and change watchlists, watch history, and ratings through confirmed write tools. Lookup logic also understands year-based queries and reports Trakt’s actual write counts instead of treating every successful HTTP response as a stored change.

• Adds AI tools for ratings, watchlist updates, watched history, and rating changes.
• Confirms the Trakt item behind each ID before making a write.
• Adds exact, related, year-aware, and score-aware lookup results.
• Updates AI instructions, API contracts, schemas, tests, and documentation.

_{Reviews (6) · Last reviewed commit: "Update CHANGELOG.md"}

[pernielsentikaer]

Hi @princeberenger 👋

Thanks for the write tools — naming the item from Trakt's own ID lookup in the confirmation dialog is a nice touch 💪

I found this while reviewing:

Season support doesn't work end to end. describeMedia() in src/tools/resolve-media.ts resolves items with Trakt's /search/trakt/:id?type=<type>, and that endpoint doesn't return seasons. Its documented type values are movie, show, episode, person, list, and ?type=season is ignored — I get the same response with and without it. So describeMedia("season", id) either receives an unrelated show/movie that shares the numeric ID or an empty array, and always throws before the write happens.

That makes rate-media and remove-rating fail for type: "season" (the confirmation never opens), and get-ratings with type: "seasons" plus a traktId always answer "… is not a season".

Episode writes sidestep this by resolving the episode from showTraktId + seasonNumber + episodeNumber. Could you do something similar for seasons — for example require the parent show ID and season number, or drop season from the write tools and the season-ID path in get-ratings — so a season is never resolved through /search/trakt/:id?

One smaller thing while you're in here: the scan termination in get-watchlist and get-ratings compares the page length against the requested limit (250). Trakt's pagination docs say the API clamps limit to an endpoint-specific maximum and that clients should use the X-Pagination-Limit header, which withPagination already exposes. Using the header would keep the "confirmed absent" answers honest if an endpoint's max is below 250.

---

I’ll convert this PR into a draft after submitting this review. Please press Ready for review when it’s ready and we’ll have a look 😊

[greptile-apps]

get-ratings can return a season rating, and package.json still says remove-rating supports seasons. This changed input rejects season, so the assistant has no way to remove that rating even though removeMediaRating already supports a seasons body. Add a safe season confirmation path, or stop advertising season removal.

Prompt To Fix With AI

This is a comment left during a code review.
Path: extensions/trakt-manager/src/tools/remove-rating.ts
Line: 9-12

Comment:
`get-ratings` can return a season rating, and `package.json` still says `remove-rating` supports seasons. This changed input rejects `season`, so the assistant has no way to remove that rating even though `removeMediaRating` already supports a `seasons` body. Add a safe season confirmation path, or stop advertising season removal.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[pernielsentikaer]

Looks good to me, approved 🔥

[github-actions]

Published to the Raycast Store:
https://raycast.com/thesobercoder/trakt-manager

[raycastbot]

🎉 🎉 🎉

We've rewarded your Raycast account with some credits. You will soon be able to exchange them for some swag.

[greptile-apps]

This title must keep the {PR_MERGE_DATE} placeholder. The fixed date stops the release flow from filling in the real merge date. Change it back to ## [Update] - {PR_MERGE_DATE}.

Suggested change

	## [Update] - 2026-09-19
	## [Update] - {PR_MERGE_DATE}

Rule Used: What: Changelog entries must use {PR_MERGE_DATE} placeholder in titles, be placed at the top of the file, and maintain descending version order. Why: Standardized placeholders and consistent ordering ensure changelogs are maintainable and merge da... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: extensions/trakt-manager/CHANGELOG.md
Line: 3

Comment:
This title must keep the `{PR_MERGE_DATE}` placeholder. The fixed date stops the release flow from filling in the real merge date. Change it back to `## [Update] - {PR_MERGE_DATE}`.

```suggestion
## [Update] - {PR_MERGE_DATE}
```

**Rule Used:** What: Changelog entries must use `{PR_MERGE_DATE}` placeholder in titles, be placed at the top of the file, and maintain descending version order.  Why: Standardized placeholders and consistent ordering ensure changelogs are maintainable and merge da... ([source](https://app.greptile.com/raycast/-/custom-context?memory=c2214c11-df56-490a-b1c0-09a385df481a))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!