e621stream 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) undefined Donovan_DMC
+
+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,46 @@
-# Temporary Holding Version
+# e621stream
 
-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 client for [E621Stream](https://e621.stream). Works in node 22+, bun, deno & browsers, has no dependencies, and every event is typed down to the record it has.
+
+```sh
+npm i e621stream
+```
+
+```ts
+import { E621Stream } from "e621stream";
+
+const stream = new E621Stream({
+    auth: { username: "your_name", apiKey: "your e621 api key" },
+    subscriptions: ["post.create", { type: "post.update", filter: { tags: "fox -solo" } }, "comment.*"],
+});
+
+stream.on("post.create", (event) => {
+    console.log(event.data.post.id, event.data.post.tags.general);
+});
+stream.on("post.update", (event) => {
+    // only what changed, tags are per category
+    console.log(event.data.changes?.["tags.general"]?.added);
+});
+stream.on("comment.update", (event) => {
+    console.log(event.data.comment.id, event.data.changes?.body?.old, "->", event.data.changes?.body?.new);
+});
+stream.on("error", err => console.error(err));
+stream.connect();
+```
+
+Listen for an event type with `on("post.create", ...)`, or everything with `on("dispatch", ...)` (check `event.type` to narrow it). The others are `ready`, `replayComplete`, `subscribed`, `reconnecting`, `close` and `error`. See [Events](https://e621.stream/events/) for what each event is.
+
+#### Options
+| Option | Type | Default | Description |
+|:---:|:---:|:---:|:---:|
+| `subscriptions` | Array | | what to subscribe to, `stream.subscribe([...])` changes it later |
+| `auth` | Object | None | `{ username, apiKey }` |
+| `cursor` | String \| Number | None | an event id or ms timestamp to replay from, `stream.cursor` is the last event you got |
+| `reconnect` | Boolean | `true` | reconnect when the connection drops (not after things like bad credentials) |
+| `client` | String | None | shown in the server's logs |
+| `url` | String | `wss://e621.stream/ws` | |
+| `WebSocket` | WebSocket | global | for older node, the `ws` package works |
+
+Private events like `dmail.create` have to be subscribed to by name.
+
+Records like `LegacyPost`, `Comment` and `ForumTopic` come from the [e621 module](https://www.npmjs.com/package/e621)'s types, and are exported here too. Mod action events are typed per action, so checking `event.data.action` narrows `event.data.values`.

package/dist/E621Stream.d.ts

@@ -0,0 +1,93 @@
+import Emitter from "./Emitter.ts";
+import { type EventType, type PrivateEventType, type StreamEvent, type Subscription } from "./events.ts";
+export interface Options {
+    /** Your e621 username & api key. */
+    auth?: {
+        apiKey: string;
+        username: string;
+    };
+    /** Shown in the server's logs. */
+    client?: string;
+    /** An event id or millisecond timestamp to replay from. */
+    cursor?: number | string;
+    /** Reconnect when the connection drops. */
+    reconnect?: boolean;
+    subscriptions: Array<Subscription>;
+    url?: string;
+    /** For runtimes without a global WebSocket (node < 22), the `ws` package works. */
+    WebSocket?: typeof WebSocket;
+}
+export interface Ready {
+    /** If the cursor was older than anything still kept. */
+    cursor_expired?: boolean;
+    replaying: boolean;
+    session_id: string;
+    subscriptions: Array<Subscription>;
+    user: {
+        id: number;
+        level: number;
+        level_string: string;
+        name: string;
+    } | null;
+}
+export interface ClientEvents {
+    close: [{
+        code: number;
+        reason: string;
+        reconnecting: boolean;
+    }];
+    /** Every event, public or private. */
+    dispatch: [StreamEvent];
+    error: [Error];
+    ready: [Ready];
+    reconnecting: [{
+        attempt: number;
+        delayMS: number;
+    }];
+    replayComplete: [{
+        cursor: string | null;
+        events: number;
+    }];
+    subscribed: [Array<Subscription>];
+}
+type Listeners = ClientEvents & {
+    [K in EventType | PrivateEventType]: [StreamEvent<K>];
+};
+export declare class StreamError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+/**
+ * A connection to E621Stream, see https://e621.stream
+ * @example
+ * ```ts
+ * const stream = new E621Stream({ auth: { username, apiKey }, subscriptions: ["post.create"] });
+ * stream.on("post.create", event => console.log(event.data.post.id));
+ * stream.connect();
+ * ```
+ */
+export declare class E621Stream extends Emitter<Listeners> {
+    private attempt;
+    private closing;
+    private heartbeat;
+    private lastError;
+    private lastHeartbeatAck;
+    private reconnectTimer;
+    private socket;
+    cursor: string | null;
+    readonly options: Options & {
+        url: string;
+    };
+    constructor(options: Options);
+    private handle;
+    private onClose;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** Close the connection. */
+    close(): void;
+    connect(): this;
+    /** Replace the current subscriptions. */
+    subscribe(subscriptions: Array<Subscription>): void;
+}
+export {};

package/dist/E621Stream.js

@@ -0,0 +1,178 @@
+import Emitter from "./Emitter.js";
+import { CloseCodes } from "./events.js";
+export class StreamError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "StreamError";
+    }
+}
+const FATAL = new Set([
+    CloseCodes.UNKNOWN_OP,
+    CloseCodes.DECODE_ERROR,
+    CloseCodes.AUTHENTICATION_FAILED,
+    CloseCodes.ALREADY_IDENTIFIED,
+    CloseCodes.INVALID_SUBSCRIPTION,
+    CloseCodes.INVALID_CURSOR,
+    CloseCodes.AUTHENTICATION_EXPIRED,
+    CloseCodes.DISCONNECTED,
+    CloseCodes.BANNED,
+]);
+const MAX_DELAY_MS = 60_000;
+const HEARTBEAT_MS = 30_000;
+/**
+ * A connection to E621Stream, see https://e621.stream
+ * @example
+ * ```ts
+ * const stream = new E621Stream({ auth: { username, apiKey }, subscriptions: ["post.create"] });
+ * stream.on("post.create", event => console.log(event.data.post.id));
+ * stream.connect();
+ * ```
+ */
+export class E621Stream extends Emitter {
+    attempt = 0;
+    closing = false;
+    heartbeat = null;
+    lastError = null;
+    lastHeartbeatAck = true;
+    reconnectTimer = null;
+    socket = null;
+    cursor;
+    options;
+    constructor(options) {
+        super();
+        this.options = { reconnect: true, url: "wss://e621.stream/ws", ...options };
+        this.cursor = options.cursor === undefined ? null : String(options.cursor);
+    }
+    handle(raw) {
+        if (typeof raw !== "string") {
+            this.emit("error", new Error("compression isn't supported"));
+            return;
+        }
+        const message = JSON.parse(raw);
+        switch (message.op) {
+            case "hello": {
+                const { auth, client, subscriptions } = this.options;
+                this.send({
+                    op: "identify",
+                    d: {
+                        ...(auth ? { auth: { username: auth.username, api_key: auth.apiKey } } : {}),
+                        ...(client ? { client } : {}),
+                        ...(this.cursor === null ? {} : { cursor: this.cursor }),
+                        subscriptions,
+                    },
+                });
+                break;
+            }
+            case "ready": {
+                this.attempt = 0;
+                this.emit("ready", message.d);
+                break;
+            }
+            case "dispatch": {
+                const event = { id: message.id, type: message.type, time: message.time, data: message.data, ...(message.private ? { private: true } : {}) };
+                if (!event.private)
+                    this.cursor = event.id;
+                this.emit("dispatch", event);
+                // typescript can't narrow this
+                this.emitUnchecked(event.type, event);
+                break;
+            }
+            case "replay_complete": {
+                this.emit("replayComplete", message.d);
+                break;
+            }
+            case "subscribed": {
+                this.emit("subscribed", message.d.subscriptions);
+                break;
+            }
+            case "heartbeat_ack": {
+                this.lastHeartbeatAck = true;
+                break;
+            }
+            case "error": {
+                const { code, message: text } = message.d;
+                this.lastError = new StreamError(code, text);
+                break;
+            }
+        }
+    }
+    onClose(code, reason) {
+        this.stopHeartbeat();
+        this.socket = null;
+        const error = this.lastError;
+        this.lastError = null;
+        const reconnecting = !this.closing && this.options.reconnect !== false && !FATAL.has(code);
+        if (error)
+            this.emit("error", error);
+        this.emit("close", { code, reason: error?.message ?? reason, reconnecting });
+        if (!reconnecting)
+            return;
+        this.attempt++;
+        const base = code === CloseCodes.RATE_LIMITED ? 30_000 : 1000;
+        const delayMS = Math.min(MAX_DELAY_MS, base * 2 ** (this.attempt - 1)) * (0.75 + Math.random() * 0.5);
+        this.emit("reconnecting", { attempt: this.attempt, delayMS: Math.round(delayMS) });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delayMS);
+    }
+    send(payload) {
+        if (this.socket?.readyState === 1)
+            this.socket.send(JSON.stringify(payload));
+    }
+    startHeartbeat() {
+        this.lastHeartbeatAck = true;
+        this.heartbeat = setInterval(() => {
+            if (!this.lastHeartbeatAck) {
+                this.socket?.close(4999, "heartbeat not acknowledged");
+                return;
+            }
+            this.lastHeartbeatAck = false;
+            this.send({ op: "heartbeat" });
+        }, HEARTBEAT_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+    }
+    /** Close the connection. */
+    close() {
+        this.closing = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.socket?.close(1000, "closed by client");
+    }
+    connect() {
+        if (this.socket)
+            return this;
+        this.closing = false;
+        // not present before node 22
+        const global = globalThis.WebSocket;
+        const Socket = this.options.WebSocket ?? global;
+        if (!Socket)
+            throw new Error("no WebSocket available, pass one with the WebSocket option");
+        const socket = this.socket = new Socket(this.options.url);
+        socket.addEventListener("open", () => { this.startHeartbeat(); });
+        socket.addEventListener("message", (event) => {
+            try {
+                this.handle(event.data);
+            }
+            catch (err) {
+                this.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        socket.addEventListener("close", (event) => { this.onClose(event.code, event.reason); });
+        socket.addEventListener("error", () => null);
+        return this;
+    }
+    /** Replace the current subscriptions. */
+    subscribe(subscriptions) {
+        this.options.subscriptions = subscriptions;
+        this.send({ op: "subscribe", d: { subscriptions } });
+    }
+}
+//# sourceMappingURL=E621Stream.js.map

package/dist/E621Stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"E621Stream.js","sourceRoot":"","sources":["../lib/E621Stream.ts"],"names":[],"mappings":"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"}

package/dist/Emitter.d.ts

@@ -0,0 +1,11 @@
+export type Listener<Args extends Array<unknown>> = (...args: Args) => void;
+export default class Emitter<Events extends {
+    [K in keyof Events]: Array<unknown>;
+}> {
+    private listeners;
+    protected emit<K extends keyof Events>(event: K, ...args: Events[K]): void;
+    protected emitUnchecked(event: keyof Events, ...args: Array<unknown>): void;
+    off<K extends keyof Events>(event: K, listener: NoInfer<Listener<Events[K]>>): this;
+    on<K extends keyof Events>(event: K, listener: NoInfer<Listener<Events[K]>>): this;
+    once<K extends keyof Events>(event: K, listener: NoInfer<Listener<Events[K]>>): this;
+}

package/dist/Emitter.js

@@ -0,0 +1,30 @@
+export default class Emitter {
+    listeners = new Map();
+    emit(event, ...args) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(...args);
+    }
+    emitUnchecked(event, ...args) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(...args);
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+        return this;
+    }
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set)
+            this.listeners.set(event, set = new Set());
+        set.add(listener);
+        return this;
+    }
+    once(event, listener) {
+        const wrapped = (...args) => {
+            this.off(event, wrapped);
+            listener(...args);
+        };
+        return this.on(event, wrapped);
+    }
+}
+//# sourceMappingURL=Emitter.js.map

package/dist/Emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Emitter.js","sourceRoot":"","sources":["../lib/Emitter.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,OAAO,OAAO;IAChB,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEhD,IAAI,CAAyB,KAAQ,EAAE,GAAG,IAAe;QAC/D,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;YAAG,QAAgC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvG,CAAC;IAES,aAAa,CAAC,KAAmB,EAAE,GAAG,IAAoB;QAChE,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;YAAG,QAAqC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5G,CAAC;IAED,GAAG,CAAyB,KAAQ,EAAE,QAAsC;QACxE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,EAAE,CAAyB,KAAQ,EAAE,QAAsC;QACvE,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC;QACrD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,CAAyB,KAAQ,EAAE,QAAsC;QACzE,MAAM,OAAO,GAAwB,CAAC,GAAG,IAAI,EAAE,EAAE;YAC7C,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACzB,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QACtB,CAAC,CAAC;QACF,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;CACJ"}

package/dist/changes.d.ts

@@ -0,0 +1,62 @@
+import type { LegacyPost } from "./generated.ts";
+/** A field's old and new value. */
+export interface ValueChange<T> {
+    new: T;
+    old: T;
+}
+export interface SetChange<T> {
+    added: Array<T>;
+    removed: Array<T>;
+}
+export type Changes<R, Field extends keyof R> = Partial<{
+    [K in Field]: ValueChange<R[K]>;
+}>;
+export type TagCategoryName = "artist" | "character" | "contributor" | "copyright" | "general" | "invalid" | "lore" | "meta" | "species";
+export type PostFlagName = Extract<keyof LegacyPost["flags"], string>;
+/** Tags are split by category, so moving a tag between categories shows up as a remove & add. */
+export type PostChanges = Partial<Record<`tags.${TagCategoryName}`, SetChange<string>> & Record<`flags.${PostFlagName}`, ValueChange<boolean>> & {
+    approver_id: ValueChange<number | null>;
+    children: SetChange<number>;
+    description: ValueChange<string>;
+    has_notes: ValueChange<boolean>;
+    locked_tags: SetChange<string>;
+    md5: ValueChange<string>;
+    parent_id: ValueChange<number | null>;
+    pools: SetChange<number>;
+    rating: ValueChange<LegacyPost["rating"]>;
+    sources: SetChange<string>;
+}>;
+/** What was last known of a post, only `id` is guaranteed. */
+export type PostSnapshot = Partial<{
+    approver_id: number | null;
+    change_seq: number;
+    children: Array<number>;
+    description: string;
+    flags: LegacyPost["flags"];
+    has_notes: boolean;
+    locked_tags: Array<string>;
+    md5: string;
+    parent_id: number | null;
+    pools: Array<number>;
+    rating: LegacyPost["rating"];
+    sources: Array<string>;
+    tags: Partial<Record<TagCategoryName, Array<string>>>;
+} & Omit<PostStats, "changes" | "post_id">> & {
+    id: number;
+};
+export interface PostScore {
+    down: number;
+    total: number;
+    up: number;
+}
+export interface PostStats {
+    changes: Partial<{
+        comment_count: ValueChange<number>;
+        fav_count: ValueChange<number>;
+        score: ValueChange<PostScore>;
+    }>;
+    comment_count: number;
+    fav_count: number;
+    post_id: number;
+    score: PostScore;
+}

package/dist/changes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=changes.js.map

package/dist/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","sourceRoot":"","sources":["../lib/changes.ts"],"names":[],"mappings":""}

package/dist/events.d.ts

@@ -0,0 +1,51 @@
+import type { EventDataMap } from "./generated.ts";
+export declare const EVENT_TYPES: readonly ["artist.create", "artist.delete", "artist.update", "artist_url.create", "artist_version.create", "avoid_posting.create", "avoid_posting.delete", "avoid_posting.destroy", "avoid_posting.undelete", "avoid_posting.update", "avoid_posting_version.create", "ban.create", "ban.delete", "ban.update", "blip.create", "bulk_update_request.create", "bulk_update_request.update", "comment.create", "comment.delete", "comment.hide", "comment.unhide", "comment.update", "forum_post.create", "forum_post.delete", "forum_post.hide", "forum_post.unhide", "forum_post.update", "forum_topic.create", "forum_topic.delete", "forum_topic.hide", "forum_topic.unhide", "forum_topic.update", "help_page.create", "help_page.update", "mod_action.create", "news_update.create", "news_update.update", "note.create", "note.update", "note_version.create", "pool.add_posts", "pool.create", "pool.delete", "pool.remove_posts", "pool.update", "pool_version.create", "post.create", "post.destroy", "post.stats", "post.update", "post_approval.create", "post_event.create", "post_flag.create", "post_flag.update", "post_replacement.create", "post_replacement.destroy", "post_replacement.update", "post_set.add_posts", "post_set.create", "post_set.delete", "post_set.remove_posts", "post_set.update", "post_version.create", "post_version.hide", "post_version.unhide", "tag.create", "tag.delete", "tag.update", "tag_alias.create", "tag_alias.update", "tag_implication.create", "tag_implication.update", "tag_type_version.create", "takedown.create", "takedown.delete", "takedown.update", "upload_karma_event.create", "user.create", "user.delete", "user.update", "user_feedback.create", "user_feedback.delete", "user_feedback.destroy", "user_feedback.undelete", "user_feedback.update", "wiki_page.create", "wiki_page.delete", "wiki_page.update", "wiki_page_version.create"];
+export type EventType = typeof EVENT_TYPES[number];
+/** Polled with your own credentials, these need to be subscribed to by name. */
+export declare const PRIVATE_EVENT_TYPES: readonly ["dmail.create", "private_post_set.add_posts", "private_post_set.remove_posts"];
+export type PrivateEventType = typeof PRIVATE_EVENT_TYPES[number];
+export declare const MOD_ACTION_EVENT_TYPES: readonly ["artist.delete", "avoid_posting.delete", "avoid_posting.destroy", "avoid_posting.undelete", "ban.delete", "ban.update", "comment.delete", "comment.hide", "comment.unhide", "forum_post.delete", "forum_post.hide", "forum_post.unhide", "forum_topic.delete", "forum_topic.hide", "forum_topic.unhide", "pool.delete", "post_set.delete", "post_version.hide", "post_version.unhide", "tag.delete", "takedown.delete", "user.delete", "user.update", "user_feedback.delete", "user_feedback.destroy", "user_feedback.undelete", "user_feedback.update", "wiki_page.delete"];
+export declare const VERSION_EVENT_TYPES: readonly ["artist.update", "avoid_posting.update", "note.update", "pool.update", "tag.update", "wiki_page.update"];
+export type ModActionEventType = typeof MOD_ACTION_EVENT_TYPES[number];
+export type VersionEventType = typeof VERSION_EVENT_TYPES[number];
+/** The data for each event type, see https://e621.stream/events/ */
+export type EventData<T extends EventType | PrivateEventType> = EventDataMap[T];
+export type StreamEvent<T extends EventType | PrivateEventType = EventType | PrivateEventType> = T extends EventType | PrivateEventType ? {
+    data: EventData<T>;
+    /** Pass this as `cursor` to resume after this event. Private events don't have one. */
+    id: string;
+    private?: true;
+    /** When it happened on e621. */
+    time: string;
+    type: T;
+} : never;
+export interface Filter {
+    actions?: Array<string>;
+    pool_ids?: Array<number>;
+    post_ids?: Array<number>;
+    set_ids?: Array<number>;
+    /** An e621 style tag query, supporting `tag`, `-tag`, `~tag` and `rating:`. */
+    tags?: string;
+    topic_ids?: Array<number>;
+    user_ids?: Array<number>;
+}
+export type Subscription = string | {
+    filter?: Filter;
+    type: string;
+};
+export declare const CloseCodes: {
+    readonly UNKNOWN_ERROR: 4000;
+    readonly UNKNOWN_OP: 4001;
+    readonly DECODE_ERROR: 4002;
+    readonly NOT_IDENTIFIED: 4003;
+    readonly AUTHENTICATION_FAILED: 4004;
+    readonly ALREADY_IDENTIFIED: 4005;
+    readonly INVALID_SUBSCRIPTION: 4006;
+    readonly INVALID_CURSOR: 4007;
+    readonly RATE_LIMITED: 4008;
+    readonly SLOW_CONSUMER: 4009;
+    readonly TOO_MANY_CONNECTIONS: 4010;
+    readonly AUTHENTICATION_EXPIRED: 4011;
+    readonly DISCONNECTED: 4012;
+    readonly BANNED: 4013;
+};