kicksdk-js 0.1.1 → 0.2.0

package/pkg/kicksdk.d.ts

@@ -1,28 +1,98 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/** Base URLs to use instead of Kick's. Any left out, or undefined, stay Kick's. */
+export interface Endpoints {
+    /** The official API: `https://api.kick.com/public/v1`. */
+    api?: string | undefined;
+    /** OAuth: `https://id.kick.com`. */
+    id?: string | undefined;
+    /** kick.com itself, whose `/api/v2` is the website API. */
+    website?: string | undefined;
+    /** The realtime endpoints: `https://web.kick.com/api/v1/realtime`. */
+    realtime?: string | undefined;
+}
+
+/** The message a reply answers, from its chat event: `sender_id` is the sender's user id. */
+export interface ReplyTo {
+    message_id: string;
+    content?: string | undefined;
+    sender_id: number;
+    sender_username: string;
+}
+
+/** A webhook delivery's headers: `[name, value]` pairs (a fetch `Headers` will do) or an object. */
+export type WebhookHeaders = Iterable<readonly [string, string]> | Record<string, string>;
+
+/** How a delivery's timestamp is checked. By default: within 5 minutes of this machine's clock. */
+export interface VerifyOptions {
+    /** Now, Unix **seconds** (not `Date.now()`'s milliseconds). Default: this machine's clock. */
+    now?: number | undefined;
+    /** How far from `now` the timestamp may be, either way, in seconds. Default 300. */
+    toleranceSecs?: number | undefined;
+    /** No freshness check: to re-check a delivery stored earlier. A live receiver never skips it. */
+    skipFreshness?: boolean | undefined;
+}
+
+/** A delivery that passed: its headers and the typed event. */
+export interface VerifiedWebhook {
+    headers: {
+        message_id: string;
+        timestamp: string;
+        signature: string;
+        event_type: string;
+        version: string;
+        subscription_id: string | null;
+    };
+    event: { type: string; [key: string]: unknown };
+}
+
+
+
 /**
- * Reconnect delays: 1 s doubling to 30 s.
+ * Reconnect delays: 1 s doubling to 30 s, and a slower stage for terminal
+ * closes (`nextDelayFor`).
  */
 export class Backoff {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * From `initialMs`, doubling to `maxMs`.
+     * From `initialMs`, doubling to `maxMs` (whole milliseconds).
      */
     constructor(initial_ms?: number | null, max_ms?: number | null);
+    /**
+     * The wait before reconnecting after a connection ended, ms.
+     * `retryAfterMs` is what the end asked for: a `close` action's
+     * `retry_after_ms`, `retryAfterMs(code)` for a socket's close code, or 0
+     * for a failure without a code. With 0, exactly `nextDelayJittered`.
+     * With more (a terminal close), at least that, doubling with each
+     * terminal close since `reset()` up to six times it (300000: 5, 10, 20,
+     * then 30 minutes), plus up to a quarter more by `random`. Reconnect
+     * with a new client id after a terminal close.
+     */
+    nextDelayFor(retry_after_ms: number, random: number): number;
+    /**
+     * The next wait, ms, spread over [half of it, all of it] by `random`,
+     * drawn uniformly from [0, 1) (`Math.random()`), so that clients dropped
+     * together do not all come back together. Out of range is clamped, NaN
+     * taken as 0.
+     */
+    nextDelayJittered(random: number): number;
     /**
      * The next wait, ms.
      */
     nextDelay(): number;
     /**
-     * A connection worked.
+     * The chat feed subscribed: back to the first wait, and the terminal
+     * streak ends.
      */
     reset(): void;
 }
 
 /**
  * One connection's protocol. Each method returns the actions to carry out.
+ * `now` is whole milliseconds from a clock that only goes forward
+ * (`Math.floor(performance.now())`, or `Date.now()`).
  */
 export class Session {
     free(): void;
@@ -65,35 +135,53 @@ export class Session {
     tick(now: number): any;
 }
 
+/**
+ * Kick's webhook key, read once: `new WebhookPublicKey(pem)`, then
+ * `key.verify(headers, body, options?)` for each delivery.
+ */
+export class WebhookPublicKey {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Reads a PEM key (`BEGIN PUBLIC KEY`, as Kick serves it, or
+     * `BEGIN RSA PUBLIC KEY`); throws if it is not one.
+     */
+    constructor(pem: string);
+    /**
+     * `verifyWebhook`, with this key.
+     */
+    verify(headers: WebhookHeaders, body: string | Uint8Array | ArrayBuffer, options?: VerifyOptions | null): VerifiedWebhook;
+}
+
 /**
  * An app token request (client credentials).
  */
-export function appTokenRequest(client_id: string, client_secret: string, endpoints_: any): any;
+export function appTokenRequest(client_id: string, client_secret: string, endpoints?: Endpoints | null): any;
 
 /**
  * Bans a user for good.
  */
-export function banRequest(session: string, channel_slug: string, username: string, endpoints_: any): any;
+export function banRequest(session: string, channel_slug: string, username: string, endpoints?: Endpoints | null): any;
 
 /**
  * A channel by slug (`kick.com/api/v2`): chatroom id, followers, live state.
  */
-export function channelRequest(slug: string, endpoints_: any): any;
+export function channelRequest(slug: string, endpoints?: Endpoints | null): any;
 
 /**
  * A user as a channel sees them.
  */
-export function channelUserRequest(channel_slug: string, username: string, endpoints_: any): any;
+export function channelUserRequest(channel_slug: string, username: string, endpoints?: Endpoints | null): any;
 
 /**
  * `/channels` for up to 50 user ids.
  */
-export function channelsByIdsRequest(token: string, user_ids: Float64Array, endpoints_: any): any;
+export function channelsByIdsRequest(token: string, user_ids: readonly number[], endpoints?: Endpoints | null): any;
 
 /**
  * `/channels` for up to 50 slugs (one unknown slug fails them all).
  */
-export function channelsBySlugsRequest(token: string, slugs: string[], endpoints_: any): any;
+export function channelsBySlugsRequest(token: string, slugs: string[], endpoints?: Endpoints | null): any;
 
 /**
  * The feeds for one chat, the chat feed first.
@@ -103,17 +191,17 @@ export function chatChannels(chatroom_id: number, channel_id?: number | null): s
 /**
  * Where a channel's chat is served.
  */
-export function chatConnectionRequest(channel_id: number, client_id: string, endpoints_: any): any;
+export function chatConnectionRequest(channel_id: number, client_id: string, endpoints?: Endpoints | null): any;
 
 /**
  * Where Kick's realtime is served in general.
  */
-export function connectionRequest(client_id: string, endpoints_: any): any;
+export function connectionRequest(client_id: string, endpoints?: Endpoints | null): any;
 
 /**
  * Deletes a message.
  */
-export function deleteMessageRequest(session: string, chatroom_id: number, message_id: string, endpoints_: any): any;
+export function deleteMessageRequest(session: string, chatroom_id: number, message_id: string, endpoints?: Endpoints | null): any;
 
 /**
  * An emote's image URL.
@@ -123,17 +211,17 @@ export function emoteUrl(id: string): string;
 /**
  * Recent chat and the pin, by channel id.
  */
-export function historyRequest(channel_id: number, endpoints_: any): any;
+export function historyRequest(channel_id: number, endpoints?: Endpoints | null): any;
 
 /**
  * `/livestreams` for any number of user ids: one request per 50.
  */
-export function livestreamsRequests(token: string, user_ids: Float64Array, endpoints_: any): any;
+export function livestreamsRequests(token: string, user_ids: readonly number[], endpoints?: Endpoints | null): any;
 
 /**
  * The signed-in viewer's standing on a channel.
  */
-export function meRequest(session: string, channel_slug: string, endpoints_: any): any;
+export function meRequest(session: string, channel_slug: string, endpoints?: Endpoints | null): any;
 
 /**
  * Whether an acting call worked; throws with `status` if not.
@@ -207,71 +295,89 @@ export function parseToken(status: number, body: string): string;
 
 /**
  * Reads a delivery's body by its type header, without checking anything.
+ * Throws when the body is not that type's shape. `body` is text or bytes.
  */
-export function parseWebhook(event_type: string, body: string): any;
+export function parseWebhook(event_type: string, body: string | Uint8Array | ArrayBuffer): any;
 
 /**
- * Pins a message (the feed's data for it, whole) for `minutes`.
+ * Pins a message (the feed's data for it, whole) for 1 to 10080 minutes.
  */
-export function pinRequest(session: string, channel_slug: string, message: any, minutes: number, endpoints_: any): any;
+export function pinRequest(session: string, channel_slug: string, message: any, minutes: number, endpoints?: Endpoints | null): any;
 
 /**
  * The webhook signing key request.
  */
-export function publicKeyRequest(endpoints_: any): any;
+export function publicKeyRequest(endpoints?: Endpoints | null): any;
+
+/**
+ * The least to wait, ms, before reconnecting after the socket closed with
+ * this code: 300000 (5 minutes) for Kick's terminal codes (3500-3999 and
+ * 4500-4999: a bad token, a ban, a refused request), then reconnect with a
+ * new client id; 0, the ordinary backoff, for the rest (1006, a network
+ * drop, among them).
+ */
+export function retryAfterMs(code: number): number;
 
 /**
  * Sends a message, or a reply when `replyTo` is
  * `{message_id, content, sender_id, sender_username}`.
  */
-export function sendRequest(session: string, chatroom_id: number, text: string, message_ref: string, reply_to: any, endpoints_: any): any;
+export function sendRequest(session: string, chatroom_id: number, text: string, message_ref: string, reply_to?: ReplyTo | null, endpoints?: Endpoints | null): any;
 
 /**
- * Subscribes the app to webhook `events` (`[{name, version}]`) for one channel.
+ * Subscribes the app to webhook `events` (`[{name, version?}]`, version 1
+ * when left out) for one channel.
  */
-export function subscribeRequest(token: string, broadcaster_user_id: number, events: any, endpoints_: any): any;
+export function subscribeRequest(token: string, broadcaster_user_id: number, events: ReadonlyArray<{ name: string; version?: number }>, endpoints?: Endpoints | null): any;
 
 /**
  * Every webhook subscription the app has.
  */
-export function subscriptionsRequest(token: string, endpoints_: any): any;
+export function subscriptionsRequest(token: string, endpoints?: Endpoints | null): any;
 
 /**
- * Times a user out.
+ * Times a user out for 1 to 10080 minutes.
  */
-export function timeoutRequest(session: string, channel_slug: string, username: string, minutes: number, endpoints_: any): any;
+export function timeoutRequest(session: string, channel_slug: string, username: string, minutes: number, endpoints?: Endpoints | null): any;
 
 /**
  * A guest token request for `clientId`.
  */
-export function tokenRequest(client_id: string, endpoints_: any): any;
+export function tokenRequest(client_id: string, endpoints?: Endpoints | null): any;
 
 /**
- * The top live streams, overall or in a category or language: up to 100.
- * `sort` is `"viewer_count"` (the default) or `"started_at"`.
+ * The top live streams, overall or in a category or language: 1 to 100
+ * (100 by default). `sort` is `"viewer_count"` (the default) or
+ * `"started_at"`.
  */
-export function topLivestreamsRequest(token: string, category_id: number | null | undefined, language: string | null | undefined, sort: string | null | undefined, limit: number | null | undefined, endpoints_: any): any;
+export function topLivestreamsRequest(token: string, category_id?: number | null, language?: string | null, sort?: 'viewer_count' | 'started_at' | null, limit?: number | null, endpoints?: Endpoints | null): any;
 
 /**
  * Lifts a ban or timeout.
  */
-export function unbanRequest(session: string, channel_slug: string, username: string, endpoints_: any): any;
+export function unbanRequest(session: string, channel_slug: string, username: string, endpoints?: Endpoints | null): any;
 
 /**
  * Removes the pin.
  */
-export function unpinRequest(session: string, channel_slug: string, endpoints_: any): any;
+export function unpinRequest(session: string, channel_slug: string, endpoints?: Endpoints | null): any;
 
 /**
  * Removes subscriptions, 50 per request.
  */
-export function unsubscribeRequests(token: string, ids: string[], endpoints_: any): any;
+export function unsubscribeRequests(token: string, ids: string[], endpoints?: Endpoints | null): any;
 
 /**
- * Checks a delivery: `headers` as `[[name, value]…]` or an object, `body` the
- * raw text. Returns the typed event, or throws.
+ * Checks a delivery and returns `{headers, event}`, or throws. `headers` as
+ * `[[name, value]…]`, a fetch `Headers` or an object; `body` the raw body,
+ * as text or bytes. The timestamp must be within 5 minutes of this
+ * machine's clock, unless `options` says otherwise: `now` (Unix seconds),
+ * `toleranceSecs`, or `skipFreshness: true` to re-check a stored delivery.
+ *
+ * A receiver checking many deliveries reads the key once, with
+ * `new WebhookPublicKey(pem)`, and calls its `verify`.
  */
-export function verifyWebhook(public_key_pem: string, headers: any, body: string): any;
+export function verifyWebhook(public_key_pem: string, headers: WebhookHeaders, body: string | Uint8Array | ArrayBuffer, options?: VerifyOptions | null): VerifiedWebhook;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
@@ -279,68 +385,70 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_backoff_free: (a: number, b: number) => void;
     readonly __wbg_session_free: (a: number, b: number) => void;
-    readonly appTokenRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly backoff_new: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbg_webhookpublickey_free: (a: number, b: number) => void;
+    readonly appTokenRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly backoff_new: (a: number, b: number, c: number) => void;
     readonly backoff_nextDelay: (a: number) => number;
+    readonly backoff_nextDelayFor: (a: number, b: number, c: number, d: number) => void;
+    readonly backoff_nextDelayJittered: (a: number, b: number, c: number) => void;
     readonly backoff_reset: (a: number) => void;
-    readonly banRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: any) => [number, number, number];
-    readonly channelRequest: (a: number, b: number, c: any) => [number, number, number];
-    readonly channelUserRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly channelsByIdsRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly channelsBySlugsRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly chatChannels: (a: number, b: number, c: number) => [number, number];
-    readonly chatConnectionRequest: (a: number, b: number, c: number, d: any) => [number, number, number];
-    readonly connectionRequest: (a: number, b: number, c: any) => [number, number, number];
-    readonly deleteMessageRequest: (a: number, b: number, c: number, d: number, e: number, f: any) => [number, number, number];
-    readonly emoteUrl: (a: number, b: number) => [number, number];
-    readonly historyRequest: (a: number, b: any) => [number, number, number];
-    readonly livestreamsRequests: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly meRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly parseAction: (a: number, b: number, c: number) => [number, number];
-    readonly parseAppToken: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseChannel: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseChannelUser: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseChannels: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseConnection: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseContent: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseEvent: (a: number, b: number, c: any) => [number, number, number];
-    readonly parseHistory: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseLivestreams: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseMe: (a: number, b: number, c: number) => [number, number, number];
-    readonly parsePublicKey: (a: number, b: number, c: number) => [number, number, number, number];
-    readonly parseSubscriptions: (a: number, b: number, c: number) => [number, number, number];
-    readonly parseToken: (a: number, b: number, c: number) => [number, number, number, number];
-    readonly parseWebhook: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly pinRequest: (a: number, b: number, c: number, d: number, e: any, f: number, g: any) => [number, number, number];
-    readonly publicKeyRequest: (a: any) => [number, number, number];
-    readonly sendRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: any, i: any) => [number, number, number];
-    readonly session_closed: (a: number) => [number, number, number];
-    readonly session_deadline: (a: number) => [number, number];
+    readonly banRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly channelRequest: (a: number, b: number, c: number, d: number) => void;
+    readonly channelUserRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly channelsByIdsRequest: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly channelsBySlugsRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly chatChannels: (a: number, b: number, c: number) => void;
+    readonly chatConnectionRequest: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly connectionRequest: (a: number, b: number, c: number, d: number) => void;
+    readonly deleteMessageRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly emoteUrl: (a: number, b: number, c: number) => void;
+    readonly historyRequest: (a: number, b: number, c: number) => void;
+    readonly livestreamsRequests: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly meRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly parseAction: (a: number, b: number, c: number, d: number) => void;
+    readonly parseAppToken: (a: number, b: number, c: number, d: number) => void;
+    readonly parseChannel: (a: number, b: number, c: number, d: number) => void;
+    readonly parseChannelUser: (a: number, b: number, c: number, d: number) => void;
+    readonly parseChannels: (a: number, b: number, c: number, d: number) => void;
+    readonly parseConnection: (a: number, b: number, c: number, d: number) => void;
+    readonly parseContent: (a: number, b: number, c: number, d: number) => void;
+    readonly parseEvent: (a: number, b: number, c: number, d: number) => void;
+    readonly parseHistory: (a: number, b: number, c: number, d: number) => void;
+    readonly parseLivestreams: (a: number, b: number, c: number, d: number) => void;
+    readonly parseMe: (a: number, b: number, c: number, d: number) => void;
+    readonly parsePublicKey: (a: number, b: number, c: number, d: number) => void;
+    readonly parseSubscriptions: (a: number, b: number, c: number, d: number) => void;
+    readonly parseToken: (a: number, b: number, c: number, d: number) => void;
+    readonly parseWebhook: (a: number, b: number, c: number, d: number) => void;
+    readonly pinRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly publicKeyRequest: (a: number, b: number) => void;
+    readonly retryAfterMs: (a: number, b: number) => void;
+    readonly sendRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly session_closed: (a: number, b: number) => void;
+    readonly session_deadline: (a: number, b: number) => void;
     readonly session_isConnected: (a: number) => number;
     readonly session_isSubscribed: (a: number, b: number, c: number) => number;
     readonly session_new: (a: number, b: number) => number;
-    readonly session_open: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly session_receive: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly session_refresh: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly session_tick: (a: number, b: number) => [number, number, number];
-    readonly subscribeRequest: (a: number, b: number, c: number, d: any, e: any) => [number, number, number];
-    readonly subscriptionsRequest: (a: number, b: number, c: any) => [number, number, number];
-    readonly timeoutRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: any) => [number, number, number];
-    readonly tokenRequest: (a: number, b: number, c: any) => [number, number, number];
-    readonly topLivestreamsRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: any) => [number, number, number];
-    readonly unbanRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: any) => [number, number, number];
-    readonly unpinRequest: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly unsubscribeRequests: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
-    readonly verifyWebhook: (a: number, b: number, c: any, d: number, e: number) => [number, number, number];
-    readonly __wbindgen_malloc: (a: number, b: number) => number;
-    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_exn_store: (a: number) => void;
-    readonly __externref_table_alloc: () => number;
-    readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __externref_table_dealloc: (a: number) => void;
-    readonly __externref_drop_slice: (a: number, b: number) => void;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-    readonly __wbindgen_start: () => void;
+    readonly session_open: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly session_receive: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly session_refresh: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly session_tick: (a: number, b: number, c: number) => void;
+    readonly subscribeRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly subscriptionsRequest: (a: number, b: number, c: number, d: number) => void;
+    readonly timeoutRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly tokenRequest: (a: number, b: number, c: number, d: number) => void;
+    readonly topLivestreamsRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly unbanRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly unpinRequest: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly unsubscribeRequests: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly verifyWebhook: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly webhookpublickey_new: (a: number, b: number, c: number) => void;
+    readonly webhookpublickey_verify: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;