@seedcord/core 0.3.1 → 0.4.0

package/dist/Pluggable-DFNUIlJM.d.mts

@@ -0,0 +1,148 @@
+import { i as Bus, n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-F8yvPd60.mjs";
+import { a as PluginCtor, d as Transport, f as TransportAssert, i as PluginArgs, l as Runtime, o as PluginLike, s as ChannelKeyAssert, t as CoreParamAssert, u as RuntimeAssert } from "./Plugin-CG9pWbPF.mjs";
+import { Logger } from "@seedcord/logger";
+import { REST } from "@discordjs/rest";
+import { HostPluginKeys, HostShutdown, HostStartup } from "@seedcord/types/internal";
+import { Config, IRateLimiter } from "@seedcord/types";
+//#region src/node/Lifecycle/LifecycleTypes.d.ts
+interface LifecycleTask {
+  name: string;
+  task: () => Promise<void>;
+  timeout: number;
+}
+//#endregion
+//#region src/node/Lifecycle/CoordinatedLifecycle.d.ts
+declare abstract class CoordinatedLifecycle<TPhase extends number> {
+  protected readonly phaseOrder: TPhase[];
+  protected readonly phaseEnum: Record<number, string>;
+  protected readonly logger: Logger;
+  protected readonly tasksMap: Map<TPhase, LifecycleTask[]>;
+  protected constructor(loggerName: string, phaseOrder: TPhase[], phaseEnum: Record<number, string>);
+  addTask(phase: TPhase, taskName: string, task: () => Promise<void>, timeoutMs: number): void;
+  removeTask(phase: TPhase, taskName: string): boolean;
+  protected runPhase(phase: TPhase): Promise<void>;
+  protected runTaskWithTimeout(phase: TPhase, task: LifecycleTask): Promise<void>;
+  protected isAborted(): boolean;
+  protected abstract canAddTask(): boolean;
+  protected abstract canRemoveTask(): boolean;
+  protected abstract getTaskType(): string;
+  protected abstract executeTasksInPhase(phase: TPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+}
+//#endregion
+//#region src/node/Lifecycle/CoordinatedShutdown.d.ts
+declare class CoordinatedShutdown extends CoordinatedLifecycle<ShutdownPhase> {
+  private isShuttingDown;
+  private hasShutdown;
+  private exitCode;
+  private onSigTerm;
+  private onSigInt;
+  private startupGate?;
+  constructor();
+  protected canAddTask(): boolean;
+  protected canRemoveTask(): boolean;
+  protected getTaskType(): string;
+  protected executeTasksInPhase(phase: ShutdownPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+  private registerSignalHandlers;
+  /** @internal */
+  removeSignalHandlers(): void;
+  /** @internal run() awaits this so boot finishes registering its dispose tasks first */
+  gateOnStartup(settled: Promise<void>): void;
+  addTask(phase: ShutdownPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
+  /** @internal */
+  removeTask(phase: ShutdownPhase, taskName: string): boolean;
+  /** @internal */
+  run(exitCode?: number, exitProcess?: boolean): Promise<void>;
+}
+//#endregion
+//#region src/node/Lifecycle/CoordinatedStartup.d.ts
+declare class CoordinatedStartup extends CoordinatedLifecycle<StartupPhase> {
+  private isStartingUp;
+  private hasStarted;
+  constructor();
+  addTask(phase: StartupPhase, taskName: string, task: () => Promise<void>, timeoutMs?: number): void;
+  protected canAddTask(): boolean;
+  protected canRemoveTask(): boolean;
+  protected getTaskType(): string;
+  protected executeTasksInPhase(phase: StartupPhase, tasks: LifecycleTask[]): Promise<PromiseSettledResult<void>[]>;
+  /** @internal */
+  run(): Promise<void>;
+  protected isAborted(): boolean;
+  /** @internal */
+  abort(): void;
+  /** @internal */
+  get isReady(): boolean;
+}
+//#endregion
+//#region src/node/Pluggable.d.ts
+/**
+ * Base class for a plugin host, a transport `Seedcord` class.
+ *
+ * You attach plugins while configuring the bot. Within one startup phase, their `init()` calls run
+ * one after another in attach order.
+ */
+declare abstract class Pluggable<BotT extends Transport, BotRt extends Runtime> implements CoreBase {
+  abstract readonly config: Config;
+  abstract readonly rest: REST;
+  abstract readonly applicationId: string;
+  abstract readonly rateLimiter: IRateLimiter;
+  abstract readonly bus: Bus;
+  /** @internal */
+  readonly [HostShutdown]: CoordinatedShutdown;
+  /** @internal */
+  readonly [HostStartup]: CoordinatedStartup;
+  /** Add a task that runs while the bot shuts down. */
+  readonly shutdown: Pick<CoordinatedShutdown, 'addTask'>;
+  /** Add a task that runs while the bot starts. */
+  readonly startup: Pick<CoordinatedStartup, 'addTask'>;
+  protected isInitialized: boolean;
+  protected startFailed: boolean;
+  protected readonly plugins: PluginLike[];
+  private readonly pluginLogger;
+  private readonly attachments;
+  private readonly completedInits;
+  private readonly disposePhases;
+  private pluginTasksRegistered;
+  private initPromise?;
+  private static isInstantiated;
+  private static liveHost?;
+  private static liveShutdown?;
+  private static liveProcessErrors?;
+  constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup);
+  /** @internal */
+  protected init(): Promise<this>;
+  private runInit;
+  /** @internal codegen reads this to emit the `Core` augmentation */
+  get [HostPluginKeys](): readonly string[];
+  /** @internal */
+  protected static reset(host?: object): boolean;
+  /**
+   * Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`
+   * writes the `Core` augmentation that types it there.
+   *
+   * Startup runs each plugin's `init()` in attach order within its phase.
+   *
+   * Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.
+   * Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).
+   * A narrower one fails to compile here.
+   *
+   * @param key - Also the channel the plugin logs on. Reserved channel names throw.
+   * @param args - Whatever your constructor takes after the host.
+   * @throws A **SeedcordError** if you attach after the bot has started. A taken or reserved key throws too.
+   * @example
+   * ```ts
+   * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });
+   * ```
+   */
+  attach<Key extends string, Ctor extends PluginCtor>(this: this, key: ChannelKeyAssert<Key>, Plugin: Ctor & TransportAssert<InstanceType<Ctor>, BotT> & RuntimeAssert<InstanceType<Ctor>, BotRt> & CoreParamAssert<Ctor>, ...args: PluginArgs<Ctor>): this & Record<Key, InstanceType<Ctor>>;
+  private registerPluginTasks;
+  private runInits;
+  private registerReadyTask;
+  private registerDisposeTask;
+  private runDisposals;
+  private disposeCompleted;
+  private rollback;
+}
+declare function shutdownOf(host: Pick<Pluggable<Transport, Runtime>, typeof HostShutdown>): CoordinatedShutdown;
+//#endregion
+export { LifecycleTask as a, CoordinatedShutdown as i, shutdownOf as n, CoordinatedStartup as r, Pluggable as t };
+//# sourceMappingURL=Pluggable-DFNUIlJM.d.mts.map

package/dist/{Plugin-D9ykXA5g.mjs → Plugin-C6oMqWf8.mjs}

@@ -2,7 +2,7 @@ import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
 import { t as getDevChannel } from "./devChannel-CQU7hq7Q.mjs";
 import { SeedcordErrorCode } from "@seedcord/errors";
 import { Logger } from "@seedcord/logger";
-import { SeedcordError } from "@seedcord/errors/internal";
+import { SeedcordError, SeedcordRangeError } from "@seedcord/errors/internal";
 
 //#region src/plugin/lifecycle.ts
 const DEFAULT_INIT_TIMEOUT_MS = 15e3;
@@ -10,7 +10,11 @@ const DEFAULT_READY_TIMEOUT_MS = 15e3;
 const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
 function timeoutOf(field, declared, fallback, pluginName) {
 	if (declared === void 0) return fallback;
-	if (!Number.isFinite(declared) || declared <= 0) throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [pluginName, `lifecycle ${field}.timeout must be a positive number of milliseconds`]);
+	if (!Number.isFinite(declared) || declared <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PluginInvalidLifecycleTimeout, [
+		pluginName,
+		field,
+		declared
+	]);
 	return declared;
 }
 /** @internal */
@@ -111,4 +115,4 @@ function pluginLoggerOf(plugin) {
 
 //#endregion
 export { pluginLoggerOf as n, resolvedLifecycleSpecOf as r, Plugin as t };
-//# sourceMappingURL=Plugin-D9ykXA5g.mjs.map
+//# sourceMappingURL=Plugin-C6oMqWf8.mjs.map

package/dist/Plugin-C6oMqWf8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-C6oMqWf8.mjs","names":[],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '#src/lifecycle/phases';\n\n/**\n * Sets when a plugin's lifecycle methods run. Pass it as the second argument to `super()`. Omit a\n * field to keep its default.\n *\n * @see {@link StartupPhase}\n * @see {@link ShutdownPhase}\n * @example\n * ```ts\n * super(host, { init: { phase: StartupPhase.Login }, dispose: { timeout: 30_000 } });\n * ```\n */\nexport interface PluginLifecycleSpec {\n    /**\n     * Defaults to `StartupPhase.Configuration` and 15000ms. Set the phase to `Ready` and `init()`\n     * runs ahead of every plugin's `ready()`.\n     */\n    init?: { phase?: StartupPhase; timeout?: number };\n    /** `ready()` always runs in `StartupPhase.Ready`. Defaults to a 15000ms timeout. */\n    ready?: { timeout?: number };\n    /** Defaults to `ShutdownPhase.Disconnect` and 10000ms. */\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.PluginInvalidLifecycleTimeout, [pluginName, field, declared]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '#hmr/devChannel';\n\nimport { RuntimeBrand, TransportBrand } from './brands';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, PluginOptions, RuntimeOf } from './options';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n/** @internal */\nconst loggerSlot = Symbol('seedcord.plugin.logger');\n\n/**\n * Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running\n * bot.\n *\n * Your constructor takes the host first and passes it to `super()`. Add your own parameters after\n * it. `attach()` types them at the call site.\n *\n * @typeParam Opts - Where this plugin may attach, checked only at compile time.\n * @typeParam TCore - The `Core` each transport binds `this.core` to.\n *\n * @example\n * ```ts\n * class Analytics extends Plugin<{ transport: 'gateway' }> {\n *     constructor(\n *         host: CoreBase,\n *         private readonly apiKey: string\n *     ) {\n *         super(host, { init: { phase: StartupPhase.Login } });\n *     }\n *\n *     public async init(): Promise<void> {\n *         await this.connect(this.apiKey);\n *     }\n * }\n *\n * seedcord.attach('analytics', Analytics, apiKey);\n * ```\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    // phantom, never set at runtime.\n    /** @internal */\n    declare readonly [TransportBrand]?: TransportOf<Opts>;\n    /** @internal */\n    declare readonly [RuntimeBrand]?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    readonly [loggerSlot]: Logger;\n\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\n    protected readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[loggerSlot] = this.logger;\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /**\n     * Runs in `StartupPhase.Configuration` by default.\n     * Move it to a different phase with the {@link PluginLifecycleSpec}.\n     */\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the Ready phase, after every attached plugin's `init()` has resolved. The other Ready\n     * tasks run alongside it, including the http server binding its port.\n     *\n     * Override it when your work needs a logged-in client or a resolved application id.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, in `ShutdownPhase.Disconnect` by default. It never runs when `init()` has thrown. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Throws a `SeedcordError` that contains the plugin class name and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\n/** @internal */\nexport function pluginLoggerOf(plugin: PluginLike): Logger {\n    return plugin[loggerSlot];\n}\n\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\n/** @internal */\nexport type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n"],"mappings":";;;;;;;AAmCA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAI,mBAAmB,kBAAkB,+BAA+B;EAAC;EAAY;EAAO;CAAQ,CAAC;CAE/G,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;ACnDA,MAAM,mBAAmB,OAAO,sBAAsB;;AAEtD,MAAM,aAAa,OAAO,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BlD,IAAsB,SAAtB,MAEA;CAiByB;;CATrB,CAAU;;CAEV,CAAU;;CAGV,AAAmB;CAGnB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAI,OAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,cAAc,KAAK;EACxB,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;;;;;CAwBA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAI,cAAc,kBAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,cAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB;;AAGA,SAAgB,eAAe,QAA4B;CACvD,OAAO,OAAO;AAClB"}

package/dist/{Plugin-CQ9IEj5X.d.mts → Plugin-CG9pWbPF.d.mts}

@@ -1,4 +1,4 @@
-import { n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-hBxMCD2V.mjs";
+import { n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-F8yvPd60.mjs";
 import { Logger } from "@seedcord/logger";
 import { FrameworkChannel, HmrAware, HmrUpdateEvent, Tail, TypedExclude } from "@seedcord/types";
 //#region src/plugin/brands.d.ts
@@ -190,4 +190,4 @@ type CoreParamTooNarrow = Record<'this plugin constructor must take CoreBase as
 type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0] ? unknown : CoreParamTooNarrow;
 //#endregion
 export { PluginCtor as a, PluginOptions as c, Transport as d, TransportAssert as f, PluginArgs as i, Runtime as l, Initializeable as n, PluginLike as o, PluginLifecycleSpec as p, Plugin as r, ChannelKeyAssert as s, CoreParamAssert as t, RuntimeAssert as u };
-//# sourceMappingURL=Plugin-CQ9IEj5X.d.mts.map
+//# sourceMappingURL=Plugin-CG9pWbPF.d.mts.map

package/dist/{cursor-BANzac53.d.mts → cursor-BcRfmTSo.d.mts}

@@ -1,9 +1,9 @@
 import { t as Constructor } from "./basic-Dng__Ena.mjs";
-import { g as ReplyTelemetry, h as Notice, k as InteractionRoutes, r as CoreBase, v as AckState } from "./phases-hBxMCD2V.mjs";
+import { b as Notice, r as CoreBase, z as InteractionRoutes } from "./phases-F8yvPd60.mjs";
 import "reflect-metadata";
 import { ActionRowBuilder, ButtonBuilder, ChannelSelectMenuBuilder, CheckboxBuilder, CheckboxGroupBuilder, CheckboxGroupOptionBuilder, ContainerBuilder, ContextMenuCommandBuilder, EmbedBuilder, FileBuilder, FileUploadBuilder, LabelBuilder, MediaGalleryBuilder, MentionableSelectMenuBuilder, ModalBuilder, RadioGroupBuilder, RadioGroupOptionBuilder, RoleSelectMenuBuilder, SectionBuilder, SeparatorBuilder, SlashCommandBuilder, SlashCommandSubcommandBuilder, SlashCommandSubcommandGroupBuilder, StringSelectMenuBuilder, StringSelectMenuOptionBuilder, TextDisplayBuilder, TextInputBuilder, UserSelectMenuBuilder } from "@discordjs/builders";
-import { APIMessageTopLevelComponent, APIModalInteractionResponseCallbackData, ApplicationCommandType, ChannelType, Snowflake } from "discord-api-types/v10";
-import { DeferOpts, ReplyResponse, SendOpts } from "@seedcord/types";
+import { APIMessageTopLevelComponent, ApplicationCommandType, ChannelType, Snowflake } from "discord-api-types/v10";
+import { ReplyResponse } from "@seedcord/types";
 //#region src/registries/ContextMenuRegistry.d.ts
 /** The two context-menu command kinds Discord defines. */
 type ContextMenuKind = ApplicationCommandType.User | ApplicationCommandType.Message;
@@ -363,6 +363,8 @@ interface CustomIdField<Decoded> {
   readonly max?: number;
   /** The allowed values, for a oneOf field. */
   readonly choices?: readonly string[];
+  /** Whether this field also carries null. */
+  readonly nullable?: boolean;
   /** Phantom only, carries the decoded type and is never set at runtime. */
   readonly decoded?: Decoded;
 }
@@ -380,6 +382,16 @@ type CustomIdShape = Record<string, CustomIdField<unknown>>;
 type DecodedParams<Shape extends CustomIdShape> = { [Name in keyof Shape]: Shape[Name] extends CustomIdField<infer Decoded> ? Decoded : never; };
 //#endregion
 //#region src/customId/CustomId.d.ts
+/** Per-field options every {@link CustomId} chain method takes. */
+interface FieldOptions<Nullable extends boolean = boolean> {
+  /**
+   * Whether the field also carries null. A nullable field costs one extra slot on the wire.
+   *
+   * @defaultValue `false`
+   */
+  nullable?: Nullable;
+}
+type Nullish<Decoded, Nullable extends boolean> = Nullable extends true ? Decoded | null : Decoded;
 /** Strip the layout hash off the routeKey to recover the stable prefix the controller routes by. @internal */
 declare function prefixOf(wire: string): string;
 /**
@@ -421,7 +433,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('ban').snowflake('userId');
    * ```
    */
-  snowflake<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<Snowflake>>>;
+  snowflake<Name extends string, const Nullable extends boolean = false>(name: Name, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<Snowflake, Nullable>>>>;
   /**
    * Add a UUID field, decoded as a lowercase uuid string.
    *
@@ -430,7 +442,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('ticket').uuid('ticketId');
    * ```
    */
-  uuid<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
+  uuid<Name extends string, const Nullable extends boolean = false>(name: Name, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<string, Nullable>>>>;
   /**
    * Add an integer field with no bounds, for a value up to 2^53.
    *
@@ -439,7 +451,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('shop').int('amount');
    * ```
    */
-  int<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  int<Name extends string, const Nullable extends boolean = false>(name: Name, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<number, Nullable>>>>;
   /**
    * Add an integer field bounded by min and max, so it packs into fewer characters on the wire.
    *
@@ -448,7 +460,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('paginate').int('page', 1, 50);
    * ```
    */
-  int<Name extends string>(name: Name, min: number, max: number): CustomId<Prefix, Shape & Record<Name, CustomIdField<number>>>;
+  int<Name extends string, const Nullable extends boolean = false>(name: Name, min: number, max: number, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<number, Nullable>>>>;
   /**
    * Add a boolean flag.
    *
@@ -457,7 +469,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('settings').bool('silent');
    * ```
    */
-  bool<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<boolean>>>;
+  bool<Name extends string, const Nullable extends boolean = false>(name: Name, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<boolean, Nullable>>>>;
   /**
    * Add a field that is one value from a fixed list, decoded as the literal union. No `as const` needed.
    *
@@ -466,7 +478,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('poll').oneOf('choice', ['yes', 'no', 'abstain']);
    * ```
    */
-  oneOf<Name extends string, const Choices extends NonEmptyTuple<string>>(name: Name, choices: Choices): CustomId<Prefix, Shape & Record<Name, CustomIdField<Choices[number]>>>;
+  oneOf<Name extends string, const Choices extends NonEmptyTuple<string>, const Nullable extends boolean = false>(name: Name, choices: Choices, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<Choices[number], Nullable>>>>;
   /**
    * Add a free short text field. Avoid it where possible. It cannot be packed, which makes it the most
    * expensive field on the wire.
@@ -476,7 +488,7 @@ declare class CustomId<Prefix extends string, Shape extends CustomIdShape = {}>
    * new CustomId('note').str('message');
    * ```
    */
-  str<Name extends string>(name: Name): CustomId<Prefix, Shape & Record<Name, CustomIdField<string>>>;
+  str<Name extends string, const Nullable extends boolean = false>(name: Name, opts?: FieldOptions<Nullable>): CustomId<Prefix, Shape & Record<Name, CustomIdField<Nullish<string, Nullable>>>>;
   /**
    * Mint a wire string from values. Throws if a value is out of its field's range or the wire is over 100 chars.
    *
@@ -548,65 +560,6 @@ interface SerializedReply<TNative = never> {
 }
 declare function serializeReply<TNative>(response: ReplyResponse<TNative> | string, routeId: string): SerializedReply<TNative>;
 //#endregion
-//#region src/reply/BaseReplySender.d.ts
-/** The shape djs modal builders emit from `toJSON()`. */
-interface ModalLike {
-  toJSON(): APIModalInteractionResponseCallbackData;
-}
-/**
- * Tracks acknowledgement state and throws a translated `SeedcordError` on an illegal verb before any
- * transport call. Every verb runs the legality check, calls the transport's wire writer, then updates
- * the state and the ack trace. Each transport binds `TMessage` to its own created-message type and
- * supplies the writers.
- */
-declare abstract class BaseReplySender<TMessage extends {
-  id: string;
-}, TNative = never> {
-  protected readonly routeId: string;
-  private readonly telemetry;
-  private state;
-  private readonly sent;
-  private ackedBy?;
-  protected constructor(routeId: string, telemetry: ReplyTelemetry, initialState?: AckState);
-  private report;
-  private attempt;
-  reply(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage>;
-  defer(opts?: DeferOpts): Promise<void>;
-  deferUpdate(): Promise<void>;
-  /**
-   * After a deferUpdate the state stays deferred-update. Calling this again rewrites. The returned message
-   * is the source message, editable only through a bare `update` or `edit`. A targeted `edit` or `delete`
-   * of it throws the foreign-target error.
-   */
-  update(response: ReplyResponse<TNative> | string): Promise<TMessage>;
-  followUp(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage>;
-  edit(response: ReplyResponse<TNative> | string): Promise<TMessage>;
-  edit(target: TMessage, response: ReplyResponse<TNative> | string): Promise<TMessage>;
-  delete(): Promise<void>;
-  delete(target: TMessage): Promise<void>;
-  /** Routes to the verb the current ack state permits. Every state has a route, so the illegal-ack throw is unreachable. */
-  send(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage>;
-  /** Must be the initial response. */
-  showModal(modal: ModalLike): Promise<void>;
-  protected serialize(response: ReplyResponse<TNative> | string): SerializedReply<TNative>;
-  protected remember(created: TMessage): TMessage;
-  private requireMessage;
-  private editOriginal;
-  private checkLegality;
-  private transition;
-  protected guardModalSource(): void;
-  protected abstract writeReply(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage | undefined>;
-  protected abstract writeDefer(opts?: DeferOpts): Promise<void>;
-  protected abstract writeDeferUpdate(): Promise<void>;
-  protected abstract writeUpdate(response: ReplyResponse<TNative> | string): Promise<TMessage | undefined>;
-  protected abstract writeFollowUp(response: ReplyResponse<TNative> | string, opts?: SendOpts): Promise<TMessage>;
-  protected abstract writeEditOriginal(response: ReplyResponse<TNative> | string): Promise<TMessage>;
-  protected abstract writeEditTarget(targetId: string, response: ReplyResponse<TNative> | string): Promise<TMessage>;
-  protected abstract writeDeleteOriginal(): Promise<void>;
-  protected abstract writeDeleteTarget(targetId: string): Promise<void>;
-  protected abstract writeModal(data: APIModalInteractionResponseCallbackData): Promise<void>;
-}
-//#endregion
 //#region src/gates/Gate.d.ts
 /**
  * The transport-agnostic gate context, the scalar identity of the acting user resolvable from any
@@ -821,7 +774,8 @@ type RequiredOf<TGate> = TGate extends Gate<infer Ctx> ? Ctx : never;
 type IntersectRequired<Gates extends readonly Gate<GateContextBase>[]> = Gates extends readonly [infer First extends Gate<GateContextBase>, ...infer Rest extends readonly Gate<GateContextBase>[]] ? RequiredOf<First> & IntersectRequired<Rest> : unknown;
 type TwoOrMore<Item> = readonly [Item, Item, ...Item[]];
 type GateName<TGate> = TGate extends Gate<GateContextBase, infer Name> ? Name : string;
-type JoinNames<Gates extends readonly Gate<GateContextBase>[], Sep extends string> = Gates extends readonly [infer Only extends Gate<GateContextBase>] ? GateName<Only> : Gates extends readonly [infer First extends Gate<GateContextBase>, ...infer Rest extends readonly Gate<GateContextBase>[]] ? `${GateName<First>}${Sep}${JoinNames<Rest, Sep>}` : string;
+type Grouped<Name extends string> = Name extends `${string} & ${string}` | `${string} | ${string}` ? `(${Name})` : Name;
+type JoinNames<Gates extends readonly Gate<GateContextBase>[], Sep extends string> = Gates extends readonly [infer Only extends Gate<GateContextBase>] ? Grouped<GateName<Only>> : Gates extends readonly [infer First extends Gate<GateContextBase>, ...infer Rest extends readonly Gate<GateContextBase>[]] ? `${Grouped<GateName<First>>}${Sep}${JoinNames<Rest, Sep>}` : string;
 type GateMismatch<Name extends string, Want extends string, Got extends string> = `gate '${Name}' requires a ${Want} handler, and this handler is ${Got}`;
 type GateFitsWith<Provided, ProvidedLabel extends string, TGate, ReqLabel extends string> = [Provided] extends [RequiredOf<TGate>] ? TGate : Constructor<[GateMismatch<GateName<TGate>, ReqLabel, ProvidedLabel>]>;
 //#endregion
@@ -1029,5 +983,5 @@ type PageCursor<Prefix extends string> = CustomId<Prefix, {
 /** Build the page cursor for a paginator. */
 declare function pageCursor<Prefix extends string>(prefix: Prefix): PageCursor<Prefix>;
 //#endregion
-export { RegisterCommand as $, ModalLike as A, SelectMenuKind as B, Gate as C, defineEffectGate as D, RequiredOf as E, ComponentKindBrand as F, storeComponentRoute as G, contextMenuRouteOf as H, ContextMenuKindBrand as I, CustomId as J, storeInteractionRoute as K, ContextMenuNamesBrand as L, serializeReply as M, AutocompleteRouteBrand as N, defineGate as O, ComponentDefsBrand as P, CommandMeta as Q, SlashRouteBrand as R, EffectGate as S, GuildPermissionsContext as T, interactionRoutesOf as U, areRoutes as V, selectMenuRouteOf as W, prefixOf as X, decodeFor as Y, DecodedParams as Z, pickNotice as _, AutocompleteOptions as a, RowType as at, JoinNames as b, FocusedField as c, RouteCache as ct, RequirePermissionsOptions as d, SlashRouteEntry as dt, Promisable as et, RequireRole as f, ContextMenuKind as ft, GateNoticeOptions as g, UserContextMenuRegistry as gt, PermissionScope as h, NamesFor as ht, AutocompletableNames as i, BuilderType as it, SerializedReply as j, BaseReplySender as k, RequireBotPermissions as l, SlashOption as lt, PermissionNames as m, MessageContextMenuRegistry as mt, PageCursor as n, BuilderComponent as nt, ChoiceValueOf as o, CacheFor as ot, RequireRoleOptions as p, MenuCacheFor as pt, AnyCustomId as q, pageCursor as r, RowComponent as rt, EntryFor as s, OptionKind as st, PAGE_MAX as t, IsNever as tt, RequirePermissions as u, SlashRegistry as ut, GateFitsWith as v, GateContextBase as w, TwoOrMore as x, IntersectRequired as y, RoutableConstructor as z };
-//# sourceMappingURL=cursor-BANzac53.d.mts.map
+export { Promisable as $, serializeReply as A, contextMenuRouteOf as B, Gate as C, defineEffectGate as D, RequiredOf as E, ContextMenuNamesBrand as F, AnyCustomId as G, selectMenuRouteOf as H, SlashRouteBrand as I, decodeFor as J, CustomId as K, RoutableConstructor as L, ComponentDefsBrand as M, ComponentKindBrand as N, defineGate as O, ContextMenuKindBrand as P, RegisterCommand as Q, SelectMenuKind as R, EffectGate as S, GuildPermissionsContext as T, storeComponentRoute as U, interactionRoutesOf as V, storeInteractionRoute as W, DecodedParams as X, prefixOf as Y, CommandMeta as Z, pickNotice as _, AutocompleteOptions as a, CacheFor as at, JoinNames as b, FocusedField as c, SlashOption as ct, RequirePermissionsOptions as d, ContextMenuKind as dt, IsNever as et, RequireRole as f, MenuCacheFor as ft, GateNoticeOptions as g, PermissionScope as h, UserContextMenuRegistry as ht, AutocompletableNames as i, RowType as it, AutocompleteRouteBrand as j, SerializedReply as k, RequireBotPermissions as l, SlashRegistry as lt, PermissionNames as m, NamesFor as mt, PageCursor as n, RowComponent as nt, ChoiceValueOf as o, OptionKind as ot, RequireRoleOptions as p, MessageContextMenuRegistry as pt, FieldOptions as q, pageCursor as r, BuilderType as rt, EntryFor as s, RouteCache as st, PAGE_MAX as t, BuilderComponent as tt, RequirePermissions as u, SlashRouteEntry as ut, GateFitsWith as v, GateContextBase as w, TwoOrMore as x, IntersectRequired as y, areRoutes as z };
+//# sourceMappingURL=cursor-BcRfmTSo.d.mts.map