feat(calendar): flatten merged-feed response to nullish fields

Reshapes the merged-feed response (`hotReleaseResponseSchema`, used by `media`
and `releases/hot`) from a `z.union([movie, show])` to a single flat object with
every field nullish. OpenAPI codegen renders a union `oneOf` as a model with all
fields required, so consumers generated a wrong schema (movie/show/episode all
non-null); nullish fields generate a correct optional-field model, and callers
null-check to discriminate. Documents the convention in AGENTS.md. Bumps to
0.4.25.

Author: vladjerca

AGENTS.md

@@ -0,0 +1,43 @@
+# trakt-api agent rules
+
+Conventions for authoring the ts-rest + zod API contract. The OpenAPI spec and
+consumer models/clients are generated from these schemas, so schema shape is a
+public artifact, not just internal typing.
+
+## Response schemas
+
+### Polymorphic / multi-shape responses: one flat object, all fields nullish
+
+When an endpoint returns entries of more than one entity shape - a merged feed
+(e.g. calendar `media` / `releases/hot` returning movies AND episodes), or any
+route whose response varies by a `type=movie|show|episode|...` param - model the
+response as a SINGLE object with **every shape-specific field nullish**. Do NOT
+use `z.union([...])`.
+
+```ts
+// ❌ BAD: union -> OpenAPI `oneOf` -> codegen emits a model with ALL fields
+//         required, so consumers get a wrong schema.
+export const feedResponseSchema = z.union([movieEntrySchema, showEntrySchema]);
+
+// ✅ GOOD: one flat object, shape-specific fields nullish -> codegen emits a
+//          correct all-optional model. Discriminate by shape at runtime.
+export const feedResponseSchema = z.object({
+  released: z.string().nullish(),
+  movie: movieResponseSchema.nullish(),
+  first_aired: z.string().nullish(),
+  episode: episodeResponseSchema.nullish(),
+  show: showResponseSchema.nullish(),
+});
+```
+
+**Why:** OpenAPI codegen turns a union `oneOf` into a single model with every
+member's fields marked required, so a downstream consumer sees `movie`, `show`,
+`episode`, `season`, etc. all as non-null and its generated model is wrong.
+Nullish fields on one object generate a correct optional-field model; the caller
+null-checks (`if (entry.movie) ...`) to discriminate.
+
+Single-shape responses stay fully required - only widen to nullish the fields
+that are genuinely absent for some variant.
+
+Reference:
+`projects/api/src/contracts/calendars/schema/response/hotReleaseResponseSchema.ts`.

projects/api/deno.json

@@ -1,7 +1,7 @@
 {
   "name": "@trakt/api",
   "exports": "./src/index.ts",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "imports": {
     "@anatine/zod-openapi": "npm:@anatine/zod-openapi@^2.2.6",
     "@std/testing": "jsr:@std/testing@^1.0.5",

projects/api/src/contracts/calendars/schema/response/hotReleaseResponseSchema.ts

@@ -1,13 +1,20 @@
+import { movieResponseSchema } from '../../../_internal/response/movieResponseSchema.ts';
+import { showResponseSchema } from '../../../_internal/response/showResponseSchema.ts';
 import { z } from '../../../_internal/z.ts';
-import { calendarMovieResponseSchema } from './calendarMovieResponseSchema.ts';
-import { calendarShowResponseSchema } from './calendarShowListResponseSchema.ts';
+import { calendarEpisodeResponseSchema } from './calendarEpisodeResponseSchema.ts';
 
 /**
- * A single entry in the merged hot-releases feed: either an upcoming movie or
- * an upcoming episode. Discriminate by shape — movie entries carry `movie`,
- * episode entries carry `episode`/`show`.
+ * A single entry in a merged calendar feed (media, hot releases): an upcoming
+ * movie OR an upcoming episode. Modeled as one flat object with every field
+ * nullish rather than a `z.union` — OpenAPI codegen turns a union `oneOf` into
+ * a model with all fields required, so consumers get a wrong schema. With
+ * nullish fields the generated model is correct; discriminate by shape (movie
+ * entries carry `movie`, episode entries carry `episode`/`show`).
  */
-export const hotReleaseResponseSchema = z.union([
-  calendarMovieResponseSchema,
-  calendarShowResponseSchema,
-]);
+export const hotReleaseResponseSchema = z.object({
+  released: z.string().nullish(),
+  movie: movieResponseSchema.nullish(),
+  first_aired: z.string().nullish(),
+  episode: calendarEpisodeResponseSchema.nullish(),
+  show: showResponseSchema.nullish(),
+});