import LocalizedString from '../internal/LocalizedString'; import Tag from './Tag'; import { fetchMD, fetchMDByArrayParam, fetchMDData, fetchMDDataWithBody, fetchMDSearch, fetchMDWithBody, } from '../util/Network'; import Relationship from '../internal/Relationship'; import Links from '../internal/Links'; import IDObject from '../internal/IDObject'; import Chapter, { ChapterSearchParams } from './Chapter'; import Cover from './Cover'; import APIResponseError from '../util/APIResponseError'; import type Author from './Author'; import { ChapterListSchema, ChapterReadMarkerBatchSchema, GetMangaRandomParamsSchema, GetSearchMangaParamsSchema, MangaAttributesSchema, MangaListSchema, MangaResponseSchema, MangaSchema, RelationshipSchema, Manga as MangaNamespace, Rating, ResponseSchema, MappingIdBodySchema, MappingIdResponseSchema, MangaRelationAttributesSchema, MangaRelationResponseSchema, MangaRelationRequestSchema, MangaRelationListSchema, Statistics, GetMangaDraftsParamsSchema, MangaCreateSchema, MangaEditSchema, User as UserNamespace, } from '../types/schema'; import type { DeepRequire, Merge } from '../types/helpers'; import type Group from './Group'; import type User from './User'; // This type supplements the schema type so that IDObjects can be used instead type MangaSearchHelpers = { group: Group; includedTags: Tag[]; excludedTags: Tag[]; authors: Author[]; artists: Author[]; authorOrArtist: Author; ids: IDObject[]; }; type MangaSearchParams = Partial>; type OtherMangaAttributes = Omit; type RelatedManga = { [x in RelationshipSchema['related']]: Relationship[] }; type ReadmarkerResponse = Required; type ReadmarkerResponseGrouped = Required; type RatingResponse = Required; type MangaReadingStatus = Required['status']; type MangaRelation = MangaRelationAttributesSchema['relation']; type MangaStatsResponse = DeepRequire; type MangaStats = MangaStatsResponse['statistics'][string]; type MangaDraftSearchParams = Partial; type MangaAggregateResponse = DeepRequire; type MangaAggregate = MangaAggregateResponse['volumes']; type FollowedMangaParams = UserNamespace.GetUserFollowsManga.RequestQuery; /** * This class represents a specific manga series. * There are many static methods for requesting manga from MangaDex. */ export default class Manga extends IDObject implements OtherMangaAttributes { /** * The MangaDex UUID of this manga */ id: string; /** * The manga's main title with different localization options */ title: LocalizedString; /** * List of alternate titles with different localization options */ altTitles: LocalizedString[]; /** * Description with different localization options */ description: LocalizedString; /** * Is this manga locked? */ isLocked: boolean; /** * Link object representing links to other websites about this manga */ links: Links; /** * 2 (or more) letter code for the original language of this manga */ originalLanguage: string; /** * This manga's last volume based on the default feed order */ lastVolume: string | null; /** * This manga's last chapter based on the default feed order */ lastChapter: string | null; /** * Publication demographic of this manga */ publicationDemographic: 'shounen' | 'shoujo' | 'josei' | 'seinen' | null; /** * Publication/Scanlation status of this manga */ status: 'completed' | 'ongoing' | 'cancelled' | 'hiatus'; /** * Year of this manga's publication */ year: number | null; /** * The content rating of this manga */ contentRating: 'safe' | 'suggestive' | 'erotica' | 'pornographic'; /** * Does the chapter count reset whenever a new volume is added? */ chapterNumbersResetOnNewVolume: boolean; /** * List of language codes that this manga has translated chapters for */ availableTranslatedLanguages: string[]; /** * Relationship to the latest chapter. Null if there is no latest chapter. */ latestUploadedChapter: Relationship | null; /** * List of this manga's genre tags */ tags: Tag[]; /** * Status of this manga as a manga submission */ state: 'draft' | 'submitted' | 'published' | 'rejected'; /** * The version of this manga (incremented by updating manga data) */ version: number; /** * Date the manga was added to the site */ createdAt: Date; /** * Date the manga was last updated */ updatedAt: Date; /** * An object containing all other manga entries related to this one. * This includes spin-offs, colorization, etc. */ relatedManga: RelatedManga; /** * List of relationships to authors attributed to this manga */ authors: Relationship[]; /** * List of relationships to artists attributed to this manga */ artists: Relationship[]; /** * A relationship to the current main cover of this series */ mainCover: Relationship; /** * The user that created this manga, if known. */ creator: Relationship | null; constructor(schem: MangaSchema) { super(); this.id = schem.id; const parentRelationship = Relationship.createSelfRelationship('manga', this); this.altTitles = schem.attributes.altTitles.map((elem) => new LocalizedString(elem)); this.artists = Relationship.convertType('artist', schem.relationships, parentRelationship); this.authors = Relationship.convertType('author', schem.relationships, parentRelationship); this.availableTranslatedLanguages = schem.attributes.availableTranslatedLanguages; this.chapterNumbersResetOnNewVolume = schem.attributes.chapterNumbersResetOnNewVolume; this.contentRating = schem.attributes.contentRating; this.createdAt = new Date(schem.attributes.createdAt); this.description = new LocalizedString(schem.attributes.description); this.isLocked = schem.attributes.isLocked; this.lastChapter = schem.attributes.lastChapter; this.lastVolume = schem.attributes.lastVolume; this.latestUploadedChapter = null; if (schem.attributes.latestUploadedChapter) { this.latestUploadedChapter = new Relationship({ id: schem.attributes.latestUploadedChapter, type: 'chapter', relationships: [parentRelationship], }); } this.links = new Links(schem.attributes.links); this.mainCover = Relationship.convertType('cover_art', schem.relationships, parentRelationship).pop()!; this.publicationDemographic = schem.attributes.publicationDemographic; this.relatedManga = Manga.getRelatedManga(schem.relationships); this.state = schem.attributes.state; this.status = schem.attributes.status; this.tags = schem.attributes.tags.map((elem) => new Tag(elem)); this.title = new LocalizedString(schem.attributes.title); this.updatedAt = new Date(schem.attributes.updatedAt); this.version = schem.attributes.version; this.year = schem.attributes.year; this.originalLanguage = schem.attributes.originalLanguage; this.creator = Relationship.convertType('creator', schem.relationships).pop() ?? null; } private static getRelatedManga(relationships: RelationshipSchema[]): RelatedManga { const relatedManga: RelatedManga = { monochrome: [], main_story: [], adapted_from: [], based_on: [], prequel: [], side_story: [], doujinshi: [], same_franchise: [], shared_universe: [], sequel: [], spin_off: [], alternate_story: [], alternate_version: [], preserialization: [], colored: [], serialization: [], }; for (const rel of relationships) { if (rel.type === 'manga') { relatedManga[rel.related].push(new Relationship(rel)); } } return relatedManga; } /** * The title of this manga according to the global locale. * @see {@link LocalizedString.localString} */ get localTitle() { return this.title.localString; } /** * List of alternate titles for manga according to the global locale. * @see {@link LocalizedString.localString} */ get localAltTitles() { return this.altTitles.map((title) => title.localString); } /** * The description of this manga according to the global locale. * @see {@link LocalizedString.localString} */ get localDescription() { return this.description.localString; } /** * Retrieves a manga object by its UUID */ static async get(id: string, expandedTypes?: MangaSearchParams['includes']): Promise { return new Manga(await fetchMDData(`/manga/${id}`, { includes: expandedTypes })); } /** * Retrieves a list of manga according to the specified search parameters * @see {@link Relationship.cached} for information on how to automatically resolve Relationships */ static async search(query?: MangaSearchParams): Promise { const res = await fetchMDSearch(`/manga`, query); return res.map((m) => new Manga(m)); } /** * Retrieves an array of manga by an array of their ids */ static async getMultiple(ids: string[], extraParams?: Omit): Promise { const res = await fetchMDByArrayParam('/manga', ids, extraParams); return res.map((m) => new Manga(m)); } /** * Returns how many manga there are total for a search query */ static async getTotalSearchResults(query?: Omit): Promise { const res = await fetchMD('/manga', { ...query, limit: 1, offset: 0 }); return res.total; } /** * Returns an array of a manga's chapters */ static async getFeed(id: string, params?: ChapterSearchParams): Promise { const res = await fetchMDSearch(`/manga/${id}/feed`, params); return res.map((c) => new Chapter(c)); } /** * Returns an array of this manga's chapters */ async getFeed(params?: ChapterSearchParams): Promise { return Manga.getFeed(this.id, params); } /** * Marks lists of chapters read or unread for a single manga */ static async updateReadChapters( manga: string, chapters: { read?: (string | Chapter)[]; unread?: (string | Chapter)[] }, updateHistory = false, ) { if (!chapters.read && !chapters.unread) return []; const body = { chapterIdsRead: chapters.read?.map((c) => (typeof c === 'string' ? c : c.id)) ?? [], chapterIdsUnread: chapters.unread?.map((c) => (typeof c === 'string' ? c : c.id)) ?? [], } as ChapterReadMarkerBatchSchema; await fetchMDWithBody(`/manga/${manga}/read`, body, { updateHistory: updateHistory }); } /** * Marks lists of chapters read or unread for this manga */ async updateReadChapters(chapters: Parameters[1], updateHistory = false) { return Manga.updateReadChapters(this.id, chapters, updateHistory); } /** * Returns an array of read chapters for a list of manga. The response is a record with the manga ids * as the keys and chapter arrays as the values. */ static async getReadChapters(ids: string[] | Manga[]): Promise> { const mangaData: Record = {}; // Split requests because there is a maximum URI length for each for (let i = 0; i < ids.length; i += 100) { let res = await fetchMDData('/manga/read', { ids: ids.slice(i, i + 100), grouped: true, }); if (Array.isArray(res)) { // The response won't be grouped if there is only one manga if (ids.length === 1) { const id = typeof ids[0] === 'string' ? ids[0] : ids[0].id; res = { [id]: res }; } else { throw new APIResponseError('MangaDex did not respond with a grouped body.'); } } for (const [key, value] of Object.entries(res)) { if (key in mangaData) mangaData[key].push(...value); else mangaData[key] = value; } } // Flatten all the chapters so only one request needs to be made const allChapters = await Chapter.getMultiple(Object.values(mangaData).flat()); const returnObj: Record = {}; for (const key in mangaData) { returnObj[key] = allChapters.filter((c) => mangaData[key].includes(c.id)); } return returnObj; } /** * Returns an array of read chapters for this manga */ async getReadChapters() { const res = await fetchMDData(`/manga/${this.id}/read`); return await Chapter.getMultiple(res); } /** * Retrieves a random manga */ static async getRandom(query?: Pick) { const res = await fetchMDData('/manga/random', query); return new Manga(res); } /** * Performs a search for a manga and returns the first one found. If no results are * found, null is returned */ static async getByQuery(query?: MangaSearchParams): Promise { const res = await this.search(query); return res[0] ?? null; } /** * Gets all covers for this manga */ async getCovers() { return Cover.getMangaCovers(this.id); } /** * Returns all manga followed by the currently authenticated user */ static async getFollowedManga(query: FollowedMangaParams = { limit: Infinity, offset: 0 }): Promise { const res = await fetchMDSearch('/user/follows/manga', query); return res.map((u) => new Manga(u)); } /** * Returns a record of all ratings given by the currently authenticated user. The object is indexed by the manga * ids and each value contains the numerical rating and when that rating was given. If a manga has no rating, * 'null' is used as the value. */ static async getUserRatings( ids: string[] | Manga[], ): Promise> { const res = await fetchMD('/rating', { manga: ids }); const parsedObj: Record = {}; for (let i of ids) { if (typeof i !== 'string') i = i.id; if (i in res.ratings) { parsedObj[i] = { rating: res.ratings[i].rating!, createdAt: new Date(res.ratings[i].createdAt!), }; } else { parsedObj[i] = null; } } return parsedObj; } /** * Returns the rating that the currently authenticated user gave to this manga on a scale of 1-10, * or returns null if there is no rating. */ async getUserRating(): Promise { const res = await Manga.getUserRatings([this.id]); return res[this.id]?.rating ?? null; } /** * Makes the currently authenticated user give a manga a rating between 1-10 (inclusive). */ static async giveRating(mangaId: string, rating: number) { if (rating > 10 || rating < 1) throw new Error('Rating must be in the range of 1-10 (inclusive).'); await fetchMDWithBody(`/rating/${mangaId}`, { rating: rating }); } /** * Makes the currently authenticated user give this manga a rating between 1-10 (inclusive). */ async giveRating(rating: number) { await Manga.giveRating(this.id, rating); } /** * Removes the currently authenticated user's rating for a manga */ static async removeRating(mangaId: string) { await fetchMD(`/rating/${mangaId}`, undefined, { method: 'DELETE' }); } /** * Removes the currently authenticated user's rating for this manga */ async removeRating() { await Manga.removeRating(this.id); } /** * Gets the combined feed of every manga followed by the logged in user */ static async getFollowedFeed(query?: ChapterSearchParams): Promise { const res = await fetchMDSearch('/user/follows/manga/feed', query); return res.map((c) => new Chapter(c)); } /** * Converts legacy pre-V5 MangaDex ids to modern UUIDs. Returns a record with legacy ids as the keys * and new ids as the values. */ static async convertLegacyId(type: MappingIdBodySchema['type'], ids: number[]): Promise> { const res = await fetchMDDataWithBody('/legacy/mapping', { type: type, ids: ids, } as MappingIdBodySchema); return Object.fromEntries(res.map((i) => [i.attributes.legacyId, i.attributes.newId])); } /** * Get every reading status (eg completed, reading, dropped, etc) for every manga marked by * the currently authenticated user. * @param filter - If specified, only manga with this status will be returned */ static async getAllReadingStatus(filter?: MangaReadingStatus): Promise> { const res = await fetchMD>('/manga/status', { status: filter, }); return res.statuses; } /** * Gets the reading status (eg completed, reading, dropped, etc) for a manga for the currently * authenticated user */ static async getReadingStatus(id: string): Promise { const res = await fetchMD>(`/manga/${id}/status`); return res.status; } /** * Gets the reading status (eg completed, reading, dropped, etc) for this manga for the currently * authenticated user */ async getReadingStatus(): Promise { return await Manga.getReadingStatus(this.id); } /** * Sets a manga's reading status (eg completed, reading, dropped, etc) for the currently authenticated user. * If the status is null, the current reading status will be removed. */ static async setReadingStatus(id: string, status: MangaReadingStatus | null): Promise { await fetchMDWithBody(`/manga/${id}/status`, { status: status }); } /** * Sets this manga's reading status (eg completed, reading, dropped, etc) for the currently authenticated user. * If the status is null, the current reading status will be removed. */ async setReadingStatus(status: MangaReadingStatus | null) { await Manga.setReadingStatus(this.id, status); } /** * Gets all of a manga's relations to other manga. */ static async getRelations(id: string, expandTypes = false): Promise { const res = await fetchMDData(`/manga/${id}/relation`, { includes: expandTypes ? ['manga'] : undefined, }); const relationships = res.flatMap((relation) => relation.relationships.map((rel) => ({ ...rel, related: relation.attributes.relation })), ); return Manga.getRelatedManga(relationships); } /** * Gets all of this manga's relations to other manga. */ async getRelations(expandTypes = false): Promise { return await Manga.getRelations(this.id, expandTypes); } /** * Creates a relation between two manga (eg sequel/prequel, monochrome/colored, spin-off, etc) * @param id - The origin manga * @param targetId - The target manga for the relation (eg the sequel, spin-off, etc) */ static async addRelation(id: string, targetId: string, relationType: MangaRelation): Promise { await fetchMDDataWithBody(`/manga/${id}/relation`, { targetManga: targetId, relation: relationType, } as MangaRelationRequestSchema); } /** * Creates a relation (eg sequel/prequel, monochrome/colored, spin-off, etc) between this manga and another * @param id - The origin manga * @param targetId - The target manga for the relation (eg the sequel, spin-off, etc) */ async addRelation(targetId: string, relationType: MangaRelation): Promise { await Manga.addRelation(this.id, targetId, relationType); } /** * Removes a relation from a manga by the relation's id */ static async removeRelation(mangaId: string, relationId: string) { await fetchMD(`/manga/${mangaId}/relation/${relationId}`, undefined, { method: 'DELETE' }); } /** * Removes a relation from this manga by the relation's id */ async removeRelation(relationId: string) { await Manga.removeRelation(this.id, relationId); } /** * Gets the statistics about manga including their rating distribution, comment count, and follow count */ static async getStatistics(ids: string[] | Manga[]): Promise> { const res = await fetchMD(`/statistics/manga`, { manga: ids }); return res.statistics; } /** * Gets the statistics about this manga including its rating distribution, comment count, and follow count */ async getStatistics(): Promise { const res = await Manga.getStatistics([this.id]); return res[this.id]; } /** * Retrieves a manga draft by its UUID */ static async getDraft(id: string, expandedTypes?: MangaDraftSearchParams['includes']): Promise { return new Manga(await fetchMDData(`/manga/draft/${id}`, { includes: expandedTypes })); } /** * Retrieves a list of manga drafts according to the specified search parameters * @see {@link Relationship.cached} for information on how to automatically resolve Relationships */ static async searchDrafts(query?: MangaDraftSearchParams): Promise { const res = await fetchMDSearch(`/manga/draft`, query); return res.map((m) => new Manga(m)); } /** * Commits a manga object as a draft. A Manga draft that is to be submitted must have at least one cover in * the original language, must be in the "draft" state, and must be passed the correct version in the request body. */ static async commitDraft(draftId: string, manga: Partial): Promise { const res = await fetchMDDataWithBody(`/manga/draft/${draftId}/commit`, manga); return new Manga(res); } /** * Create a new manga. MangaDex only allows admins to use this endpoint. Use the a manga draft instead */ static async create(data: MangaCreateSchema) { return new Manga(await fetchMDDataWithBody('/manga', data)); } /** * Deletes a manga by its id */ static async delete(id: string) { await fetchMD(`/manga/${id}`, undefined, { method: 'DELETE' }); } /** * Deletes this manga */ async delete() { await Manga.delete(this.id); } /** * Updates this manga's information. */ async update(data: Omit) { return new Manga( await fetchMDDataWithBody( `/author/${this.id}`, { ...data, version: this.version + 1, } as MangaEditSchema, undefined, 'PUT', ), ); } /** * Returns an abridged list of chapter ids for a manga separated by their volumes */ static async getAggregate(id: string, groups?: string[] | Group[], languages?: string[]): Promise { const res = await fetchMD(`/manga/${id}/aggregate`, { groups: groups, translatedLanguage: languages, }); return res.volumes; } /** * Returns an abridged list of chapter ids for this manga separated by their volumes */ async getAggregate(groups?: string[] | Group[], languages?: string[]): Promise { return Manga.getAggregate(this.id, groups, languages); } /** * Makes the logged in user follow or unfollow a manga */ static async changeFollowship(id: string, follow = true): Promise { await fetchMD(`/manga/${id}/follow`, undefined, { method: follow ? 'POST' : 'DELETE' }); } /** * Makes the user follow or unfollow this manga */ async changeFollowship(follow = true): Promise { await Manga.changeFollowship(this.id, follow); } }