JavaScript client for Kitsu

@cgwire/kitsu-client is the JavaScript counterpart of gazu: a client for the API of Kitsu, the collaboration platform for animation and VFX studios. It targets plugin and app authors: browsers, webviews (Tauri, Electron) and Node 22.12 or later.

• Every client is isolated: its own session, requests and event socket.
• Same function names as gazu, in camelCase: all*, get*, new*, update*, remove*.
• Typed: declarations are generated from the JSDoc of the sources.
• ES modules only: CommonJS code can require() it from Node 22.12, and TypeScript 5.9 types it with module set to node20 or nodenext.
• No runtime dependency

Install

npm i @cgwire/kitsu-client
# only if you listen to real-time events:
npm i socket.io-client

It needs Zou 1.0.94 or later, the API server of Kitsu.

For real-time events, pass the io function of socket.io-client: createClient({ host, io }). A bundled app must, since the client loads it by itself only in Node. In bearer mode the events need Node or the main process of Electron; a browser or a webview listens in cookie mode, on the Kitsu origin (see Real-time events).

With Vite, exclude the package from the pre-bundle of the dev server:

// vite.config.js
export default { optimizeDeps: { exclude: ['@cgwire/kitsu-client'] } }

The pre-bundle changes the optional import of socket.io-client into a literal import, and the dev server then cannot resolve it. The package is plain ESM, thus Vite can serve it as it is.

Quick start

With a bot token, the recommended mode for integrations:

import { createClient } from '@cgwire/kitsu-client'

const kitsu = createClient({ host: 'https://kitsu.mystudio.com/api' })
kitsu.setToken(process.env.KITSU_TOKEN)

const projects = await kitsu.project.allOpenProjects()
const shots = await kitsu.shot.allShotsForProject(projects[0])
const tasks = await kitsu.task.allTasksForShot(shots[0])

User credentials, two-factor authentication and cookie mode are covered in Authentication and sessions.

Documentation

• Authentication and sessions
• Conventions and errors
• Working files, uploads and downloads
• Real-time events
• Utilities and smaller bundles
• Development

Contributing

Bug reports go to the issue page of this repository, feature requests to our Canny page. Pull requests follow the C4 contract.

About authors

Kitsu is written by CGWire, a company based in France. We help animation and VFX studios to collaborate better through efficient tooling. Visit cg-wire.com for more information.