@phxgg/kick.js 0.1.1 → 0.1.3

package/README.md

@@ -1,448 +1,444 @@
-# @phxgg/kick.js
-
-A JavaScript/TypeScript client for the [Kick.com public API](https://docs.kick.com).
-
-> [!WARNING]
-> This project is in early development. The API may change significantly between releases.
-
-## Installation
-
-```bash
-npm install @phxgg/kick.js
-```
-
-## Table of contents
-
-- [Setup](#setup)
-- [OAuth](#oauth)
-- [Users](#users)
-- [Channels](#channels)
-- [Livestreams](#livestreams)
-- [Categories](#categories)
-- [Chat](#chat)
-- [Channel Rewards](#channel-rewards)
-- [Moderation](#moderation)
-- [KICKs](#kicks)
-- [Event Subscriptions](#event-subscriptions)
-- [Webhooks](#webhooks)
-- [Error handling](#error-handling)
-
----
-
-## Setup
-
-```ts
-import { KickClient } from '@phxgg/kick.js';
-
-const client = new KickClient({
-  clientId: 'YOUR_CLIENT_ID',
-  clientSecret: 'YOUR_CLIENT_SECRET',
-  redirectUri: 'https://yourapp.com/oauth/callback', // required for OAuth flows
-});
-```
-
-Once you have a user token (obtained via [OAuth](#oauth)), attach it to the client:
-
-```ts
-client.setToken({
-  access_token: 'USER_ACCESS_TOKEN',
-  refresh_token: 'USER_REFRESH_TOKEN',
-  token_type: 'bearer',
-  expires_in: 3600,
-  scope: 'user:read channel:read',
-});
-```
-
-After `setToken` is called, the client automatically fetches the authenticated user in the background and registers itself in the global event manager so that [webhook events](#webhooks) can be routed to it.
-
----
-
-## OAuth
-
-### Generate authorization URL
-
-Redirect your user to this URL to begin the authorization flow. Store the `codeVerifier` in the session — you'll need it in the next step.
-
-```ts
-const { url, codeVerifier } = await client.oauth.generateAuthorizeURL();
-// redirect user to `url`
-```
-
-### Exchange code for token
-
-```ts
-const token = await client.oauth.exchangeToken(code, codeVerifier);
-client.setToken(token);
-```
-
-### Generate an app token (client credentials)
-
-Use this for API calls that don't require a user context.
-
-```ts
-const appToken = await client.oauth.generateAppToken();
-client.appToken = appToken;
-```
-
-### Refresh a token
-
-```ts
-const refreshed = await client.oauth.refreshToken(token.refresh_token);
-client.setToken(refreshed);
-```
-
-### Revoke a token
-
-```ts
-import { TokenHintType } from '@phxgg/kick.js';
-
-await client.oauth.revokeToken(token.access_token, TokenHintType.ACCESS_TOKEN);
-```
-
-### Introspect a token
-
-```ts
-const info = await client.oauth.introspect();
-console.log(info.active, info.scope);
-```
-
----
-
-## Users
-
-Required scope: `user:read`
-
-```ts
-// Fetch the authenticated user
-const me = await client.users.me();
-console.log(me.name, me.email, me.userId);
-
-// Fetch specific users by ID
-const users = await client.users.fetch([123, 456]);
-```
-
----
-
-## Channels
-
-Required scope: `channel:read` (read), `channel:write` (update)
-
-```ts
-// Fetch by slug
-const channel = await client.channels.fetchBySlug('monstercat');
-
-// Fetch by broadcaster user ID
-const channel = await client.channels.fetchById(123);
-
-// Fetch multiple at once
-const channels = await client.channels.fetch({ slug: ['monstercat', 'kick'] });
-// or: client.channels.fetch({ broadcasterUserId: [123, 456] })
-
-// Update the authenticated user's channel
-await client.channels.update({
-  streamTitle: 'My new stream title',
-  categoryId: 15,
-  customTags: ['gaming', 'chill'],
-});
-```
-
----
-
-## Livestreams
-
-```ts
-// Fetch live streams (no scope required)
-const streams = await client.livestreams.fetch({
-  broadcasterUserId: [123, 456],
-  categoryId: 15,
-  language: 'en',
-  limit: 20,
-  sort: 'viewer_count', // or 'started_at'
-});
-
-// Total live stream count
-const stats = await client.livestreams.fetchStats();
-console.log(stats.total_count);
-```
-
----
-
-## Categories
-
-```ts
-// v1: fetch all categories
-const categories = await client.categories.fetch();
-
-// v2: search with pagination
-const results = await client.categoriesV2.search({ query: 'gaming', limit: 10 });
-
-// v2: fetch a single category by ID
-const category = await client.categoriesV2.fetch(15);
-```
-
----
-
-## Chat
-
-Required scope: `chat:write` (send), `moderation:chat_message:manage` (delete)
-
-```ts
-import { ChatMessageType } from '@phxgg/kick.js';
-
-// Send a bot message (default)
-const message = await client.chat.send({
-  content: 'Hello from kick.js!',
-});
-
-// Send a message as the authenticated user to a specific channel
-const message = await client.chat.send({
-  content: 'Hello!',
-  broadcasterUserId: 123,
-  type: ChatMessageType.USER,
-});
-
-// Reply to a message
-const reply = await client.chat.send({
-  content: 'Nice catch!',
-  replyToMessageId: 'some-message-id',
-});
-
-// Delete a message
-await client.chat.delete('some-message-id');
-```
-
----
-
-## Channel Rewards
-
-Required scope: `channel:rewards:read` (read), `channel:rewards:write` (create / update / delete)
-
-```ts
-// Fetch all rewards for the authenticated broadcaster
-const rewards = await client.channelRewards.fetch();
-
-// Create a reward
-const reward = await client.channelRewards.create({
-  title: 'Hydrate!',
-  cost: 500,
-  description: 'Make the streamer drink water.',
-  isEnabled: true,
-  isUserInputRequired: false,
-});
-
-// Update a reward
-await client.channelRewards.update(reward.id, {
-  cost: 1000,
-  isPaused: false,
-});
-
-// Delete a reward
-await client.channelRewards.delete(reward.id);
-
-// Fetch redemptions (defaults to pending)
-const redemptions = await client.channelRewards.getRedemptions({
-  rewardId: reward.id,
-  status: 'pending',
-});
-
-// Accept / reject redemptions (up to 25 per call)
-await client.channelRewards.acceptRedemptions({ ids: [redemptions[0].id] });
-await client.channelRewards.rejectRedemptions({ ids: [redemptions[1].id] });
-```
-
----
-
-## Moderation
-
-Required scope: `moderation:ban`
-
-```ts
-// Ban a user permanently
-await client.moderation.banUser({
-  broadcasterUserId: 123,
-  userId: 456,
-  reason: 'Spamming',
-});
-
-// Timeout a user (duration in minutes, max 10080 = 7 days)
-await client.moderation.timeoutUser({
-  broadcasterUserId: 123,
-  userId: 456,
-  duration: 10,
-  reason: 'Cool off.',
-});
-
-// Remove a ban or timeout
-await client.moderation.removeBan({
-  broadcasterUserId: 123,
-  userId: 456,
-});
-```
-
----
-
-## KICKs
-
-Required scope: `kicks:read`
-
-```ts
-// Fetch the KICKs leaderboard for the authenticated broadcaster
-const leaderboard = await client.kicks.fetchLeaderboard({ top: 10 });
-```
-
----
-
-## Event subscriptions
-
-Required scope: `events:subscribe`
-
-Subscribe your app to receive webhook events for a broadcaster.
-
-```ts
-import { WebhookEvents } from '@phxgg/kick.js';
-
-// Subscribe to a single event
-await client.events.subscribe({
-  broadcasterUserId: 123,
-  event: { name: WebhookEvents.CHAT_MESSAGE_SENT, version: 1 },
-});
-
-// Subscribe to multiple events at once
-await client.events.subscribeMultiple({
-  broadcasterUserId: 123,
-  events: [
-    { name: WebhookEvents.CHANNEL_FOLLOWED, version: 1 },
-    { name: WebhookEvents.LIVESTREAM_STATUS_UPDATED, version: 1 },
-  ],
-});
-
-// List active subscriptions
-const subs = await client.events.fetch();
-
-// Unsubscribe
-await client.events.unsubscribe(subs[0].id);
-await client.events.unsubscribeMultiple(subs.map((s) => s.id));
-```
-
----
-
-## Webhooks
-
-kick.js provides framework-agnostic primitives so you can handle Kick webhook deliveries in any HTTP server.
-
-### Verify & dispatch
-
-```ts
-import {
-  verifyKickSignature,
-  dispatchWebhookEvent,
-  getKickPublicKey,
-} from '@phxgg/kick.js';
-
-// Inside your POST /webhooks/kick handler:
-const publicKey = await getKickPublicKey(); // cached, refreshes every hour
-
-const valid = verifyKickSignature({
-  messageId:        req.headers['kick-event-message-id'],
-  messageTimestamp: req.headers['kick-event-message-timestamp'],
-  rawBody:          rawBody, // Buffer or string — must be read before JSON.parse
-  signature:        req.headers['kick-event-signature'],
-  publicKey,
-});
-
-if (!valid) return res.sendStatus(403);
-
-const eventType = req.headers['kick-event-type'];
-const payload = JSON.parse(rawBody);
-
-// Route to whichever KickClient is registered for this broadcaster
-dispatchWebhookEvent(eventType, payload);
-
-res.sendStatus(200);
-```
-
-### Per-client listeners
-
-After calling `client.setToken()`, the client registers itself so that `dispatchWebhookEvent` can route events to the correct instance. Use `client.on()` to react to events:
-
-```ts
-import { WebhookEvents } from '@phxgg/kick.js';
-
-client.on(WebhookEvents.CHAT_MESSAGE_SENT, (payload) => {
-  console.log(`${payload.sender.username}: ${payload.content}`);
-});
-
-client.on(WebhookEvents.CHANNEL_FOLLOWED, (payload) => {
-  console.log(`${payload.follower.username} followed the channel!`);
-});
-
-client.on(WebhookEvents.LIVESTREAM_STATUS_UPDATED, (payload) => {
-  console.log('Stream is now', payload.is_live ? 'live' : 'offline');
-});
-
-// Remove a listener
-client.off(WebhookEvents.CHAT_MESSAGE_SENT, myListener);
-
-// Remove all listeners
-client.removeAllListeners();
-
-// Clean up the client and deregister it from the event manager
-client.destroy();
-```
-
-**Supported webhook events**
-
-| Event | Constant |
-|---|---|
-| `chat.message.sent` | `WebhookEvents.CHAT_MESSAGE_SENT` |
-| `channel.followed` | `WebhookEvents.CHANNEL_FOLLOWED` |
-| `channel.subscription.new` | `WebhookEvents.CHANNEL_SUBSCRIPTION_NEW` |
-| `channel.subscription.renewal` | `WebhookEvents.CHANNEL_SUBSCRIPTION_RENEWAL` |
-| `channel.subscription.gifts` | `WebhookEvents.CHANNEL_SUBSCRIPTION_GIFTS` |
-| `channel.reward.redemption.updated` | `WebhookEvents.CHANNEL_REWARD_REDEMPTION_UPDATED` |
-| `livestream.status.updated` | `WebhookEvents.LIVESTREAM_STATUS_UPDATED` |
-| `livestream.metadata.updated` | `WebhookEvents.LIVESTREAM_METADATA_UPDATED` |
-| `moderation.banned` | `WebhookEvents.MODERATION_BANNED` |
-| `kicks.gifted` | `WebhookEvents.KICKS_GIFTED` |
-
----
-
-## Error handling
-
-All methods throw typed errors on non-2xx responses:
-
-```ts
-import {
-  UnauthorizedError,
-  ForbiddenError,
-  NotFoundError,
-  RateLimitError,
-  BadRequestError,
-  MissingScopeError,
-  NoTokenSetError,
-} from '@phxgg/kick.js';
-
-try {
-  const me = await client.users.me();
-} catch (err) {
-  if (err instanceof UnauthorizedError) {
-    // token expired — refresh and retry
-  } else if (err instanceof MissingScopeError) {
-    // the token is missing a required scope
-  } else if (err instanceof RateLimitError) {
-    // back off and retry
-  } else {
-    throw err;
-  }
-}
-```
-
----
-
-## Example app
-
-A full Express + MongoDB reference implementation is available in [`examples/express-app`](https://github.com/phxgg/kick.js/tree/main/examples/express-app).
-
-## License
-
-[MIT](./LICENSE)
+# @phxgg/kick.js
+
+A JavaScript/TypeScript client for the [Kick.com public API](https://docs.kick.com).
+
+> [!WARNING]
+> This project is in early development. The API may change significantly between releases.
+
+## Installation
+
+```bash
+npm install @phxgg/kick.js
+```
+
+## Table of contents
+
+- [Setup](#setup)
+- [OAuth](#oauth)
+- [Users](#users)
+- [Channels](#channels)
+- [Livestreams](#livestreams)
+- [Categories](#categories)
+- [Chat](#chat)
+- [Channel Rewards](#channel-rewards)
+- [Moderation](#moderation)
+- [KICKs](#kicks)
+- [Event Subscriptions](#event-subscriptions)
+- [Webhooks](#webhooks)
+- [Error handling](#error-handling)
+
+---
+
+## Setup
+
+```ts
+import { KickClient } from '@phxgg/kick.js';
+
+const client = new KickClient({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  redirectUri: 'https://yourapp.com/oauth/callback', // required for OAuth flows
+});
+```
+
+Once you have a user token (obtained via [OAuth](#oauth)), attach it to the client:
+
+```ts
+client.setToken({
+  access_token: 'USER_ACCESS_TOKEN',
+  refresh_token: 'USER_REFRESH_TOKEN',
+  token_type: 'bearer',
+  expires_in: 3600,
+  scope: 'user:read channel:read',
+});
+```
+
+After `setToken` is called, the client automatically fetches the authenticated user in the background and registers itself in the global event manager so that [webhook events](#webhooks) can be routed to it.
+
+---
+
+## OAuth
+
+### Generate authorization URL
+
+Redirect your user to this URL to begin the authorization flow. Store the `codeVerifier` in the session — you'll need it in the next step.
+
+```ts
+const { url, codeVerifier } = await client.oauth.generateAuthorizeURL();
+// redirect user to `url`
+```
+
+### Exchange code for token
+
+```ts
+const token = await client.oauth.exchangeToken(code, codeVerifier);
+client.setToken(token);
+```
+
+### Generate an app token (client credentials)
+
+Use this for API calls that don't require a user context.
+
+```ts
+const appToken = await client.oauth.generateAppToken();
+client.appToken = appToken;
+```
+
+### Refresh a token
+
+```ts
+const refreshed = await client.oauth.refreshToken(token.refresh_token);
+client.setToken(refreshed);
+```
+
+### Revoke a token
+
+```ts
+import { TokenHintType } from '@phxgg/kick.js';
+
+await client.oauth.revokeToken(token.access_token, TokenHintType.ACCESS_TOKEN);
+```
+
+### Introspect a token
+
+```ts
+const info = await client.oauth.introspect();
+console.log(info.active, info.scope);
+```
+
+---
+
+## Users
+
+Required scope: `user:read`
+
+```ts
+// Fetch the authenticated user
+const me = await client.users.me();
+console.log(me.name, me.email, me.userId);
+
+// Fetch specific users by ID
+const users = await client.users.fetch([123, 456]);
+```
+
+---
+
+## Channels
+
+Required scope: `channel:read` (read), `channel:write` (update)
+
+```ts
+// Fetch by slug
+const channel = await client.channels.fetchBySlug('monstercat');
+
+// Fetch by broadcaster user ID
+const channel = await client.channels.fetchById(123);
+
+// Fetch multiple at once
+const channels = await client.channels.fetch({ slug: ['monstercat', 'kick'] });
+// or: client.channels.fetch({ broadcasterUserId: [123, 456] })
+
+// Update the authenticated user's channel
+await client.channels.update({
+  streamTitle: 'My new stream title',
+  categoryId: 15,
+  customTags: ['gaming', 'chill'],
+});
+```
+
+---
+
+## Livestreams
+
+```ts
+// Fetch live streams (no scope required)
+const streams = await client.livestreams.fetch({
+  broadcasterUserId: [123, 456],
+  categoryId: 15,
+  language: 'en',
+  limit: 20,
+  sort: 'viewer_count', // or 'started_at'
+});
+
+// Total live stream count
+const stats = await client.livestreams.fetchStats();
+console.log(stats.total_count);
+```
+
+---
+
+## Categories
+
+```ts
+// v1: fetch all categories
+const categories = await client.categories.fetch();
+
+// v2: search with pagination
+const results = await client.categoriesV2.search({ query: 'gaming', limit: 10 });
+
+// v2: fetch a single category by ID
+const category = await client.categoriesV2.fetch(15);
+```
+
+---
+
+## Chat
+
+Required scope: `chat:write` (send), `moderation:chat_message:manage` (delete)
+
+```ts
+import { ChatMessageType } from '@phxgg/kick.js';
+
+// Send a bot message (default)
+const message = await client.chat.send({
+  content: 'Hello from kick.js!',
+});
+
+// Send a message as the authenticated user to a specific channel
+const message = await client.chat.send({
+  content: 'Hello!',
+  broadcasterUserId: 123,
+  type: ChatMessageType.USER,
+});
+
+// Reply to a message
+const reply = await client.chat.send({
+  content: 'Nice catch!',
+  replyToMessageId: 'some-message-id',
+});
+
+// Delete a message
+await client.chat.delete('some-message-id');
+```
+
+---
+
+## Channel Rewards
+
+Required scope: `channel:rewards:read` (read), `channel:rewards:write` (create / update / delete)
+
+```ts
+// Fetch all rewards for the authenticated broadcaster
+const rewards = await client.channelRewards.fetch();
+
+// Create a reward
+const reward = await client.channelRewards.create({
+  title: 'Hydrate!',
+  cost: 500,
+  description: 'Make the streamer drink water.',
+  isEnabled: true,
+  isUserInputRequired: false,
+});
+
+// Update a reward
+await client.channelRewards.update(reward.id, {
+  cost: 1000,
+  isPaused: false,
+});
+
+// Delete a reward
+await client.channelRewards.delete(reward.id);
+
+// Fetch redemptions (defaults to pending)
+const redemptions = await client.channelRewards.getRedemptions({
+  rewardId: reward.id,
+  status: 'pending',
+});
+
+// Accept / reject redemptions (up to 25 per call)
+await client.channelRewards.acceptRedemptions({ ids: [redemptions[0].id] });
+await client.channelRewards.rejectRedemptions({ ids: [redemptions[1].id] });
+```
+
+---
+
+## Moderation
+
+Required scope: `moderation:ban`
+
+```ts
+// Ban a user permanently
+await client.moderation.banUser({
+  broadcasterUserId: 123,
+  userId: 456,
+  reason: 'Spamming',
+});
+
+// Timeout a user (duration in minutes, max 10080 = 7 days)
+await client.moderation.timeoutUser({
+  broadcasterUserId: 123,
+  userId: 456,
+  duration: 10,
+  reason: 'Cool off.',
+});
+
+// Remove a ban or timeout
+await client.moderation.removeBan({
+  broadcasterUserId: 123,
+  userId: 456,
+});
+```
+
+---
+
+## KICKs
+
+Required scope: `kicks:read`
+
+```ts
+// Fetch the KICKs leaderboard for the authenticated broadcaster
+const leaderboard = await client.kicks.fetchLeaderboard({ top: 10 });
+```
+
+---
+
+## Event subscriptions
+
+Required scope: `events:subscribe`
+
+Subscribe your app to receive webhook events for a broadcaster.
+
+```ts
+import { WebhookEvents } from '@phxgg/kick.js';
+
+// Subscribe to a single event
+await client.events.subscribe({
+  broadcasterUserId: 123,
+  event: { name: WebhookEvents.CHAT_MESSAGE_SENT, version: 1 },
+});
+
+// Subscribe to multiple events at once
+await client.events.subscribeMultiple({
+  broadcasterUserId: 123,
+  events: [
+    { name: WebhookEvents.CHANNEL_FOLLOWED, version: 1 },
+    { name: WebhookEvents.LIVESTREAM_STATUS_UPDATED, version: 1 },
+  ],
+});
+
+// List active subscriptions
+const subs = await client.events.fetch();
+
+// Unsubscribe
+await client.events.unsubscribe(subs[0].id);
+await client.events.unsubscribeMultiple(subs.map((s) => s.id));
+```
+
+---
+
+## Webhooks
+
+kick.js provides framework-agnostic primitives so you can handle Kick webhook deliveries in any HTTP server.
+
+### Verify & dispatch
+
+```ts
+import { verifyKickSignature, dispatchWebhookEvent, getKickPublicKey } from '@phxgg/kick.js';
+
+// Inside your POST /webhooks/kick handler:
+const publicKey = await getKickPublicKey(); // cached, refreshes every hour
+
+const valid = verifyKickSignature({
+  messageId: req.headers['kick-event-message-id'],
+  messageTimestamp: req.headers['kick-event-message-timestamp'],
+  rawBody: rawBody, // Buffer or string — must be read before JSON.parse
+  signature: req.headers['kick-event-signature'],
+  publicKey,
+});
+
+if (!valid) return res.sendStatus(403);
+
+const eventType = req.headers['kick-event-type'];
+const payload = JSON.parse(rawBody);
+
+// Route to whichever KickClient is registered for this broadcaster
+dispatchWebhookEvent(eventType, payload);
+
+res.sendStatus(200);
+```
+
+### Per-client listeners
+
+After calling `client.setToken()`, the client registers itself so that `dispatchWebhookEvent` can route events to the correct instance. Use `client.on()` to react to events:
+
+```ts
+import { WebhookEvents } from '@phxgg/kick.js';
+
+client.on(WebhookEvents.CHAT_MESSAGE_SENT, (payload) => {
+  console.log(`${payload.sender.username}: ${payload.content}`);
+});
+
+client.on(WebhookEvents.CHANNEL_FOLLOWED, (payload) => {
+  console.log(`${payload.follower.username} followed the channel!`);
+});
+
+client.on(WebhookEvents.LIVESTREAM_STATUS_UPDATED, (payload) => {
+  console.log('Stream is now', payload.is_live ? 'live' : 'offline');
+});
+
+// Remove a listener
+client.off(WebhookEvents.CHAT_MESSAGE_SENT, myListener);
+
+// Remove all listeners
+client.removeAllListeners();
+
+// Clean up the client and deregister it from the event manager
+client.destroy();
+```
+
+**Supported webhook events**
+
+| Event                               | Constant                                          |
+| ----------------------------------- | ------------------------------------------------- |
+| `chat.message.sent`                 | `WebhookEvents.CHAT_MESSAGE_SENT`                 |
+| `channel.followed`                  | `WebhookEvents.CHANNEL_FOLLOWED`                  |
+| `channel.subscription.new`          | `WebhookEvents.CHANNEL_SUBSCRIPTION_NEW`          |
+| `channel.subscription.renewal`      | `WebhookEvents.CHANNEL_SUBSCRIPTION_RENEWAL`      |
+| `channel.subscription.gifts`        | `WebhookEvents.CHANNEL_SUBSCRIPTION_GIFTS`        |
+| `channel.reward.redemption.updated` | `WebhookEvents.CHANNEL_REWARD_REDEMPTION_UPDATED` |
+| `livestream.status.updated`         | `WebhookEvents.LIVESTREAM_STATUS_UPDATED`         |
+| `livestream.metadata.updated`       | `WebhookEvents.LIVESTREAM_METADATA_UPDATED`       |
+| `moderation.banned`                 | `WebhookEvents.MODERATION_BANNED`                 |
+| `kicks.gifted`                      | `WebhookEvents.KICKS_GIFTED`                      |
+
+---
+
+## Error handling
+
+All methods throw typed errors on non-2xx responses:
+
+```ts
+import {
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  RateLimitError,
+  BadRequestError,
+  MissingScopeError,
+  NoTokenSetError,
+} from '@phxgg/kick.js';
+
+try {
+  const me = await client.users.me();
+} catch (err) {
+  if (err instanceof UnauthorizedError) {
+    // token expired — refresh and retry
+  } else if (err instanceof MissingScopeError) {
+    // the token is missing a required scope
+  } else if (err instanceof RateLimitError) {
+    // back off and retry
+  } else {
+    throw err;
+  }
+}
+```
+
+---
+
+## Example app
+
+A full Express + MongoDB reference implementation is available in [`examples/express-app`](https://github.com/phxgg/kick.js/tree/main/examples/express-app).
+
+## License
+
+[MIT](./LICENSE)