📖 kickbans

A clean and production-ready Node.js wrapper for the kickbans.app API.

Fetch recent moderation actions, user profiles, user history, global stats, and graph data from one package.

---

✨ Features

• 🔌 Simple function-based API for kickbans.app
• 📚 Full TypeScript support with rich IntelliSense
• 🧠 VS Code-friendly hints: autocomplete, parameter help, return types
• 📦 Dual module support: CommonJS (require) and ESM (import)
• 🛡️ Built-in errors for HTTP failures and request timeouts
• ⚡ Zero dependencies, uses native fetch

---

📦 Installation

npm install kickbans

---

🚀 Quick Start

CommonJS

const kickbans = require("kickbans");

kickbans.getRecentActions().then((actions) => {
  console.log(actions[0]);
});

ESM

import kickbans from "kickbans";

const stats = await kickbans.getStats();
const overview = await kickbans.getOverviewStats();
const profile = await kickbans.getUserProfileStats("seoyoon1o1");

console.log(stats);
console.log(overview.newVerifiedLast30Days?.stat);
console.log(profile.longestBan, profile.lastBanAgo);

---

📚 API Methods

getRecentActions()

Calls GET /actions/recent.

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const actions = await kickbans.getRecentActions();
  console.log(actions[0]);
})();

ESM:

import kickbans from "kickbans";

const actions = await kickbans.getRecentActions();
console.log(actions[0]);

getUser(usernameOrSlug)

Calls GET /users/:usernameOrSlug.

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const user = await kickbans.getUser("seoyoon1o1");
  console.log(user.user.username, user.actions.length);
})();

ESM:

import kickbans from "kickbans";

const user = await kickbans.getUser("seoyoon1o1");
console.log(user.user.username, user.actions.length);

searchUsers(query, options?)

Calls GET /users?query=...&limit=....

• query is required
• options.limit is optional but must be an integer between 1 and 10

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const users = await kickbans.searchUsers("seo", { limit: 5 });
  console.log(users.map((u) => u.username));
})();

ESM:

import kickbans from "kickbans";

const users = await kickbans.searchUsers("seo", { limit: 5 });
console.log(users.map((u) => u.username));

getStats()

Calls GET /stats.

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const stats = await kickbans.getStats();
  console.log(stats);
})();

ESM:

import kickbans from "kickbans";

const stats = await kickbans.getStats();
console.log(stats);

getActionGraphAll()

Calls GET /actions/graph/all.

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const graph = await kickbans.getActionGraphAll();
  console.log(graph[0], graph[graph.length - 1]);
})();

ESM:

import kickbans from "kickbans";

const graph = await kickbans.getActionGraphAll();
console.log(graph[0], graph[graph.length - 1]);

getOverviewStats()

Returns homepage-style overview cards using /stats:

• totalVerified
• newVerifiedLast30Days

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const overview = await kickbans.getOverviewStats();
  console.log(overview.totalVerified?.stat, overview.newVerifiedLast30Days?.stat);
})();

ESM:

import kickbans from "kickbans";

const overview = await kickbans.getOverviewStats();
console.log(overview.totalVerified?.stat, overview.newVerifiedLast30Days?.stat);

getGlobalActivityStats()

Returns computed global values from /actions/graph/all:

• totalBans
• totalUnbans
• averageDailyBans
• averageDailyUnbans
• netChange

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const globalStats = await kickbans.getGlobalActivityStats();
  console.log(globalStats.totalBans, globalStats.totalUnbans, globalStats.netChange);
})();

ESM:

import kickbans from "kickbans";

const globalStats = await kickbans.getGlobalActivityStats();
console.log(globalStats.totalBans, globalStats.totalUnbans, globalStats.netChange);

getUserProfileStats(usernameOrSlug)

Returns computed profile metrics from /users/:usernameOrSlug:

• totalActions
• longestBan (example: 6 days)
• lastBanAgo (example: 1 day ago)
• isCurrentlyBanned

CommonJS:

const kickbans = require("kickbans");

(async () => {
  const profile = await kickbans.getUserProfileStats("seoyoon1o1");
  console.log(profile.totalActions, profile.longestBan, profile.lastBanAgo);
})();

ESM:

import kickbans from "kickbans";

const profile = await kickbans.getUserProfileStats("seoyoon1o1");
console.log(profile.totalActions, profile.longestBan, profile.lastBanAgo);

---

❗ Error Types

KickbansApiError

Thrown when API responds with non-2xx status.

• status
• data
• url

KickbansTimeoutError

Thrown when a request exceeds timeout.

• timeoutMs
• url

---

⚙️ Requirements

• Node.js >=18.0.0

---

📝 License

MIT © 2026