refactor: add series contract alignment guidance and update type checks for anime and manga (#269)

* refactor: add series contract alignment guidance and update type checks for anime and manga

* refactor: update type handling for series and transform tests to use string literals

* feat: enhance seriesTransform to support manga type detection

Author: wax911

docs/series-schema-alignment.md

@@ -0,0 +1,43 @@
+# Series contract alignment guidance
+
+This note documents the current gaps between the TypeScript contract exposed by `src/series/types.ts` in **on-the-edge** and the Python data schemas in `media/data/schemas.py` within the `AniTrend/anitrend` repository. Use it as a checklist when updating the Python layer so that both sides remain type-safe and compatible.
+
+## 1. Nullability and required fields
+- Treat every property that is declared without `| null` in TypeScript as required in Python.
+  - `SeriesId.shoboi` is **required** (`number`), whereas the Python schema currently makes it optional.
+  - `SeriesScheduleEpisode` fields such as `name`, `overview`, `airDate`, `episodeNumber`, `productionCode`, `runtime`, `seasonNumber`, and `tmdbId` are required in TypeScript but marked optional in Python.
+  - `SeriesSchedule.firstAirDate` and `SeriesSchedule.lastAirDate` are non-nullable `Instant` values in TypeScript and must be required integers in Python.
+  - `SeriesNetwork.isPrimary` is required in TypeScript but optional in Python.
+  - `SeriesImageAttributes.height`, `SeriesImageAttributes.width`, and `SeriesImageAttributes.type` must be required to match the TypeScript definition.
+  - `Media.banner`, `Media.fanart`, `Media.description`, and other fields already allow `null` in TypeScript, so using `Optional[...]` in Python is correct.
+- For properties that are nullable (`| null`) in TypeScript, the Python schema should continue using `Optional[...]`. Avoid defaulting to an empty container when the TypeScript side may emit `null`.
+
+## 2. Collection defaults
+- When TypeScript types specify `string[] | null` (for example `SeriesTitle.synonyms`), Python should allow `None` to be stored as-is instead of silently substituting an empty list. Prefer `Optional[List[str]]` with `default=None` unless there is a guaranteed non-null invariant.
+- Lists that are always present in TypeScript (e.g. `Media.images: SeriesImageAttributes[]`) should default to empty lists in Python to preserve parity with an empty array payload.
+
+## 3. Enumerations and literal unions
+- Ensure Python `Literal[...]` declarations cover the exact value set:
+  - `MediaKind` → `"ANIME" | "MANGA"`
+  - `SeriesImageAttributes.type` → `"BACKDROP" | "POSTER" | "LOGO"`
+  - `SeriesNetwork.category` → `"DISTRIBUTION" | "PRODUCTION"`
+- If additional enum members are added in TypeScript, replicate them immediately in Python to prevent validation drift.
+
+## 4. Temporal fields (`Instant`)
+- `Instant` in TypeScript is defined as a numeric epoch (`number`). Mirror this using `int` (or `datetime` conversions) in Python. Do not coerce these to optional strings; treat them as required integers wherever `Instant` lacks `| null`.
+- If you need richer date handling on the Python side, perform conversions at the application boundary while keeping the raw contract aligned.
+
+## 5. Media union structure
+- The TypeScript contract models media as a discriminated union: `Media` (base), `Media & AnimeMetadata`, and `Media & MangaMetadata`. The Python schema currently flattens everything into `MediaEntity` with many optional fields. Either:
+  1. Split the Python models into `Media`, `AnimeMedia`, and `MangaMedia` dataclasses with the correct required metadata, or
+  2. Keep a single dataclass but document that anime/manga metadata fields are only optional because the union collapses. If this option is chosen, add runtime validation to enforce that `AnimeMetadata` fields are present when `kind == "ANIME"` and vice versa.
+
+## 6. Theme songs and trailers
+- `AnimeMetadata.themeSongs` is required and defaults to an empty array in TypeScript; match this by defaulting to an empty list (not `None`) in Python.
+- `SeriesTrailer.thumbnail` is optional (`?`), which aligns with `Optional[str]` in Python.
+
+## 7. Future-proofing
+- Automate contract generation (e.g. generate JSON Schema from TypeScript or run Quicktype) so Python models stay synchronized. Add a CI check in both repositories to fail when schemas diverge.
+- Document any intentional deviations locally in both codebases so future contributors understand why a field differs.
+
+Follow this checklist whenever `src/series/types.ts` changes or when updating the Python contract to keep the TypeScript and Python definitions in lockstep.

src/common/helpers/date.ts

@@ -31,11 +31,7 @@ export const toFuzzyDate = (date?: string | Date): FuzzyDate => {
   }
 };
 
-export const toInstant = (date?: string | Date): Instant => {
-  if (!date) {
-    return -1;
-  }
-
+export const toInstant = (date: string | Date): Instant => {
   if (date instanceof Date) {
     return date.getTime() / 1000;
   } else {

src/series/repository/helpers/qualifier.ts

@@ -1,3 +1,4 @@
 import { MalType } from '@scope/service/jikan';
 
-export const isManga = (type?: MalType): boolean => type == MalType.Manga;
+export const isManga = (type?: MalType): boolean => type === 'Manga';
+export const isAnime = (type?: MalType): boolean => type === 'TV';

src/series/repository/series.repository.ts

@@ -8,7 +8,7 @@ import { getTmdbShow } from '@scope/service/tmdb';
 import { getTraktShow } from '@scope/service/trakt';
 import { seriesTransform } from '../transformer/series.transformer.ts';
 import { MediaEntity } from '../types.ts';
-import { isManga } from './helpers/qualifier.ts';
+import { isAnime } from './helpers/qualifier.ts';
 import LocalSource from '../local/series.local.source.ts';
 import { Theme } from '@scope/service/theme';
 import { SkyhookShow } from '@scope/service/skyhook';
@@ -36,7 +36,7 @@ export default class SeriesRepository {
       skyhook: SkyhookShow | undefined,
       trakt: Show | undefined,
       tmdb: TmdbShow | undefined;
-    if (!isManga(mal?.type)) {
+    if (isAnime(mal?.type)) {
       [themes, skyhook] = await Promise.all([
         getThemesForAnime(relation?.myanimelist),
         getSkyhookShow(relation?.thetvdb),

src/series/transformer/series.anime.transformer.test.ts

@@ -4,7 +4,6 @@ import { seriesTransform } from './series.transformer.ts';
 import { SeriesRelationId } from '@scope/service/arm';
 import { JikanAnime } from '@scope/service/jikan';
 import { MediaUnion } from '../types.ts';
-import { MalType } from '@scope/service/jikan';
 
 // Minimal anime fixture focusing on discriminated union behavior
 
@@ -39,7 +38,7 @@ describe('seriesTransform (anime union)', () => {
       title_english: 'Primary Anime Title EN',
       title_japanese: 'アニメ',
       title_synonyms: ['Alt Anime Title'],
-      type: MalType.ANIME,
+      type: 'TV',
       score: 0,
       scored_by: 0,
       rank: null,

src/series/transformer/series.manga.transformer.test.ts

@@ -36,7 +36,7 @@ describe('seriesTransform (manga support)', () => {
       title_english: 'Primary Manga Title EN',
       title_japanese: 'マンガ',
       title_synonyms: ['Alt Title'],
-      type: 1, // MalType.Manga
+      type: 'Manga',
       score: 0,
       scored_by: 0,
       rank: null,

src/series/transformer/series.transformer.ts

@@ -1,7 +1,7 @@
 import { currentDate, toEpotch } from '@scope/common/core';
 import { toInstant } from '@scope/common/helpers';
 import { SeriesRelationId } from '@scope/service/arm';
-import { Jikan, JikanAnime, JikanManga, MalType } from '@scope/service/jikan';
+import { Jikan, JikanAnime, JikanManga } from '@scope/service/jikan';
 import { NotifyAnime } from '@scope/service/notify';
 import { SkyhookShow } from '@scope/service/skyhook';
 import { AnimeTheme } from '@scope/service/theme';
@@ -27,6 +27,7 @@ import {
   SeriesTitle,
   SeriesTrailer,
 } from '../types.ts';
+import { isAnime, isManga } from '../repository/helpers/qualifier.ts';
 
 const seriesId = (
   relation?: SeriesRelationId,
@@ -50,7 +51,7 @@ const seriesId = (
   tvMazeId: skyhook?.tvMazeId ?? null,
   tvrage: trakt?.mediaId?.tvrage ?? null,
   slug: relation?.animePlanet ?? trakt?.mediaId?.slug ?? skyhook?.slug ?? null,
-  shoboi: Number(notify?.mediaId?.shoboi),
+  shoboi: notify?.mediaId?.shoboi ? Number(notify.mediaId.shoboi) : null,
   trakt: trakt?.mediaId?.trakt ?? null,
 });
 
@@ -102,8 +103,8 @@ const seriesSchedule = (
   if (!tmdb) return null;
 
   return {
-    firstAirDate: toInstant(tmdb?.first_air_date),
-    lastAirDate: toInstant(tmdb?.last_air_date),
+    firstAirDate: tmdb?.first_air_date ? toInstant(tmdb.first_air_date) : null,
+    lastAirDate: tmdb?.last_air_date ? toInstant(tmdb.last_air_date) : null,
     lastAiredEpisode: seriesScheduleEpisode(tmdb?.last_episode_to_air),
     nextEpisodeToAir: seriesScheduleEpisode(tmdb?.next_episode_to_air),
   };
@@ -217,9 +218,7 @@ export const seriesTransform = (
   jikan?: Jikan,
   trakt?: TraktShow,
 ): MediaUnion => {
-  const isAnime = jikan?.type === MalType.ANIME;
-
-  const kind: MediaKind = isAnime ? 'ANIME' : 'MANGA';
+  const kind: MediaKind = isAnime(jikan?.type) ? 'ANIME' : 'MANGA';
 
   const base = {
     kind,
@@ -238,7 +237,7 @@ export const seriesTransform = (
     description: seriesDescription(skyhook, tmdb, notify, jikan, trakt),
   };
 
-  if (!isAnime) {
+  if (isManga(jikan?.type)) {
     const jikanManga = jikan as JikanManga;
     const manga: MangaMetadata = {
       chapters: typeof jikanManga.chapters === 'number'
@@ -258,7 +257,7 @@ export const seriesTransform = (
     return { ...base, ...manga };
   }
 
-  if (isAnime) {
+  if (isAnime(jikan?.type)) {
     const jikanAnime = jikan as JikanAnime;
     const anime: AnimeMetadata = {
       themeSongs: themes ?? [],

src/series/types.ts

@@ -17,7 +17,7 @@ export type SeriesId = {
   tvMazeId: number | null;
   tvrage: string | null;
   slug: string | null;
-  shoboi: number;
+  shoboi: number | null;
   trakt: number | null;
 };
 
@@ -44,8 +44,8 @@ export type SeriesScheduleEpisode = {
 };
 
 export type SeriesSchedule = {
-  firstAirDate: Instant;
-  lastAirDate: Instant;
+  firstAirDate: Instant | null;
+  lastAirDate: Instant | null;
   lastAiredEpisode: SeriesScheduleEpisode | null;
   nextEpisodeToAir: SeriesScheduleEpisode | null;
 };

src/service/jikan/index.ts

@@ -1,4 +1,3 @@
 export * from './jikan.service.ts';
 export * from './types.ts';
 export * from './remote/types.ts';
-export * from './remote/enums.ts';

src/service/jikan/jikan.manga.transformer.test.ts

@@ -17,7 +17,7 @@ describe('jikan manga transformer', () => {
       title: 'Manga Title',
       title_english: 'Manga English',
       title_japanese: 'マンガ',
-      type: 1, // MalType.Manga
+      type: 'Manga',
       score: 0,
       scored_by: 0,
       rank: 0,