kicksdk-js 0.2.0 → 0.3.0

package/README.md

@@ -36,7 +36,9 @@ limit: `terminal: true`) it never gives up, but waits long - 5, 10, 20, then
 comes back as a new guest client (a new client id, so a new token). The chat
 feed subscribing again ends the streak. `docs/KICK.md` §6.1 has the rules.
 A callback that throws is reported to `onError` (or `console.error`) without
-disturbing the connection; none fires after `close()`.
+disturbing the connection; none fires after `close()`, and what throws after
+it goes to `console.error`. A panic in the WebAssembly is reported too, and
+ends that connection; the next one starts on a new session.
 
 A mistake in the options throws from `connectChat` at once: a bad id or
 endpoint, a `timeoutMs` that is not a number of ms above 0 and at most
@@ -59,12 +61,72 @@ relay through a server.
 Everything else - `channelRequest` / `parseChannel`, `historyRequest`,
 `livestreamsRequests`, `verifyWebhook`, `parseEvent`, `parseContent`, … -
 returns plain request objects for your `fetch` and parses what comes back.
-Parsers throw an `Error` with a `status` when Kick answered with an error.
+Parsers throw an `Error` with a `status` when Kick answered with an error,
+and an `excerpt`: the start of Kick's answer, which often says why
+(`CHANNEL_IS_NOT_LIVE`). The message ends with it too.
 Every number must be a JS number - a numeric string or a boolean throws a
 `TypeError` rather than being converted - and ids, statuses, times and
 counts whole ones in range (ids at most `Number.MAX_SAFE_INTEGER`), or a
 `RangeError` is thrown rather than the number being rounded into another
-id.
+id. The same holds for results: one that would carry an integer above
+`Number.MAX_SAFE_INTEGER` (an id Kick sent that large) throws rather than
+coming back rounded.
+
+**User tokens.** To act as a Kick user (send chat, moderate, edit their
+channel, manage rewards), get a user token with OAuth's authorization code
+flow and PKCE. The core draws no random numbers: `newPkce()` and `newState()`
+take them from `crypto.getRandomValues`.
+
+```js
+const pkce = kick.newPkce();                  // { verifier, challenge }
+const state = kick.newState();
+// keep pkce.verifier and state (a session) until the user comes back
+location = kick.oauthAuthorizeUrl(clientId, redirectUri, ['user:read', 'chat:write'], state, pkce.verifier);
+
+// on the redirect: check ?state= is yours, then
+const token = kick.oauthParseUserToken(...await call(
+  kick.oauthCodeRequest(clientId, clientSecret, redirectUri, code, pkce.verifier)));
+// later: oauthRefreshRequest(clientId, clientSecret, token.refresh_token) -> a new pair
+```
+`oauthRevokeRequest(token, 'access_token' | 'refresh_token')` /
+`oauthParseRevoke`, `oauthIntrospectRequest(token)` / `oauthParseIntrospect`
+(`{active, client_id, exp, scopes, token_type}`), and `oauthScopes()`, the 13
+scopes Kick documents, complete the set; `oauthPkce(bytes)` and
+`oauthPkceFromVerifier(verifier)` make a pair from your own 32 to 96 random
+bytes or a kept verifier. **The verifier, the client secret and both tokens
+are secrets: never log them**, nor a request carrying them
+(`oauthRevokeRequest` puts the token in its URL).
+
+With the token (`call` being your `fetch` that returns `[status, text]`):
+
+```js
+const sent = kick.chatParseSend(...await call(kick.chatSendRequest(token, { user: broadcasterUserId }, 'hi')));
+kick.parseDone(...await call(kick.moderationTimeoutRequest(token, broadcasterUserId, userId, 10, 'spam')));
+```
+- chat: `chatSendRequest(token, {user} | 'bot', content, replyToMessageId?)` /
+  `chatParseSend`, `chatDeleteRequest(token, messageId)`;
+- moderation: `moderationBanRequest(token, broadcasterUserId, userId, reason?)`,
+  `moderationTimeoutRequest(…, minutes, reason?)`, `moderationUnbanRequest`;
+- the token's channel: `channelsUpdateRequest(token, categoryId?, customTags?, streamTitle?)`;
+- rewards: `rewardsListRequest` / `rewardsParseRewards`,
+  `rewardsCreateRequest(token, fields)` and `rewardsUpdateRequest(token, id, fields)` /
+  `rewardsParseReward` (`fields` as Kick names them: `{title, cost, is_enabled, …}`),
+  `rewardsDeleteRequest`, `rewardsRedemptionsRequest(token, rewardId?, status?, cursor?)`
+  and `rewardsRedemptionsByIdsRequest(token, ids, cursor?)` / `rewardsParseRedemptions`,
+  `rewardsAcceptRequest` and `rewardsRejectRequest(token, ids)` / `rewardsParseFailures`;
+- ads: `adsAdBreakRequest(token, crypto.randomUUID(), seconds)` / `adsParseAdBreak`,
+  `adsStatusRequest` / `adsParseStatus`, `adsEnrollRequest`;
+- drops (an app token): `dropsClaimsRequest(token, {campaign_id, user_id, limit, cursor, …})` /
+  `dropsParseClaims`, `dropsUpdateClaimsRequest(token, [{claim_id, external_status}])`;
+- reads, an app or a user token: `usersRequest(token, userIds?)` / `parseUsers`,
+  `categoriesRequest(token, names?, tags?, ids?, limit?, cursor?)` / `parseCategories`,
+  `livestreamStatsRequest` / `parseLivestreamStats`, `kicksLeaderboardRequest(token, top?)` /
+  `parseKicksLeaderboard`.
+
+Calls whose answer carries nothing are read with `parseDone(status, body)`,
+which throws with the `status` unless it is a 2xx. Option objects (`fields`,
+the drops filter, the claim updates, `{user}`) refuse a key they do not know.
+`index.d.ts` types every result (`UserToken`, `Reward`, `Page<Category>`, …).
 
 **Webhooks.** Read Kick's key once and check each delivery against the raw
 body (text or bytes), its headers (pairs, a fetch `Headers`, or an object),
@@ -83,3 +145,17 @@ the key): deduplicate on `headers.message_id`. See `docs/KICK.md` §4.3.
 
 See the repository's `docs/KICK.md` for everything known about Kick, with
 sources. MIT OR Apache-2.0. Not affiliated with Kick.
+
+## Live API coverage
+
+The shared core was checked against Kick on 2026-11-15: OAuth code exchange
+with PKCE, refresh/revocation/introspection, app and user reads, chat
+send/reply/delete, timeout/ban/unban and reward create/update/delete.
+Bot send returned 404; channel editing was skipped because no original title
+was available to restore. Ad breaks, enrollment, drops and redemption
+accept/reject remain documentation-based. See the repository `docs/KICK.md`
+and `fixtures/{public_api,id}/README.md` for evidence and limits.
+
+Check granted OAuth scopes before protected calls: Kick can grant fewer than
+requested. Never log tokens, client secrets, authorization codes, PKCE
+verifiers or requests carrying them.

package/index.d.ts

@@ -1,9 +1,19 @@
 export * from './pkg/kicksdk.js';
-import type { Endpoints } from './pkg/kicksdk.js';
+import type { Endpoints, Pkce } from './pkg/kicksdk.js';
 
 /** The Origin Kick's realtime server accepts. */
 export const REQUIRED_ORIGIN: 'https://kick.com';
 
+/**
+ * A new PKCE pair from 32 bytes of `crypto.getRandomValues`, for
+ * `oauthAuthorizeUrl` and `oauthCodeRequest`. The verifier is a secret: keep
+ * it until the user comes back, never log it.
+ */
+export function newPkce(): Pkce;
+
+/** A new OAuth `state`: 32 bytes of `crypto.getRandomValues`, base64url without padding. */
+export function newState(): string;
+
 /**
  * Loads the WebAssembly: a URL, a Response (or a promise of one), the .wasm
  * bytes or a compiled module. Safe to call more than once; after a failure,
@@ -100,7 +110,8 @@ export interface ChatOptions {
   onDrop?: ((reason: string, drop: ChatDrop) => void) | undefined;
   /**
    * A callback above threw, or `now` gave a reading it cannot use. Default:
-   * console.error. The connection carries on either way.
+   * console.error. The connection carries on either way. Not called after
+   * `close()`: what throws then goes to console.error.
    */
   onError?: ((error: unknown) => void) | undefined;
   /** The fetch to make Kick's requests with. Default: the global fetch. */

package/index.js

@@ -20,13 +20,35 @@ import initWasm, {
   parseConnection,
   tokenRequest,
   parseToken,
-  retryAfterMs
+  retryAfterMs,
+  oauthPkce
 } from './pkg/kicksdk.js';
 
 export * from './pkg/kicksdk.js';
 
 export const REQUIRED_ORIGIN = 'https://kick.com';
 
+// The core draws no random numbers: these two take them from the platform's
+// CSPRNG (crypto.getRandomValues, in browsers and Node alike).
+
+const randomBytes = (n) => crypto.getRandomValues(new Uint8Array(n));
+
+/**
+ * A new PKCE pair, from 32 random bytes. The verifier is a secret: keep it
+ * until the user comes back, never log it.
+ */
+export function newPkce() {
+  return oauthPkce(randomBytes(32));
+}
+
+/** A new OAuth `state`: 32 random bytes, base64url without padding. */
+export function newState() {
+  return btoa(String.fromCharCode(...randomBytes(32)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
 let ready = null;
 
 /**
@@ -149,7 +171,9 @@ function socketFactory(o) {
  *
  * Callbacks are isolated: one that throws is reported to `onError` (or
  * console.error) and the connection carries on. None is called after
- * close(), which may be called from inside one.
+ * close(), which may be called from inside one; what throws after it goes
+ * to console.error. A panic in the WebAssembly ends the connection, and the
+ * reconnect starts on a new Session.
  *
  * @param {object} o  ChatOptions, in index.d.ts
  * @returns {{ close(): void }}
@@ -192,7 +216,8 @@ export function connectChat(o) {
   let retry = null;
 
   function report(error) {
-    if (o.onError) {
+    // After close() no callback runs, onError included.
+    if (o.onError && !closed) {
       try {
         o.onError(error);
         return;
@@ -371,9 +396,22 @@ export function connectChat(o) {
     }
   }
 
+  /**
+   * Frees `x`, if any. After a panic in the WebAssembly (a trap) a Session
+   * stays borrowed and throws on every call, free included: it is let go
+   * all the same.
+   */
+  function free(x) {
+    try {
+      x?.free();
+    } catch {
+      // Unusable; nothing more to do with it.
+    }
+  }
+
   function release() {
-    if (session) session.free();
-    if (backoff) backoff.free();
+    free(session);
+    free(backoff);
     session = backoff = null;
   }
 
@@ -397,7 +435,14 @@ export function connectChat(o) {
   function end(reason, code, retryAfterMs, terminal) {
     detach();
     if (closed) return;
-    session.closed();
+    try {
+      session.closed();
+    } catch {
+      // A panic (a trap, reported where it happened) left the session
+      // unusable: start over with a new one, which the reconnect opens.
+      free(session);
+      session = new Session(channels);
+    }
     state();
     drop(reason, code, retryAfterMs, terminal);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kicksdk-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Kick (kick.com) without the I/O: requests, parsers, the realtime chat protocol and webhook verification, from one Rust core",
   "license": "MIT OR Apache-2.0",
   "repository": { "type": "git", "url": "git+https://github.com/AnisAbdellatif/kicksdk.git", "directory": "bindings/js" },