DTO Entities: MikroORM and TypeGraphQL Schema Reference

The Riven Plugin SDK ships a set of MikroORM entities that are also decorated with type-graphql @ObjectType / @InterfaceType annotations. These classes represent the canonical data model used across all plugins, resolvers, and event payloads. You can import any of them from @repo/util-plugin-sdk/dto/entities and use them directly in queries, mutations, or event handlers.

Entity classes are shared across plugins via the single MikroORM EntityManager that Riven manages. Never instantiate entities with new inside a resolver — always use repositories or the EntityManager from the request context.

Media Item Hierarchy

MediaItem (abstract InterfaceType)
├── Movie
└── ShowLikeMediaItem (abstract InterfaceType)
    ├── Show
    ├── Season
    └── Episode

MediaItem

The abstract base for all media content. Mapped to the media_item table with a discriminator column type.

MediaItem fields

UUID

required

Primary key. Auto-generated with randomUUID() on construction.

title

string

required

The canonical title of the media item as returned by the indexer.

fullTitle

string

The full title including subtitle or year suffix, used for display purposes.

imdbId

string | null

IMDB identifier. Must match /^tt\d+$/. Used as the primary external lookup key for most scrapers.

posterPath

string | null

URL or relative path to the poster image.

createdAt

Date

UTC timestamp when the entity was first persisted. Defaults to DateTime.utc().toJSDate().

updatedAt

Date | null

UTC timestamp of the last update. Set automatically via onUpdate hook.

indexedAt

Date

required

UTC timestamp when the item was indexed by an indexer plugin.

scrapedAt

Date | null

UTC timestamp of the most recent successful scrape.

scrapedTimes

number

Count of how many times this item has been successfully scraped. Defaults to 0.

failedScrapeAttempts

number

Number of consecutive scrape failures. Defaults to 0. Reset by .reset().

aliases

Record<string, string[]> | null

A map of locale codes to alternative title strings, e.g. { "de": ["Deutsch Titel"] }.

isAnime

boolean

Computed (not persisted). Returns true when language !== "en" and both "animation" and "anime" appear in genres.

isReleased

boolean

Computed (not persisted). Returns true when releaseDate is in the past.

network

string | null

Broadcasting network or streaming platform name.

country

string | null

Country of origin.

language

string | null

Language code.

releaseDate

Date | null

required

The theatrical or first-air release date. null for unreleased items.

year

number | null

The release year, used in pretty-name generation.

genres

string[] | null

Array of genre strings as returned by the indexer.

rating

number | null

Audience rating on a 0–10 scale.

state

MediaItemState

required

Current position in the processing state machine. See MediaItemState.

type

MediaItemType

required

Discriminator column. One of movie, show, season, or episode.

streams

Collection<Stream>

All Stream candidates associated with this item via a ManyToMany relation.

activeStream

Ref<Stream> | null

The Stream currently selected for download. null when no stream is active.

filesystemEntries

Collection<FileSystemEntry>

All filesystem entries (media files and subtitles) linked to this item.

subtitles

Collection<SubtitleEntry>

Subtitle entries linked to this item. Filtered view of filesystemEntries where type === "subtitle".

blacklistedStreams

Collection<BlacklistedStream>

Streams that have been explicitly blocked from being selected again.

itemRequest

Ref<ItemRequest>

required

The originating ItemRequest that triggered this item’s creation.

isRequested

boolean

required

Whether this item is directly requested (as opposed to being an inferred child like an unrequested season).

Movie

Extends MediaItem. Discriminator value: "movie".

Movie fields

tmdbId

string

required

TMDB identifier. Must be a numeric string. Used as the external ID in VFS pretty-name generation.

runtime

number | null

Runtime in minutes.

contentRating

MovieContentRating

MPAA rating. One of g, pg, pg-13, r, nc-17, or unknown.

type

"movie"

Always "movie".

Pretty name format: "<Title> (<Year>) {tmdb-<tmdbId>}"
e.g. "The Dark Knight (2008) {tmdb-155}"

ShowLikeMediaItem

Abstract InterfaceType that extends MediaItem and adds a tvdbId field shared by shows, seasons, and episodes.

ShowLikeMediaItem fields

tvdbId

string

required

TVDB identifier. Must be a numeric string.

contentRating

ShowContentRating

TV Parental Guidelines rating. One of tv-y, tv-y7, tv-g, tv-pg, tv-14, tv-ma, or unknown.

Show

Extends ShowLikeMediaItem. Discriminator value: "show".

Show fields

status

ShowStatus

required

Broadcast status. See ShowStatus.

seasons

Collection<Season>

All seasons belonging to this show, including specials (season 0).

requestedSeasons

Collection<Season>

Subset of seasons where isRequested === true.

nextAirDate

Date | null

required

Scheduled air date of the next episode. Used internally for scheduling re-indexing.

contentRating

ShowContentRating

TV Parental Guidelines rating inherited from ShowLikeMediaItem.

type

"show"

Always "show".

Pretty name format: "<Title> (<Year>) {tvdb-<tvdbId>}"

Season

Extends ShowLikeMediaItem. Discriminator value: "season".

Season fields

number

required

Season number. 0 denotes a specials season. Minimum: 0.

show

Ref<Show>

required

Reference to the parent Show.

episodes

Collection<Episode>

All episodes belonging to this season.

isSpecial

boolean

Computed (persisted). Returns true when number === 0.

type

"season"

Always "season".

Pretty name format: "Season 01" (zero-padded two digits)

Episode

Extends ShowLikeMediaItem. Discriminator value: "episode".

Episode fields

number

required

Episode number within its season. Minimum: 0.

absoluteNumber

number

required

Episode number across all seasons of the show. Used for anime ordering.

season

Ref<Season>

required

Reference to the parent Season.

runtime

number | null

Runtime in minutes.

contentRating

ShowContentRating

Per-episode TV Parental Guidelines rating.

type

"episode"

Always "episode".

Pretty name format: "<Show> (<Year>) {tvdb-<id>} - s01e01"

FileSystemEntry

Abstract base for files tracked in Riven’s virtual filesystem. Mapped with a discriminator column type; concrete subclasses are MediaEntry ("media") and SubtitleEntry ("subtitle").

FileSystemEntry fields

UUID

Primary key, auto-generated.

fileSize

number

required

File size in bytes. Must be a positive integer (stored as bigint).

createdAt

Date

UTC creation timestamp.

updatedAt

Date | null

UTC timestamp of the last update.

mediaItem

Ref<Movie | Episode>

required

The Movie or Episode this file belongs to. Only leaf items (Movie, Episode) have associated filesystem entries.

type

FileSystemEntryType

required

Discriminator column. Either "media" or "subtitle".

path

string

VFS path for this entry, generated before first persist.
e.g. "The Dark Knight (2008) {tmdb-155}/The Dark Knight (2008) {tmdb-155}.mkv"

MediaEntry

A concrete filesystem entry representing a downloaded media file. Extends FileSystemEntry with discriminator value "media".

MediaEntry fields

originalFilename

string

required

The filename as returned by the debrid service.

downloadUrl

string | null

Direct download URL provided by the debrid service.

streamPermalink

string | null

A permanent stream URL, if one has been resolved and cached.

plugin

string

required

The plugin name that created this entry.

provider

string | null

required

The debrid provider name (e.g. "real-debrid", "all-debrid").

providerDownloadId

string | null

The download/torrent ID assigned by the debrid provider. Used to poll status or generate stream links.

libraryProfiles

string[] | null

Identifiers of library profiles this entry has been linked into.

mediaMetadata

object | null

Arbitrary metadata blob stored as JSON. Plugin-defined.

type

"media"

Always "media".

Stream

Represents a torrent/magnet candidate identified by its SHA-1 info hash.

Stream fields

infoHash

string

Primary key. A 40-character hexadecimal SHA-1 hash identifying the torrent.

parsedData

ParsedData (JSON)

Structured torrent metadata parsed by @repo/util-rank-torrent-name. Stored as a JSON column.

parents

Collection<MediaItem>

All MediaItem instances that include this stream as a candidate.

activeParents

Collection<MediaItem>

MediaItem instances that currently have this stream selected as their activeStream.

ItemRequest

Represents a user or content-service request to acquire a piece of media. Owns all the MediaItem records created in response.

ItemRequest fields

UUID

Primary key, auto-generated with randomUUID().

imdbId

string | null

IMDB identifier. Unique constraint. Must match /^tt\d+$/.

tmdbId

string | null

TMDB identifier. Unique constraint. Numeric string.

tvdbId

string | null

TVDB identifier. Unique constraint. Numeric string.

type

ItemRequestType

required

Either "movie" or "show". See ItemRequestType.

requestedBy

string | null

required

Free-form string identifying the requester (e.g. a username or service name).

externalRequestId

string | null

An opaque ID passed by the requesting service for correlation.

state

ItemRequestState

required

Current lifecycle state. See ItemRequestState.

seasons

number[] | null

Specific season numbers requested. null means all seasons.

createdAt

Date

UTC creation timestamp.

completedAt

Date | null

UTC timestamp when all requested media reached completed state.

isPartialRequest

boolean

true when seasons specifies a subset of the show’s total seasons. Always false for movies. Defaults to false until indexer data resolves total season count.

mediaItems

Collection<MediaItem>

All MediaItem records created for this request.

seasonItems

Collection<Season>

Subset of mediaItems where type === "season".

requestedItems

Collection<MediaItem>

Subset of mediaItems where isRequested === true.

Enums

`MediaItemState`

Tracks a media item’s position in the processing pipeline.

Value	Description
`unknown`	State could not be determined
`unreleased`	Release date is in the future
`ongoing`	Show is currently airing
`indexed`	Metadata has been fetched by an indexer plugin
`scraped`	Stream candidates have been found by a scraper plugin
`downloaded`	Files have been downloaded to the debrid service
`completed`	All files are available and stream links are valid
`partially_completed`	Some (but not all) episodes/seasons are complete
`failed`	Processing has permanently failed
`paused`	Processing is temporarily suspended

`ItemRequestState`

Value	Description
`requested`	Initial state after creation
`requested_additional_seasons`	Additional seasons have been added to an existing show request
`completed`	All requested media is complete
`failed`	The request could not be fulfilled
`ongoing`	Show is still airing; request remains open
`unreleased`	All requested media is unreleased

`ItemRequestType`

Value	Description
`movie`	A single film
`show`	A TV series

`MediaItemType`

Value	Description
`movie`	A movie entity
`show`	A show entity
`season`	A season entity
`episode`	An episode entity

`ShowStatus`

Value	Description
`continuing`	Show is actively airing new episodes
`upcoming`	Show has been announced but not yet aired
`ended`	Show has concluded
`unknown`	Status could not be determined

`MediaItemContentRating`

Umbrella enum covering both MPAA and TV Parental Guidelines ratings. Use the more specific MovieContentRating or ShowContentRating subsets where appropriate.

Movie Ratings (MPAA)

g · pg · pg-13 · r · nc-17 · unknown

TV Ratings (TV Parental Guidelines)

tv-y · tv-y7 · tv-g · tv-pg · tv-14 · tv-ma · unknown

Overview

Building a Plugin

Reference

DTO Entities: MikroORM and TypeGraphQL Schema Reference

Media Item Hierarchy

MediaItem

Movie

ShowLikeMediaItem

Show

Season

Episode

FileSystemEntry

MediaEntry

Stream

ItemRequest

Enums

`MediaItemState`

`ItemRequestState`

`ItemRequestType`

`MediaItemType`

`ShowStatus`

`MediaItemContentRating`

Movie Ratings (MPAA)

TV Ratings (TV Parental Guidelines)

Build docs developers (and LLMs) love

Overview

Building a Plugin

Reference

Documentation Index

​Media Item Hierarchy

​MediaItem

​Movie

​ShowLikeMediaItem

​Show

​Season

​Episode

​FileSystemEntry

​MediaEntry

​Stream

​ItemRequest

​Enums

​MediaItemState

​ItemRequestState

​ItemRequestType

​MediaItemType

​ShowStatus

​MediaItemContentRating

Movie Ratings (MPAA)

TV Ratings (TV Parental Guidelines)

Build docs developers (and LLMs) love

Media Item Hierarchy

MediaItem

Movie

ShowLikeMediaItem

Show

Season

Episode

FileSystemEntry

MediaEntry

Stream

ItemRequest

Enums

`MediaItemState`

`ItemRequestState`

`ItemRequestType`

`MediaItemType`

`ShowStatus`

`MediaItemContentRating`