kicksdk-js 0.1.1 → 0.3.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

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

@@ -19,10 +19,40 @@ const chat = kick.connectChat({
     if (event.type === 'chat_message') console.log(`${event.sender.username}: ${event.content}`);
   },
   onState: ({ connected, subscribed }) => {},
+  onDrop: (reason, { code, terminal, waitMs }) => {
+    if (terminal) console.warn(`Kick refused this client (${reason}); back in ${waitMs / 60_000} min`);
+  },
 });
 chat.close();
 ```
 
+`connectChat` keeps the chat up until `close()`. Whenever a connection ends
+(Kick went quiet, the socket closed, a request or the handshake took longer
+than `timeoutMs`, 10 s by default), `onDrop` says why and how long it waits
+before connecting again (`waitMs`): a jittered backoff from 0.5 s to 30 s.
+After one of Kick's terminal closes (a refused token, a ban, a connection
+limit: `terminal: true`) it never gives up, but waits long - 5, 10, 20, then
+30 minutes for terminal closes in a row, each plus up to a quarter - and
+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()`, 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
+2147483647 (setTimeout's limit), an option that should be a function and is
+not. The backoff resets when the first of `channels` (the chat feed, by
+default) subscribes, or, with `channels: []`, when Kick accepts the
+connection. A `now` clock that returns anything but a number of ms from 0
+to `Number.MAX_SAFE_INTEGER` is reported to `onError` once, and
+`performance.now()` takes over.
+
+Node 22 and later have a `WebSocket`. On older Node, pass one:
+`connectChat({ ..., WebSocket })` with the `ws` package's class. Without
+one, `connectChat` throws.
+
 **Where the feed works.** Kick's realtime server only accepts a WebSocket whose
 Origin is `https://kick.com`. Node: works (the driver sets the header). Browser:
 only on kick.com - a page there or an extension's content script. Elsewhere,
@@ -31,7 +61,101 @@ 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. 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),
+and the clock: the timestamp must be within 5 minutes of `now` (Unix
+seconds; this machine's clock by default).
+
+```js
+const key = new kick.WebhookPublicKey(pem);   // from publicKeyRequest / parsePublicKey
+const { headers, event } = key.verify(req.headers, rawBody);
+// or: kick.verifyWebhook(pem, headers, rawBody, { now, toleranceSecs })
+// a stored delivery, checked again later: { skipFreshness: true }
+```
+
+A valid signature means Kick sent this body to *some* app (every app shares
+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,10 +1,27 @@
 export * 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';
 
-/** Loads the WebAssembly: a URL, a Response, or the .wasm bytes. */
-export function init(input?: string | URL | Request | Response | BufferSource): Promise<void>;
+/**
+ * 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,
+ * the next call tries again.
+ */
+export function init(
+  input?: string | URL | Request | Response | Promise<Response> | BufferSource | WebAssembly.Module
+): Promise<void>;
 
 export interface ChatEvent {
   /** The feed it came on, e.g. `chatrooms.668.v2`. */
@@ -17,18 +34,119 @@ export interface ChatEvent {
   event: { type: string; [key: string]: unknown };
 }
 
+/** What connectChat knows of the connection. */
+export interface ChatState {
+  /** Kick accepted the connection. */
+  connected: boolean;
+  /** The feeds subscribed now. */
+  subscribed: string[];
+}
+
+/** Why a connection, or an attempt at one, ended, and when the next one starts. */
+export interface ChatDrop {
+  /**
+   * Kick's disconnect or error code, the socket's close code (1006 for a
+   * network drop or a refused handshake), or 0 (a timeout, a failed request,
+   * silence).
+   */
+  code: number;
+  /**
+   * Kick will not take this client back as it is (a refused token, a ban, a
+   * connection limit: codes 3500-3999 and 4500-4999, among others). Not the
+   * end: connectChat waits longer (`waitMs`, 5 minutes or more) and comes
+   * back as a new guest client. Worth a warning.
+   */
+  terminal: boolean;
+  /**
+   * How long connectChat waits before connecting again, ms: the ordinary
+   * backoff (0.5 s growing to 30 s, jittered), or after a terminal close 5,
+   * 10, 20, then 30 minutes in a row, plus up to a quarter.
+   */
+  waitMs: number;
+}
+
+/**
+ * The part of a WebSocket connectChat uses: the browser's, Node's (22 and
+ * later), and the `ws` package's all fit.
+ */
+export interface ChatSocket {
+  readonly readyState: number;
+  send(data: string): void;
+  close(): void;
+  onopen: ((ev: any) => any) | null;
+  onmessage: ((ev: any) => any) | null;
+  onclose: ((ev: any) => any) | null;
+  onerror: ((ev: any) => any) | null;
+}
+
+/**
+ * A WebSocket class. In Node it is given `{ headers: { Origin } }` as its
+ * second argument, as Node's own and the `ws` package's take it.
+ */
+export type ChatSocketConstructor = new (url: string, options?: any) => ChatSocket;
+
+/**
+ * connectChat's options. Every optional one may be left out or given as
+ * undefined (as a `Partial<>` or optional config carries it), with the same
+ * meaning.
+ */
 export interface ChatOptions {
+  /** The chatroom (website API `chatroom.id`). */
   chatroomId: number;
-  channelId?: number;
-  channels?: string[];
+  /** The channel; also locates the chat's region. */
+  channelId?: number | undefined;
+  /**
+   * The feeds to subscribe to; `chatChannels(chatroomId, channelId)` by
+   * default. The first is taken for the chat feed: its subscribe resets the
+   * reconnect backoff (with none listed, Kick accepting the connection does).
+   * A feed listed twice is subscribed and reported once.
+   */
+  channels?: readonly string[] | undefined;
+  /** An event on a feed. */
   onEvent(e: ChatEvent): void;
-  onState?(s: { connected: boolean; subscribed: string[] }): void;
-  onDrop?(reason: string): void;
-  fetch?: typeof fetch;
-  createSocket?(url: string): WebSocket;
-  endpoints?: Partial<{ api: string; id: string; website: string; realtime: string }>;
-  now?(): number;
+  /** The connection or its subscriptions changed. */
+  onState?: ((s: ChatState) => void) | undefined;
+  /** A connection, or an attempt at one, ended; another follows after `drop.waitMs`. */
+  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. 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. */
+  fetch?: typeof fetch | undefined;
+  /**
+   * The WebSocket class, where the runtime has none (Node before 22: pass the
+   * `ws` package's). Default: the global WebSocket.
+   */
+  WebSocket?: ChatSocketConstructor | undefined;
+  /** Opens the socket yourself, instead of `WebSocket`. */
+  createSocket?: ((url: string) => ChatSocket) | undefined;
+  /** Kick's URLs to use instead; a key left out or undefined stays Kick's. */
+  endpoints?: Endpoints | undefined;
+  /**
+   * The session's clock, ms, only ever going forward. Default:
+   * `performance.now()`. A reading that is not a number from 0 to
+   * `Number.MAX_SAFE_INTEGER` (or a throw) is reported to `onError` once,
+   * and connectChat carries on with `performance.now()`.
+   */
+  now?: (() => number) | undefined;
+  /**
+   * How long a request, or the WebSocket handshake, may take, ms: above 0
+   * and at most 2147483647 (setTimeout's limit; there is no "no timeout").
+   * Default 10000. Out of range, or not a number: connectChat throws a
+   * RangeError.
+   */
+  timeoutMs?: number | undefined;
 }
 
-/** Connects to one channel's chat and keeps it up until `close()`. */
+/**
+ * Connects to one channel's chat and keeps it up until `close()`: whatever
+ * ends a connection, `onDrop` says why and how long connectChat waits before
+ * the next (long after a `terminal` one). No callback fires after `close()`,
+ * which may be called more than once, and from inside a callback. Throws at
+ * once on a mistake in the options, or when the runtime has no WebSocket and
+ * none is given.
+ */
 export function connectChat(options: ChatOptions): { close(): void };