twitch-api-kit 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Code Shadow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+```md
+![npm version](https://img.shields.io/npm/v/twitch-api-kit)
+![downloads](https://img.shields.io/npm/dw/twitch-api-kit)
+![node](https://img.shields.io/node/v/twitch-api-kit)
+![license](https://img.shields.io/github/license/CodeShadow17/twitch-api-kit)
+![stars](https://img.shields.io/github/stars/CodeShadow17/twitch-api-kit)
+![issues](https://img.shields.io/github/issues/CodeShadow17/twitch-api-kit)
+
+### Nodejs Classes for Twitch Helix and EventSub
+
+A small, focused utility library that exposes two helpers: **Helix** for Twitch Helix API calls and **Subscribe** for creating EventSub websocket subscriptions. The classes handle API requests and subscription creation only. **WebSocket connection management and event handling must be implemented by the consumer**
+
+---
+
+### Installation
+
+**Install via npm**
+
+```bash
+npm install twitch-api-kit
+```
+
+---
+
+### Compatibility
+
+- **Node 18+** is recommended. This library relies on native `fetch` and `AbortController`.
+- If you use **Node 16 or older**, install a fetch polyfill:
+
+  ```bash
+  npm install node-fetch@2
+  ```
+
+---
+
+### Quick Start
+
+**Import and instantiate**
+
+```js
+const { Helix, Subscribe } = require("twitch-api-kit");
+
+// Helix
+const helix = new Helix({
+  client_token: "YOUR_OAUTH_TOKEN",
+  client_id: "YOUR_CLIENT_ID",
+  channelName: "your_channel"
+});
+await helix.init();
+
+// Subscribe
+const sub = new Subscribe({
+  clientId: "YOUR_CLIENT_ID",
+  token: "YOUR_OAUTH_TOKEN",
+  broadcasterId: "BROADCASTER_USER_ID",
+  sessionId: "YOUR_WEBSOCKET_SESSION_ID"
+});
+await sub.toFollows();
+```
+
+**Important**  
+The library **does not** open or manage WebSocket connections. Use your own WebSocket client (for example `ws`) to create a session and forward the `session_id` to `Subscribe`. Handle incoming EventSub messages and dispatch them to your app.
+
+---
+
+### API Reference
+
+#### Helix class
+
+**Constructor options**
+- **client_token** `string` — OAuth token with required scopes  
+- **client_id** `string` — Twitch app client id  
+- **channelName** `string` — broadcaster login name  
+
+**Key methods**
+- `init()` → `Promise<void>`
+- `viewerCount()` → `Promise<number>`
+- `getUserID(username)` → `Promise<string | null>`
+- `followCount()` → `Promise<number>`
+- `lastFollow()` → `Promise<string | null>`
+- `createClip(title?, duration?)` → `Promise<object | null>`
+- `createCustomReward(options)` → `Promise<object | null>`
+- `updateRedemptionStatus(options)` → `Promise<object>`
+- `cheerLeaderboard()` → `Promise<Array>`
+
+#### Subscribe class
+
+**Constructor options**
+- **clientId** `string`  
+- **token** `string`  
+- **broadcasterId** `string | null`  
+- **sessionId** `string | null`  
+
+**Key methods**
+- `toFollows()` → `Promise<boolean>`
+- `toRedemptions()` → `Promise<boolean>`
+- `toStreamOnline()` → `Promise<boolean>`
+- `toStreamOffline()` → `Promise<boolean>`
+- `toChannelUpdate()` → `Promise<boolean>`
+- `toAll()` → `Promise<object>`
+
+---
+
+### Example: Using the Helix class
+
+```js
+const { Helix } = require("twitch-api-kit");
+
+(async () => {
+  // Create the Helix client
+  const helix = new Helix({
+    client_token: process.env.TWITCH_OAUTH_TOKEN,
+    client_id: process.env.TWITCH_CLIENT_ID,
+    channelName: "your_channel_name"
+  });
+
+  // Initialize (fetches broadcaster_id and sets helix.ready = true)
+  await helix.init();
+  console.log("Helix is ready. Broadcaster ID:", helix.broadcaster_id);
+
+  // Get viewer count
+  const viewers = await helix.viewerCount();
+  console.log("Current viewers:", viewers);
+
+  // Get total followers
+  const followers = await helix.followCount();
+  console.log("Total followers:", followers);
+
+  // Get last follower
+  const lastFollower = await helix.lastFollow();
+  console.log("Latest follower:", lastFollower);
+
+  // Get user ID of someone
+  const userId = await helix.getUserID("some_username");
+  console.log("User ID:", userId);
+
+  // Create a clip
+  const clip = await helix.createClip("Awesome moment!", 20);
+  console.log("Clip created:", clip);
+
+  // Get channel point rewards
+  const rewards = await helix.getChannelRewards();
+  console.log("Rewards:", rewards);
+
+  // Example: send a shoutout (requires moderator permissions)
+  // Replace moderatorId with your broadcaster ID or a moderator ID
+  const shoutoutSuccess = await helix.sendShoutout(userId, helix.broadcaster_id);
+  console.log("Shoutout sent:", shoutoutSuccess);
+})();
+
+```
+
+### Example: Using the Subscribe Class
+
+```js
+const WebSocket = require("ws");
+const { Subscribe } = require("twitch-api-kit");
+
+const sub = new Subscribe({
+  clientId: "CLIENT_ID",
+  token: "OAUTH_TOKEN",
+  broadcasterId: "BROADCASTER_USER_ID",
+  sessionId: null // will be set after welcome message
+});
+
+const ws = new WebSocket("wss://eventsub.wss.twitch.tv/ws");
+
+ws.on("open", () => {
+  console.log("Connected to Twitch EventSub WebSocket");
+});
+
+ws.on("message", async (raw) => {
+  const data = JSON.parse(raw);
+
+  if (data.metadata?.message_type === "session_welcome") {
+    const sessionId = data.payload.session.id;
+    sub.session_id = sessionId;
+
+    console.log("Session ID:", sessionId);
+
+    // Example: subscribe to follow events
+    await sub.toFollows();
+  }
+
+  // Handle other EventSub messages here...
+});
+```
+
+---
+
+### TypeScript and Editor Tips
+
+**Bundled typings**
+- The package ships `index.d.ts`.  
+- `package.json` includes `"types": "index.d.ts"` so TypeScript and VS Code pick up signatures automatically.
+
+**When you add methods**
+- Implement the method in JS  
+- Add JSDoc above the method  
+- Update `index.d.ts`  
+- Restart the TypeScript server in VS Code  
+
+**CommonJS export shape**
+- Keep `module.exports = { Helix, Subscribe }` in sync with `index.d.ts`.
+
+---
+
+### Contributing and License
+
+**Contributing**
+- Add new classes under `classes/`  
+- Re-export from `index.js`  
+- Update `index.d.ts`  
+- Add JSDoc for public methods  
+- Follow semver  
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Code Shadow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+### Checklist for Adding a Method
+
+- Implement JS method  
+- Add JSDoc  
+- Update `index.d.ts`  
+- Ensure `index.js` exports it  
+- Update README  
+- Bump version  
+```
+
+---

package/classes/twitchHelix.js

@@ -0,0 +1,512 @@
+const fetch = require('node-fetch');
+
+class Helix {
+    constructor({client_token, client_id, channelName}){
+        this.token = client_token;
+        this.channel = channelName;
+        this.client_id = client_id; //The client id you have, to get it go to https://dev.twitch.tv/console/apps and obtain it from your app
+        this.moderator = null; //the user id of the moderator
+        this.broadcaster_id = null; //this can be set later on
+        this.ready = false;
+        this.shoutoutCooldownGlobal = {last: 0};
+        this.shoutoutCooldownPerTarget = new Map();
+        this.emoteCache = new Map();
+    };
+
+    _setBroadcasterId(id){
+        this.broadcaster_id = id;
+    }
+
+    _error(message, error) {
+    return new Error(`${message}: ${error?.message || error}`);
+}
+
+
+    _headers() {
+    return {
+        "Client-ID": this.client_id,
+        "Authorization": `Bearer ${this.token}`,
+        "Content-Type": "application/json"
+    };
+}
+
+
+    async _withTimeout(promise, ms = 5000){
+        let timeout;
+        const controller = new AbortController();
+
+        const timer = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                reject(new Error("Helix request timed out"));
+            }, ms);
+        });
+
+        try {
+            const result = await Promise.race([
+                promise(controller.signal),
+                timer
+            ]);
+            return result;
+        }catch(error){
+            throw this._error(`There was an issue with fetch Timeout:`,error);
+        } 
+        finally {
+            clearTimeout(timeout);
+        };
+    };
+
+    async _safeFetch(url, options, timeoutMs = 5000){
+        try {
+            return await this._withTimeout(
+                async (signal) => {
+                    const res = await fetch(url, {...options, signal});
+
+                    if(res.status === 204) return {success: true}
+                    return await res.json();
+                },
+                timeoutMs
+            );
+        } catch (error) {
+            console.error("Helix fetch failed:", url, error)
+            return null;
+        }
+    };
+
+    async init(){
+        const id = await this.getUserID(this.channel);
+        this.broadcaster_id = id;
+        this.ready = true;
+    }
+
+    _checkReady() {
+    if (!this.ready) {
+        throw new Error("Helix.init() has not been called yet.");
+    }
+}
+
+    async viewerCount(){
+        this._checkReady();
+        try {
+            return await this._withTimeout(async (signal) => {
+        const res = await fetch(
+            `https://api.twitch.tv/helix/streams?user_login=${this.channel}`,
+            {
+                method: "GET",
+                headers: this._headers(),
+                signal
+            }
+        );
+
+        const data = await res.json();
+        if (data.data.length === 0) return 0;
+        return data.data[0].viewer_count;
+    }, 3000);
+        } catch (error) {
+            throw this._error(`There was an error with retrieving Viewer Count`, error );
+        }
+    };
+
+
+    async getUserID(username){
+        //this._checkReady(); //commented out cause without the init starting and this one always waiting for init to have the id, it goes into a logical loop
+        try {
+        const data = await this._safeFetch(`https://api.twitch.tv/helix/users?login=${username}`, {
+        method: "GET",
+        headers: this._headers()
+    });
+
+        if (!data || !data.data?.length) { 
+        console.error("Broadcaster not found:", username, data); 
+        return null; 
+        } 
+
+        return data.data[0].id;
+        } catch (error) {
+            throw this._error(`There was an error obtaining User's twitch Id`, error)
+        }
+    };
+
+
+    async followCount(){
+        this._checkReady();
+        try {
+            const data = await this._safeFetch(`https://api.twitch.tv/helix/channels/followers?broadcaster_id=${this.broadcaster_id}`, {
+                method: "GET",
+                headers: this._headers()
+            });
+
+            if(!data || typeof data.total !== "number"){
+            console.error("Follower count error:", data); 
+            return 0;
+            }
+            return data.total;
+
+        } catch (error) {
+            throw this._error(`There was an error retrieving the follow count`, error);
+        }
+    };
+
+    async lastFollow(){
+        this._checkReady();
+        try {
+        const data = await this._safeFetch(`https://api.twitch.tv/helix/channels/followers?broadcaster_id=${this.broadcaster_id}&first=1`, {
+            method: "GET",
+            headers: this._headers()
+        });
+
+        if (!data?.data?.length) return null;
+
+        return data.data[0].user_login;
+        } catch (error) {
+            throw this._error(`There was an error retrieving latest follower`, error)
+        }
+    }
+
+    async followAge(userId){
+        this._checkReady();
+        try {
+           const data = await this._safeFetch(
+    `https://api.twitch.tv/helix/channels/followers?broadcaster_id=${this.broadcaster_id}&user_id=${userId}`,
+    {
+        method: "GET",
+      headers: this._headers()
+    }
+  );
+
+  if (!data || !data.data) return null;
+
+  return data.data[0] || null;
+  } catch (error) {
+    throw this._error(`There was an error retrieving the follow age of the user`, error);
+  }
+};
+
+
+async emoteNameById(id){
+    if(this.emoteCache.has(id)) return this.emoteCache.get(id);
+
+    try {
+            const data = await this._safeFetch(
+    `https://api.twitch.tv/helix/emotes?id=${id}`,
+    {
+        method: "GET",
+      headers: this._headers()
+    }
+  );
+
+  const name = data?.data?.[0]?.name || null;
+  if (name) this.emoteCache.set(id, name);
+
+  return name;
+    } catch (error) {
+        throw this._error(`There was en error retrieving Emote name by Id`, error)
+    }
+};
+
+_isShoutoutCooldown(targetId){
+  const now = Date.now();
+
+  if(now - this.shoutoutCooldownGlobal.last < 60_000){
+    return true
+  }
+
+  const lastTarget = this.shoutoutCooldownPerTarget.get(targetId) || 0;
+  if(now - lastTarget < 120_000){
+    return true;
+  }
+  return false
+};
+
+_setShoutoutCooldown(targetId){
+  const now = Date.now();
+  this.shoutoutCooldownGlobal.last = now;
+  this.shoutoutCooldownPerTarget.set(targetId, now);
+};
+
+async sendShoutout(userId, moderatorId){
+    this._checkReady();
+    try {
+        if(this._isShoutoutCooldown(userId)){
+            console.log("Shoutout has been skipped due to cooldown");
+            return false;
+        }
+
+          const url = "https://api.twitch.tv/helix/chat/shoutouts";
+
+  const body = {
+    from_broadcaster_id: this.broadcaster_id,
+    to_broadcaster_id: userId,
+    moderator_id: moderatorId ?? this.broadcaster_id
+  };
+
+  const data = await this._safeFetch(url, {
+    method: "POST",
+    headers: this._headers(),
+    body: JSON.stringify(body)
+  });
+
+  if(data && data.success){
+    this._setShoutoutCooldown(userId);
+    return true;
+  }
+  else return false
+
+    } catch (error) {
+        throw this._error(`There was an error using shoutout`, error)
+    }
+}
+
+
+async createClip(title = "", duration = 30){
+    try{
+         const url = "https://api.twitch.tv/helix/clips";
+  duration = Math.min(60, Math.max(5, duration));
+
+  const extra = title ? `&title=${encodeURIComponent(title)}` : "";
+  const time = duration !== 30 ? `&has_delay=false&duration=${duration}` : "";
+
+  const data = await this._safeFetch(
+    `${url}?broadcaster_id=${this.broadcaster_id}${extra}${time}`,
+    {
+      method: "POST",
+      headers: this._headers(),
+    }
+  );
+
+  if (!data || data.error) {
+    console.error("Clip creation failed:", data);
+    return null;
+  }
+
+  return data.data?.[0] || null;
+    }
+    catch(error){
+        throw this._error("There was an error with the create Clip function", error);
+    }
+};
+
+
+async getChannelRewards(){
+    const url = `https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=${this.broadcaster_id}`;
+
+    try {
+        const data = await this._safeFetch(url, {
+            method: "GET",
+            headers: this._headers(),
+        });
+
+        if(!data || data.error) {
+            console.error("Get rewards failed:", data);
+            return [];
+        }
+        return data.data || [];
+    } catch (error) {
+        throw this._error("There was an error with getting channel rewards", error);
+    }
+};
+
+
+async getChatters(moderatorId){
+    const url = `https://api.twitch.tv/helix/chat/chatters`
+    const body = {
+      broadcaster_id: this.broadcaster_id,
+      moderator_id: moderatorId ?? this.broadcaster_id
+    };
+    try {
+        const data = await this._safeFetch(url, {
+        method: "GET",
+        headers: this._headers(),
+        body: JSON.stringify(body)
+    });
+
+    if(!data || data.error){
+        console.error("Get chatters failed:", error);
+        return null
+    }
+    return typeof data?.total === "number" ? data.total : null;
+    } catch (error) {
+        throw this._error("There was an error with Getting chatters", error);
+    }
+};
+
+
+_randomHexColor(){
+    const r = Math.floor(100 + Math.random() * 155);
+  const g = Math.floor(100 + Math.random() * 155);
+  const b = Math.floor(100 + Math.random() * 155);
+
+  return (
+    "#" +
+    r.toString(16).padStart(2, "0") +
+    g.toString(16).padStart(2, "0") +
+    b.toString(16).padStart(2, "0")
+  );
+};
+
+async createCustomReward({
+  title, 
+  cost, 
+  prompt = "",
+  is_enabled = true, 
+  background_color,
+  is_user_input_required = false,
+  is_max_per_stream_enabled = false,
+  max_per_stream = null,
+  is_max_per_user_per_stream_enabled = false,
+  max_per_user_per_stream = null,
+  is_global_cooldown_enabled = false,
+  global_cooldown_seconds = null
+}){
+if(!title || !cost) return {error: "Missing title or cost for reward"};
+
+if(!background_color) background_color = this._randomHexColor();
+
+  const rewardToCreate = {
+    title: title,
+    prompt: prompt,
+    cost: cost,
+    background_color: background_color,
+    is_enabled: is_enabled,
+    is_user_input_required: is_user_input_required,
+    is_max_per_stream_enabled: is_max_per_stream_enabled,
+    max_per_stream: max_per_stream,
+    is_max_per_user_per_stream_enabled: is_max_per_user_per_stream_enabled,
+    max_per_user_per_stream: max_per_user_per_stream,
+    is_global_cooldown_enabled: is_global_cooldown_enabled,
+    global_cooldown_seconds: global_cooldown_seconds
+  }
+
+
+    // Remove invalid fields based on Twitch rules 
+  if (!is_max_per_stream_enabled) { 
+    delete rewardToCreate.max_per_stream; 
+  } 
+  
+  if (!is_max_per_user_per_stream_enabled) {
+     delete rewardToCreate.max_per_user_per_stream; 
+    } 
+    
+  if (!is_global_cooldown_enabled) { 
+    delete rewardToCreate.global_cooldown_seconds; 
+  } 
+  
+  // Remove any undefined/null fields Twitch doesn't want 
+  Object.keys(rewardToCreate).forEach(key => { 
+    if (rewardToCreate[key] === null || rewardToCreate[key] === undefined) { 
+      delete rewardToCreate[key]; 
+    } 
+  });
+
+    try {
+    const data = await this._safeFetch(`https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=${this.broadcaster_id}`,
+      {
+        method: "POST",
+        headers: this._headers(),
+        body: JSON.stringify(rewardToCreate),
+      }
+    );
+
+
+  if (!data || data.error) {
+    console.error("Reward creation failed:", data);
+    return null;
+  }
+  const reward = data.data[0]
+
+
+  let rewardSave = {id: reward.id, title: reward.title, prompt: reward.prompt, cost: reward.cost};
+
+  
+
+  //console.log(data)
+  return rewardSave || null;
+
+  } catch (error) {
+    throw this._error("There was an error with creating the reward", error)
+  }
+
+};
+
+
+async deleteCustomRewards(rewardId){
+    const url = `https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=${this.broadcaster_id}&id=${rewardId}`;
+
+    try {
+        const data = await this._safeFetch(url, {
+            method: "DELETE",
+            headers: this._headers()
+        });
+
+        if(data && data.success){
+            return true;
+        };
+    } catch (error) {
+        throw this._error("There was an error deleting Custom Reward", error);
+    }
+};
+
+async updateRedemptionStatus({redemptionId, rewardId, status = "FULFILLED"}){
+    this._checkReady()
+    if (!["FULFILLED", "CANCELED"].includes(status)) { status = "FULFILLED"; }
+    const url = `https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=${this.broadcaster_id}&reward_id=${rewardId}&id=${redemptionId}`;
+
+    try {
+        const data = await this._safeFetch(url, {
+        method: "PATCH",
+        headers: this._headers(),
+        body: JSON.stringify({status: status})
+    });
+    if (!data || data.error || !Array.isArray(data.data) || data.data.length === 0) { return {simplified: null, full: null }; }
+    const entry = data.data[0];
+    const reward = entry.reward;
+
+    const summary = {
+        redeemed_by: entry.user_name,
+        user_id: entry.user_id,
+        reward_id: reward.id,
+        reward_title: reward.title,
+        reward_cost: reward.cost,
+        reward_status: entry.status,
+        reward_redeemed_at: entry.redeemed_at
+    };
+    return {simplified: summary, full: entry}
+    } catch (error) {
+        throw this._error("There was an error with adjusting reward status", error)
+    }
+}
+
+
+async cheerLeaderboard(){
+    const url = `https://api.twitch.tv/helix/bits/leaderboard`;
+    try {
+        const data = await this._safeFetch(url, {
+        method: "GET",
+        headers: this._headers()
+    });
+
+if (!data || data.error || !Array.isArray(data.data)) { return []; }
+    const array = [];
+
+    for(const profile of data.data){
+      const index = {
+        userId: profile.user_id, 
+        username: profile.user_login, 
+        rank: profile.rank, 
+        score: profile.score
+      };
+      
+      array.push(index);
+    }
+    return array 
+
+    } catch (error) {
+    throw this._error("There was an error getting the cheer Leaderboard", error)
+    }
+
+}
+
+};
+
+
+module.exports = {Helix}

package/classes/twitchSubscriptions.js

@@ -0,0 +1,291 @@
+// top of file
+const fs = require("fs");
+const path = require("path");
+
+let fetchFn = globalThis.fetch;
+if (!fetchFn) {
+  // for environments without global fetch (older Node), require node-fetch v2
+  // ensure you install node-fetch@2 if you use this fallback
+  fetchFn = require('node-fetch');
+}
+
+
+
+
+class Subscribe{
+    constructor({clientId, token, broadcasterId = null, sessionId = null}){
+        this.client_id = clientId;
+        this.token = token;
+        this.broadcaster_id = broadcasterId;
+        this.session_id = sessionId;
+        this._eventsub_url = "https://api.twitch.tv/helix/eventsub/subscriptions";
+
+       
+    }
+
+_canStart() {
+    const required = {
+        client_id: this.client_id,
+        token: this.token,
+        broadcaster_id: this.broadcaster_id,
+        session_id: this.session_id
+    };
+
+    for (const [key, value] of Object.entries(required)) {
+        if (!value) {
+            throw new Error(`${key} was not defined`);
+        }
+    }
+}
+
+
+    _error(message, error) {
+    return new Error(`${message}: ${error?.message || error}`);
+    }
+
+    _headers() {
+    return {
+        "Client-ID": this.client_id,
+        "Authorization": `Bearer ${this.token}`,
+        "Content-Type": "application/json"
+    }
+    }
+
+
+        async _withTimeout(promise, ms = 5000){
+            let timeout;
+            const controller = new AbortController();
+    
+            const timer = new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error("Helix request timed out"));
+                }, ms);
+            });
+    
+            try {
+                const result = await Promise.race([
+                    promise(controller.signal),
+                    timer
+                ]);
+                return result;
+            }catch(error){
+                throw this._error(`There was an issue with fetch Timeout:`,error);
+            } 
+            finally {
+                clearTimeout(timeout);
+            };
+        }
+
+    
+        async _safeFetch(url, options, timeoutMs = 5000){
+            try {
+                const result = await this._withTimeout(
+                    async (signal) => {
+                        const res = await fetchFn(url, {...options, signal});
+    
+                        if(res.status === 204) return {success: true, data: null}
+                        const json = await res.json();
+                        return {success: !json?.error, data: json }
+                    },
+                    timeoutMs
+                );
+                return result
+            } catch (error) {
+                console.error("Helix fetch failed:", url, error)
+                return {success: false, error };
+            }
+        }
+
+        async _safeSub(description, fn){
+            try {
+        const data = await fn();
+
+        if (!data?.data || data.data.length === 0) {
+            console.error(`❌ Subscription FAILED for ${description}:`, data);
+            return false;
+        }
+
+        const sub = data.data[0];
+        console.log(`✔ Subscription OK: ${sub.type} → ${sub.status}`);
+        return true;
+
+    } catch (err) {
+        console.error(`❌ Subscription ERROR for ${description}:`, err);
+        return false;
+    }
+        }
+
+        async toFollows(){
+            this._canStart();
+           // try {
+                return this._safeSub("Follow Event", async () => {
+                    const url = this._eventsub_url;
+        const body = {
+            type: "channel.follow",
+            version: "2",
+            condition: {
+                broadcaster_user_id: this.broadcaster_id,
+                moderator_user_id: this.broadcaster_id
+            },
+            transport: {
+                method: "websocket",
+                session_id: this.session_id
+            }
+        }; 
+
+            const data = await this._safeFetch(url, { 
+                method: "POST", 
+                headers: this._headers(), 
+                body: JSON.stringify(body) 
+            });
+
+            return {success: !data?.error, data: data?.data}
+                })
+
+          //  } catch (error) {
+            //    throw this._error("There was an error with subscribing to twitch follows", error)
+           // }
+        }
+
+
+        async toRedemptions(){
+            this._canStart();
+          
+                return this._safeSub("Redemption Event", async () => {
+                                const url = this._eventsub_url;
+            const body = {
+                type: "channel.channel_points_custom_reward_redemption.add",
+                version: "1",
+                condition: {
+                    broadcaster_user_id: this.broadcaster_id
+                },
+                transport: {
+                    method: "websocket",
+                    session_id: this.session_id
+                }
+            };
+
+            const data = await this._safeFetch(url, {
+                method: "POST",
+                headers: this._headers(),
+                body: JSON.stringify(body)
+            });
+            return {success: !data?.error, data: data}
+                })
+            }
+
+
+        async toStreamOnline(){
+            this._canStart();
+
+                return this._safeSub("Stream Online Event", async () => {
+                    const url = this._eventsub_url;
+                const body = {
+                    type: "stream.online",
+                    version: "1",
+                    condition: {
+                        broadcaster_user_id: this.broadcaster_id
+                    },
+                    transport: {
+                        method: "websocket",
+                        session_id: this.session_id
+                    }
+                };
+
+                return await this._safeFetch(url, {
+                    method: "POST",
+                    headers: this._headers(),
+                    body: JSON.stringify(body)
+                });
+                })
+
+        }
+
+
+        async toStreamOffline(){
+            this._canStart();
+
+                return this._safeSub("Stream offline Event", async () => {
+                    const url = this._eventsub_url;
+                const body = {
+                    type: "stream.offline",
+                    version: "1",
+                    condition: {
+                        broadcaster_user_id: this.broadcaster_id,
+                    },
+                    transport: {
+                        method: "websocket",
+                        session_id: this.session_id
+                    }
+                };
+
+                return await this._safeFetch(url, {
+                    method: "POST",
+                    headers: this._headers(),
+                    body: JSON.stringify(body)
+                });
+                })
+        }
+
+        async toChannelUpdate(){
+                this._canStart();
+            const url = this._eventsub_url;
+            
+            return this._safeSub("Channell Update Event", async () => {
+                    const body = {
+            type: "channel.update",
+            version: "2",
+            condition: {
+                broadcaster_user_id: this.broadcaster_id
+            },
+            transport: {
+                method: "websocket",
+                session_id: this.session_id
+            }
+            };
+
+            return await this._safeFetch(url, {
+                method: "POST",
+                headers: this._headers(),
+                body: JSON.stringify(body)
+            });
+                })
+
+
+        }
+
+
+
+        async toAll(){
+            this._canStart();
+           try {
+            const [ 
+                updates,
+                follows, 
+                redemptions, 
+                online, 
+                offline 
+            ] = await Promise.all([ 
+                this.toChannelUpdate(),
+                this.toFollows(), 
+                this.toRedemptions(), 
+                this.toStreamOnline(), 
+                this.toStreamOffline() 
+            ]);
+
+            return {
+                channelUpdateData: updates,
+                followsData: follows, 
+                redemptionsData: redemptions, 
+                isOnlineData: online, 
+                isOfflineData: offline
+            }
+           } catch (error) {
+            throw this._error("There was an error subscribing to all events", error)
+           }
+        }
+
+}
+
+module.exports = {Subscribe}

package/index.d.ts

@@ -0,0 +1,143 @@
+export interface HelixOptions {
+    client_token: string;
+    client_id: string;
+    channelName: string;
+}
+
+export interface CustomRewardOptions {
+    title: string;
+    cost: number;
+    prompt?: string;
+    is_enabled?: boolean;
+    background_color?: string;
+    is_user_input_required?: boolean;
+    is_max_per_stream_enabled?: boolean;
+    max_per_stream?: number | null;
+    is_max_per_user_per_stream_enabled?: boolean;
+    max_per_user_per_stream?: number | null;
+    is_global_cooldown_enabled?: boolean;
+    global_cooldown_seconds?: number | null;
+}
+
+export interface RedemptionStatusOptions {
+    redemptionId: string;
+    rewardId: string;
+    status?: "FULFILLED" | "CANCELED";
+}
+
+export interface RedemptionSummary {
+    redeemed_by: string;
+    user_id: string;
+    reward_id: string;
+    reward_title: string;
+    reward_cost: number;
+    reward_status: string;
+    reward_redeemed_at: string;
+}
+
+export interface RedemptionStatusResult {
+    simplified: RedemptionSummary | null;
+    full: any | null;
+}
+
+export interface CheerLeaderboardEntry {
+    userId: string;
+    username: string;
+    rank: number;
+    score: number;
+}
+
+export class Helix {
+    constructor(options: HelixOptions);
+
+    token: string;
+    channel: string;
+    client_id: string;
+    moderator: string | null;
+    broadcaster_id: string | null;
+    ready: boolean;
+
+    init(): Promise<void>;
+    viewerCount(): Promise<number>;
+    getUserID(username: string): Promise<string | null>;
+    followCount(): Promise<number>;
+    lastFollow(): Promise<string | null>;
+    followAge(userId: string): Promise<any | null>;
+    emoteNameById(id: string): Promise<string | null>;
+
+    sendShoutout(userId: string, moderatorId?: string): Promise<boolean>;
+
+    createClip(title?: string, duration?: number): Promise<any | null>;
+
+    getChannelRewards(): Promise<any[]>;
+
+    getChatters(moderatorId?: string): Promise<number | null>;
+
+    createCustomReward(options: CustomRewardOptions): Promise<{
+        id: string;
+        title: string;
+        prompt: string;
+        cost: number;
+    } | null>;
+
+    deleteCustomRewards(rewardId: string): Promise<boolean>;
+
+    updateRedemptionStatus(options: RedemptionStatusOptions): Promise<RedemptionStatusResult>;
+
+    cheerLeaderboard(): Promise<CheerLeaderboardEntry[]>;
+}
+
+
+export interface SubscribeOptions {
+    clientId: string;
+    token: string;
+    broadcasterId?: string | null;
+    sessionId?: string | null;
+}
+
+export interface SafeFetchResult {
+    success: boolean;
+    data?: any | null;
+    error?: any;
+}
+
+export class Subscribe {
+    constructor(options: SubscribeOptions);
+
+   client_id: string;
+   token: string;
+   broadcaster_id: string | null;
+   session_id: string | null;
+   _eventsub_url: string;
+
+   _canStart(): void;
+   _error(message: string, error?: any): Error;
+   _headers(): { "Client-ID": string; Authorization: string; "Content-Type": string };
+   _withTimeout<T>(promise: (signal: AbortSignal) => Promise<T>, ms?: number): Promise<T>;
+   _safeFetch(url: string, options?: any, timeoutMs?: number): Promise<SafeFetchResult>;
+   _safeSub(description: string, fn: () => Promise<SafeFetchResult | { success?: boolean; data?: any }>): Promise<boolean>;
+
+
+
+   toFollows(): Promise<boolean>;
+   toRedemptions(): Promise<boolean>;
+   toStreamOnline(): Promise<boolean>;
+   toStreamOffline(): Promise<boolean>;
+   toChannelUpdate(): Promise<boolean>;
+   toAll(): Promise<{
+    channelUpdateData: any;
+    followData: any;
+    redemptionsData: any;
+    isOnlineData: any;
+    isOfflineData: any;
+   }>;
+}
+
+
+
+declare const _default: {
+    Helix: typeof Helix;
+    Subscribe: typeof Subscribe;
+};
+
+export = _default;

package/index.js

@@ -0,0 +1,8 @@
+const { Helix } = require("./classes/twitchHelix");
+const { Subscribe } = require("./classes/twitchSubscriptions");
+
+
+module.exports = {
+    Helix,
+    Subscribe
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "twitch-api-kit",
+  "version": "1.0.0",
+  "description": "Utility classes for Twitch Helix API and EventSub WebSocket subscriptions",
+  "license": "MIT",
+  "author": "Code Shadow",
+  "repository": {
+  "type": "git",
+  "url": "https://github.com/CodeShadow17/twitch-api-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CodeShadow17/twitch-api-kit/issues"
+  },
+  "homepage": "https://github.com/CodeShadow17/twitch-api-kit#readme",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "twitch",
+    "twitch-helix",
+    "eventsub",
+    "twitch-eventsub",
+    "twitch-api",
+    "twitch-subscribe",
+    "twitch-websocket",
+    "twitch-api-kit",
+    "twitch-helper",
+    "nodejs",
+    "websocket",
+    "streaming"
+  ],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "classes/",
+    "README.md"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "ws": "^8.19.0"
+  }
+}