snowtransfer 0.18.0 → 0.19.0

package/dist/SnowTransfer.js

@@ -0,0 +1,105 @@
+"use strict";
+const RequestHandler_1 = require("./RequestHandler");
+const AssetsMethods = require("./methods/Assets");
+const AuditLogMethods = require("./methods/AuditLog");
+const AutoModerationMethods = require("./methods/AutoModeration");
+const BotMethods = require("./methods/Bot");
+const ChannelMethods = require("./methods/Channel");
+const EntitlementMethods = require("./methods/Entitlements");
+const GuildMethods = require("./methods/Guild");
+const GuildScheduledEventMethods = require("./methods/GuildScheduledEvent");
+const GuildTemplateMethods = require("./methods/GuildTemplate");
+const InteractionMethods = require("./methods/Interaction");
+const InviteMethods = require("./methods/Invite");
+const SkuMethods = require("./methods/Sku");
+const StageInstanceMethods = require("./methods/StageInstance");
+const UserMethods = require("./methods/User");
+const VoiceMethods = require("./methods/Voice");
+const WebhookMethods = require("./methods/Webhook");
+const Endpoints = require("./Endpoints");
+const Constants = require("./Constants");
+/**
+ * @since 0.1.0
+ */
+class SnowTransfer {
+    /** Options for this SnowTransfer instance */
+    options;
+    /** The access token to use for requests. Can be a bot or bearer token */
+    token;
+    /** Methods related to channels */
+    channel;
+    /** Helper to execute REST calls */
+    requestHandler;
+    /** Methods related to users */
+    user;
+    /** Methods related to stickers and emojis */
+    assets;
+    /** Methods related to webhooks */
+    webhook;
+    /** Methods related to guilds */
+    guild;
+    /** Methods related to guild scheduled events */
+    guildScheduledEvent;
+    /** Methods related to guild templates */
+    guildTemplate;
+    /** Methods related to application commands/interactions */
+    interaction;
+    /** Methods related to invites */
+    invite;
+    /** Methods related to voice regions */
+    voice;
+    /** Methods related to getting gateway connect info */
+    bot;
+    /** Methods related to guild audit logs */
+    auditLog;
+    /** Methods related to guild stage instances */
+    stageInstance;
+    /** Methods related to guild auto mod */
+    autoMod;
+    /** Methods related to entitlements */
+    entitlement;
+    /** Methods related to SKUs */
+    sku;
+    /** Ratelimiter used for handling the ratelimits imposed by the rest api */
+    ratelimiter;
+    /**
+     * Create a new Rest Client
+     * @param token Discord Bot token to use
+     * @param options options
+     */
+    constructor(token, options) {
+        if (typeof token === "string" && token === "")
+            throw new Error("Missing token");
+        if (token && (!token.startsWith("Bot ") && !token.startsWith("Bearer ")))
+            token = `Bot ${token}`;
+        this.options = { baseHost: Endpoints.BASE_HOST, baseURL: Endpoints.BASE_URL, fetch: globalThis.fetch, allowed_mentions: undefined, bypassBuckets: false, retryRequests: false, retryLimit: Constants.DEFAULT_RETRY_LIMIT, ...options };
+        this.token = token;
+        this.ratelimiter = new RequestHandler_1.Ratelimiter();
+        this.requestHandler = new RequestHandler_1.RequestHandler(this.ratelimiter, {
+            token: this.token,
+            baseHost: this.options.baseHost,
+            baseURL: this.options.baseURL,
+            bypassBuckets: this.options.bypassBuckets,
+            retryFailed: this.options.retryRequests,
+            retryLimit: this.options.retryLimit,
+            fetch: this.options.fetch
+        });
+        this.channel = new ChannelMethods(this.requestHandler, this.options);
+        this.user = new UserMethods(this.requestHandler);
+        this.assets = new AssetsMethods(this.requestHandler);
+        this.webhook = new WebhookMethods(this.requestHandler, this.options);
+        this.guild = new GuildMethods(this.requestHandler);
+        this.guildScheduledEvent = new GuildScheduledEventMethods(this.requestHandler);
+        this.guildTemplate = new GuildTemplateMethods(this.requestHandler);
+        this.interaction = new InteractionMethods(this.requestHandler, this.webhook, this.options);
+        this.invite = new InviteMethods(this.requestHandler);
+        this.voice = new VoiceMethods(this.requestHandler);
+        this.bot = new BotMethods(this.requestHandler);
+        this.auditLog = new AuditLogMethods(this.requestHandler);
+        this.stageInstance = new StageInstanceMethods(this.requestHandler);
+        this.autoMod = new AutoModerationMethods(this.requestHandler);
+        this.entitlement = new EntitlementMethods(this.requestHandler);
+        this.sku = new SkuMethods(this.requestHandler);
+    }
+}
+module.exports = SnowTransfer;

package/dist/StateMachine.d.ts

@@ -0,0 +1,104 @@
+import { EventEmitter } from "node:events";
+import type { SMState, SMTransition } from "./Types";
+interface StateMachineEvents {
+    enter: [string];
+}
+/**
+ * Class used to define states code is expected to be in and transitions to other states and code to run during those transitions and states
+ * @since 0.16.0
+ */
+declare class StateMachine extends EventEmitter<StateMachineEvents> {
+    currentStateName: string;
+    readonly states: Map<string, SMState>;
+    private editable;
+    private readonly deferredTransitionCreators;
+    private readonly history;
+    /** Transitions requested while another transition was still running. Drained in order once the running transition completes. */
+    private readonly pendingTransitions;
+    /** Whether a transition is currently being executed, making new transition requests queue instead of nesting. */
+    private transitioning;
+    /**
+     * Create a new StateMachine
+     * @param currentStateName The state this state machine is currently in. When constructing the StateMachine, this is the entry state.
+     */
+    constructor(currentStateName: string);
+    /**
+     * Helper function that throws an Error when something tries to edit the state machine after it has been frozen/finalized.
+     * @since 0.16.0
+     */
+    guardEditable(): void;
+    /**
+     * Helper function that throws an Error when something tries to use the state machine before it has been frozen/finalized.
+     * @since 0.16.0
+     */
+    guardNotEditable(): void;
+    /**
+     * Define a state in the state machine.
+     * @since 0.16.0
+     * @param name The name of the state.
+     * @param cbs Callbacks for points during transitions relating to this state as well as transitions to other states.
+     */
+    defineState(name: string, cbs?: {
+        onEnter: SMState["onEnter"];
+        onLeave: SMState["onLeave"];
+        transitions: Map<string, SMTransition>;
+    }): this;
+    /**
+     * Define a transition between 2 states in the state machine.
+     * @since 0.16.0
+     * @param from The name of the state this transition would come from.
+     * @param event The event that can trigger this transition.
+     * @param to The name of the state this transition would go to.
+     * @param cb A callback to run when this transition occurs.
+     */
+    defineTransition(from: string, event: string, to: string, cb?: (...args: any[]) => unknown): this;
+    /**
+     * Define a transition from every state to another state in the state machine.
+     * @since 0.16.0
+     * @param event The event that can trigger this transition.
+     * @param to The name of the state this transition would go to.
+     * @param cb A callback to run when this transition occurs.
+     */
+    defineUniversalTransition(event: string, to: string, cb?: (...args: any[]) => unknown): this;
+    /**
+     * Finalize the state machine, making its states and transitions now readonly and usable.
+     * @since 0.16.0
+     */
+    freeze(): void;
+    /**
+     * Trigger an event to do a transition from the current state to another as defined previously.
+     *
+     * Will throw an Error if there is no transition from the current state to another based off the event.
+     *
+     * If called while another transition is still running (from an onLeave/onTransition/onEnter callback or
+     * something those callbacks synchronously invoke), the transition is queued and runs once the current one
+     * has fully completed, instead of nesting. Nested execution used to corrupt the enter sequence: the outer
+     * transition would re-emit "enter" for whatever state the nested transition landed in, re-running that
+     * state's onEnter callbacks and cancelling doTransitionLater timers that were still supposed to be pending.
+     * @since 0.16.0
+     * @param event The event that occurred.
+     * @param args Arguments to pass to the callback of the transition's onTransition functions if any.
+     */
+    doTransition(event: string, ...args: any[]): void;
+    /**
+     * Runs a single transition to completion: onLeave, state change, onTransition, "enter", onEnter.
+     * Only ever called from doTransition's drain loop so transitions cannot nest.
+     */
+    private _transition;
+    /**
+     * Trigger an event to do a transition from the current state to another as defined previously at a later point in time.
+     *
+     * Will throw an Error if there is no transition from the current state to another based off the event.
+     * @since 0.16.0
+     * @param event The event that occured.
+     * @param delayMs The time in milliseconds this transition will run in.
+     * @param args Arguments to pass to the callback of the transition's onTransition functions if any.
+     */
+    doTransitionLater(event: string, delayMs: number, ...args: Array<any>): void;
+    /**
+     * Print debug info about this state machine to stdout in the form of a table.
+     * @since 0.16.0
+     */
+    debug(): void;
+}
+export = StateMachine;

package/dist/StateMachine.js

@@ -0,0 +1,238 @@
+"use strict";
+const node_events_1 = require("node:events");
+/**
+ * Class used to define states code is expected to be in and transitions to other states and code to run during those transitions and states
+ * @since 0.16.0
+ */
+class StateMachine extends node_events_1.EventEmitter {
+    currentStateName;
+    states = new Map();
+    editable = true;
+    deferredTransitionCreators = [];
+    history = [];
+    /** Transitions requested while another transition was still running. Drained in order once the running transition completes. */
+    pendingTransitions = [];
+    /** Whether a transition is currently being executed, making new transition requests queue instead of nesting. */
+    transitioning = false;
+    /**
+     * Create a new StateMachine
+     * @param currentStateName The state this state machine is currently in. When constructing the StateMachine, this is the entry state.
+     */
+    constructor(currentStateName) {
+        super();
+        this.currentStateName = currentStateName;
+        this.deferredTransitionCreators.push(() => {
+            if (!this.states.has(currentStateName)) {
+                this.defineState(currentStateName);
+            }
+        });
+    }
+    /**
+     * Helper function that throws an Error when something tries to edit the state machine after it has been frozen/finalized.
+     * @since 0.16.0
+     */
+    guardEditable() {
+        if (!this.editable)
+            throw new Error("tried to edit state machine after machine has been frozen");
+    }
+    /**
+     * Helper function that throws an Error when something tries to use the state machine before it has been frozen/finalized.
+     * @since 0.16.0
+     */
+    guardNotEditable() {
+        if (this.editable)
+            throw new Error("tried to do transition before machine has been frozen");
+    }
+    /**
+     * Define a state in the state machine.
+     * @since 0.16.0
+     * @param name The name of the state.
+     * @param cbs Callbacks for points during transitions relating to this state as well as transitions to other states.
+     */
+    defineState(name, cbs) {
+        const options = { onEnter: [], onLeave: [], transitions: new Map(), ...cbs };
+        this.guardEditable();
+        if (this.states.has(name))
+            throw new Error(`attempt to redefine state ${name}, please edit it instead`);
+        this.states.set(name, {
+            onEnter: options.onEnter,
+            onLeave: options.onLeave,
+            transitions: options.transitions
+        });
+        return this;
+    }
+    /**
+     * Define a transition between 2 states in the state machine.
+     * @since 0.16.0
+     * @param from The name of the state this transition would come from.
+     * @param event The event that can trigger this transition.
+     * @param to The name of the state this transition would go to.
+     * @param cb A callback to run when this transition occurs.
+     */
+    defineTransition(from, event, to, cb) {
+        this.guardEditable();
+        const state = this.states.get(from);
+        if (state.transitions.has(event))
+            throw new Error(`attempt to redefine transition ${from} --${event}--> *, please only create transitions once`);
+        const onTransition = [];
+        if (cb)
+            onTransition.push(cb);
+        state.transitions.set(event, { destination: to, onTransition });
+        return this;
+    }
+    /**
+     * Define a transition from every state to another state in the state machine.
+     * @since 0.16.0
+     * @param event The event that can trigger this transition.
+     * @param to The name of the state this transition would go to.
+     * @param cb A callback to run when this transition occurs.
+     */
+    defineUniversalTransition(event, to, cb) {
+        this.guardEditable();
+        this.deferredTransitionCreators.push(() => {
+            for (const [stateName, state] of this.states.entries()) {
+                if (!state.transitions.has(event)) {
+                    this.defineTransition(stateName, event, to, cb);
+                }
+            }
+        });
+        return this;
+    }
+    /**
+     * Finalize the state machine, making its states and transitions now readonly and usable.
+     * @since 0.16.0
+     */
+    freeze() {
+        this.guardEditable();
+        // Add deferred transitions
+        for (const cb of this.deferredTransitionCreators) {
+            cb();
+        }
+        // Check consistency
+        const problems = [];
+        for (const [stateName, state] of this.states.entries()) {
+            for (const [transitionName, transition] of state.transitions.entries()) {
+                if (!this.states.has(transition.destination)) {
+                    problems.push(`transition ${stateName} --${transitionName}--> ${transition.destination} has an invalid destination`);
+                }
+            }
+        }
+        if (problems.length) {
+            throw new Error(`Consistency problems in state machine: ${problems.join(";")}`);
+        }
+        this.editable = false;
+    }
+    /**
+     * Trigger an event to do a transition from the current state to another as defined previously.
+     *
+     * Will throw an Error if there is no transition from the current state to another based off the event.
+     *
+     * If called while another transition is still running (from an onLeave/onTransition/onEnter callback or
+     * something those callbacks synchronously invoke), the transition is queued and runs once the current one
+     * has fully completed, instead of nesting. Nested execution used to corrupt the enter sequence: the outer
+     * transition would re-emit "enter" for whatever state the nested transition landed in, re-running that
+     * state's onEnter callbacks and cancelling doTransitionLater timers that were still supposed to be pending.
+     * @since 0.16.0
+     * @param event The event that occurred.
+     * @param args Arguments to pass to the callback of the transition's onTransition functions if any.
+     */
+    doTransition(event, ...args) {
+        this.guardNotEditable();
+        this.pendingTransitions.push({ event, args });
+        if (this.transitioning)
+            return; // the drain loop below picks it up once the current transition has fully completed
+        this.transitioning = true;
+        try {
+            while (this.pendingTransitions.length) {
+                const next = this.pendingTransitions.shift();
+                this._transition(next.event, next.args);
+            }
+        }
+        finally {
+            this.transitioning = false;
+            this.pendingTransitions.length = 0; // if a transition threw, queued followers must not leak into an unrelated later call
+        }
+    }
+    /**
+     * Runs a single transition to completion: onLeave, state change, onTransition, "enter", onEnter.
+     * Only ever called from doTransition's drain loop so transitions cannot nest.
+     */
+    _transition(event, args) {
+        const from = this.currentStateName;
+        const currentState = this.states.get(this.currentStateName);
+        const transition = currentState.transitions.get(event);
+        if (!transition)
+            throw new Error(`undefined transition: ${this.currentStateName} -> ${event} -> ?`);
+        this.history.push({ from, event, to: transition.destination, time: Date.now() });
+        if (this.history.length > 20)
+            this.history.shift();
+        // Leave state
+        for (const cb of this.states.get(this.currentStateName).onLeave) {
+            try {
+                cb(event);
+            }
+            catch (e) {
+                this.debug();
+                throw new Error(`onLeave callback for state ${from} (during transition ${from} --${event}--> ${transition.destination})`, { cause: e });
+            }
+        }
+        // Do transition
+        this.currentStateName = transition.destination;
+        for (const cb of transition.onTransition ?? []) {
+            try {
+                cb(...args);
+            }
+            catch (e) {
+                this.debug();
+                throw new Error(`onTransition callback during ${from} --${event}--> ${transition.destination}`, { cause: e });
+            }
+        }
+        // Enter state
+        this.emit("enter", this.currentStateName);
+        for (const cb of this.states.get(this.currentStateName).onEnter) {
+            try {
+                cb(event);
+            }
+            catch (e) {
+                this.debug();
+                throw new Error(`onEnter callback for state ${transition.destination} (during transition ${from} --${event}--> ${transition.destination})`, { cause: e });
+            }
+        }
+    }
+    /**
+     * Trigger an event to do a transition from the current state to another as defined previously at a later point in time.
+     *
+     * Will throw an Error if there is no transition from the current state to another based off the event.
+     * @since 0.16.0
+     * @param event The event that occured.
+     * @param delayMs The time in milliseconds this transition will run in.
+     * @param args Arguments to pass to the callback of the transition's onTransition functions if any.
+     */
+    doTransitionLater(event, delayMs, ...args) {
+        this.guardNotEditable();
+        const timer = setTimeout(() => {
+            this.doTransition(event, ...args);
+        }, delayMs);
+        this.once("enter", () => {
+            clearTimeout(timer);
+        });
+    }
+    /**
+     * Print debug info about this state machine to stdout in the form of a table.
+     * @since 0.16.0
+     */
+    debug() {
+        console.table(this.history.map(h => ({
+            "At": new Date(h.time),
+            "From -->": h.from,
+            "-- Event -->": h.event,
+            "--> To": h.to
+        })).concat({
+            "At": new Date(),
+            "From -->": this.currentStateName,
+            "-- Event -->": "(debug)",
+            "--> To": ""
+        }));
+    }
+}
+module.exports = StateMachine;

package/dist/StateMachineGraph.d.ts

@@ -0,0 +1,3 @@
+import StateMachine = require("./StateMachine");
+declare function graph(stateMachine: StateMachine): string;
+export { graph };

package/dist/StateMachineGraph.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graph = graph;
+function graph(stateMachine) {
+    stateMachine.guardNotEditable();
+    let output = "digraph {\n";
+    output += "rankdir=LR\n";
+    output += `${stateMachine.currentStateName}\n`;
+    for (const [stateName, state] of stateMachine.states.entries()) {
+        if (state.onEnter.length) {
+            output += `${stateName} [fontcolor=blue]\n`;
+        }
+        for (const [transitionName, transition] of state.transitions.entries()) {
+            output += `${stateName} -> ${transition.destination}`;
+            const attrs = [`label="${transitionName}"`];
+            if (transition.onTransition?.length)
+                attrs.push("color=blue", "fontcolor=blue");
+            output += `[${attrs.join(" ")}]\n`;
+        }
+    }
+    output += "}";
+    return output;
+}

package/dist/Types.d.ts

@@ -0,0 +1,76 @@
+import type { APIAllowedMentions } from "discord-api-types/v10";
+import type { Readable } from "node:stream";
+export type HTTPMethod = "get" | "post" | "patch" | "head" | "put" | "delete" | "connect" | "options" | "trace";
+/**
+ * A file that can be uploaded to Discord's API
+ * @since 0.18.1
+ */
+export type SendableFile = Buffer | Blob | File | Readable | ReadableStream;
+/**
+ * A file to upload, or a factory that produces a fresh one each time the payload is materialized.
+ *
+ * Streams are single use: once a request has consumed them, sending the same payload again would upload nothing.
+ * If you want to reuse a payload containing streams across calls, pass a factory that returns a new stream each time,
+ * e.g. `file: () => fs.createReadStream(path)`. Buffers and Blobs are re-readable and don't need this.
+ * @since 0.18.1
+ */
+export type FileInput = SendableFile | (() => SendableFile | Promise<SendableFile>);
+export type SnowTransferOptions = {
+    /** The URL to start requests from. eg: https://discord.com */
+    baseHost: string;
+    /** The base path of the base URL to use for the API. Defaults to /api/v${Constants.REST_API_VERSION} */
+    baseURL: string;
+    /** The fetch implementation to use when making requests. Defaults to globalThis.fetch */
+    fetch: typeof globalThis.fetch;
+    /** The default allowed_mentions object to send when creating/updating messages */
+    allowed_mentions: APIAllowedMentions | undefined;
+    /** If rate limit buckets should be totally bypassed and functions are executed as fast as possible. Only use if you are 100% certain you wont run into issues or if you are proxying */
+    bypassBuckets: boolean;
+    /** If failed requests that can be retried should be retried, up to retryLimit times. */
+    retryRequests: boolean;
+    /** How many times requests should be retried if they fail and can be retried. */
+    retryLimit: number;
+};
+export type RESTPostAPIAttachmentsRefreshURLsResult = {
+    refreshed_urls: Array<{
+        original: string;
+        refreshed: string;
+    }>;
+};
+export type RatelimitInfo = {
+    message: string;
+    retry_after: number;
+    global: boolean;
+    code?: number;
+};
+export type RequestEventData = {
+    endpoint: string;
+    method: string;
+    dataType: "json" | "multipart";
+    data: any;
+};
+export type HandlerEvents = {
+    request: [string, RequestEventData];
+    done: [string, Response, RequestEventData];
+    requestError: [string, Error];
+    rateLimit: [{
+        method: string;
+        path: string;
+        route: string;
+    }];
+};
+export type SMState = {
+    onEnter: Array<(event: string) => unknown>;
+    onLeave: Array<(event: string) => unknown>;
+    transitions: Map<string, SMTransition>;
+};
+export type SMTransition = {
+    destination: string;
+    onTransition?: Array<(...args: any[]) => unknown>;
+};
+export type SMHistory = {
+    from: string;
+    event: string;
+    to: string;
+    time: number;
+};

package/dist/Types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });