feat: integrate AIOratings as a poster service

[nippe3r]

Add AIOratings alongside RPDB and Top Poster as a selectable poster service. AIOratings supports custom poster profiles with configurable rating overlays via imdb and tmdb IDs (with series→tv conversion and tvdb fallback through AnimeDatabase).

Summary by CodeRabbit

Release Notes

• New Features
  • Added AIOratings as a new poster service provider option. Users can now select AIOratings from the poster service dropdown and configure their API credentials via new AIOratings API Key and Profile ID fields in settings. This expands available poster source options alongside existing providers.

[coderabbitai]

Walkthrough

This PR introduces support for a new AIOratings poster service across the codebase, extending database schemas, implementing the service backend with validation and caching, updating configuration surfaces, and providing frontend UI and server API routes for poster discovery.

Changes

Cohort / File(s)	Summary
Schema & Type Definitions packages/core/src/db/schemas.ts	Added aioratingsApiKey and aioratingsProfileId optional properties to UserDataSchema; extended posterService enum to include 'aioratings'; introduced AIOratingsIsValidResponse validation schema.
AIOratings Service Core packages/core/src/utils/aioratings.ts, packages/core/src/main.ts	Implemented new AIOratings class with API key validation, poster URL retrieval with caching (24-hour TTL), and ID type parsing; integrated AIOratings selection into poster resolution logic with profileId handling and URL construction for redirects.
Configuration & Validation packages/core/src/config.ts, packages/core/src/utils/constants.ts, packages/core/src/utils/env.ts	Added AIOratings API key validation in config flow with error suppression support; extended TOP_LEVEL_OPTION_DETAILS with aioratingsApiKey and aioratingsProfileId entries; introduced AIORATINGS_API_URL environment variable with default endpoint.
Module Exports packages/core/src/utils/index.ts	Added re-export of aioratings module to utils public API surface.
Frontend UI packages/frontend/src/components/menu/services.tsx	Added AIOratings option to Poster Service selector; introduced AIOratings API Key and Profile ID input fields with conditional rendering; extended credential validation to include aioratingsApiKey in credential checking logic.
Server API Routes packages/server/src/app.ts, packages/server/src/routes/api/aioratings.ts, packages/server/src/routes/api/index.ts	Mounted new /aioratings API route; implemented GET handler with input validation, AIOratings instantiation, poster URL resolution, 301 redirect on success, and standardised error responses; exported aioratingsApi module from routes index.

Sequence Diagram

sequenceDiagram
    actor User
    participant Frontend
    participant Server as Server API<br/>/aioratings
    participant AIOratings as AIOratings<br/>Service
    participant Cache as Cache Layer
    participant AIOratingsAPI as AIOratings<br/>External API

    User->>Frontend: Request poster for<br/>type & id
    Frontend->>Server: GET /api/v1/aioratings<br/>(id, type, apiKey)
    Server->>Server: Validate input params
    Server->>AIOratings: new AIOratings(apiKey,<br/>profileId)
    Server->>AIOratings: getPosterUrl(type, id)
    AIOratings->>Cache: Check cached result<br/>for key
    alt Cache Hit
        Cache-->>AIOratings: Return cached URL
    else Cache Miss
        AIOratings->>AIOratings: Parse id to<br/>idType & idValue
        AIOratings->>AIOratingsAPI: HEAD /api/{apiKey}/...<br/>{idType}/{profileId}/{idValue}.jpg
        AIOratingsAPI-->>AIOratings: 200 OK / 404 Not Found
        AIOratings->>Cache: Store result<br/>(24h TTL)
    end
    AIOratings-->>Server: Return poster URL<br/>or null
    alt Poster Found
        Server->>User: HTTP 301 Redirect<br/>to poster URL
    else Poster Not Found
        Server->>User: HTTP 404 with<br/>error response
    end

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related PRs

• feat(metadata): implement top poster api option #583: Adds top-poster service with nearly identical plumbing modifications (schema, main poster resolution, utils exports, config/constants, frontend selector, and server routes).

Suggested Reviewers

• Viren070

Poem

🐰 Hop hop, the AIOratings hops in,
With cached posters and validation spin,
Frontend forms dance, the server routes gleam,
Another poster service joins the dream! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarises the main change—adding AIOratings as a new poster service option—which is the primary objective reflected throughout the changeset.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/core/src/main.ts (1)

972-1038: Respect AIORATINGS_API_URL overrides when recognising existing posters.
Using a hard‑coded host can miss instances that override the base URL, leading to unnecessary re‑wrapping.

♻️ Suggested update

   private async applyPosterModifications(
     items: MetaPreview[],
     type: string,
     applyPosterService: boolean = true
   ): Promise<MetaPreview[]> {
+    const aioratingsBase = Env.AIORATINGS_API_URL.replace(/\/$/, '');
     const posterService = applyPosterService
       ? this.userData.posterService ||
         (this.userData.rpdbApiKey ? 'rpdb' : undefined)
       : undefined;
@@
-          if (
-            posterUrl.includes('api.ratingposterdb.com') ||
-            posterUrl.includes('api.top-streaming.stream') ||
-            posterUrl.includes('apiv2.aioratings.com')
-          ) {
+          if (
+            posterUrl.includes('api.ratingposterdb.com') ||
+            posterUrl.includes('api.top-streaming.stream') ||
+            posterUrl.includes(aioratingsBase)
+          ) {

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}