e621stream 0.0.0-stage → 0.0.0

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,39 @@
-# 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 TypeScript client for [E621Stream](https://e621.stream), a live WebSocket stream of e621 activity. It works in Node 22+, Bun, Deno and browsers, has no dependencies, and every event type is typed down to the record it carries.
+
+```bash
+npm install 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 the fields that changed, tags 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();
+```
+
+- **Events:** `on("<event type>", ...)` for one type, typed to its data, or `on("dispatch", ...)` for everything, narrowed by checking `event.type`. See [Events](https://e621.stream/events/) for what each one is.
+- **Reconnecting:** the connection is reopened with backoff when it drops, and resumes from the last event it got, so nothing is missed. It isn't reopened after a close retrying won't fix, like bad credentials. `reconnect: false` turns it off.
+- **Resuming:** pass `cursor` (an event id, or a millisecond timestamp) to replay from there. `stream.cursor` is the last event received.
+- **Changing subscriptions:** `stream.subscribe([...])`.
+- **Private events:** like `dmail.create`, these are polled with your own credentials and have to be subscribed to by name.
+- **Other events:** `ready`, `replayComplete`, `subscribed`, `reconnecting`, `close` and `error`.
+- **Older Node:** pass a WebSocket implementation, like the `ws` package, as the `WebSocket` option.
+
+Event data comes from the [e621 module](https://www.npmjs.com/package/e621)'s types, so records like `LegacyPost`, `Comment` and `ForumTopic` are exported here too. Mod action events are typed per action: checking `event.data.action` narrows `event.data.values`.

package/dist/E621Stream.d.ts

@@ -0,0 +1,95 @@
+import Emitter from "./Emitter.ts";
+import { type EventType, type PrivateEventType, type StreamEvent, type Subscription } from "./events.ts";
+export interface Options {
+    /** your e621 username and an api key, from Account > Manage API Access */
+    auth?: {
+        apiKey: string;
+        username: string;
+    };
+    /** a name for your client, shown in the server's logs */
+    client?: string;
+    /** an event id (or a millisecond timestamp) to replay from. after that, reconnecting resumes from the last event */
+    cursor?: number | string;
+    /** reconnects with backoff when the connection drops, unless the server closed it for something retrying won't fix */
+    reconnect?: boolean;
+    subscriptions: Array<Subscription>;
+    url?: string;
+    /** for runtimes without a global WebSocket, like node before 22 (the `ws` package works) */
+    WebSocket?: typeof WebSocket;
+}
+export interface Ready {
+    /** when replaying, set 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;
+    }];
+    /** replay is done, live events follow */
+    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
+ *
+ * ```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 lastMessage;
+    private reconnectTimer;
+    private socket;
+    /** the newest event received, which reconnecting resumes from */
+    cursor: string | null;
+    readonly options: Options & {
+        url: string;
+    };
+    constructor(options: Options);
+    private handle;
+    private onClose;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** closes the connection for good */
+    close(): void;
+    connect(): this;
+    /** replaces the current subscriptions, and keeps them for reconnecting */
+    subscribe(subscriptions: Array<Subscription>): void;
+}
+export {};

package/dist/E621Stream.js

@@ -0,0 +1,180 @@
+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";
+    }
+}
+// closing for any of these again would just get the same result
+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,
+]);
+const MAX_DELAY_MS = 60_000;
+const HEARTBEAT_MS = 30_000;
+// the server answers heartbeats and pings, nothing for this long means the connection is gone without having closed
+const SILENT_MS = 75_000;
+/**
+ * a connection to E621Stream, see https://e621.stream
+ *
+ * ```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;
+    lastMessage = 0;
+    reconnectTimer = null;
+    socket = null;
+    /** the newest event received, which reconnecting resumes from */
+    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("got a binary message, compression isn't supported by this client"));
+            return;
+        }
+        this.lastMessage = Date.now();
+        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 } : {}) };
+                // private events aren't in the stream, so they can't be resumed from
+                if (!event.private)
+                    this.cursor = event.id;
+                this.emit("dispatch", event);
+                // typescript can't tie each type in the union to its own listener, it's the same event either way
+                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 "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++;
+        // a server that's rate limiting this connection wants a longer break
+        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.lastMessage = Date.now();
+        this.heartbeat = setInterval(() => {
+            if (Date.now() - this.lastMessage > SILENT_MS) {
+                // a client-side close code, nothing the server would send
+                this.socket?.close(4999, "no response from the server");
+                return;
+            }
+            this.send({ op: "heartbeat" });
+        }, HEARTBEAT_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+    }
+    /** closes the connection for good */
+    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;
+        // the dom types say it's always there, node before 22 doesn't have it
+        const global = globalThis.WebSocket;
+        const Socket = this.options.WebSocket ?? global;
+        if (!Socket)
+            throw new Error("there's no global WebSocket here, pass one as 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); });
+        // the close event that follows has the details
+        socket.addEventListener("error", () => null);
+        return this;
+    }
+    /** replaces the current subscriptions, and keeps them for reconnecting */
+    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,12 @@
+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;
+    /** for an event name only known at runtime, whose listeners' arguments can't be checked */
+    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,33 @@
+// a minimal typed event emitter, so the client has no dependencies and works anywhere
+export default class Emitter {
+    // listeners of every event share one map, so they're stored without their argument types
+    listeners = new Map();
+    emit(event, ...args) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(...args);
+    }
+    /** for an event name only known at runtime, whose listeners' arguments can't be checked */
+    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":"AAAA,sFAAsF;AAItF,MAAM,CAAC,OAAO,OAAO,OAAO;IACxB,yFAAyF;IACjF,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;IAED,2FAA2F;IACjF,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,30 @@
+import type { LegacyPost } from "./generated.ts";
+/** a field's value before and after */
+export interface ValueChange<T> {
+    new: T;
+    old: T;
+}
+/** what was added to and removed from a list */
+export interface SetChange<T> {
+    added: Array<T>;
+    removed: Array<T>;
+}
+/** what changed on a record, only the fields that did */
+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>;
+/** what changed on a post, only the fields that did. tags are per category, so a category change shows up as a move */
+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>;
+}>;

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,54 @@
+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.update", "post_approval.create", "post_event.create", "post_flag.create", "post_flag.update", "post_replacement.create", "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 and only sent to you, they have to be subscribed to by name */
+export declare const PRIVATE_EVENT_TYPES: readonly ["dmail.create"];
+export type PrivateEventType = typeof PRIVATE_EVENT_TYPES[number];
+/** events whose data is the mod action they come from */
+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"];
+/** updates whose data is the version record they come from */
+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];
+/** what an event type's `data` is, see https://e621.stream/events/ */
+export type EventData<T extends EventType | PrivateEventType> = EventDataMap[T];
+/** one event from the stream, narrowed to its type's data by checking `type` */
+export type StreamEvent<T extends EventType | PrivateEventType = EventType | PrivateEventType> = T extends EventType | PrivateEventType ? {
+    data: EventData<T>;
+    /** the event's cursor, pass it as `cursor` to resume after it. private events have no cursor */
+    id: string;
+    /** only for private events, which are polled with your own credentials and never stored */
+    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>;
+    /** e621 style tag query, supports `tag`, `-tag`, `~tag` and `rating:<s|q|e>` */
+    tags?: string;
+    topic_ids?: Array<number>;
+    user_ids?: Array<number>;
+}
+/** an event type, `<resource>.*`, `*`, or one of those with a filter */
+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;
+};

package/dist/events.js

@@ -0,0 +1,138 @@
+// kept identical to the server's src/events.ts, the repository's tests check it
+export const EVENT_TYPES = [
+    "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.update",
+    "post_approval.create",
+    "post_event.create",
+    "post_flag.create",
+    "post_flag.update",
+    "post_replacement.create",
+    "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",
+];
+/** polled with your own credentials and only sent to you, they have to be subscribed to by name */
+export const PRIVATE_EVENT_TYPES = ["dmail.create"];
+/** events whose data is the mod action they come from */
+export const MOD_ACTION_EVENT_TYPES = [
+    "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",
+];
+/** updates whose data is the version record they come from */
+export const VERSION_EVENT_TYPES = ["artist.update", "avoid_posting.update", "note.update", "pool.update", "tag.update", "wiki_page.update"];
+export const CloseCodes = {
+    UNKNOWN_ERROR: 4000,
+    UNKNOWN_OP: 4001,
+    DECODE_ERROR: 4002,
+    NOT_IDENTIFIED: 4003,
+    AUTHENTICATION_FAILED: 4004,
+    ALREADY_IDENTIFIED: 4005,
+    INVALID_SUBSCRIPTION: 4006,
+    INVALID_CURSOR: 4007,
+    RATE_LIMITED: 4008,
+    SLOW_CONSUMER: 4009,
+    TOO_MANY_CONNECTIONS: 4010,
+    AUTHENTICATION_EXPIRED: 4011,
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../lib/events.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAEhF,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,eAAe;IACf,eAAe;IACf,eAAe;IACf,mBAAmB;IACnB,uBAAuB;IACvB,sBAAsB;IACtB,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,8BAA8B;IAC9B,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,4BAA4B;IAC5B,4BAA4B;IAC5B,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;IACnB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,oBAAoB;IACpB,kBAAkB;IAClB,kBAAkB;IAClB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,aAAa;IACb,aAAa;IACb,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,mBAAmB;IACnB,aAAa;IACb,qBAAqB;IACrB,aAAa;IACb,aAAa;IACb,sBAAsB;IACtB,mBAAmB;IACnB,kBAAkB;IAClB,kBAAkB;IAClB,yBAAyB;IACzB,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;IACvB,iBAAiB;IACjB,qBAAqB;IACrB,mBAAmB;IACnB,qBAAqB;IACrB,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,kBAAkB;IAClB,kBAAkB;IAClB,wBAAwB;IACxB,wBAAwB;IACxB,yBAAyB;IACzB,iBAAiB;IACjB,iBAAiB;IACjB,iBAAiB;IACjB,2BAA2B;IAC3B,aAAa;IACb,aAAa;IACb,aAAa;IACb,sBAAsB;IACtB,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAClB,0BAA0B;CACpB,CAAC;AAIX,mGAAmG;AAEnG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,cAAc,CAAU,CAAC;AAI7D,yDAAyD;AAEzD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,eAAe;IACf,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,YAAY;IACZ,YAAY;IACZ,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,aAAa;IACb,iBAAiB;IACjB,mBAAmB;IACnB,qBAAqB;IACrB,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,aAAa;IACb,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,kBAAkB;CACZ,CAAC;AAEX,8DAA8D;AAE9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,eAAe,EAAE,sBAAsB,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,CAAU,CAAC;AAkCtJ,MAAM,CAAC,MAAM,UAAU,GAAG;IACtB,aAAa,EAAE,IAAI;IACnB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;IACpB,qBAAqB,EAAE,IAAI;IAC3B,kBAAkB,EAAE,IAAI;IACxB,oBAAoB,EAAE,IAAI;IAC1B,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,oBAAoB,EAAE,IAAI;IAC1B,sBAAsB,EAAE,IAAI;CACtB,CAAC"}