node-catbox

node-catbox A library for interacting with Catbox.moe written in TypeScript with no dependencies.

This library aims to be a sort of successor to https://www.npmjs.com/package/catbox.moe.

Requirements

• >= Node.js 22

Installation

npm i node-catbox
yarn add node-catbox
bun add node-catbox

Usage

Uploading to Catbox

import { Catbox } from 'node-catbox';

const catbox = new Catbox();

try {
	const response = await catbox.uploadFile({
		path: '/path/to/my/file.ext'
	});
	// or to upload from direct file URL
	const response = await catbox.uploadURL({
		url: 'https://i.imgur.com/8rR6IZn.png'
	});

	console.log(response); // -> https://files.catbox.moe/XXXXX.ext
} catch (err) {
	console.error(err); // -> error message from server
}

// ---

// NEW in v3.4.0

const stream = createReadStream('/path/to/my/file.ext');
await catbox.uploadFileStream({
	stream,
	filename: 'file.ext'
});

User Hash

Some operations require your account's user hash which can be set on instantiation with

const catbox = new Catbox('098f6bcd4621d373cade4e832');

... or later with

const catbox = new Catbox();

catbox.setUserHash('098f6bcd4621d373cade4e832');

Deleting Files

import { Catbox } from 'node-catbox';

// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');

await catbox.deleteFiles({
	files: ['XXXXX.ext']
});

Creating an album

import { Catbox } from 'node-catbox';

// user hash only required if you plan to edit or delete the album later
const catbox = new Catbox('098f6bcd4621d373cade4e832');

const albumURL = await catbox.createAlbum({
	title: 'album title',
	description: 'album description',
	files: ['XXXXX.ext'] // optional
});

Editing an album

import { Catbox } from 'node-catbox';

// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');

await catbox.editAlbum({
	id: 'YYYYY',
	title: 'new title',
	description: 'new description',
	files:  ['WWWWW.ext', 'VVVVV.ext'] // optional
});

Warning This is a potentially destructive method where values are applied to the album directly. Consider using the method below if you are only adding/removing files from an album.

Adding and removing files from an album

import { Catbox } from 'node-catbox';

// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');

await catbox.addFilesToAlbum({
	id: 'YYYYY',
	files: ['ZZZZZ.ext']
});
await catbox.removeFilesFromAlbum({
	id: 'YYYYY',
	files: ['ZZZZZ.ext']
});

Deleting an album

import { Catbox } from 'node-catbox';

// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');

await catbox.removeAlbum({
	id: 'YYYYY'
});

Uploading to Litterbox

import { Litterbox } from 'node-catbox';

const litterbox = new Litterbox();

await litterbox.uploadFile({
	path: '/path/to/my/file.ext',
	duration: '12h' // or omit to default to 1h
});

// ---

import { FileLifetime } from 'node-catbox';

// Using an enum for duration
await litterbox.uploadFile({
	path: '/path/to/my/file.ext',
	duration: FileLifetime.TwelveHours
});

// ---

// NEW in v3.4.0

const stream = createReadStream('/path/to/my/file.ext');
await litterbox.uploadFileStream({
	stream,
	filename: 'file.ext'
});

// ---

// NEW in v4.1.0

import { FileNameLength } from 'node-catbox';

// Using an enum for duration
await litterbox.uploadFile({
	path: '/path/to/my/file.ext',
	fileNameLength: FileNameLength.Sixteen
});

Events

As of 4.0.0, both Catbox and Litterbox emit a request and response event as well as events specific to each class:

import { Catbox, Litterbox } from 'node-catbox';

const catbox    = new Catbox();
const litterbox = new Litterbox();

// `request` is a sanitized read-only snapshot (no raw body)
catbox.on('request', request => console.log(request.method, request.hasBody));
// `response` is a read-only snapshot
catbox.on('response', response => console.log(`${response.status} - ${response.statusText}`));

litterbox.on('uploadingFile', (filepath, duration) => console.log('Uploading file', filepath, 'with a duration of', duration));

Testing

Before you test the library you need to provide your Catbox account's user hash. Create a .env file in the project root and set the USER_HASH value to your account's user hash.

By default, network-dependent integration tests are skipped to avoid flaky failures and rate limits.

• Run default deterministic test suite: yarn test
• Run full suite including live integration tests with RUN_INTEGRATION_TESTS=1

Use of AI Tools

This project does not include any source code generated by artificial intelligence tools. All application logic, implementation, and architectural decisions are authored and maintained by human contributors, flaws and all.

AI tools may be used in a limited, non-code capacity to assist with:

• Grammar and spelling checks
• Wording improvements for documentation
• Changelog entry refinement
• README and other markdown documentation editing

No AI-generated content is used for:

• Application source code
• Build scripts or tooling
• Configuration logic

Any use of AI is strictly limited to improving clarity and readability of written documentation, and all changes are reviewed before being committed.