@neuroinfoapi-client/node 0.0.0-stage → 2.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appstun
+
+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

@@ -1,3 +1,288 @@
-# Temporary Holding Version
+# @neuroinfoapi-client/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A comprehensive TypeScript/JavaScript client that provides full access to NeuroInfoAPI endpoints with proper type definitions.
+
+## Other runtime clients
+
+- [@neuroinfoapi-client/native](https://github.com/NeuroInfoAPI/NPM-Package/blob/master/packages/native/README.md): standard WebSocket in browsers and Node.js, ticket authentication, and JSON heartbeat.
+- [@neuroinfoapi-client/bun](https://github.com/NeuroInfoAPI/NPM-Package/blob/master/packages/bun/README.md): Bun's native WebSocket, automatic protocol pongs, and header authentication by default.
+
+## Features
+
+- HTTP access to streams, VODs, schedules, subathons, blog and X feeds
+- Full TypeScript support with typed API responses and event payloads
+- HTTP Bearer authentication with an optional token in the constructor
+- Type-safe HTTP error handling through `{ data, error }`
+- Configurable API base URL and HTTP request timeout (10 seconds by default)
+- WebSocket in Node.js using the `ws` npm package, with header authentication by default
+- Real-time subscriptions with automatic reconnect and subscription recovery
+- Automatic protocol pong replies and a 90-second heartbeat timeout by default
+- `NeuroInfoApiEventer` for polling-based updates (deprecated)
+
+## Installation
+
+```bash
+npm install @neuroinfoapi-client/node
+```
+
+## Quick Start
+
+```ts
+import { NeuroInfoApiClient } from "@neuroinfoapi-client/node";
+
+// Optional token can be passed directly in the constructor
+const client = new NeuroInfoApiClient("your-api-token-here");
+
+const { data, error } = await client.getCurrentStream();
+
+if (error) {
+  console.error(`Error ${error.code}: ${error.message}`);
+} else {
+  console.log(data);
+}
+```
+
+## Client Configuration
+
+Constructor signature:
+
+```ts
+new NeuroInfoApiClient(token?: string, options?: NeuroInfoApiClientOptions)
+```
+
+`NeuroInfoApiClientOptions` supports:
+
+| Option             | Default                   | Description                              |
+| ------------------ | ------------------------- | ---------------------------------------- |
+| `apiBaseUrl`       | `neuroinfoapi.dev/api/v2` | API host and path without a protocol     |
+| `useTls`           | `true`                    | Use HTTPS when `true`, HTTP when `false` |
+| `requestTimeoutMs` | `10000`                   | HTTP request timeout in milliseconds     |
+
+The legacy `baseUrl` option is deprecated and will be removed in a future major version.
+
+Examples:
+
+```ts
+import { NeuroInfoApiClient } from "@neuroinfoapi-client/node";
+
+// 1) No token in constructor (set later)
+const clientA = new NeuroInfoApiClient();
+clientA.setApiToken("your-api-token-here");
+
+// 2) Token in constructor
+const clientB = new NeuroInfoApiClient("your-api-token-here");
+
+// 3) for testing with Mock-TesServer (https://github.com/NeuroInfoAPI/Mock-TestServer)
+const clientC = new NeuroInfoApiClient(undefined, {
+  apiBaseUrl: "localhost:8787/api/v2",
+  useTls: false,
+  requestTimeoutMs: 15000,
+});
+```
+
+## Node.js Usage
+
+```ts
+import { NeuroInfoApiClient, NeuroInfoApiWebsocketClient } from "@neuroinfoapi-client/node";
+
+const client = new NeuroInfoApiClient();
+client.setApiToken("your-api-token-here");
+
+// Sends Authorization: Bearer during the handshake by default
+const wsClient = new NeuroInfoApiWebsocketClient("your-api-token-here");
+await wsClient.connect();
+```
+
+This package defaults to `authMethod: "header"` in Node.js. Set `authMethod: "ticket"` to obtain a one-time ticket through HTTP before connecting. For browser usage, use `@neuroinfoapi-client/native`.
+
+## Error Handling
+
+All HTTP API request methods return a result object with either `data` or `error`:
+
+```ts
+import { NeuroInfoApiClient } from "@neuroinfoapi-client/node";
+
+const client = new NeuroInfoApiClient("your-api-token-here");
+const { data, error } = await client.getCurrentStream();
+
+if (error) {
+  // error is NeuroApiError with code, message, and optional status
+  console.log(`Error ${error.code}: ${error.message}`);
+} else if (data.isLive) {
+  console.log(data.title);
+} else {
+  console.log("Stream is offline");
+}
+```
+
+## HTTP API Methods
+
+All methods below return `Promise<ApiResult<T>>`:
+
+- `getCurrentStream()` — current Twitch stream state
+- `getAllVods()` — all Twitch VODs
+- `getVod(id)` — a VOD by stream ID
+- `getSchedule(week, year?)` — schedule for a specific week and optional year
+- `getLatestSchedule()` — latest schedule
+- `getScheduleWeeks()` — available schedule weeks grouped by year
+- `getDevstreamTimes()` — devstream schedule timestamps
+- `getScheduleSearch(query, options?)` — search schedules with filters and cursor pagination
+- `getCurrentSubathons()` — currently active subathons
+- `getSubathon(year)` — subathon data for a year
+- `getSubathonYears()` — available subathon years
+- `getBlogFeed(raw?)` — Neuro-sama blog feed; requires an API token
+- `getXFeed(user)` — cached X feed for `NeurosamaAI`, `EvilNeuroAI`, or `Vedal987`; requires an API token
+
+## Schedule Search Pagination
+
+Use `getScheduleSearch` and continue with `nextCursor`.
+Optional filter: `type` (`normal`, `offline`, `canceled`, `TBD`, `unknown`).
+
+`/schedule/search` has rate limits (`6 requests/minute` and `2 requests/10 seconds` per token), so avoid tight loops.
+
+```ts
+import { NeuroInfoApiClient } from "@neuroinfoapi-client/node";
+
+const client = new NeuroInfoApiClient("your-api-token-here");
+const firstPage = await client.getScheduleSearch("karaoke", { limit: 5, sort: "desc", type: "normal" });
+if (firstPage.error) {
+  console.error(firstPage.error.code, firstPage.error.message);
+} else {
+  console.log("matches:", firstPage.data.results.length);
+
+  if (firstPage.data.nextCursor) {
+    const secondPage = await client.getScheduleSearch("karaoke", {
+      limit: 5,
+      sort: "desc",
+      cursor: firstPage.data.nextCursor,
+    });
+    console.log("next page:", secondPage.data?.results.length ?? 0);
+  }
+}
+```
+
+## Event System (Deprecated)
+
+`NeuroInfoApiEventer` is deprecated in favor of `NeuroInfoApiWebsocketClient`.
+
+```ts
+import { NeuroInfoApiEventer } from "@neuroinfoapi-client/node";
+
+const eventer = new NeuroInfoApiEventer();
+eventer.setApiToken("your-api-token-here");
+
+eventer.on("streamOnline", (stream) => {
+  console.log(`${stream.title} is now live!`);
+});
+
+eventer.on(
+  "scheduleUpdate",
+  (schedule) => console.log(`New schedule for week ${schedule.week}`),
+  (error) => console.log(`Failed to fetch schedule: ${error.code}`),
+);
+
+// Default: 60s, minimum: 10s
+eventer.fetchInterval = 30000;
+eventer.startEventLoop();
+```
+
+Available events: `streamOnline`, `streamOffline`, `streamUpdate`, `scheduleUpdate`, `subathonUpdate`, `subathonGoalUpdate`
+
+## WebSocket Client
+
+`heartbeatMonitoring` defaults to `true` and can also be changed on the client
+instance. Set it to `false` to disable heartbeat timeout monitoring; Native also
+stops its automatic JSON pings. Protocol pong replies and incoming `_pong`
+notifications remain active.
+
+Constructor signature:
+
+```ts
+new NeuroInfoApiWebsocketClient(token: string, options?: NeuroInfoApiWebsocketClientOptions)
+```
+
+The options include `apiBaseUrl`, `useTls`, `websocketUrl`, `authMethod`, `autoReconnect`, `maxReconnectAttempts`, `reconnectBaseDelay`, `heartbeatMonitoring`, `heartbeatIntervalMs`, `heartbeatTimeoutMs`, and `connectTimeoutMs`. The legacy WebSocket `baseUrl` option is deprecated; use `websocketUrl` for a full URL override.
+
+```ts
+import { NeuroInfoApiWebsocketClient } from "@neuroinfoapi-client/node";
+
+const wsClient = new NeuroInfoApiWebsocketClient("your-api-token-here");
+
+wsClient.on("_connected", (sessionId) => {
+  console.log("Connected with session:", sessionId);
+});
+
+wsClient.on("_eventAdded", (eventType) => {
+  console.log("Subscribed:", eventType);
+});
+
+wsClient.on("_eventRemoved", (eventType) => {
+  console.log("Unsubscribed:", eventType);
+});
+
+wsClient.on("streamOnline", (stream) => {
+  console.log("Stream online:", stream.title);
+});
+
+await wsClient.connect();
+```
+
+Available WebSocket events:
+
+- `streamOnline`
+- `streamOffline`
+- `streamUpdate`
+- `secretneuroaccountOnline`
+- `streamRaidIncoming`
+- `streamRaidOutgoing`
+- `scheduleUpdate`
+- `subathonUpdate`
+- `subathonGoalUpdate`
+- `blogFeedUpdate`
+- `xFeedNewEntries`
+- `xFeedUpdate` (deprecated alias for `xFeedNewEntries`)
+
+**Heartbeat:** The server must send WebSocket protocol ping frames. `ws` responds automatically with pong; this package sends no JSON heartbeat messages. The client waits a fixed **90 seconds** for the next server ping; each incoming protocol ping restarts that timer. If the ping is missing, the connection is terminated and automatic reconnect runs when enabled. Disable timeout monitoring with `heartbeatMonitoring: false`. `heartbeatIntervalMs` and `heartbeatTimeoutMs` apply only to Native and are ignored here, both in constructor options and when assigned on the client instance. Automatic protocol pongs remain active when `heartbeatMonitoring: false`. Ticket authentication does not change this heartbeat behavior. The `_pong` event reports heartbeat activity: an incoming server protocol ping that the runtime automatically answers, or an incoming JSON pong. It also fires with `heartbeatMonitoring: false`; that option disables timeout monitoring, not protocol replies or event notifications. This event does not confirm that the server received the reply.
+
+## Unsubscribe and clean up
+
+Using the connected `wsClient` from the WebSocket example:
+
+```ts
+const unsubscribe = wsClient.on("streamUpdate", (stream) => {
+  console.log("Updated stream:", stream.title);
+});
+
+// Later, remove this listener.
+unsubscribe();
+
+// Disconnect intentionally; listeners are retained for a later connect().
+wsClient.disconnect();
+
+// When finished, remove every listener and disconnect.
+wsClient.destroy();
+```
+
+`connect()` returns a promise that can reject. Handle connection failures with `try`/`catch`, and register an `_error` listener for errors after connecting:
+
+```ts
+import { NeuroInfoApiWebsocketClient } from "@neuroinfoapi-client/node";
+
+const wsClient = new NeuroInfoApiWebsocketClient("your-api-token-here");
+wsClient.on("_error", (error) => console.error("WebSocket error:", error));
+
+try {
+  await wsClient.connect();
+} catch (error) {
+  console.error("Connection failed:", error);
+  wsClient.destroy();
+}
+```
+
+## Documentation
+
+- [API documentation](https://neuroinfoapi.dev/api/docs)
+
+## License
+
+MIT

package/dist/WSController.d.ts

@@ -0,0 +1,13 @@
+import type { WSController as SharedWSController } from "@neuroinfoapi-client/core";
+export declare class WSController implements SharedWSController {
+    readonly heartbeatMode = "server-ping";
+    onPing: (() => void) | null;
+    private readonly socket;
+    constructor(url: string, headers?: Record<string, string>);
+    get readyState(): SharedWSController["readyState"];
+    send(data: Parameters<SharedWSController["send"]>[0]): void;
+    close(code?: number, reason?: string): void;
+    terminate(_code: number, _reason: string): void;
+    addEventListener: SharedWSController["addEventListener"];
+    removeEventListener: SharedWSController["removeEventListener"];
+}

package/dist/WSController.js

@@ -0,0 +1,24 @@
+import WebSocket from "ws";
+export class WSController {
+    constructor(url, headers) {
+        this.heartbeatMode = "server-ping";
+        this.onPing = null;
+        // ws's EventTarget adapter converts text frames and close reasons to strings
+        // and preserves listener identities (including once and handleEvent objects).
+        this.addEventListener = (type, listener, options) => {
+            this.socket.addEventListener(type, listener, options);
+        };
+        this.removeEventListener = (type, listener) => {
+            this.socket.removeEventListener(type, listener);
+        };
+        this.socket = new WebSocket(url, { headers });
+        // ws automatically answers protocol pings with matching pong frames.
+        this.socket.on("ping", () => this.onPing?.());
+        // An aborted handshake can emit error after the shared client removes listeners.
+        this.socket.on("error", () => { });
+    }
+    get readyState() { return this.socket.readyState; }
+    send(data) { this.socket.send(data); }
+    close(code, reason) { this.socket.close(code, reason); }
+    terminate(_code, _reason) { this.socket.terminate(); }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { NeuroInfoApiWebsocketClient as SharedWebsocketClient } from "@neuroinfoapi-client/core";
+import type { WSController as SharedWSController, NeuroInfoApiWebsocketClientOptions } from "@neuroinfoapi-client/core";
+export * from "@neuroinfoapi-client/core";
+export declare class NeuroInfoApiWebsocketClient extends SharedWebsocketClient {
+    constructor(token: string, options?: NeuroInfoApiWebsocketClientOptions);
+    /** Native-only timing option. Ignored here; server-ping monitoring uses a fixed 90-second timeout. */
+    get heartbeatIntervalMs(): number;
+    set heartbeatIntervalMs(_value: number);
+    /** Native-only timing option. Ignored here, including assignments after connecting. */
+    get heartbeatTimeoutMs(): number;
+    set heartbeatTimeoutMs(_value: number);
+    protected createWSController(url: string, headers?: Record<string, string>): SharedWSController;
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+import { NeuroInfoApiWebsocketClient as SharedWebsocketClient } from "@neuroinfoapi-client/core";
+import { WSController } from "./WSController.js";
+export * from "@neuroinfoapi-client/core";
+export class NeuroInfoApiWebsocketClient extends SharedWebsocketClient {
+    constructor(token, options = {}) {
+        super(token, {
+            ...options,
+            authMethod: options.authMethod ?? "header",
+        });
+    }
+    /** Native-only timing option. Ignored here; server-ping monitoring uses a fixed 90-second timeout. */
+    get heartbeatIntervalMs() { return 60000; }
+    set heartbeatIntervalMs(_value) { }
+    /** Native-only timing option. Ignored here, including assignments after connecting. */
+    get heartbeatTimeoutMs() { return 30000; }
+    set heartbeatTimeoutMs(_value) { }
+    createWSController(url, headers) {
+        return new WSController(url, { "User-Agent": this.userAgent, ...headers });
+    }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@neuroinfoapi-client/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.6.1",
+  "description": "A client for interacting with the NeuroInfoAPI (Node.js edition)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "publishPackage": "powershell -NoProfile -ExecutionPolicy Bypass -File ../../scripts/publishAsk.ps1 -Package node",
+    "deprecatePackage": "powershell -NoProfile -ExecutionPolicy Bypass -File ../../scripts/deprecateAsk.ps1 -Package node"
+  },
+  "keywords": [
+    "node",
+    "neuroinfoapi",
+    "nia",
+    "vedal987",
+    "neurosama",
+    "neuro-sama"
+  ],
+  "author": "Appstun",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/NeuroInfoAPI/NPM-Package/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NeuroInfoAPI/NPM-Package.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://neuroinfoapi.dev/api/docs",
+  "dependencies": {
+    "@neuroinfoapi-client/core": "2.6.1",
+    "ws": "^8.22.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/ws": "^8.18.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}