MAL Management JS

> Note: This repo is still in aggressive development.

At first with the roll out of new MAL v2 api, I just want to play around th api itself however I find it inconvenient to do different call to each of items I needed off the api.

These is heavily inspired from contentful-management.js, and actually created because I want to manage my anime using a globally installed CLI . But in order to create a cli, a good wrapper that is easy to use, fluent, developer friendly and removes the pain staking part of api call creation is needed, hence the project is born.

Current Features available
- Public Anime
- Public Manga
- Public Forum
- User Profile (Authenticated)

In flight
- Update User Manga and Anime Entries

Usage

1. Instantiating the Client
2. Anime List
3. Anime Detail
4. Anime Ranking List
5. Seasonal Anime List
6. Manga List
7. Manga Detail
8. Manga Ranking List
9. Forum Boards List
10. Forum Topics List
11. Forum Topic Detail
12. User Profile
13. Logging
14. Field Cheatsheet
15. Gotchas
16. Future Plans

Instantiating the Client

For accessing public data only
``

javascript

import mal from 'mal-management-js'

...

const client = mal.createClient({

  clientId: CLIENT_ID

})





If you need to use authenticated api endpoints.

javascript

import mal from 'mal-management-js'

...

const client = mal.createClient({

  accessToken: ACCESS_TOKEN,

})





CommonJS

javascript

const mal = require('mal-management-js')

...

const client = mal.createClient({

  clientId: CLIENT_ID

})





NSFW



By default NSFW are automatically filtered, if you want to include nsfw entries, you could instantiate the

createClient with .allowNSFW()

 extension. This setting will affect all of subsequent functions and is useful for setting general NSFW rule.

javascript

const client = mal.createClient({

  clientId: CLIENT_ID

}).allowNSFW()



Alternatively, you could also give it to

CreateClientOptions as a nsfw

 option

javascript

const client = mal.createClient({

  clientId: CLIENT_ID,

  nsfw: true

})



$3

| Function  | Description |

| ------------- | ------------- |

| .allowNSFW()  | Allows showing of nsfw entries ( ͡° ͜ʖ ͡°)  |

| .setRequestLogger(request=> void)  | Add a custom request logger (See logging)  |

| .setResponseLogger(request=> void)  | Add a custom response logger  (See logging)  |








Getting Anime List



Using

async await

typescript

const animes: Anime[] = await client

  .getAnime({ q: 'Jujutsu Kaisen', fields:[...] })





Using

`Promise`

javascript

client.getAnime({ q: 'Jujutsu Kaisen' })

  .then(animes => console.log(animes))



Both of approach mentioned can be chained with

.catch

 for error busting and such.





Full Configuration Options (AnimeListOptions)





| Options  | Description |

| ------------- | ------------- |

| q  | Search String |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet |

| nsfw (optional)  | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request  |

| limit (optional)  | Pagination |

| offset (optional)  | Pagination |














Getting Anime Detail



For example you just want to get the detail of the first result from

getAnime()

.

You could chain it like this

javascript

const animes = await client

  .getAnime({ q: 'Jujutsu Kaisen' })

const anime = await animes[0].getDetail()



You could also configure the fields you want to show using

fields

 options

javascript

const animes = await client

  .getAnime({ q: 'Jujutsu Kaisen' })

const anime = await animes[0].getDetail({fields: [...]})





Alternatively If you have the

 of the anime, you could directly get the anime details using client

javascript

const animeDetail = await client

.getAnimeDetail({

    id: 30276,

    // Using TS Enums

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date], 

    // Or using string

    // fields:  ['alternative_titles', 'start_date']

})







Full Configuration Options (AnimeDetailOptions)





| Options  | Description |

| ------------- | ------------- |

| id  | anime id |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet














Getting Anime Ranking List

javascript

const animeRanking = await client

  .getAnimeRanking({

    ranking_type: 'airing', 

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called AnimeRankingType

typescript

type AnimeRankingType = 'all' | 'airing' |'upcoming' |'tv' |'ova' |'movie' | 'special' |'bypopularity' |'favorite'



Full Configuration Options (AnimeRankingListOptions)

| Options | Description | | ------------- | ------------- | | ranking_type | Specifying the ranking criteria SeeAnimeRankingType| | fields (optional) | Use to add additional fields the api should return. See field cheatsheet | nsfw (optional) | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request | | limit (optional) | Pagination | | offset (optional) | Pagination |










Getting Seasonal Anime List

javascript

const animeSeasonal = await client

  .getAnimeSeasonal({

    year: 2020,

    season: 'fall',

    sort: 'anime_score',

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called AnimeSeason and AnimeSortType

typescript

type AnimeSeason = 'winter' | 'spring' | 'summer' | 'fall'



type AnimeSortType = 'anime_score' | 'anime_num_list_users'



Full Configuration Options (AnimeSeasonalListOptions)

| Options | Description | | ------------- | ------------- | | year | target year | | season | Specify what airing season SeeAnimeSeason| | sort | Specify what sort criteria. SeeAnimeSortType| | fields (optional) | Use to add additional fields the api should return. See field cheatsheet | nsfw (optional) | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request | | limit (optional) | Pagination | | offset (optional) | Pagination |










Getting Manga List



Using async await

typescript

const mangas: Manga[] = await client

  .getManga({ q: 'Jujutsu Kaisen' })





Using Promise

javascript

client.getManga({ q: 'Jujutsu Kaisen' }).then(mangas => console.log(mangas))



Both of approach mentioned can be chained with

.catch

 for error busting and such.

Specifiying

Fields

 are also available.





Full Configuration Options (MangaListOptions)





| Options  | Description |

| ------------- | ------------- |

| q  | Search String |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet |

| nsfw (optional)  | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request  |

| limit (optional)  | Pagination |

| offset (optional)  | Pagination |














Getting Manga Detail



For example you just want to get the detail of the first result from

getManga()

.

You could chain it like this

javascript

const mangas = await client

  .getManga({ q: 'Jujutsu Kaisen' })

const manga = mangas[0].getDetail()



You could also configure the fields you want to show using

fields

 options

javascript

const mangas = await client

  .getManga({ q: 'Jujutsu Kaisen' })

const manga =  await mangas[0].getDetail({fields: [...]})





Alternatively If you have the

 of the anime, you could directly get the anime details using client

javascript

const mangaDetail = await client

.getMangaDetail({

    id: 30276,

    // Using TS Enums

    fields: [MangaFields.mean,

        MangaFields.num_chapters,

        MangaFields.media_type], 

    // Or using string

    // fields:  ['alternative_titles', 'start_date']

})







Full Configuration Options (MangaDetailOptions)





| Options  | Description |

| ------------- | ------------- |

| id  | manga id |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet














Getting Manga Ranking List

javascript

const mangaRanking = await client

  .getMangaRanking({

    ranking_type: 'all', 

    fields: [...],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called MangaRankingType

typescript

export type MangaRankingType = 'all' | 'manga' | 'novels' | 'oneshots' |'doujin' | 'manhwa' | 'manhua' | 'bypopularity'| 'favorite'



Full Configuration Options (MangaRankingListOptions)

| Options | Description | | ------------- | ------------- | | ranking_type | Specifying the ranking criteria SeeMangaRankingType| | fields (optional) | Use to add additional fields the api should return. See field cheatsheet | nsfw (optional) | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request | | limit (optional) | Pagination | | offset (optional) | Pagination |








Getting Main Forum Boards

This will return all of Main Forum Boards Categories

typescript

const forumBoards: ForumBoardCategory[] = await client.getForumBoard();





> Note that at the moment MAL only return

Main Boards. Hence reason that Subboards

 is not yet available.








Getting Forum Topics



This will query against all Board Topics

typescript

const forumTopics = await client.getForumTopics({

  q: "love"

})



If you want to specify a board or a subboard

typescript

const forumTopics = await client.getForumTopics({

  board_id: 2,

  subboard_id: 3,

  q: "love"

})



Full Configuration Options (ForumTopicOptions)

| Options | Description | | ------------- | ------------- | | board_id | Id of the board topic you want to search against | | subboard_id | Id of the subboard topic you want to search against | | sort | MAL only hasrecentavailable at the moment | | q | Search String | | topic_user_name | Use to filter using topic_user_name | | user_name | Use to filter using user_name that participated | | limit | Pagination | | offset | Pagination |










Getting Forum Topic Detail

This gives details about all of posts, poll and title related to the topic 



Similar to Anime and Manga, you could also get a injected

getDetail()

 to each of instances of Forum Topic

typescript

const forumTopics = await client.getForumTopics({

  q: "love"

})

const oregairu = await forumTopics[0].getDetail()





Or if you have the

topic id

typescript

  const forumDetail = await client.getForumTopicDetail({

    id: 614681, //topic id

    limit: 10,

  })

  console.log('OreGairu ', forumDetail)





Full Configuration Options (ForumTopicDetailOptions)







| Options  | Description |

| ------------- | ------------- |

| id  | Id of the topic.  |

| limit  | Pagination |

| offset  | Pagination |












Getting User Profile 



> AUTHENTICATION NEEDED !  Client must be instantiated with

accessToken

 option.



This will get the user's profile.

typescript

const userProfile = await client.getUserProfile()



Or if you want to specify additional user fields

typescript

const userProfile = await client.getUserProfile({

  // Using TS enums

  fields: [UserFields.anime_statistics, UserFields.is_supporter, UserFields.time_zone]

  // Works also using string

  // fields: ['anime_statistics', 'is_supporter', 'time_zone']

})



> Note: Only the current Authenticated user are allowed to get profile. No official endpoint yet are available for public profile.








Logging



mal-management-js offers a way to logged both of request and response using a

extension

 function which is you can chain to client. This is useful for apps that is running on backend that needs robusts logging. You could implement a file logging by hooking into this.



Sample Request logging

javascript

const client = mal.createClient({

  accessToken: ACCESS_TOKEN,

}).setRequestLogger(request => {

  console.log('REQUEST URL', request.url)

  console.log('REQUEST QUERIES', request.params)

})














Field Cheatsheet



$3









 
  



  - alternative_titles

  - start_date

  - end_date

  - synopsis

  - mean

  - rank

  - popularity

  - num_list_users

  - num_scoring_users

  - nsfw

  - created_at  



  
  



  - media_type

  - status

  - genres

  - pictures

  - background

  - related_anime

  - related_manga

  - recommendations

  - statistics

  - my_list_status    



  
 


 





$3



  - num_episodes

  - start_season

  - broadcast

  - source

  - average_episode_duration

  - rating

  - studios



$3



  - num_volumes

  - num_chapters

  - 'authors{first_name,last_name}'

  - 'serialization{name}'







Gotchas



$3



> Fields are way to control what

fields

 are going to be responsed by MAL API. 



At default

id, title, main_picture will always be present regardless if you put it at fields

 or not.





Another thing is some of the

field options are only available to details

 endpoint

examples of such are

- picture

- background

- related_anime

- related_manga

- recommendations

- statistics



User Fields



There are also default Fields for User Profile that will always be present irregardless if you added it at

fields

 options, namely.

- id

- name

- picture

- gender

- birthday

- joined_at

- location



Future Plans



Although currently APIs that MAL offers is very limited. 



The aim of this library is to be

Backend and Scripts First

, while technically you can use this at Front end space. The rationale was to create a wrapper tool to navigate and manage MyAnimeList via scripts and also to ease the backend integration.  



For example, if in

FUTURE

 MAL officially release an api for a Anime's characters.



This wrapper could end with api of

javascript

const anime = client.getAnimeDetail({id: 30276})

const characters = anime.getCharacters()

LICENSE

MIT

MAL Management JS

Usage

Instantiating the Client

For accessing public data only
``

javascript

import mal from 'mal-management-js'

...

const client = mal.createClient({

  clientId: CLIENT_ID

})





If you need to use authenticated api endpoints.

javascript

import mal from 'mal-management-js'

...

const client = mal.createClient({

  accessToken: ACCESS_TOKEN,

})





CommonJS

javascript

const mal = require('mal-management-js')

...

const client = mal.createClient({

  clientId: CLIENT_ID

})





NSFW



By default NSFW are automatically filtered, if you want to include nsfw entries, you could instantiate the

createClient with .allowNSFW()

 extension. This setting will affect all of subsequent functions and is useful for setting general NSFW rule.

javascript

const client = mal.createClient({

  clientId: CLIENT_ID

}).allowNSFW()



Alternatively, you could also give it to

CreateClientOptions as a nsfw

 option

javascript

const client = mal.createClient({

  clientId: CLIENT_ID,

  nsfw: true

})



$3

| Function  | Description |

| ------------- | ------------- |

| .allowNSFW()  | Allows showing of nsfw entries ( ͡° ͜ʖ ͡°)  |

| .setRequestLogger(request=> void)  | Add a custom request logger (See logging)  |

| .setResponseLogger(request=> void)  | Add a custom response logger  (See logging)  |








Getting Anime List



Using

async await

typescript

const animes: Anime[] = await client

  .getAnime({ q: 'Jujutsu Kaisen', fields:[...] })





Using

`Promise`

javascript

client.getAnime({ q: 'Jujutsu Kaisen' })

  .then(animes => console.log(animes))



Both of approach mentioned can be chained with

.catch

 for error busting and such.





Full Configuration Options (AnimeListOptions)





| Options  | Description |

| ------------- | ------------- |

| q  | Search String |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet |

| nsfw (optional)  | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request  |

| limit (optional)  | Pagination |

| offset (optional)  | Pagination |














Getting Anime Detail



For example you just want to get the detail of the first result from

getAnime()

.

You could chain it like this

javascript

const animes = await client

  .getAnime({ q: 'Jujutsu Kaisen' })

const anime = await animes[0].getDetail()



You could also configure the fields you want to show using

fields

 options

javascript

const animes = await client

  .getAnime({ q: 'Jujutsu Kaisen' })

const anime = await animes[0].getDetail({fields: [...]})





Alternatively If you have the

 of the anime, you could directly get the anime details using client

javascript

const animeDetail = await client

.getAnimeDetail({

    id: 30276,

    // Using TS Enums

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date], 

    // Or using string

    // fields:  ['alternative_titles', 'start_date']

})







Full Configuration Options (AnimeDetailOptions)





| Options  | Description |

| ------------- | ------------- |

| id  | anime id |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet














Getting Anime Ranking List

javascript

const animeRanking = await client

  .getAnimeRanking({

    ranking_type: 'airing', 

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called AnimeRankingType

typescript

type AnimeRankingType = 'all' | 'airing' |'upcoming' |'tv' |'ova' |'movie' | 'special' |'bypopularity' |'favorite'



Full Configuration Options (AnimeRankingListOptions)










Getting Seasonal Anime List

javascript

const animeSeasonal = await client

  .getAnimeSeasonal({

    year: 2020,

    season: 'fall',

    sort: 'anime_score',

    fields: [AnimeFields.alternative_titles, AnimeFields.start_date],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called AnimeSeason and AnimeSortType

typescript

type AnimeSeason = 'winter' | 'spring' | 'summer' | 'fall'



type AnimeSortType = 'anime_score' | 'anime_num_list_users'



Full Configuration Options (AnimeSeasonalListOptions)










Getting Manga List



Using async await

typescript

const mangas: Manga[] = await client

  .getManga({ q: 'Jujutsu Kaisen' })





Using Promise

javascript

client.getManga({ q: 'Jujutsu Kaisen' }).then(mangas => console.log(mangas))



Both of approach mentioned can be chained with

.catch

 for error busting and such.

Specifiying

Fields

 are also available.





Full Configuration Options (MangaListOptions)





| Options  | Description |

| ------------- | ------------- |

| q  | Search String |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet |

| nsfw (optional)  | If global allowNSFW() is not present, you could use this option to explicitly allow nsfw for the current request  |

| limit (optional)  | Pagination |

| offset (optional)  | Pagination |














Getting Manga Detail



For example you just want to get the detail of the first result from

getManga()

.

You could chain it like this

javascript

const mangas = await client

  .getManga({ q: 'Jujutsu Kaisen' })

const manga = mangas[0].getDetail()



You could also configure the fields you want to show using

fields

 options

javascript

const mangas = await client

  .getManga({ q: 'Jujutsu Kaisen' })

const manga =  await mangas[0].getDetail({fields: [...]})





Alternatively If you have the

 of the anime, you could directly get the anime details using client

javascript

const mangaDetail = await client

.getMangaDetail({

    id: 30276,

    // Using TS Enums

    fields: [MangaFields.mean,

        MangaFields.num_chapters,

        MangaFields.media_type], 

    // Or using string

    // fields:  ['alternative_titles', 'start_date']

})







Full Configuration Options (MangaDetailOptions)





| Options  | Description |

| ------------- | ------------- |

| id  | manga id |

| fields (optional)  |  Use to add additional fields the api should return. See field cheatsheet














Getting Manga Ranking List

javascript

const mangaRanking = await client

  .getMangaRanking({

    ranking_type: 'all', 

    fields: [...],

  })



Pro-tip: If you are on typescript 

There's a exposed Typescript

Type called MangaRankingType

typescript

export type MangaRankingType = 'all' | 'manga' | 'novels' | 'oneshots' |'doujin' | 'manhwa' | 'manhua' | 'bypopularity'| 'favorite'



Full Configuration Options (MangaRankingListOptions)








Getting Main Forum Boards

This will return all of Main Forum Boards Categories

typescript

const forumBoards: ForumBoardCategory[] = await client.getForumBoard();





> Note that at the moment MAL only return

Main Boards. Hence reason that Subboards

 is not yet available.








Getting Forum Topics



This will query against all Board Topics

typescript

const forumTopics = await client.getForumTopics({

  q: "love"

})



If you want to specify a board or a subboard

typescript

const forumTopics = await client.getForumTopics({

  board_id: 2,

  subboard_id: 3,

  q: "love"

})



Full Configuration Options (ForumTopicOptions)










Getting Forum Topic Detail

This gives details about all of posts, poll and title related to the topic 



Similar to Anime and Manga, you could also get a injected

getDetail()

 to each of instances of Forum Topic

typescript

const forumTopics = await client.getForumTopics({

  q: "love"

})

const oregairu = await forumTopics[0].getDetail()





Or if you have the

topic id

typescript

  const forumDetail = await client.getForumTopicDetail({

    id: 614681, //topic id

    limit: 10,

  })

  console.log('OreGairu ', forumDetail)





Full Configuration Options (ForumTopicDetailOptions)







| Options  | Description |

| ------------- | ------------- |

| id  | Id of the topic.  |

| limit  | Pagination |

| offset  | Pagination |












Getting User Profile 



> AUTHENTICATION NEEDED !  Client must be instantiated with

accessToken

 option.



This will get the user's profile.

typescript

const userProfile = await client.getUserProfile()



Or if you want to specify additional user fields

typescript

const userProfile = await client.getUserProfile({

  // Using TS enums

  fields: [UserFields.anime_statistics, UserFields.is_supporter, UserFields.time_zone]

  // Works also using string

  // fields: ['anime_statistics', 'is_supporter', 'time_zone']

})



> Note: Only the current Authenticated user are allowed to get profile. No official endpoint yet are available for public profile.








Logging



mal-management-js offers a way to logged both of request and response using a

extension

 function which is you can chain to client. This is useful for apps that is running on backend that needs robusts logging. You could implement a file logging by hooking into this.



Sample Request logging

javascript

const client = mal.createClient({

  accessToken: ACCESS_TOKEN,

}).setRequestLogger(request => {

  console.log('REQUEST URL', request.url)

  console.log('REQUEST QUERIES', request.params)

})














Field Cheatsheet



$3









 
  



  - alternative_titles

  - start_date

  - end_date

  - synopsis

  - mean

  - rank

  - popularity

  - num_list_users

  - num_scoring_users

  - nsfw

  - created_at  



  
  



  - media_type

  - status

  - genres

  - pictures

  - background

  - related_anime

  - related_manga

  - recommendations

  - statistics

  - my_list_status    



  
 


 





$3



  - num_episodes

  - start_season

  - broadcast

  - source

  - average_episode_duration

  - rating

  - studios



$3



  - num_volumes

  - num_chapters

  - 'authors{first_name,last_name}'

  - 'serialization{name}'







Gotchas



$3



> Fields are way to control what

fields

 are going to be responsed by MAL API. 



At default

id, title, main_picture will always be present regardless if you put it at fields

 or not.





Another thing is some of the

field options are only available to details

 endpoint

examples of such are

- picture

- background

- related_anime

- related_manga

- recommendations

- statistics



User Fields



There are also default Fields for User Profile that will always be present irregardless if you added it at

fields

 options, namely.

- id

- name

- picture

- gender

- birthday

- joined_at

- location



Future Plans



Although currently APIs that MAL offers is very limited. 



The aim of this library is to be

Backend and Scripts First

, while technically you can use this at Front end space. The rationale was to create a wrapper tool to navigate and manage MyAnimeList via scripts and also to ease the backend integration.  



For example, if in

FUTURE

 MAL officially release an api for a Anime's characters.



This wrapper could end with api of

javascript

const anime = client.getAnimeDetail({id: 30276})

const characters = anime.getCharacters()

LICENSE

MIT