@nubisjs/core 0.0.0-stage → 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EYTAK LIMITED
+
+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,7 @@
-# Temporary Holding Version
+# @nubisjs/core
 
-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.
+The engine behind [Nubis](https://eytak.com/nubis): command, component and modal definitions with inferred types, guards and middleware, Discord's rules checked at definition time, and dispatch with the reply lifecycle.
+
+Most bots should install [`nubis`](https://www.npmjs.com/package/nubis), which re-exports everything here.
+
+MIT. Built by [Eytak](https://eytak.com).

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Discord API client handlers get as `api`. Empty here so core stays
+ * free of any HTTP library; the `nubis` package fills it in with
+ * @discordjs/core's typed API through module augmentation:
+ *
+ *     declare module "@nubisjs/core" { interface NubisApi extends API {} }
+ */
+export interface NubisApi {
+}
+/**
+ * Stands in when no API client was given: any use explains how to get one,
+ * instead of failing with "cannot read properties of undefined".
+ */
+export declare function missingApi(): NubisApi;

package/dist/autocomplete.d.ts

@@ -0,0 +1,37 @@
+import { type APIApplicationCommandAutocompleteInteraction } from "discord-api-types/v10";
+import { type NubisApi } from "./api";
+import { type ErrorHandler } from "./errors";
+import { type Guard } from "./guard";
+import type { Transport } from "./lifecycle";
+import type { CommandTree } from "./tree";
+export interface AutocompleteOptions {
+    /** The bot's guards; see DispatchOptions.guards. */
+    readonly guards?: readonly Guard[];
+    readonly onError?: ErrorHandler;
+    readonly api?: NubisApi;
+}
+export type AutocompleteResult = {
+    readonly status: "handled";
+    readonly path: readonly string[];
+    readonly count: number;
+}
+/** No command, no focused option, or the option has no autocomplete handler. */
+ | {
+    readonly status: "unknown";
+    readonly path: readonly string[];
+}
+/** A guard denied: no suggestions, so they can't leak what the command would show. */
+ | {
+    readonly status: "denied";
+    readonly path: readonly string[];
+} | {
+    readonly status: "error";
+    readonly path: readonly string[];
+    readonly error: unknown;
+};
+/**
+ * Answers an autocomplete interaction with the focused option's suggestions.
+ * Every outcome answers, with an empty list when there's nothing to suggest,
+ * because Discord shows an error for autocomplete that doesn't respond.
+ */
+export declare function dispatchAutocomplete(tree: CommandTree, interaction: APIApplicationCommandAutocompleteInteraction, transport: Transport, options?: AutocompleteOptions): Promise<AutocompleteResult>;

package/dist/command.d.ts

@@ -0,0 +1,67 @@
+import type { APIChatInputApplicationCommandInteraction } from "discord-api-types/v10";
+import type { NubisApi } from "./api";
+import type { ModalData } from "./component";
+import type { Guard } from "./guard";
+import type { Middleware } from "./middleware";
+import type { OptionMap, ResolvedOptions } from "./option";
+import type { ReplyInput } from "./reply";
+/** Where a command can be used: servers, the bot's DMs, or group DMs and other users' DMs. */
+export type CommandContextName = "guild" | "bot-dm" | "private-channel";
+/** How the app is installed: to a server, or to a user's account. */
+export type IntegrationTypeName = "guild" | "user";
+/** Settings Discord only reads on top-level commands; folders can set them too. */
+export interface TopLevelSettings {
+    readonly defaultMemberPermissions?: readonly bigint[];
+    readonly contexts?: readonly CommandContextName[];
+    readonly integrationTypes?: readonly IntegrationTypeName[];
+    readonly nsfw?: boolean;
+}
+export interface CommandContext<T extends OptionMap> {
+    readonly options: ResolvedOptions<T>;
+    /** The raw interaction from Discord, for anything Nubis doesn't cover yet. */
+    readonly interaction: APIChatInputApplicationCommandInteraction;
+    /** Discord's API: ban members, send messages, look things up. */
+    readonly api: NubisApi;
+    /** Sends a message. The first one answers the command, later ones are follow-ups. */
+    reply(message: ReplyInput): Promise<void>;
+    /** Edits the first reply, e.g. to show progress. */
+    editReply(message: ReplyInput): Promise<void>;
+    /**
+     * Shows "thinking…" for work over three seconds. Nubis does this on its
+     * own after two seconds; call it earlier to choose `ephemeral` yourself.
+     */
+    defer(options?: {
+        readonly ephemeral?: boolean;
+    }): Promise<void>;
+    /** Opens a modal. Must be the first response, so call it before reply(). */
+    showModal(modal: ModalData): Promise<void>;
+}
+export interface CommandConfig<T extends OptionMap> {
+    readonly description: string;
+    readonly options?: T;
+    /** Makes replies (and the automatic "thinking…") visible only to the user. */
+    readonly ephemeral?: boolean;
+    /** Checks that run before `run`, after the folder's and the bot's own. */
+    readonly guards?: readonly Guard[];
+    /** Wraps `run`, inside the folder's and the bot's own middleware. */
+    readonly middleware?: readonly Middleware[];
+    /**
+     * Hides the command from members without these permissions
+     * (`PermissionFlagsBits`). Server admins can change this in Discord's
+     * settings, so pair it with a `hasPermission` guard when it matters.
+     * Top-level commands only; for subcommands, set it on the folder.
+     */
+    readonly defaultMemberPermissions?: readonly bigint[];
+    /** Top-level only. Where the command can be used. Defaults to everywhere it's installed. */
+    readonly contexts?: readonly CommandContextName[];
+    /** Top-level only. "user" makes it usable when installed to a user's account. */
+    readonly integrationTypes?: readonly IntegrationTypeName[];
+    /** Top-level only. Age-restricted: only shown in age-restricted channels. */
+    readonly nsfw?: boolean;
+    run(context: CommandContext<T>): unknown;
+}
+export interface CommandDefinition<T extends OptionMap> extends CommandConfig<T> {
+    readonly kind: "command";
+    readonly options: T;
+}
+export declare function command<T extends OptionMap = Record<never, never>>(config: CommandConfig<T>): CommandDefinition<T>;

package/dist/component-dispatch.d.ts

@@ -0,0 +1,45 @@
+import type { APIMessageComponentInteraction, APIModalSubmitInteraction } from "discord-api-types/v10";
+import { type ComponentDefinition, type ComponentRuntime } from "./component";
+import type { NubisApi } from "./api";
+import { type ErrorHandler } from "./errors";
+import { type Guard } from "./guard";
+import { type Middleware } from "./middleware";
+import { type Scheduler, type Transport } from "./lifecycle";
+export type ComponentRegistry = ReadonlyMap<string, ComponentRuntime>;
+export declare function createComponentRegistry(components: readonly ComponentDefinition[]): ComponentRegistry;
+export type ComponentDispatchResult = {
+    readonly status: "handled";
+    readonly id: string;
+    readonly responded: boolean;
+} | {
+    readonly status: "error";
+    readonly id: string;
+    readonly error: unknown;
+} | {
+    readonly status: "denied";
+    readonly id: string;
+    readonly message: string;
+} | {
+    readonly status: "unknown";
+    readonly customId: string;
+} | {
+    readonly status: "stale";
+    readonly id: string;
+    readonly reason: string;
+};
+export declare const STALE_MESSAGE = "This no longer works. It may be from an older message; try the command again.";
+export interface ComponentDispatchOptions {
+    readonly autoDeferMs?: number | false;
+    readonly schedule?: Scheduler;
+    /** Run before every component and modal handler, before their own guards. */
+    readonly guards?: readonly Guard[];
+    readonly middleware?: readonly Middleware[];
+    /** Receives every error a handler throws, after the user is told. */
+    readonly onError?: ErrorHandler;
+    /** Discord's API client, handed to handlers as `api`. */
+    readonly api?: NubisApi;
+}
+/** Routes a button click or select to its component, with its state validated. */
+export declare function dispatchComponent(registry: ComponentRegistry, interaction: APIMessageComponentInteraction, transport: Transport, options?: ComponentDispatchOptions): Promise<ComponentDispatchResult>;
+/** Routes a modal submission to its modal, with state and values validated. */
+export declare function dispatchModal(registry: ComponentRegistry, interaction: APIModalSubmitInteraction, transport: Transport, options?: ComponentDispatchOptions): Promise<ComponentDispatchResult>;

package/dist/component.d.ts

@@ -0,0 +1,214 @@
+import { type APIButtonComponentWithCustomId, type APIButtonComponentWithURL, type APIChannelSelectComponent, type APIInteractionDataResolvedChannel, type APIInteractionDataResolvedGuildMember, type APIMentionableSelectComponent, type APIMessageComponentEmoji, type APIMessageComponentInteraction, type APIModalInteractionResponseCallbackData, type APIModalSubmitInteraction, type APIRole, type APIRoleSelectComponent, type APIStringSelectComponent, type APIUser, type APIUserSelectComponent, ButtonStyle, type ChannelType } from "discord-api-types/v10";
+import type { NubisApi } from "./api";
+import type { Guard } from "./guard";
+import type { Middleware } from "./middleware";
+import type { ReplyInput } from "./reply";
+import type { SchemaInput, SchemaOutput, StandardSchemaV1 } from "./schema";
+import type { StateStore } from "./store";
+export type AnySchema = StandardSchemaV1<unknown, unknown>;
+/** A rendered modal, ready for `showModal()`. */
+export type ModalData = APIModalInteractionResponseCallbackData;
+/** State inside handlers: the schema's output, or `undefined` without one. */
+export type ComponentState<S> = [S] extends [undefined] ? undefined : SchemaOutput<S>;
+/** Arguments for rendering: state first when the component has a schema. */
+export type RenderArgs<S, O> = [S] extends [undefined] ? [overrides?: O] : [state: SchemaInput<S>, overrides?: O];
+export interface ComponentContext<State> {
+    readonly state: State;
+    /** The raw interaction from Discord, for anything Nubis doesn't cover yet. */
+    readonly interaction: APIMessageComponentInteraction;
+    /** Discord's API: act on what was clicked. */
+    readonly api: NubisApi;
+    /** Sends a new message. */
+    reply(message: ReplyInput): Promise<void>;
+    /** Edits the message the component is on. Call it before reply(). */
+    update(message: ReplyInput): Promise<void>;
+    /** Edits the first reply. */
+    editReply(message: ReplyInput): Promise<void>;
+    /** Shows "thinking…" and a reply to come. */
+    defer(options?: {
+        readonly ephemeral?: boolean;
+    }): Promise<void>;
+    /**
+     * Acknowledges the click without a message; update() can still edit later.
+     * Nubis does this on its own after two seconds.
+     */
+    deferUpdate(): Promise<void>;
+    /** Opens a modal. Must be the first response, so call it before reply(). */
+    showModal(modal: ModalData): Promise<void>;
+}
+/** The parts of a handler context that don't depend on the interaction type. */
+export interface HandlerBase {
+    readonly state: unknown;
+    readonly api: NubisApi;
+    reply(message: ReplyInput): Promise<void>;
+    update(message: ReplyInput): Promise<void>;
+    editReply(message: ReplyInput): Promise<void>;
+    defer(options?: {
+        readonly ephemeral?: boolean;
+    }): Promise<void>;
+    deferUpdate(): Promise<void>;
+    showModal(modal: ModalData): Promise<void>;
+}
+export type ComponentKind = "button" | "string-select" | "user-select" | "role-select" | "channel-select" | "mentionable-select" | "modal";
+/** What dispatch needs from any component or modal, whatever its state type. */
+export interface ComponentRuntime {
+    readonly kind: ComponentKind;
+    readonly id: string;
+    readonly schema: AnySchema | undefined;
+    /** Where state lives when it's kept outside the custom_id. */
+    readonly store: StateStore | undefined;
+    readonly guards: readonly Guard[];
+    readonly middleware: readonly Middleware[];
+    /** Returns false when the interaction doesn't fit (a stale message or form). */
+    handle(base: HandlerBase, interaction: APIMessageComponentInteraction | APIModalSubmitInteraction): Promise<boolean>;
+}
+export declare const RUNTIME = "~nubis";
+export interface WithRuntime {
+    readonly id: string;
+    readonly [RUNTIME]: ComponentRuntime;
+}
+/** Settings every interactive component shares. */
+interface InteractiveConfig<S extends AnySchema | undefined> {
+    /** Routes clicks to this component. Changing it makes ones already sent stop working. */
+    readonly id: string;
+    /** Validates the state that comes back with each interaction. */
+    readonly state?: S;
+    /**
+     * Keeps state here instead of in the custom_id, for state over Discord's
+     * 100 characters. The custom_id then only carries a key.
+     */
+    readonly store?: StateStore;
+    /**
+     * Checks before the handler. Anyone who can see a message can click its
+     * components, so use `invokerOnly` or a permission guard for anything that
+     * acts on someone's behalf.
+     */
+    readonly guards?: readonly Guard[];
+    readonly middleware?: readonly Middleware[];
+}
+/** "🔥", "<:party:123>", "<a:dance:456>", or Discord's emoji object. */
+export type EmojiInput = string | APIMessageComponentEmoji;
+export declare function toEmoji(input: EmojiInput): APIMessageComponentEmoji;
+declare const BUTTON_STYLES: {
+    readonly primary: ButtonStyle.Primary;
+    readonly secondary: ButtonStyle.Secondary;
+    readonly success: ButtonStyle.Success;
+    readonly danger: ButtonStyle.Danger;
+};
+export type ButtonStyleName = keyof typeof BUTTON_STYLES;
+export interface ButtonOverrides {
+    readonly label?: string;
+    readonly style?: ButtonStyleName;
+    readonly emoji?: EmojiInput;
+    readonly disabled?: boolean;
+}
+export interface ButtonConfig<S extends AnySchema | undefined> extends InteractiveConfig<S> {
+    readonly label: string;
+    readonly style?: ButtonStyleName;
+    readonly emoji?: EmojiInput;
+    onClick(context: ComponentContext<ComponentState<S>>): unknown;
+}
+export interface ButtonDefinition<S extends AnySchema | undefined> extends WithRuntime {
+    (...args: RenderArgs<S, ButtonOverrides>): APIButtonComponentWithCustomId;
+    readonly kind: "button";
+}
+export declare function button<S extends AnySchema | undefined = undefined>(config: ButtonConfig<S>): ButtonDefinition<S>;
+export interface LinkButtonConfig {
+    readonly url: string;
+    readonly label?: string;
+    readonly emoji?: EmojiInput;
+    readonly disabled?: boolean;
+}
+/**
+ * A button that opens a URL. It has no handler: Discord opens the link
+ * without telling the bot, so it needs no id and no registration.
+ */
+export declare function linkButton(config: LinkButtonConfig): APIButtonComponentWithURL;
+export interface SelectOption<V extends string = string> {
+    readonly label: string;
+    readonly value: V;
+    readonly description?: string;
+    readonly emoji?: EmojiInput;
+    readonly default?: boolean;
+}
+export interface StringSelectOverrides {
+    readonly placeholder?: string;
+    readonly disabled?: boolean;
+}
+export interface StringSelectConfig<O extends readonly SelectOption[], S extends AnySchema | undefined> extends InteractiveConfig<S> {
+    readonly options: O;
+    readonly placeholder?: string;
+    readonly minValues?: number;
+    readonly maxValues?: number;
+    onSelect(context: ComponentContext<ComponentState<S>> & {
+        /** The chosen values, typed from `options`. */
+        readonly values: O[number]["value"][];
+    }): unknown;
+}
+export interface StringSelectDefinition<O extends readonly SelectOption[], S extends AnySchema | undefined> extends WithRuntime {
+    (...args: RenderArgs<S, StringSelectOverrides>): APIStringSelectComponent;
+    readonly kind: "string-select";
+    readonly options: O;
+}
+export declare function stringSelect<const O extends readonly SelectOption[], S extends AnySchema | undefined = undefined>(config: StringSelectConfig<O, S>): StringSelectDefinition<O, S>;
+/** What each select hands its handler: Discord's resolved objects, not bare ids. */
+export interface UserSelection {
+    readonly users: APIUser[];
+    /** Server memberships by user id, when used in a server. */
+    readonly members: Readonly<Record<string, APIInteractionDataResolvedGuildMember | undefined>>;
+}
+export interface RoleSelection {
+    readonly roles: APIRole[];
+}
+export interface ChannelSelection {
+    readonly channels: APIInteractionDataResolvedChannel[];
+}
+export interface MentionableSelection {
+    readonly users: APIUser[];
+    readonly roles: APIRole[];
+}
+interface EntitySelectOverrides {
+    readonly placeholder?: string;
+    readonly disabled?: boolean;
+}
+export interface UserSelectOverrides extends EntitySelectOverrides {
+    /** Users selected when the menu appears. */
+    readonly defaultUsers?: readonly string[];
+}
+export interface RoleSelectOverrides extends EntitySelectOverrides {
+    readonly defaultRoles?: readonly string[];
+}
+export interface ChannelSelectOverrides extends EntitySelectOverrides {
+    readonly defaultChannels?: readonly string[];
+}
+export interface MentionableSelectOverrides extends EntitySelectOverrides {
+    readonly defaultUsers?: readonly string[];
+    readonly defaultRoles?: readonly string[];
+}
+interface EntitySelectConfig<S extends AnySchema | undefined, Selection> extends InteractiveConfig<S> {
+    readonly placeholder?: string;
+    readonly minValues?: number;
+    readonly maxValues?: number;
+    onSelect(context: ComponentContext<ComponentState<S>> & Selection): unknown;
+}
+export type UserSelectConfig<S extends AnySchema | undefined> = EntitySelectConfig<S, UserSelection>;
+export type RoleSelectConfig<S extends AnySchema | undefined> = EntitySelectConfig<S, RoleSelection>;
+export type MentionableSelectConfig<S extends AnySchema | undefined> = EntitySelectConfig<S, MentionableSelection>;
+export interface ChannelSelectConfig<S extends AnySchema | undefined> extends EntitySelectConfig<S, ChannelSelection> {
+    /** Only these channel types can be picked. */
+    readonly channelTypes?: readonly ChannelType[];
+}
+export interface EntitySelectDefinition<S extends AnySchema | undefined, Overrides, Rendered, Kind extends ComponentKind> extends WithRuntime {
+    (...args: RenderArgs<S, Overrides>): Rendered;
+    readonly kind: Kind;
+}
+/** Pick server members or users. The handler gets their user objects and memberships. */
+export declare function userSelect<S extends AnySchema | undefined = undefined>(config: UserSelectConfig<S>): EntitySelectDefinition<S, UserSelectOverrides, APIUserSelectComponent, "user-select">;
+/** Pick roles. */
+export declare function roleSelect<S extends AnySchema | undefined = undefined>(config: RoleSelectConfig<S>): EntitySelectDefinition<S, RoleSelectOverrides, APIRoleSelectComponent, "role-select">;
+/** Pick channels, optionally of certain types. */
+export declare function channelSelect<S extends AnySchema | undefined = undefined>(config: ChannelSelectConfig<S>): EntitySelectDefinition<S, ChannelSelectOverrides, APIChannelSelectComponent, "channel-select">;
+/** Pick users and roles in one menu. */
+export declare function mentionableSelect<S extends AnySchema | undefined = undefined>(config: MentionableSelectConfig<S>): EntitySelectDefinition<S, MentionableSelectOverrides, APIMentionableSelectComponent, "mentionable-select">;
+export type ComponentDefinition = WithRuntime;
+export {};

package/dist/custom-id.d.ts

@@ -0,0 +1,26 @@
+import { type StateStore } from "./store";
+export declare function assertValidComponentId(id: string): void;
+/** `confirm-ban~{"userId":"42"}`: the id routes the interaction, the JSON is the state. */
+export declare function encodeCustomId(id: string, state: unknown): string;
+/** `confirm-ban~$Kq3…`: the state lives in a StateStore under that key. */
+export declare function encodeStoredCustomId(id: string, key: string): string;
+/**
+ * The custom_id for a render: state inline as JSON, or with a store, saved
+ * under a fresh key. The write is tracked so replies wait for it.
+ */
+export declare function renderCustomId(id: string, state: unknown, store: StateStore | undefined): string;
+export type DecodedCustomId = {
+    readonly id: string;
+    readonly ok: true;
+    readonly state: unknown;
+}
+/** State is in a store under `key`. JSON never starts with "$", so this can't be mistaken for inline state. */
+ | {
+    readonly id: string;
+    readonly ok: true;
+    readonly key: string;
+} | {
+    readonly id: string;
+    readonly ok: false;
+};
+export declare function decodeCustomId(customId: string): DecodedCustomId;

package/dist/dispatch.d.ts

@@ -0,0 +1,59 @@
+import { type APIApplicationCommandInteractionDataBasicOption, type APIApplicationCommandInteractionDataOption, type APIChatInputApplicationCommandInteraction } from "discord-api-types/v10";
+import type { NubisApi } from "./api";
+import { type ErrorHandler } from "./errors";
+import { type Guard } from "./guard";
+import { type Middleware } from "./middleware";
+import { type Lifecycle, type Scheduler, type Transport } from "./lifecycle";
+import type { CommandLeaf, CommandParent, CommandTree } from "./tree";
+export interface DispatchOptions {
+    /** See LifecycleOptions.autoDeferMs. */
+    readonly autoDeferMs?: number | false;
+    readonly schedule?: Scheduler;
+    /** Run before every handler, before folder and command guards. */
+    readonly guards?: readonly Guard[];
+    /** Wraps every handler, outermost. */
+    readonly middleware?: readonly Middleware[];
+    /** Receives every error a handler throws, after the user is told. */
+    readonly onError?: ErrorHandler;
+    /** Discord's API client, handed to handlers as `api`. */
+    readonly api?: NubisApi;
+}
+export type DispatchResult = {
+    readonly status: "handled";
+    readonly path: readonly string[];
+    /** False when the handler finished without answering; Discord shows "did not respond". */
+    readonly responded: boolean;
+} | {
+    readonly status: "unknown";
+    readonly path: readonly string[];
+} | {
+    readonly status: "denied";
+    readonly path: readonly string[];
+    readonly message: string;
+} | {
+    readonly status: "error";
+    readonly path: readonly string[];
+    readonly error: unknown;
+};
+export declare const ERROR_MESSAGE = "Something went wrong. Please try again.";
+export declare const UNKNOWN_COMMAND_MESSAGE = "This command isn't available anymore. Discord may still be catching up.";
+/** Tells the user something broke, if the interaction can still be answered. */
+export declare function answerError(lifecycle: Lifecycle): Promise<void>;
+export interface Located {
+    readonly leaf: CommandLeaf | undefined;
+    /** Folders on the way to the leaf, outermost first. */
+    readonly parents: readonly CommandParent[];
+    readonly path: readonly string[];
+    readonly options: readonly APIApplicationCommandInteractionDataBasicOption[];
+}
+/** Finds the command an interaction's data points at, through subcommands and groups. */
+export declare function locate(tree: CommandTree, data: {
+    readonly name: string;
+    readonly options?: readonly APIApplicationCommandInteractionDataOption[];
+}): Located;
+/**
+ * Routes a slash command interaction to the command that handles it, and
+ * answers Discord on time: "thinking…" after two seconds of silence, follow-ups
+ * for later replies, and an error message if the handler throws.
+ */
+export declare function dispatch(tree: CommandTree, interaction: APIChatInputApplicationCommandInteraction, transport: Transport, options?: DispatchOptions): Promise<DispatchResult>;

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/** Thrown for mistakes in a bot's own definitions, with the file or command it came from. */
+export declare class NubisError extends Error {
+    readonly name = "NubisError";
+}
+/** Where a handler error happened, for logging and error trackers. */
+export interface ErrorInfo {
+    readonly kind: "command" | "menu" | "component" | "modal" | "autocomplete" | "event";
+    /** "/config set", a component id, a menu name, or an event name. */
+    readonly name: string;
+    /** The interaction, for everything but events. */
+    readonly interaction?: unknown;
+}
+/**
+ * Receives every error a handler throws, after the user has been told
+ * something went wrong. A good place for logging or Sentry.
+ */
+export type ErrorHandler = (error: unknown, info: ErrorInfo) => void;
+/** Calls the error handler without letting it break the dispatch. */
+export declare function reportError(onError: ErrorHandler | undefined, error: unknown, info: ErrorInfo): void;

package/dist/events.d.ts

@@ -0,0 +1,57 @@
+import type { GatewayDispatchPayload } from "discord-api-types/v10";
+import { type NubisApi } from "./api";
+import { type ErrorHandler } from "./errors";
+type DispatchData = {
+    [P in GatewayDispatchPayload as P["t"]]: P["d"];
+};
+type PascalTail<S extends string> = S extends `${infer Head}_${infer Rest}` ? `${Capitalize<Lowercase<Head>>}${PascalTail<Rest>}` : Capitalize<Lowercase<S>>;
+/** "GUILD_MEMBER_ADD" → "guildMemberAdd". */
+export type CamelCase<S extends string> = S extends `${infer Head}_${infer Rest}` ? `${Lowercase<Head>}${PascalTail<Rest>}` : Lowercase<S>;
+/** Gateway events by their Nubis name, with Discord's payload for each. */
+export type EventPayloads = {
+    [K in keyof DispatchData as CamelCase<K & string>]: DispatchData[K];
+};
+export type EventName = keyof EventPayloads;
+export interface EventContext {
+    readonly name: EventName;
+    /** The shard that received the event, when the transport shards. */
+    readonly shardId: number | undefined;
+    /** Discord's API, to act on the event. */
+    readonly api: NubisApi;
+}
+export interface EventDefinition<N extends EventName = EventName> {
+    readonly kind: "event";
+    readonly name: N;
+    readonly handler: (data: EventPayloads[N], context: EventContext) => unknown;
+}
+/** Discord's event name in Nubis form, the same conversion the types do. */
+export declare function toEventName(type: string): string;
+/**
+ * Runs `handler` for a gateway event, with Discord's payload typed:
+ *
+ *     event("guildMemberAdd", (member) => member.user.username)
+ */
+export declare function event<N extends EventName>(name: N, handler: (data: EventPayloads[N], context: EventContext) => unknown): EventDefinition<N>;
+/** Any one event's definition. A union, so each keeps its own payload type. */
+export type AnyEventDefinition = {
+    [N in EventName]: EventDefinition<N>;
+}[EventName];
+export type EventRegistry = ReadonlyMap<string, readonly AnyEventDefinition[]>;
+/** Groups handlers by event. Several handlers can listen to the same event. */
+export declare function createEventRegistry(events: readonly AnyEventDefinition[]): EventRegistry;
+export interface EventDispatchResult {
+    readonly name: string;
+    /** How many handlers ran to completion. */
+    readonly handled: number;
+    readonly errors: readonly unknown[];
+}
+/**
+ * Runs every handler for a gateway dispatch (`t` and `d` as Discord sends
+ * them). Handlers run concurrently; one throwing doesn't stop the others.
+ */
+export declare function dispatchEvent(registry: EventRegistry, type: string, data: unknown, options?: {
+    readonly shardId?: number;
+    readonly onError?: ErrorHandler;
+    readonly api?: NubisApi;
+}): Promise<EventDispatchResult>;
+export {};

package/dist/guard.d.ts

@@ -0,0 +1,62 @@
+import type { APIApplicationCommandAutocompleteInteraction, APIChatInputApplicationCommandInteraction, APIContextMenuInteraction, APIInteractionGuildMember, APIMessageComponentInteraction, APIModalSubmitInteraction, APIUser } from "discord-api-types/v10";
+import { type NubisApi } from "./api";
+export type GuardedInteraction = APIApplicationCommandAutocompleteInteraction | APIChatInputApplicationCommandInteraction | APIContextMenuInteraction | APIMessageComponentInteraction | APIModalSubmitInteraction;
+declare const DENIAL: unique symbol;
+/** Returned by `deny()`; tells Nubis to stop and answer with `message`. */
+export interface Denial {
+    readonly [DENIAL]: true;
+    readonly message: string;
+}
+export interface GuardContext {
+    readonly interaction: GuardedInteraction;
+    /** Discord's API, to look things up before deciding. */
+    readonly api: NubisApi;
+    /** Who used the command or component, in a server or in DMs. */
+    readonly user: APIUser;
+    /** The member, in a server; `undefined` in DMs. */
+    readonly member: APIInteractionGuildMember | undefined;
+    readonly guildId: string | undefined;
+    readonly channelId: string | undefined;
+    /** Stops here. The user sees `message`, only to them. */
+    deny(message: string): Denial;
+}
+export type GuardResult = Denial | undefined | void;
+/** A check that runs before a handler. Return `deny(...)` to stop, anything else to go on. */
+export type Guard = (context: GuardContext) => GuardResult | Promise<GuardResult>;
+/** Defines a guard. An identity function, for types and readability. */
+export declare function guard(check: Guard): Guard;
+export declare function isDenial(value: unknown): value is Denial;
+export declare function guardContext(interaction: GuardedInteraction, api?: NubisApi): GuardContext;
+/** Runs guards in order and returns the first denial, if any. */
+export declare function runGuards(guards: readonly Guard[], context: GuardContext): Promise<Denial | undefined>;
+/** Only in servers, not in DMs. */
+export declare const guildOnly: Guard;
+/**
+ * The member needs every one of these permissions (`PermissionFlagsBits` from
+ * discord-api-types). Unlike `defaultMemberPermissions`, server admins can't
+ * override this: it's checked when the command runs.
+ */
+export declare function hasPermission(...permissions: bigint[]): Guard;
+/** The bot needs these permissions in the channel, e.g. BanMembers before banning. */
+export declare function botHasPermission(...permissions: bigint[]): Guard;
+/** The member needs at least one of these roles. Pass ids, or a function that reads them (e.g. from config). */
+export declare function hasRole(...roles: (string | (() => string | undefined))[]): Guard;
+/**
+ * For components: only the person who ran the command that sent the message
+ * can use it. Without this, anyone who can see a public message can click it.
+ */
+export declare const invokerOnly: Guard;
+export interface CooldownOptions {
+    readonly seconds: number;
+    /** Whose uses count together. Defaults to "user". */
+    readonly per?: "user" | "member" | "channel" | "guild" | "global";
+    /** Milliseconds since the epoch. Swappable in tests. */
+    readonly now?: () => number;
+}
+/**
+ * Allows one use per `seconds`. Uses are counted when this guard passes, so
+ * put it after other guards: a denied permission check shouldn't use up a turn.
+ * Kept in memory, per process.
+ */
+export declare function cooldown(options: CooldownOptions): Guard;
+export {};