@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/api/effect/bot.d.ts

@@ -0,0 +1,233 @@
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import { ApplicationError, ConfigurationError, type ConnectError } from "#sdk/errors";
+import { CriticalWorkerStoppedError, type RunBotOptions } from "#sdk/bot-runner";
+import type { SendError } from "#sdk/message-errors";
+import type { Message, MessageCore, MessageFields, SelectedMessage, ReplyInput, SendOptions } from "#sdk/messages";
+import type { HandlerOptions, EventMap, EventName } from "#sdk/events";
+import type { CommandArgumentSchema } from "#sdk/command-arguments";
+import { type NativeBatchRequirements, type NativePrefixCommandBatch, type NativePrefixCommandRouter, type NativePrefixCommandsOptions } from "#sdk/native-commands";
+import { type ClientOptions, type Client } from "./client.js";
+import { type FailureReport } from "./failures.js";
+/**
+ * Give a bot handler its event payload and client. The messageCreate context also provides
+ * `message` as an alias for the payload and `reply`, which uses the client's native messages.reply operation.
+ * The reply Effect sends only when executed and retains its normal SendError and interruption behavior
+ *
+ * @category Client and lifecycle
+ */
+export type BotEventContext<K extends EventName, M extends MessageCore = Message> = {
+    /** The payload delivered by the named gateway event */
+    readonly event: EventMap<M>[K];
+    /** The client owned by this bot run. Do not retain it after the run stops */
+    readonly client: Client<M>;
+} & (K extends "messageCreate" ? {
+    /** The messageCreate payload, identical to event */
+    readonly message: M;
+    /** Build a native reply Effect targeting this message. A string is sent as the content. Executing it can fail with SendError */
+    readonly reply: (input: ReplyInput | string, options?: SendOptions) => Effect.Effect<M, SendError>;
+} : {});
+/**
+ * A native runBot event handler
+ *
+ * @category Client and lifecycle
+ */
+export type BotEventHandler<K extends EventName, E = never, R = never, M extends MessageCore = Message> = (context: BotEventContext<K, M>) => Effect.Effect<unknown, E, R>;
+/** A native runBot event handler with its own delivery settings.
+ * Omitted settings use the runBot defaults: Overflow dropOldest, concurrency 8 for messageCreate or a partitioned handler and 1 otherwise,
+ * and the client.on queue limits
+ *
+ * @category Client and lifecycle
+ */
+export interface BotEventOptions<K extends EventName, E = never, R = never, M extends MessageCore = Message> extends HandlerOptions<EventMap<M>[K]> {
+    /** Called for each event */
+    readonly handler: BotEventHandler<K, E, R, M>;
+    /** Receive this handler's failures instead of the client-level onError */
+    readonly onError?: (report: FailureReport) => Effect.Effect<unknown, E, R>;
+}
+/** One optional handler per event, as a function or an object with a handler and delivery settings.
+ * The runBot function delivers with overflow dropOldest, so a full queue drops the oldest waiting event with a Warn record and a
+ * counter instead of stopping the bot. Handlers for messageCreate run up to eight at a time by default, and other events
+ * run one at a time. A failed handler is reported with its original Cause without stopping the bot
+ *
+ * @category Client and lifecycle
+ */
+export type BotEvents<E = never, R = never, M extends MessageCore = Message> = {
+    readonly [K in EventName]?: BotEventHandler<K, E, R, M> | BotEventOptions<K, E, R, M> | undefined;
+};
+/**
+ * The keyed-command constraint the native runBot infers command services from: Each entry's optional argument schema and callback
+ *
+ * @category Commands
+ */
+export type BotCommandEntries<S> = Readonly<Record<keyof S, {
+    /** Argument schema of the command under this key */
+    readonly arguments?: CommandArgumentSchema;
+    /** Command callback, whose required services runBot adds to its own requirements */
+    readonly execute: unknown;
+}>>;
+/**
+ * Prefix commands for the native runBot: The router options of commands.create, the commands themselves, an optional
+ * failure hook and the delivery settings of the router's attach. Router-level callbacks, such as onUnmatched and middleware, run without extra services, while each
+ * command's services are added to the bot's requirements. The router is attached before the gateway starts and closed when the bot stops.
+ * The delivery settings concurrency, partition, overflow, maxPendingMessages and maxPendingBytes are passed to attach
+ * unchanged and checked before any client exists. Omitted settings keep the attach defaults: Eight commands at a time
+ * and overflow dropOldest, so a burst drops the oldest waiting message with a Warn record. With overflow "stop", a full
+ * queue fails the bot with CriticalWorkerStoppedError.
+ * Unlike commands.create, runBot replies to a rejected command by default, such as one with a missing argument, as
+ * `onReject: "reply"` does. Set `onReject: "silent"` to send no reply, or a function to give custom feedback.
+ * An unset ignoreBots follows the runBot ignoreBots setting
+ *
+ * @category Commands
+ */
+export interface BotCommandsOptions<M extends MessageCore = Message, S extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, C extends BotCommandEntries<S> = BotCommandEntries<S>, RouterServices = never> extends NativePrefixCommandsOptions<unknown, never, M>, HandlerOptions<M> {
+    /**
+     * Commands keyed by name, such as `{ ping: { execute: ({ reply }) => reply("Pong") } }`, or a callback that
+     * receives the empty router and returns it with registrations, for groups or commands built elsewhere.
+     * The callback runs synchronously when the runBot Effect runs. Invalid registrations and a return value other than
+     * the registered router are misuse and die with ConfigurationError. Any other throw from the callback creates no
+     * client, and runBot fails with ApplicationError whose source is "runBot commands" and whose cause is the thrown value
+     */
+    readonly commands: (C & NativePrefixCommandBatch<M, S>) | ((router: NativePrefixCommandRouter<never, M>) => NativePrefixCommandRouter<RouterServices, M>);
+    /** Receive command failures instead of the client-level onError, as the router attach option does */
+    readonly onError?: (report: FailureReport) => Effect.Effect<unknown, unknown, never>;
+}
+/**
+ * Configure one Effect bot with client settings, optional stop signals, event handlers, prefix commands and startup work.
+ * The token accepts an unvalidated environment value. A missing or blank value is not misuse: Once the other options
+ * are valid, the bot fails with ConfigurationError. Client settings, including messageFields and cache callbacks, retain their native semantics.
+ * Handlers and commands are registered when the Effect runs, before the gateway starts.
+ * Reports before client creation use the configured logging settings and mask the normalized token, including a token
+ * enclosed in matching quotes. If an option getter throws, readable token, logging and reportFailure settings are retained
+ * independently for reporting. Unreadable logging uses the native default output, and unreadable reportFailure enables reporting
+ *
+ * @category Client and lifecycle
+ */
+export type BotOptions<EventError = never, EventServices = never, OptionsError = never, OptionsServices = never, F extends MessageFields | undefined = undefined> = ClientOptions<OptionsError, OptionsServices, F> & RunBotOptions & {
+    /** Event handlers registered before the gateway starts and closed when the bot stops.
+     * Pass a function, or an object with a handler and its own delivery settings.
+     * By default messageCreate runs up to 8 callbacks at a time and other events 1, and a full queue drops the oldest
+     * waiting event with a Warn record instead of stopping the bot.
+     * Bot-authored messageCreate and messageUpdate events skip these handlers unless ignoreBots is false
+     */
+    readonly events?: BotEvents<EventError, EventServices, SelectedMessage<F>>;
+    /**
+     * Skip messageCreate and messageUpdate events whose author is a bot, including this bot's own messages, before they
+     * reach the events handlers or prefix commands. Defaults to true, so a reply cannot trigger its own handler.
+     * Set false for a bridge or logging bot that handles every message, and check message.author.isBot where needed.
+     * Prefix commands follow the same setting unless commands.ignoreBots sets its own.
+     * A value other than a boolean is misuse and dies with ConfigurationError
+     */
+    readonly ignoreBots?: boolean;
+    /** Prefix commands registered and attached before the gateway starts. See BotCommandsOptions */
+    readonly commands?: BotCommandsOptions<SelectedMessage<F>>;
+    /**
+     * Startup work after events and commands are registered and before the gateway connects, such as extra
+     * subscriptions in the bot's Scope. The bot connects only after the Effect succeeds, so no handler runs before
+     * setup finishes. A failure stops the bot before connecting, and runBot fails with ApplicationError whose source is
+     * "runBot setup" and whose cause is the original failure, such as the GuildOperationError of a failed read.
+     * A defect or interruption stops the bot with that cause unchanged. Passed inline to runBot, the Effect's other
+     * services are added to the bot's requirements.
+     * The Effect runs in the bot's Scope, so its finalizers run and fibers it forks into that Scope are interrupted when
+     * the bot stops, after its client has shut down. A forked fiber's failure is not reported, so start delayed,
+     * repeating and background work with client.schedule instead: A requested stop lets its running work finish
+     * within drainMs, and a failure reaches onError or the log. The default API instead passes setup an AbortSignal
+     * that aborts when the bot begins stopping
+     */
+    readonly setup?: (client: Client<SelectedMessage<F>>) => Effect.Effect<unknown, unknown, Scope.Scope>;
+};
+/**
+ * The services required by one runBot event handler H, including its onError hook
+ *
+ * @category Client and lifecycle
+ */
+export type HandlerServices<H> = H extends (...args: never[]) => Effect.Effect<unknown, unknown, infer R> ? R : H extends {
+    /** Event handler of an options-object entry */
+    readonly handler: (...args: never[]) => Effect.Effect<unknown, unknown, infer R>;
+    /** Optional failure hook of an options-object entry */
+    readonly onError?: infer Hook;
+} ? R | (Hook extends (...args: never[]) => Effect.Effect<unknown, unknown, infer R2> ? R2 : never) : never;
+/**
+ * The services required by every handler in a runBot events object, which runBot adds to its own requirements.
+ * Omitted events require no services
+ *
+ * @category Client and lifecycle
+ */
+export type BotEventServices<Events> = {
+    [K in keyof Events]-?: HandlerServices<NonNullable<Events[K]>> extends infer R ? unknown extends R ? never : R : never;
+}[keyof Events];
+/**
+ * Register runBot events and commands on a test client in the current Scope, with the same checks, contexts and
+ * registration as runBot, returning the setup Effect that the test client runs before it connects. Used by the
+ * Effect testing entry point. Misuse dies with ConfigurationError, and a commands register callback's own
+ * failure fails with its ApplicationError
+ */
+export declare function installNativeTestBot(client: Client, options: {
+    readonly events?: unknown;
+    readonly ignoreBots?: unknown;
+    readonly commands?: unknown;
+    readonly setup?: unknown;
+}): Effect.Effect<Effect.Effect<void, ApplicationError, Scope.Scope>, ApplicationError, Scope.Scope>;
+/**
+ * Run a bot from one configuration object in the application's Effect context and scope.
+ * When the Effect runs, it creates the client and registers every event handler and command before the gateway
+ * starts, so no event is missed and no handler runs before registration and setup complete.
+ * A malformed option, misspelled option key, non-function handler, unsupported event name, invalid delivery setting or
+ * invalid command is misuse and dies with ConfigurationError. Every option is checked before any client, signal
+ * listener or request exists, even when the signal is already aborted, so misuse leaves nothing to clean up.
+ * A missing or empty token, usually from an unset environment variable, is a failure instead: Once every other option
+ * is valid, the bot fails with ConfigurationError with field token before any client exists.
+ * Handler and command failures are reported to onError, or logged with their full Cause, and do not stop the bot.
+ * By default, messageCreate and messageUpdate events written by bots skip the events handlers and prefix commands.
+ * Set ignoreBots to false to opt out.
+ * A failed setup Effect or a throwing commands register callback fails the bot with ApplicationError before it connects.
+ * A subscription that closes while the bot runs fails the bot with CriticalWorkerStoppedError. That includes a handler
+ * or command router set to overflow "stop" whose queue overflows. The overflow is still reported to onError or logged,
+ * and the error names the event and the exceeded capacity, with the EventOverflowError as its cause. Cleanup is awaited.
+ * Aborting the signal option, or SIGINT or SIGTERM when processSignals is true, stops the bot successfully after running
+ * handlers, scheduled tasks and their requests have had up to drainMs, default 5,000 ms, to finish.
+ * Fiber interruption remains interruption and does not drain.
+ * Process signals stay opt-in here, because a launcher such as NodeRuntime.runMain already interrupts the program on
+ * SIGINT and SIGTERM. Set processSignals to true only when nothing else handles them and a drained stop is wanted.
+ * By default a failure or defect that stops the bot, including misuse and a missing token, is also logged once, with
+ * code lifecycle.botFailed unless the client already logged that error, and sets process.exitCode to 1, so running the
+ * Effect needs no further handling.
+ * Set reportFailure to false when the application handles the failure and exit status itself.
+ * Reports before client creation use the configured logging settings, print no stack for a missing token and mask the
+ * token after removing surrounding whitespace and one pair of matching quotes. An option getter that throws remains
+ * the original defect. For that report, token, logging and reportFailure are read independently and may be read again
+ * if the option snapshot already read them.
+ * A throwing reporting getter does not discard the other readable settings. Unusable logging uses the native default
+ * output, and an unreadable reportFailure setting keeps reporting enabled.
+ * No separate runtime is created and the process is not exited
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { runBot } from "@neontechspace/fluxerly/effect"
+ *
+ * export function pingBot(token: string | undefined) {
+ *     return runBot({
+ *         token,
+ *         processSignals: true,
+ *         commands: {
+ *             prefix: "!",
+ *             commands: {
+ *                 ping: { execute: ({ reply }) => reply("Pong!") },
+ *             },
+ *         },
+ *         events: {
+ *             guildCreate: ({ event }) => Effect.logInfo(`Joined ${event.name}`),
+ *         },
+ *     })
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export declare function runBot<const F extends MessageFields | undefined = undefined, const Events extends BotEvents<unknown, unknown, SelectedMessage<F>> = BotEvents<unknown, unknown, SelectedMessage<F>>, const S extends Readonly<Record<string, unknown>> = {}, const C extends BotCommandEntries<S> = BotCommandEntries<S>, RouterServices = never, OptionsError = never, OptionsServices = never, SetupServices = never>(options: Omit<BotOptions<unknown, unknown, OptionsError, OptionsServices, F>, "events" | "commands" | "setup"> & {
+    readonly events?: Events & Record<Exclude<keyof Events, EventName>, never>;
+    readonly commands?: BotCommandsOptions<SelectedMessage<F>, S, C, RouterServices>;
+    readonly setup?: (client: Client<SelectedMessage<F>>) => Effect.Effect<unknown, unknown, SetupServices>;
+}): Effect.Effect<void, ConnectError | CriticalWorkerStoppedError | ApplicationError | ConfigurationError, Exclude<BotEventServices<Events> | NativeBatchRequirements<C> | RouterServices | OptionsServices | SetupServices, Scope.Scope>>;
+//# sourceMappingURL=bot.d.ts.map

package/dist/api/effect/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../../src/api/effect/bot.ts"],"names":[],"mappings":"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"}

package/dist/api/effect/bot.js

@@ -0,0 +1,230 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { readIgnoreBots, reportBotFailure, runBotCore, skipsBotMessage, snapshotBotCommandDelivery, snapshotBotEvents, standaloneBotLogger, validateBotClientOptions, validateRunOptions, } from "#sdk/internal/bot-runner";
+import { ApplicationError, ConfigurationError } from "#sdk/errors";
+import { CriticalWorkerStoppedError } from "#sdk/bot-runner";
+import { nativeBotRouter, } from "#sdk/native-commands";
+import { createClient } from "./client.js";
+import {} from "./failures.js";
+import {} from "./events.js";
+/** Read and check a native bot's events, commands and setup callback. Misuse throws ConfigurationError */
+function prepareNativeBot(events, ignoreBots, commands, setup) {
+    if (setup !== undefined && typeof setup !== "function")
+        throw new ConfigurationError("configuration", 'The option "setup" must be a function');
+    const entries = snapshotBotEvents(events);
+    const skipBots = readIgnoreBots(ignoreBots);
+    let router;
+    let commandsFailure;
+    try {
+        router = commands === undefined ? undefined : nativeBotRouter(commands, skipBots);
+    }
+    catch (error) {
+        // A register callback's own failure is an application outcome, failed once the other options are checked
+        if (!(error instanceof ApplicationError))
+            throw error;
+        commandsFailure = error;
+    }
+    const onError = commands?.onError;
+    if (onError !== undefined && typeof onError !== "function")
+        throw new ConfigurationError("onError", 'The option "commands.onError" must be a function');
+    return {
+        entries,
+        skipBots,
+        router,
+        onError: onError,
+        delivery: commands === undefined ? undefined : snapshotBotCommandDelivery(commands),
+        setup: setup,
+        commandsFailure,
+    };
+}
+/** Register a native bot's event handlers and command router on a client in the current Scope, as runBot does */
+function registerNativeBot(client, prepared) {
+    return Effect.gen(function* () {
+        const subscriptions = [];
+        for (const { event, handler, options } of prepared.entries)
+            subscriptions.push(yield* client.on(event, (payload) => skipsBotMessage(event, payload, prepared.skipBots)
+                ? Effect.void
+                : handler(Object.freeze(event === "messageCreate"
+                    ? {
+                        event: payload,
+                        client,
+                        message: payload,
+                        reply: (input, options) => client.messages.reply(payload, input, options),
+                    }
+                    : { event: payload, client })), options));
+        if (prepared.router !== undefined)
+            subscriptions.push(yield* prepared.router.attach(client, {
+                ...prepared.delivery,
+                ...(prepared.onError === undefined ? {} : { onError: prepared.onError }),
+            }));
+        return subscriptions;
+    });
+}
+/** Run a native bot's setup once. A failure becomes ApplicationError with source "runBot setup", and defects stay defects */
+function nativeBotSetup(client, setup) {
+    if (setup === undefined)
+        return Effect.void;
+    return Effect.suspend(() => setup(client)).pipe(
+    // A setup failure, such as a failed read, is an application outcome. Defects stay defects
+    Effect.mapError((error) => new ApplicationError("runBot setup", error)), Effect.asVoid);
+}
+/** Split runBot options once into runner settings and client settings. A throwing getter throws its value */
+function readNativeBotOptions(options) {
+    const { events, ignoreBots, commands, setup, signal, processSignals, reportFailure, drainMs, ...clientOptions } = options;
+    return { events, ignoreBots, commands, setup, signal, processSignals, reportFailure, drainMs, clientOptions };
+}
+/** Recover each reporting setting independently after an option getter throws, without replacing that original defect */
+function readNativeBotReportingOptions(options) {
+    const clientOptions = {};
+    let reportFailure;
+    for (const key of ["token", "logging", "reportFailure"]) {
+        try {
+            const value = options[key];
+            if (key === "reportFailure")
+                reportFailure = value;
+            else
+                clientOptions[key] = value;
+        }
+        catch {
+            // allow-silent: An unreadable reporting setting falls back independently, preserving the original option defect
+        }
+    }
+    return { clientOptions, reportFailure };
+}
+/**
+ * End a native run on misuse or a throwing option getter before any client exists. The error is a defect in the
+ * native API, and it is reported like any failure that stops the bot, logged once and setting process.exitCode to 1
+ * unless reportFailure is false, because nothing else shows a defect when the application only runs the Effect
+ */
+function misuse(error, clientOptions, reportFailure) {
+    return reportBotFailure(Exit.die(error), standaloneBotLogger(clientOptions, true), reportFailure === false ? { reportFailure } : {}).pipe(Effect.andThen(Effect.die(error)));
+}
+/**
+ * Register runBot events and commands on a test client in the current Scope, with the same checks, contexts and
+ * registration as runBot, returning the setup Effect that the test client runs before it connects. Used by the
+ * Effect testing entry point. Misuse dies with ConfigurationError, and a commands register callback's own
+ * failure fails with its ApplicationError
+ */
+export function installNativeTestBot(client, options) {
+    return Effect.suspend(() => {
+        let prepared;
+        try {
+            prepared = prepareNativeBot(options.events, options.ignoreBots, options.commands, options.setup);
+        }
+        catch (error) {
+            return Effect.die(error);
+        }
+        if (prepared.commandsFailure !== undefined)
+            return Effect.fail(prepared.commandsFailure);
+        return registerNativeBot(client, prepared).pipe(Effect.as(nativeBotSetup(client, prepared.setup)));
+    });
+}
+/**
+ * Run a bot from one configuration object in the application's Effect context and scope.
+ * When the Effect runs, it creates the client and registers every event handler and command before the gateway
+ * starts, so no event is missed and no handler runs before registration and setup complete.
+ * A malformed option, misspelled option key, non-function handler, unsupported event name, invalid delivery setting or
+ * invalid command is misuse and dies with ConfigurationError. Every option is checked before any client, signal
+ * listener or request exists, even when the signal is already aborted, so misuse leaves nothing to clean up.
+ * A missing or empty token, usually from an unset environment variable, is a failure instead: Once every other option
+ * is valid, the bot fails with ConfigurationError with field token before any client exists.
+ * Handler and command failures are reported to onError, or logged with their full Cause, and do not stop the bot.
+ * By default, messageCreate and messageUpdate events written by bots skip the events handlers and prefix commands.
+ * Set ignoreBots to false to opt out.
+ * A failed setup Effect or a throwing commands register callback fails the bot with ApplicationError before it connects.
+ * A subscription that closes while the bot runs fails the bot with CriticalWorkerStoppedError. That includes a handler
+ * or command router set to overflow "stop" whose queue overflows. The overflow is still reported to onError or logged,
+ * and the error names the event and the exceeded capacity, with the EventOverflowError as its cause. Cleanup is awaited.
+ * Aborting the signal option, or SIGINT or SIGTERM when processSignals is true, stops the bot successfully after running
+ * handlers, scheduled tasks and their requests have had up to drainMs, default 5,000 ms, to finish.
+ * Fiber interruption remains interruption and does not drain.
+ * Process signals stay opt-in here, because a launcher such as NodeRuntime.runMain already interrupts the program on
+ * SIGINT and SIGTERM. Set processSignals to true only when nothing else handles them and a drained stop is wanted.
+ * By default a failure or defect that stops the bot, including misuse and a missing token, is also logged once, with
+ * code lifecycle.botFailed unless the client already logged that error, and sets process.exitCode to 1, so running the
+ * Effect needs no further handling.
+ * Set reportFailure to false when the application handles the failure and exit status itself.
+ * Reports before client creation use the configured logging settings, print no stack for a missing token and mask the
+ * token after removing surrounding whitespace and one pair of matching quotes. An option getter that throws remains
+ * the original defect. For that report, token, logging and reportFailure are read independently and may be read again
+ * if the option snapshot already read them.
+ * A throwing reporting getter does not discard the other readable settings. Unusable logging uses the native default
+ * output, and an unreadable reportFailure setting keeps reporting enabled.
+ * No separate runtime is created and the process is not exited
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { runBot } from "@neontechspace/fluxerly/effect"
+ *
+ * export function pingBot(token: string | undefined) {
+ *     return runBot({
+ *         token,
+ *         processSignals: true,
+ *         commands: {
+ *             prefix: "!",
+ *             commands: {
+ *                 ping: { execute: ({ reply }) => reply("Pong!") },
+ *             },
+ *         },
+ *         events: {
+ *             guildCreate: ({ event }) => Effect.logInfo(`Joined ${event.name}`),
+ *         },
+ *     })
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export function runBot(options) {
+    const botOptions = options;
+    return Effect.suspend(() => {
+        if (typeof botOptions !== "object" || botOptions === null || Array.isArray(botOptions))
+            return misuse(new ConfigurationError("configuration", "The runBot options must be an object"), {}, undefined);
+        let read;
+        try {
+            read = readNativeBotOptions(botOptions);
+        }
+        catch (error) {
+            const { clientOptions, reportFailure } = readNativeBotReportingOptions(botOptions);
+            return misuse(error, clientOptions, reportFailure);
+        }
+        const { events, ignoreBots, commands, setup, signal, processSignals, reportFailure, drainMs, clientOptions } = read;
+        let prepared;
+        let missingToken;
+        try {
+            validateRunOptions({ signal, processSignals, reportFailure, drainMs });
+            prepared = prepareNativeBot(events, ignoreBots, commands, setup);
+            // Checked before the runner adds signal listeners or creates the client, so misuse has no side effects
+            missingToken = validateBotClientOptions(clientOptions, true);
+        }
+        catch (error) {
+            return misuse(error, clientOptions, reportFailure);
+        }
+        const runOptions = {
+            ...(signal === undefined ? {} : { signal }),
+            ...(processSignals === undefined ? {} : { processSignals }),
+            ...(reportFailure === undefined ? {} : { reportFailure }),
+            ...(drainMs === undefined ? {} : { drainMs }),
+        };
+        // A missing token and the callback's failure are returned even when the signal is already aborted
+        const failure = missingToken ?? prepared.commandsFailure;
+        if (failure !== undefined)
+            return reportBotFailure(Exit.fail(failure), standaloneBotLogger(clientOptions, true), runOptions).pipe(Effect.andThen(Effect.fail(failure)));
+        // Bound first, so the result type below does not narrow the inferred worker failure
+        const run = runBotCore(Effect.suspend(() => createClient(clientOptions)), (client) => Effect.gen(function* () {
+            const subscriptions = yield* registerNativeBot(client, prepared);
+            yield* nativeBotSetup(client, prepared.setup);
+            // A subscription stopped by overflow "stop" stops the bot, naming its event and capacity
+            return subscriptions.map((subscription, index) => ({
+                waitForClose: () => subscription.waitForClose().pipe(Effect.mapError((error) => new CriticalWorkerStoppedError(index, {
+                    // The command router follows the event handlers and receives messageCreate
+                    event: prepared.entries[index]?.event ?? "messageCreate",
+                    error,
+                }))),
+            }));
+        }), runOptions, () => standaloneBotLogger(clientOptions, true));
+        return run;
+    });
+}
+//# sourceMappingURL=bot.js.map

package/dist/api/effect/bot.js.map

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

package/dist/api/effect/cache.d.ts

@@ -0,0 +1,103 @@
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import type { CacheChange, CacheObserverOptions } from "#sdk/cache";
+import type { CacheEntriesOptions, CachedResources, CacheKind } from "#sdk/client";
+import type { Message, MessageCore } from "#sdk/messages";
+/**
+ * Stop receiving cache changes from client.cache.onChange before its registration Scope closes
+ *
+ * @category Caching
+ */
+export interface CacheObserver {
+    /** Identifier of this observer, such as cacheChange#3, used in its log records */
+    readonly id: string;
+    /** Stop delivering changes, including changes recorded or waiting but not yet delivered, and interrupt running listener work without waiting for it. Repeated calls do nothing */
+    close(): Effect.Effect<void>;
+}
+/** Inspect, clear or remove entries of this client's optional in-memory caches.
+ * These controls do not request fresh data, change remote resources or retain Effect services
+ *
+ * @category Caching
+ */
+export interface ClientCache<M extends MessageCore = Message> {
+    /**
+     * Return frozen snapshots from one configured cache category, ordered least to most recently used.
+     * The limit option defaults to 100 and accepts a positive safe integer from 1 through 1,000. It is read once, so the
+     * validated limit is the one applied.
+     * Expired entries are released first.
+     * Enumeration neither refreshes them nor changes eviction order, while local lookups do promote recency.
+     * Unlike diagnostics, the array contains actual cached resource data, and no network request or remote completeness claim is made.
+     * It may be partial because cache limits, expiry, conflicts, gateway gaps, clear or shutdown can discard entries.
+     * A closed client produces an empty array.
+     * Invalid kind or limit is misuse: The default API throws ConfigurationError without exposing the rejected value, and the native API dies with it
+     *
+     * @remarks
+     * Captures no service or scope.
+     * Interruption before execution leaves cache state unchanged, and once started it completes synchronously
+     */
+    entries<K extends CacheKind>(kind: K, options?: CacheEntriesOptions): Effect.Effect<readonly CachedResources<M>[K][]>;
+    /**
+     * Release data held by this client's caches without changing which caches are enabled.
+     * Pass a kind to release only that category, or omit it to release every category.
+     * Objects already returned to the caller, requests and remote resources stay unchanged.
+     * Older in-flight reads cannot refill the cleared entries and may skip caching their results, while later reads can cache normally.
+     * Existing write-related invalidation remains in effect.
+     * Each category that held entries reports one clear change to cache.onChange listeners, and a disabled category is left as is.
+     * This runs immediately, takes no signal and can be repeated, including after closure.
+     * An invalid kind is misuse: Both APIs throw ConfigurationError without exposing the rejected value
+     */
+    clear(kind?: CacheKind): void;
+    /**
+     * Remove one entry from a cache category by its key, without fetching, refreshing or changing the remote resource.
+     * The key uses the format described on CacheChange: `channelId:messageId` for messages, `guildId:userId` for members,
+     * `guildId:id` for roles, emojis and stickers, and the resource ID alone for communities, channels, users and direct messages.
+     * Objects already returned to the caller stay unchanged.
+     * Reads of this category already in flight cannot restore the removed entry and some may skip caching their other results,
+     * while later reads and events can cache it again.
+     * A removed entry reports one delete change to cache.onChange listeners, and a missing entry or disabled category is left as is.
+     * This runs immediately, takes no signal and can be repeated, including after closure.
+     * An invalid kind or key is misuse: Both APIs throw ConfigurationError without exposing the rejected value
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function forgetMember(client: Client, guildId: string, userId: string) {
+     *     return Effect.sync(() => client.cache.delete("members", `${guildId}:${userId}`))
+     * }
+     * ```
+     */
+    delete(kind: CacheKind, key: string): void;
+    /**
+     * Observe every later change to this client's local caches: Stored or replaced entries, removed entries and whole-category clears.
+     * Changes are delivered in the order they were applied, from a microtask after the cache work that produced them, so a listener never runs inside a cache operation and can read or clear the cache itself.
+     * Lookups, enumeration and diagnostics are not changes, and a clear is reported only for a category that held at least one entry.
+     * No change is recorded while no listener is registered, and a new listener receives no earlier changes or current contents.
+     * Delivery has no ordering relative to event handlers, and listener work never changes a cache result, a REST outcome or event delivery.
+     * A failing listener is reported as a cache failure to the client-level onError, or logged at Error, and keeps receiving later changes.
+     * Client shutdown records its final clears, then closes every observer without waiting for unfinished listener calls.
+     * A listener with a free call receives those clears, and changes still waiting for a busy listener are dropped with a cache.changesDropped Warn.
+     * Registering after shutdown returns an observer that never receives a change.
+     * A listener that is not a function, or invalid options, is misuse: The default API throws ConfigurationError, and the native API dies with it
+     *
+     * @remarks
+     * Registration runs when this Effect executes and lasts until observer close, client shutdown or the closing of the executing Scope.
+     * Each change starts the listener's Effect in its own fiber with the services available at registration, without awaiting it,
+     * so asynchronous listener work overlaps, up to options.concurrency running fibers, 256 by default. Synchronous Effects finish before the next change starts.
+     * Later changes then wait in order, up to options.maxPendingChanges, 256 by default, and a change arriving at that limit
+     * drops the oldest waiting change with a cache.changesDropped Warn.
+     * A failed or defective listener Effect is reported with its full Cause. Closing the observer interrupts listener fibers still running and discards waiting changes.
+     * A throwing options getter dies with the thrown value
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function cacheChangesExample(client: Client) {
+     *     return client.cache.onChange((change) => Effect.logDebug(`${change.kind} ${change.op}`))
+     * }
+     * ```
+     */
+    onChange<E = never, R = never>(listener: (change: CacheChange) => Effect.Effect<unknown, E, R>, options?: CacheObserverOptions): Effect.Effect<CacheObserver, never, R | Scope.Scope>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/api/effect/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/api/effect/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEzD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,kLAAkL;IAClL,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,OAAO;IACxD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,CAAC,SAAS,SAAS,EACvB,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,mBAAmB,GAC9B,MAAM,CAAC,MAAM,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAClD;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EACzB,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAC/D,OAAO,CAAC,EAAE,oBAAoB,GAC/B,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;CAC1D"}

package/dist/api/effect/cache.js

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

package/dist/api/effect/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/api/effect/cache.ts"],"names":[],"mappings":""}