anilink-api-wrapper 1.29.2 → 2.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 RLAlpha49
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 RLAlpha49
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,241 +1,71 @@
-# AniLink
-
-For full documentation on methods and parameters, please refer to the [AniLink documentation](https://rlalpha49.github.io/AniLink/).
-
-AniLink is a TypeScript library for interacting with the AniList API. It provides methods for querying and mutating data, making it easier to integrate AniList's features into your own applications.
-
-## Installation
-
-To install AniLink, you can use npm or yarn.:
-
-```bash
-npm install anilink-api-wrapper
-```
-
-or
-
-```bash
-yarn add anilink-api-wrapper
-```
-
-## Initialization
-
-### AniList
-
-To start using AniLink, you need to import it and initialize it with an optional authentication token. You can get an authentication token by registering your application on the AniList website.
-
-#### Typescript
-
-```typescript
-import AniLink from 'anilink-api-wrapper';
-```
-
-#### Javascript
-
-```javascript
-const AniLink = require('anilink-api-wrapper');
-```
-
-#### Initialization
-
-```typescript
-const authToken = 'your-auth-token';
-const aniLink = new AniLink(authToken);
-```
-
-You can also initialize AniLink without an authentication token
-
-```typescript
-const aniLink = new AniLink();
-```
-
-## AniList API
-
-### Structure
-
-AniLink for AniList is divided into two main sections: `anilist.query` and `anilist.mutation`. The `anilist.query` section contains methods for querying data from the AniList API, while the `anilist.mutation` section contains methods for mutating data.
-
-#### Custom Queries and Mutations
-
-If needed there is a custom section `anilist.custom` that allows the user to pass a custom query or mutation to the AniList API.
-
-The method accepts two parameters: the query or mutation string and an optional variables object.
-
-```typescript
-const viewer = await aniLink.anilist.custom('query {Viewer {id}}');
-
-const mutation = 'mutation ($about: String) {UpdateUser (about: $about) {id}}';
-const variables = { about: "New about text" };
-const response = await aniLink.anilist.custom(mutation, variables);
-```
-
-#### Query Methods
-
-The `anilist.query` section is further divided into main query methods and page query methods. The main query methods return a single piece of data, while the page query methods return pages of data.
-
-List of main query methods in `anilist.query`:
-
-- user
-- media
-- mediaTrend
-- airingSchedule
-- character
-- staff
-- mediaList
-- mediaListCollection
-- genreCollection
-- mediaTagCollection
-- viewer
-- notification
-- studio
-- review
-- activity
-- activityReply
-- following
-- follower
-- thread
-- threadComment
-- recommendation
-- markdown
-- aniChartUser
-- siteStatistics
-- externalLinkSourceCollection
-
-List of page query methods in `anilist.query.page`:
-
-- users
-- medias
-- characters
-- staffs
-- studios
-- mediaLists
-- airingSchedules
-- mediaTrends
-- notifications
-- followers
-- following
-- activities
-- activityReplies
-- threads
-- threadComments
-- reviews
-- recommendations
-- likes
-
-#### Mutation Methods
-
-List of methods in `anilist.mutation`:
-
-- updateUser
-- saveMediaListEntry
-- updateMediaListEntries
-- deleteMediaListEntries
-- deleteCustomLists
-- saveTextActivity
-- saveMessageActivity
-- deleteActivity
-- toggleActivityPin
-- toggleActivitySubscription
-- saveActivityReply
-- deleteActivityReply
-- toggleLike
-- toggleLikeV2
-- toggleFollow
-- toggleFavourite
-- updateFavouriteOrder
-- saveReview
-- deleteReview
-- saveRecommendation
-- saveThread
-- deleteThread
-- toggleThreadSubscription
-- saveThreadComment
-- deleteThreadComment
-- updateAniChartSettings
-- updateAniChartHighlights
-
-### Error Handling
-
-AniLink will throw an error if the AniList API returns an error. You can catch these errors using a try-catch block.
-
-```typescript
-try {
-  const user = await aniLink.anilist.query.user({id: 542244});
-  console.log(user);
-} catch (error) {
-  console.error(error);
-}
-```
-
-This includes status codes and error messages returned by the AniList API. Here is an example rate limit handler to catch the errors thrown by AniLink:
-
-##### Typescript
-
-```typescript
-async function handleRateLimit(apiCall: () => Promise<any>, retryAfter = 60) {
-  try {
-    let response;
-    try {
-      response = await apiCall();
-    } catch (error) {
-      throw error;
-    }
-    console.log(response.data);
-    return response;
-  } catch (error: any) {
-    if (error.response && error.response.status === 429) {
-      console.log('Rate limit exceeded, waiting for 1 minute before retrying...');
-      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
-      console.log('Retrying...');
-      return handleRateLimit(apiCall, retryAfter);
-    } else {
-      if (error.response && error.response.data) {
-        throw error.response.data;
-      } else {
-        throw error.response || error;
-      }
-    }
-  }
-}
-```
-
-##### Javascript
-
-```javascript
-async function handleRateLimit(apiCall, retryAfter = 60) {
-    // Same as above
-}
-```
-
-The possible error codes returned by the AniList API are:
-- 400: Bad Request (e.g. missing variables, invalid variables, or invalid query)
-- 401: Unauthorized (e.g. invalid authentication token)
-- 404: Not Found (e.g. user not found)
-- 429: Too Many Requests (e.g. rate limit exceeded)
-- 500: Internal Server Error (e.g. AniList server error)
-
-#### Missing or Invalid Variables
-
-AniLink will also throw an error if any variables are missing or invalid. For example, if you try to query a user providing a string instead of a number for ID, AniLink will throw an error. Most variables are optional however there a few that are required.
-```typescript
-try {
-  const user = await aniLink.anilist.query.user({id: '542244'});
-  console.log(user);
-} catch (error) {
-  console.error(error);
-}
-```
-
-Example Error Thrown:
-
-```typescript
-  Invalid id: 542244. Expected type: number
-```
-
-### Examples
-
-See the [ANILIST_API_EXAMPLES](https://github.com/RLAlpha49/AniLink/blob/master/Examples/ANILIST_API_EXAMPLES.md) for examples of how to use AniLink to interact with the AniList API.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](https://github.com/RLAlpha49/AniLink/blob/master/LICENSE) file for details.
+<p align="center">
+  <img src="docs-src/public/logo.png" alt="AniLink" width="256" />
+</p>
+
+<h1 align="center">AniLink</h1>
+
+[![npm version](https://img.shields.io/npm/v/anilink-api-wrapper.svg)](https://www.npmjs.com/package/anilink-api-wrapper)
+[![npm downloads](https://img.shields.io/npm/dm/anilink-api-wrapper.svg)](https://www.npmjs.com/package/anilink-api-wrapper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/RLAlpha49/AniLink/blob/master/LICENSE)
+[![CI](https://github.com/RLAlpha49/AniLink/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/RLAlpha49/AniLink/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/RLAlpha49/AniLink/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/RLAlpha49/AniLink/actions/workflows/codeql.yml)
+[![Documentation](https://img.shields.io/website?url=https%3A%2F%2Fanilink.alpha49.com%2F&label=docs)](https://anilink.alpha49.com/)
+
+A typed TypeScript wrapper for the [AniList GraphQL API](https://docs.anilist.co/) and the [MyAnimeList REST API](https://myanimelist.net/apiconfig/references/api/v2). One class, two isolated provider surfaces, normalized errors, retries, and a generated operation reference.
+
+## Quickstart
+
+```bash
+npm install anilink-api-wrapper
+```
+
+```typescript
+import { AniLink } from "anilink-api-wrapper";
+
+// AniList (GraphQL) — public queries need no token
+const aniLink = new AniLink();
+const anime = await aniLink.anilist.query.media({ id: 21, type: "ANIME" });
+
+// MyAnimeList (REST) — isolated credential slot
+const client = new AniLink({ mal: { accessToken: "mal-token" } });
+const malAnime = await client.mal.anime.get(21, { fields: ["id", "title", "main_picture"] });
+```
+
+## What you can do
+
+| Provider | Namespace | Capabilities |
+| --- | --- | --- |
+| **AniList** | `aniLink.anilist` | Queries, page queries, mutations, pagination helpers, `custom()`, data helpers |
+| **MyAnimeList** | `aniLink.mal` | `anime.get` and `user.me` REST reads with field selection |
+
+Both surfaces share one transport layer (timeouts, retries, pacing, circuit breaker, hooks) while keeping credentials and transport settings isolated per provider slot.
+
+## Documentation
+
+| Surface | Start here |
+| --- | --- |
+| **Guides** | [Introduction](https://anilink.alpha49.com/introduction) · [Getting started](https://anilink.alpha49.com/getting-started) · [Provider configuration](https://anilink.alpha49.com/provider-configuration) · [Per-request options](https://anilink.alpha49.com/per-request-options) · [Error handling](https://anilink.alpha49.com/error-handling) · [Retries & resilience](https://anilink.alpha49.com/retries-and-resilience) · [Cancellation & timeouts](https://anilink.alpha49.com/cancellation-and-timeouts) · [Observability](https://anilink.alpha49.com/observability) · [Recipes](https://anilink.alpha49.com/recipes) · [TypeScript patterns](https://anilink.alpha49.com/typescript-patterns) · [Troubleshooting](https://anilink.alpha49.com/troubleshooting) |
+| **AniList guides** | [Authentication](https://anilink.alpha49.com/guides/anilist/authentication) · [Client configuration](https://anilink.alpha49.com/guides/anilist/configuration) · [Querying](https://anilink.alpha49.com/guides/anilist/querying) · [Page queries](https://anilink.alpha49.com/guides/anilist/page-queries) · [Pagination](https://anilink.alpha49.com/guides/anilist/pagination) · [Mutations](https://anilink.alpha49.com/guides/anilist/mutations) · [Custom queries](https://anilink.alpha49.com/guides/anilist/custom-queries) · [Helpers](https://anilink.alpha49.com/guides/anilist/helpers) |
+| **MAL guides** | [Authentication](https://anilink.alpha49.com/guides/mal/authentication) · [Client configuration](https://anilink.alpha49.com/guides/mal/configuration) · [Operations](https://anilink.alpha49.com/guides/mal/operations) |
+| **Operation reference** | [Overview](https://anilink.alpha49.com/operations/) · [AniList catalog](https://anilink.alpha49.com/operations/anilist) · [MAL catalog](https://anilink.alpha49.com/operations/mal) |
+| **API reference (TypeDoc)** | [AniLink](https://anilink.alpha49.com/classes/AniLink.AniLink.html) — full generated reference at the [docs root](https://anilink.alpha49.com/) |
+
+## Development
+
+```bash
+npm install               # install dependencies
+npm run check             # typecheck, lint, tests, format, JSDoc, api-compare, build
+npm run docs:generate     # TypeDoc + operation reference + guides site into docs/
+npm run docs:dev          # serve the guides site locally
+```
+
+See the [contributing guide](CONTRIBUTING.md) for workflow details.
+
+## Resources
+
+- [Changelog](CHANGELOG.md) and [GitHub Releases](https://github.com/RLAlpha49/AniLink/releases)
+- [Contributing guide](CONTRIBUTING.md)
+
+## License
+
+[MIT](https://github.com/RLAlpha49/AniLink/blob/master/LICENSE)