|
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.
- Catbox uploads by file path, direct URL, and stream
- Litterbox uploads by file path and stream with configurable lifetime
- Catbox album management (create, edit, add/remove files, delete)
- Native
EventEmitterevents - Built-in timeout and retry handling for transient request failures
- >= Node.js 22
npm i node-catbox
yarn add node-catbox
bun add node-catboximport { Catbox } from 'node-catbox';
const catbox = new Catbox();
try {
const response = await catbox.uploadFile({
path: '/path/to/my/file.ext',
// NEW in v4.2.0 (optional)
// default: 200 * 1024 * 1024 (200 MB)
maxFileBytes: 200 * 1024 * 1024
});
// 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',
// NEW in v4.2.0 (optional)
// default: 200 * 1024 * 1024 (200 MB)
maxStreamBytes: 200 * 1024 * 1024
});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');import { Catbox } from 'node-catbox';
// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');
await catbox.deleteFiles({
files: ['XXXXX.ext']
});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
});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.
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']
});import { Catbox } from 'node-catbox';
// user hash required
const catbox = new Catbox('098f6bcd4621d373cade4e832');
await catbox.removeAlbum({
id: 'YYYYY'
});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
// NEW in v4.1.0 (optional)
// FileNameLength.Six | FileNameLength.Sixteen
fileNameLength: 16,
// NEW in v4.2.0 (optional)
// default: 1024 * 1024 * 1024 (1 GB)
maxFileBytes: 1024 * 1024 * 1024
});
// ---
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 file name length
await litterbox.uploadFile({
path: '/path/to/my/file.ext',
fileNameLength: FileNameLength.Sixteen
});As of v4.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));As of v4.2.0, request snapshots are explicitly sanitized and do not expose raw request body data (including any userhash values).
Catbox-specific events:
uploadingURLuploadingFileuploadingStreamdeletingFilescreatingAlbumeditingAlbumaddingFilesToAlbumremovingFilesFromAlbumremovingAlbum
Litterbox-specific events:
uploadingFileuploadingStream
By default, network-dependent integration tests are skipped to avoid flaky failures and rate limits.
- Run default deterministic test suite (no Catbox account required):
yarn test - Run full suite including live integration tests:
- Create a
.envfile in the project root withUSER_HASH=<your_catbox_user_hash> - Run with
RUN_INTEGRATION_TESTS=1
- Create a
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.