A zero-dependency TypeScript library for interacting with the Kick.com API. Features automatic OAuth 2.1 token management and a clean, intuitive interface.

Features

• 🔒 Automatic OAuth Management - Handles token refresh automatically
• 📝 Full TypeScript Support - Complete type definitions for all API responses
• 🚀 Zero Dependencies - Uses built-in Node.js fetch
• 🎯 Clean API - Organized modules for different endpoints
• ⚡ Modern - Built with async/await and ES modules

Install

npm install @nekiro/kick-api

Quick Start

You'll need kick developer app to use the API. Read more at https://docs.kick.com/getting-started/kick-apps-setup.

import { client } from "@nekiro/kick-api";

const kickClient = new client({
	clientId: "your-client-id",
	clientSecret: "your-client-secret",
});

const channel = await kickClient.channels.getChannel("xqc");

Examples

The examples/ directory contains comprehensive, runnable examples for all authentication methods and API usage patterns:

🚀 Quick Start Examples

# Basic API usage with all modules
npx ts-node examples/basic-usage.ts

# Bot authentication (automatic)
npx ts-node examples/bot-authentication.ts

# Interactive user authentication
npx ts-node examples/user-authentication.ts

📚 Available Examples

| Example | Description | Use Case | | -------------------------------- | ---------------------------- | ------------------------- | | basic-usage.ts | Complete API showcase | Learning all endpoints | | bot-authentication.ts | Client credentials flow | Automated bots, servers | | user-authentication.ts | Interactive OAuth 2.1 + PKCE | User-facing applications | | interactive-user-auth.ts | Enhanced OAuth experience | Step-by-step user auth | | authentication-comparison.ts | Bot vs User auth guide | Choosing the right method | | oauth-troubleshooting.ts | Fix redirect URI errors | Debugging OAuth issues | | debug-token-exchange.ts | Token exchange debugging | Fixing auth failures |

🎯 Authentication Methods

Bot Authentication (Server-to-Server):

// Automatic token management
const botClient = new client({
	clientId: "your-client-id",
	clientSecret: "your-client-secret",
	// No redirectUri = bot mode
});

await botClient.chat.postMessage({
	type: "bot",
	content: "Hello from bot!",
});

User Authentication (OAuth 2.1):

// User permission-based
const userClient = new client({
	clientId: "your-client-id",
	clientSecret: "your-client-secret",
	redirectUri: "http://localhost:3000/callback",
});

// Generate OAuth URL
const pkceParams = userClient.generatePKCEParams();
const authUrl = userClient.getAuthorizationUrl(pkceParams, ["public", "chat:write"]);

// Exchange code for token
const token = await userClient.exchangeCodeForToken({
	code: authorizationCode,
	codeVerifier: pkceParams.codeVerifier,
});

🛠️ Troubleshooting Tools

Got OAuth errors? Use our built-in debugging tools:

# Fix "invalid redirect uri" errors
npx ts-node examples/oauth-troubleshooting.ts

# Debug token exchange failures
npx ts-node examples/debug-token-exchange.ts

📖 Learn More

See the complete examples documentation: examples/README.md

Error Handling

The library provides specific error classes for different types of failures:

import {
	client,
	KickOAuthError,
	KickBadRequestError,
	KickUnauthorizedError,
	KickNotFoundError,
	KickRateLimitError,
} from "@nekiro/kick-api";

try {
	const result = await kickClient.categories.getCategories({ q: "gaming" });
} catch (error) {
	if (error instanceof KickOAuthError) {
		console.log("OAuth failed:", error.responseBody);
	} else if (error instanceof KickBadRequestError) {
		console.log("Bad request:", error.responseBody);
	} else if (error instanceof KickRateLimitError) {
		console.log("Rate limited, retry after:", error.retryAfter, "seconds");
	}
}

Testing

# Run unit tests
npm test