@ix-xs/twitch.api 1.0.5 → 2.0.1

package/dist/node.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/node.ts
+var FileTokenStore = class {
+  path;
+  #cache;
+  #queue = Promise.resolve();
+  constructor(path$1 = "./tokens.json") {
+    this.path = path.resolve(path$1);
+  }
+  async get(userId) {
+    return (await this.#read())[userId];
+  }
+  async set(userId, token) {
+    const tokens = await this.#read();
+    tokens[userId] = token;
+    await this.#write();
+  }
+  async delete(userId) {
+    const tokens = await this.#read();
+    if (!(userId in tokens)) return;
+    delete tokens[userId];
+    await this.#write();
+  }
+  async list() {
+    return Object.keys(await this.#read());
+  }
+  #read() {
+    return this.#cache ??= (async () => {
+      try {
+        const parsed = JSON.parse(await promises.readFile(this.path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+      } catch (error) {
+        if (error.code === "ENOENT") return {};
+        this.#cache = void 0;
+        throw error;
+      }
+    })();
+  }
+  #write() {
+    const run = this.#queue.then(async () => {
+      const temporary = `${this.path}.${process.pid}.tmp`;
+      await promises.mkdir(path.dirname(this.path), { recursive: true });
+      await promises.writeFile(temporary, `${JSON.stringify(await this.#read(), null, 2)}
+`, { mode: 384 });
+      await promises.rename(temporary, this.path);
+    });
+    this.#queue = run.catch(() => {
+    });
+    return run;
+  }
+};
+
+exports.FileTokenStore = FileTokenStore;

package/dist/node.d.cts

@@ -0,0 +1,36 @@
+import { T as TokenStore, U as UserToken } from './tokens-DlOL0kjk.cjs';
+
+/**
+ * Persists user tokens in a JSON file. Writes are atomic (a temporary file
+ * renamed into place) and serialised, so a crash or two refreshes at once
+ * never leave a broken file behind. The file is created with owner-only
+ * permissions where the platform supports them.
+ *
+ * Add the file to your `.gitignore`: it holds credentials.
+ *
+ * @example
+ * import { Twitch } from "@ix-xs/twitch.api";
+ * import { FileTokenStore } from "@ix-xs/twitch.api/node";
+ *
+ * const twitch = new Twitch({
+ *   clientId,
+ *   clientSecret,
+ *   tokens: new FileTokenStore("./tokens.json"),
+ * });
+ */
+declare class FileTokenStore implements TokenStore {
+    #private;
+    /** Absolute path of the file. */
+    readonly path: string;
+    constructor(path?: string);
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): Promise<UserToken | undefined>;
+    /** Saves or replaces the token of `userId`, then writes the file. */
+    set(userId: string, token: UserToken): Promise<void>;
+    /** Forgets the token of `userId`, then writes the file. */
+    delete(userId: string): Promise<void>;
+    /** Returns every saved user ID. */
+    list(): Promise<string[]>;
+}
+
+export { FileTokenStore };

package/dist/node.d.ts

@@ -0,0 +1,36 @@
+import { T as TokenStore, U as UserToken } from './tokens-DlOL0kjk.js';
+
+/**
+ * Persists user tokens in a JSON file. Writes are atomic (a temporary file
+ * renamed into place) and serialised, so a crash or two refreshes at once
+ * never leave a broken file behind. The file is created with owner-only
+ * permissions where the platform supports them.
+ *
+ * Add the file to your `.gitignore`: it holds credentials.
+ *
+ * @example
+ * import { Twitch } from "@ix-xs/twitch.api";
+ * import { FileTokenStore } from "@ix-xs/twitch.api/node";
+ *
+ * const twitch = new Twitch({
+ *   clientId,
+ *   clientSecret,
+ *   tokens: new FileTokenStore("./tokens.json"),
+ * });
+ */
+declare class FileTokenStore implements TokenStore {
+    #private;
+    /** Absolute path of the file. */
+    readonly path: string;
+    constructor(path?: string);
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): Promise<UserToken | undefined>;
+    /** Saves or replaces the token of `userId`, then writes the file. */
+    set(userId: string, token: UserToken): Promise<void>;
+    /** Forgets the token of `userId`, then writes the file. */
+    delete(userId: string): Promise<void>;
+    /** Returns every saved user ID. */
+    list(): Promise<string[]>;
+}
+
+export { FileTokenStore };

package/dist/node.js

@@ -0,0 +1,55 @@
+import { readFile, mkdir, writeFile, rename } from 'fs/promises';
+import { resolve, dirname } from 'path';
+
+// src/node.ts
+var FileTokenStore = class {
+  path;
+  #cache;
+  #queue = Promise.resolve();
+  constructor(path = "./tokens.json") {
+    this.path = resolve(path);
+  }
+  async get(userId) {
+    return (await this.#read())[userId];
+  }
+  async set(userId, token) {
+    const tokens = await this.#read();
+    tokens[userId] = token;
+    await this.#write();
+  }
+  async delete(userId) {
+    const tokens = await this.#read();
+    if (!(userId in tokens)) return;
+    delete tokens[userId];
+    await this.#write();
+  }
+  async list() {
+    return Object.keys(await this.#read());
+  }
+  #read() {
+    return this.#cache ??= (async () => {
+      try {
+        const parsed = JSON.parse(await readFile(this.path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+      } catch (error) {
+        if (error.code === "ENOENT") return {};
+        this.#cache = void 0;
+        throw error;
+      }
+    })();
+  }
+  #write() {
+    const run = this.#queue.then(async () => {
+      const temporary = `${this.path}.${process.pid}.tmp`;
+      await mkdir(dirname(this.path), { recursive: true });
+      await writeFile(temporary, `${JSON.stringify(await this.#read(), null, 2)}
+`, { mode: 384 });
+      await rename(temporary, this.path);
+    });
+    this.#queue = run.catch(() => {
+    });
+    return run;
+  }
+};
+
+export { FileTokenStore };

package/dist/tokens-DlOL0kjk.d.cts

@@ -0,0 +1,97 @@
+/** A value or a promise of it. */
+type Awaitable<T> = T | PromiseLike<T>;
+type Listener<A extends unknown[]> = (...args: A) => void;
+/** Minimal typed event emitter. A listener that throws never breaks the emitter. */
+declare class Emitter<Events extends {
+    [K in keyof Events]: unknown[];
+}> {
+    #private;
+    /** Registers a listener. Returns a function that removes it. */
+    on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /** Registers a listener that runs once. */
+    once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /** Removes a listener. */
+    off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+    /** Calls every listener of `event`. Returns whether there was at least one. */
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): boolean;
+    /** Whether `event` has at least one listener. */
+    has(event: keyof Events): boolean;
+    /** Removes every listener. */
+    clear(): void;
+}
+
+/** A user access token and what is known about it. Plain JSON, safe to persist. */
+interface UserToken {
+    /** ID of the user who granted the token. */
+    userId: string;
+    /** Login name of that user, when known. */
+    login?: string;
+    /** The access token itself. */
+    accessToken: string;
+    /** Refresh token. Without it the access token cannot be renewed once it expires. */
+    refreshToken?: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Epoch milliseconds at which the access token expires. Absent when unknown. */
+    expiresAt?: number;
+}
+/** What you hand to `twitch.auth.addUser()`. Only the access token is mandatory. */
+interface UserTokenInput {
+    /** The access token. */
+    accessToken: string;
+    /** Refresh token, needed for automatic renewal. */
+    refreshToken?: string;
+    /** Scopes of the token. Looked up from Twitch when omitted. */
+    scopes?: readonly string[];
+    /** Expiry as epoch milliseconds or a `Date`. */
+    expiresAt?: number | Date;
+    /** Lifetime in seconds, as returned by Twitch. Used when `expiresAt` is absent. */
+    expiresIn?: number;
+    /** Owner of the token. Looked up from Twitch when omitted. */
+    userId?: string;
+    /** Login of the owner. */
+    login?: string;
+}
+/** Result of validating a token against Twitch. */
+interface TokenInfo {
+    /** Client ID the token was issued to. */
+    clientId: string;
+    /** Owner of the token. `null` for an app access token. */
+    userId: string | null;
+    /** Login of the owner. `null` for an app access token. */
+    login: string | null;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Seconds left before the token expires. `0` means it never expires. */
+    expiresIn: number;
+    /** Epoch milliseconds at which the token expires. Absent when it never expires. */
+    expiresAt?: number;
+}
+/**
+ * Where user tokens are persisted between runs. Implement it on top of a
+ * database, a KV store or a file. Every method may be sync or async.
+ */
+interface TokenStore {
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): Awaitable<UserToken | undefined>;
+    /** Saves or replaces the token of `userId`. Called after every refresh. */
+    set(userId: string, token: UserToken): Awaitable<void>;
+    /** Forgets the token of `userId`. */
+    delete(userId: string): Awaitable<void>;
+    /** Returns every saved user ID. When present, tokens are restored on first use. */
+    list?(): Awaitable<string[]>;
+}
+/** Keeps tokens in memory. The default store: nothing survives a restart. */
+declare class MemoryTokenStore implements TokenStore {
+    #private;
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): UserToken | undefined;
+    /** Saves or replaces the token of `userId`. */
+    set(userId: string, token: UserToken): void;
+    /** Forgets the token of `userId`. */
+    delete(userId: string): void;
+    /** Returns every saved user ID. */
+    list(): string[];
+}
+
+export { type Awaitable as A, Emitter as E, MemoryTokenStore as M, type TokenStore as T, type UserToken as U, type UserTokenInput as a, type TokenInfo as b };

package/dist/tokens-DlOL0kjk.d.ts

@@ -0,0 +1,97 @@
+/** A value or a promise of it. */
+type Awaitable<T> = T | PromiseLike<T>;
+type Listener<A extends unknown[]> = (...args: A) => void;
+/** Minimal typed event emitter. A listener that throws never breaks the emitter. */
+declare class Emitter<Events extends {
+    [K in keyof Events]: unknown[];
+}> {
+    #private;
+    /** Registers a listener. Returns a function that removes it. */
+    on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /** Registers a listener that runs once. */
+    once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /** Removes a listener. */
+    off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+    /** Calls every listener of `event`. Returns whether there was at least one. */
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): boolean;
+    /** Whether `event` has at least one listener. */
+    has(event: keyof Events): boolean;
+    /** Removes every listener. */
+    clear(): void;
+}
+
+/** A user access token and what is known about it. Plain JSON, safe to persist. */
+interface UserToken {
+    /** ID of the user who granted the token. */
+    userId: string;
+    /** Login name of that user, when known. */
+    login?: string;
+    /** The access token itself. */
+    accessToken: string;
+    /** Refresh token. Without it the access token cannot be renewed once it expires. */
+    refreshToken?: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Epoch milliseconds at which the access token expires. Absent when unknown. */
+    expiresAt?: number;
+}
+/** What you hand to `twitch.auth.addUser()`. Only the access token is mandatory. */
+interface UserTokenInput {
+    /** The access token. */
+    accessToken: string;
+    /** Refresh token, needed for automatic renewal. */
+    refreshToken?: string;
+    /** Scopes of the token. Looked up from Twitch when omitted. */
+    scopes?: readonly string[];
+    /** Expiry as epoch milliseconds or a `Date`. */
+    expiresAt?: number | Date;
+    /** Lifetime in seconds, as returned by Twitch. Used when `expiresAt` is absent. */
+    expiresIn?: number;
+    /** Owner of the token. Looked up from Twitch when omitted. */
+    userId?: string;
+    /** Login of the owner. */
+    login?: string;
+}
+/** Result of validating a token against Twitch. */
+interface TokenInfo {
+    /** Client ID the token was issued to. */
+    clientId: string;
+    /** Owner of the token. `null` for an app access token. */
+    userId: string | null;
+    /** Login of the owner. `null` for an app access token. */
+    login: string | null;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Seconds left before the token expires. `0` means it never expires. */
+    expiresIn: number;
+    /** Epoch milliseconds at which the token expires. Absent when it never expires. */
+    expiresAt?: number;
+}
+/**
+ * Where user tokens are persisted between runs. Implement it on top of a
+ * database, a KV store or a file. Every method may be sync or async.
+ */
+interface TokenStore {
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): Awaitable<UserToken | undefined>;
+    /** Saves or replaces the token of `userId`. Called after every refresh. */
+    set(userId: string, token: UserToken): Awaitable<void>;
+    /** Forgets the token of `userId`. */
+    delete(userId: string): Awaitable<void>;
+    /** Returns every saved user ID. When present, tokens are restored on first use. */
+    list?(): Awaitable<string[]>;
+}
+/** Keeps tokens in memory. The default store: nothing survives a restart. */
+declare class MemoryTokenStore implements TokenStore {
+    #private;
+    /** Returns the token saved for `userId`, if any. */
+    get(userId: string): UserToken | undefined;
+    /** Saves or replaces the token of `userId`. */
+    set(userId: string, token: UserToken): void;
+    /** Forgets the token of `userId`. */
+    delete(userId: string): void;
+    /** Returns every saved user ID. */
+    list(): string[];
+}
+
+export { type Awaitable as A, Emitter as E, MemoryTokenStore as M, type TokenStore as T, type UserToken as U, type UserTokenInput as a, type TokenInfo as b };

package/package.json

@@ -1,20 +1,101 @@
-{
-    "name": "@ix-xs/twitch.api",
-    "version": "1.0.5",
-    "description": "Twitch API JS",
-    "main": "twitchapi.js",
-    "scripts": {
-      "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "repository": {
-      "type": "git",
-      "url": "github.com/ix-xs/twitch.api"
-    },
-    "keywords": [
-      "Twitch",
-      "API",
-      "JS"
-    ],
-    "author": "ix-xs",
-    "license": "ISC"
-}
+{
+  "name": "@ix-xs/twitch.api",
+  "version": "2.0.1",
+  "description": "The whole Twitch API, typed. A zero-dependency client for JavaScript and TypeScript: all 149 Helix endpoints and 83 EventSub events, with tokens, rate limits, pagination and reconnects handled for you.",
+  "keywords": [
+    "twitch",
+    "twitch-api",
+    "helix",
+    "eventsub",
+    "twitch-bot",
+    "chat-bot",
+    "oauth",
+    "websocket",
+    "webhook",
+    "typescript",
+    "esm",
+    "zero-dependency",
+    "api-client"
+  ],
+  "author": "ix-xs.dev <contact@ix-xs.dev>",
+  "license": "MIT",
+  "homepage": "https://ix-xs.github.io/twitch.api/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ix-xs/twitch.api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ix-xs/twitch.api/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./node": {
+      "import": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "node": [
+        "./dist/node.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "tsc -p tsconfig.test.json",
+    "attw": "attw --pack .",
+    "check": "npm run typecheck && npm run test:types && npm run check:jsdoc && npm run build && npm test && npm run docs:check",
+    "docs": "npm --prefix docs install && npm --prefix docs run dev",
+    "docs:build": "npm --prefix docs install && npm --prefix docs run build",
+    "docs:reference": "node docs/scripts/reference.mjs",
+    "docs:check": "node docs/scripts/reference.mjs --check && node docs/scripts/check-snippets.mjs",
+    "prepublishOnly": "npm run check",
+    "check:jsdoc": "node scripts/check-jsdoc.mjs"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/Token.json

@@ -1,6 +0,0 @@
-{
-    "access_token": "",
-    "expires_in": 0,
-    "token_type": "",
-    "created_at": 0
-}