Kitsu JSON:API Client

Kitsu is a simple, lightweight, and framework-agnostic JSON:API client designed for kitsu.app and other JSON:API compliant services. It is distributed as a monorepo with two primary packages:

• kitsu: A framework-agnostic client that uses Axios for HTTP requests.
• kitsu-core: Framework-agnostic (de)serialization components. This package is designed to work with any HTTP library of your choice.

Key features include:

• Full JSON:API 1.0 compliance.
• Automatic linking of relationships to data.
• Support for both Node.js and browser environments.

Response Changes

• Headers: Requests now return a headers object alongside data if the API provides them: const { data, headers } = await api.get('products').
• api.self: Now returns data wrapped in a data object to prevent conflicts with the header object: await api.self() returns { data: { ... }, headers?: {} }.

Serialization Changes (PATCH/POST)

Relationships in the body of PATCH and POST requests must now be objects containing either a data object or a data array. This enables support for top-level relationship links and meta objects.

New Input Format Example:

{
  id: '1',
  type: 'libraryEntries',
  user: {
    links: {
      self: '...', 
      related: '...'
    },
    data: { id: '2', type: 'users', name: 'Example' }
  }
}

In 5.0.0, internal functions were moved to a standalone package called kitsu-core. This allows you to use Kitsu's serialization and deserialization logic with other HTTP clients (like got) or via WebSockets.

Removed Features:

• isAuth() was removed. To check authentication with oAuth2, use the expires_in property from your token response to manage the Authorization header manually.

In 9.0.0, kitsu-core was refactored to preserve link objects from the root data object/array and relationships, rather than omitting them.

Key changes in output structure:

• Root links: Available via data.links or data[].links.
• Relationship objects: Accessed via relationshipName.data.id (previously relationshipName.id).
• Relationship arrays: Accessed via relationshipName.data[].id (previously relationshipName[] .id).
• Relationship links: Available via relationshipName.links.

// New Behaviour Output Example
data: {
  id: '1',
  type: 'libraryEntries',
  links: { self: '...' },
  user: {
    links: { self: '...', related: '...' },
    data: { id: '2', type: 'users', name: 'Example' }
  }
}

In kitsu-core version 10.0.0, the compiled output directory changed from lib to dist. Update your import paths accordingly.

For the main package and serialise:

• Use import kitsu from 'kitsu-core'
• Use import { serialise } from 'kitsu-core'

For sub-module imports:

• Replace kitsu-core/lib/... with kitsu-core/... (Node 12+) or kitsu-core/dist/...

// Legacy behaviour
import { serialise } from 'kitsu-core/lib/serialise'

// New behaviour (Node 12+)
import { serialise } from 'kitsu-core/serialise'
// OR
import { serialise } from 'kitsu-core/dist/serialise"

Starting from version 4.0.0, support for Internet Explorer was dropped from the main package. If you need to support IE8+, you must import or require the legacy build instead:

import 'kitsu/lib/legacy' or require('kitsu/lib/legacy').

import 'kitsu/lib/legacy';

Version 8.0.0 dropped Node 8 support (minimum is Node 10) and removed the kitsu/node entry point as it is now identical to kitsu.

Required Changes:

• Replace kitsu/node imports with kitsu.
• Replace kitsu/node/index.mjs imports with kitsu/lib/index.mjs.

In version 10.0.0, the compiled output directory changed from lib to dist. Update your import statements accordingly.

New valid import paths:

• import Kitsu from 'kitsu'
• import Kitsu from 'kitsu/index' (Node 12+)
• import Kitsu from 'kitsu/dist/index'

// New behaviour, any of:
import Kitsu from 'kitsu'
import Kitsu from 'kitsu/index' // Node 12+
import Kitsu from 'kitsu/dist/index'

When creating new test cases for JSON:API compliance, follow this directory structure for each caseName:

• index.js: The entry point for the test case.
• jsonapi.js: Contains the JSON:API structured data.
• kitsu.js: Contains the data specifically consumed by the kitsu client.

The root directory should also contain an index.js to aggregate the cases.

.
|-- caseName
|   |-- index.js
|   |-- jsonapi.js
|   `-- kitsu.js
`-- index.js

When upgrading from 2.x to 3.0.0, the following constructor options were renamed:

• apiUrl is now baseURL
• apiVer is now version

Additionally, in 3.0.0:

• Built-in OAuth2 authentication was removed. Use the client-oauth2 package directly.
• The compact option in whoAmI() was removed.
• Network failure retry ability was removed due to the switch from got to axios.

In 4.0.0, the default behavior for converting model/resource names in request URLs changed from snake_case to kebab-case. You can control this behavior using the resourceCase option in the new Kitsu({ options }) constructor:

• resourceCase: 'kebab' (default): /libraryEntries/1 becomes /library-entries/1.
• resourceCase: 'snake': /libraryEntries/1 becomes /library_entries/1 (reverts to 3.x behavior).
• resourceCase: 'none': /libraryEntries/1 is not modified.