@azurioh/discord-kernel 0.1.0

package/dist/datetime.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zonedWallClockToUtc = zonedWallClockToUtc;
+exports.isValidWallClock = isValidWallClock;
+exports.dayString = dayString;
+exports.startOfGuildDay = startOfGuildDay;
+exports.endOfGuildDay = endOfGuildDay;
+exports.startOfNextGuildWeek = startOfNextGuildWeek;
+exports.addGuildDays = addGuildDays;
+/**
+ * Wall-clock datetime input grammar: `YYYY-MM-DD` with an optional
+ * ` HH:MM` / `THH:MM` time (seconds optional). Matches the format documented to
+ * users in the slash-command options.
+ */
+const WALL_CLOCK_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+function parseWallClock(input) {
+    const match = WALL_CLOCK_PATTERN.exec(input.trim());
+    if (!match) {
+        return null;
+    }
+    const [, year, month, day, hour, minute, second] = match;
+    const wallClock = {
+        year: Number(year),
+        month: Number(month),
+        day: Number(day),
+        hour: hour ? Number(hour) : 0,
+        minute: minute ? Number(minute) : 0,
+        second: second ? Number(second) : 0,
+    };
+    return isRealCalendarInstant(wallClock) ? wallClock : null;
+}
+/**
+ * Reject impossible values the regex alone allows (month 13, day 32, hour 25)
+ * by round-tripping through `Date.UTC` and checking nothing overflowed.
+ */
+function isRealCalendarInstant(wallClock) {
+    const date = new Date(Date.UTC(wallClock.year, wallClock.month - 1, wallClock.day, wallClock.hour, wallClock.minute, wallClock.second));
+    return (date.getUTCFullYear() === wallClock.year &&
+        date.getUTCMonth() === wallClock.month - 1 &&
+        date.getUTCDate() === wallClock.day &&
+        date.getUTCHours() === wallClock.hour &&
+        date.getUTCMinutes() === wallClock.minute &&
+        date.getUTCSeconds() === wallClock.second);
+}
+/**
+ * Offset, in milliseconds, between the given instant and how that instant reads
+ * as a wall clock in `timeZone` (positive when the zone is ahead of UTC).
+ */
+function timeZoneOffsetMs(timestamp, timeZone) {
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    const parts = new Map();
+    for (const { type, value } of formatter.formatToParts(new Date(timestamp))) {
+        if (type !== "literal") {
+            parts.set(type, Number(value));
+        }
+    }
+    const read = (key) => {
+        const value = parts.get(key);
+        if (value === undefined) {
+            throw new RangeError(`Missing "${key}" in formatted parts for time zone "${timeZone}"`);
+        }
+        return value;
+    };
+    const asUtc = Date.UTC(read("year"), read("month") - 1, read("day"), read("hour"), read("minute"), read("second"));
+    return asUtc - timestamp;
+}
+/**
+ * Interpret a wall-clock datetime string as local time in `timeZone` and return
+ * the matching UTC instant. Discord renders stored timestamps in each viewer's
+ * own timezone, so an event entered as "18:00" guild-local must be stored as the
+ * equivalent UTC instant — otherwise it drifts by the guild's UTC offset.
+ * @throws RangeError When the input does not match the wall-clock grammar.
+ */
+function zonedWallClockToUtc(input, timeZone) {
+    const wallClock = parseWallClock(input);
+    if (!wallClock) {
+        throw new RangeError(`Invalid wall-clock datetime: "${input}"`);
+    }
+    const utcGuess = Date.UTC(wallClock.year, wallClock.month - 1, wallClock.day, wallClock.hour, wallClock.minute, wallClock.second);
+    // Two passes: the offset read at `utcGuess` can be wrong across a DST
+    // transition (the guessed instant may land on the far side of the boundary
+    // from the target). Re-reading the offset at the first candidate pins the
+    // correct one for every time except the ~1h/year that either does not exist
+    // (spring-forward gap) or is ambiguous (fall-back overlap), which resolve
+    // deterministically to one side.
+    const firstOffset = timeZoneOffsetMs(utcGuess, timeZone);
+    const secondOffset = timeZoneOffsetMs(utcGuess - firstOffset, timeZone);
+    return new Date(utcGuess - secondOffset);
+}
+/** Whether `input` is a valid wall-clock datetime string. */
+function isValidWallClock(input) {
+    return parseWallClock(input) !== null;
+}
+/** `YYYY-MM-DD` of a date-only value, read in UTC (matches `Date`-only options). */
+function dayString(date) {
+    return date.toISOString().slice(0, 10);
+}
+/** Start of `date`'s calendar day (00:00:00) anchored to `timeZone`. */
+function startOfGuildDay(date, timeZone) {
+    return zonedWallClockToUtc(`${dayString(date)} 00:00:00`, timeZone);
+}
+/** End of `date`'s calendar day (23:59:59) anchored to `timeZone`. */
+function endOfGuildDay(date, timeZone) {
+    return zonedWallClockToUtc(`${dayString(date)} 23:59:59`, timeZone);
+}
+/**
+ * Monday 00:00 (guild-local) of the week following `reference`'s week. Used to
+ * anchor "next week"/"week after next" ranges to the guild's own calendar
+ * rather than to UTC day boundaries, which can disagree with the guild's local
+ * week near midnight around the timezone offset.
+ */
+function startOfNextGuildWeek(reference, timeZone) {
+    // Both the weekday *and* the calendar date must be read in `timeZone`, not
+    // UTC: near midnight, the guild-local day can already differ from the UTC
+    // day, and mixing the two would misplace the coming Monday by a day.
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        weekday: "short",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    });
+    const weekdayIndex = {
+        Sun: 0,
+        Mon: 1,
+        Tue: 2,
+        Wed: 3,
+        Thu: 4,
+        Fri: 5,
+        Sat: 6,
+    };
+    const parts = new Map();
+    for (const { type, value } of formatter.formatToParts(reference)) {
+        if (type !== "literal") {
+            parts.set(type, value);
+        }
+    }
+    const currentDay = weekdayIndex[parts.get("weekday") ?? ""] ?? 0;
+    // ISO week starts on Monday: ahead-days is 0 only when already Monday and we
+    // still want *next* week's Monday, hence the `=== 1 ? 7` special-case.
+    const daysUntilNextMonday = currentDay === 1 ? 7 : (8 - currentDay) % 7;
+    // Advance the *calendar date* (a pure Y-M-D operation, DST-agnostic) before
+    // re-anchoring to the timezone — advancing the UTC instant instead would
+    // drift by an hour across a DST transition inside the date range.
+    const year = Number(parts.get("year"));
+    const month = Number(parts.get("month"));
+    const day = Number(parts.get("day"));
+    const nextMondayUtcCalendarDay = new Date(Date.UTC(year, month - 1, day + daysUntilNextMonday));
+    return startOfGuildDay(nextMondayUtcCalendarDay, timeZone);
+}
+/**
+ * Add `days` guild-local calendar days to `instant`, re-anchoring to
+ * `timeZone`'s midnight. `instant` is assumed to already be a guild-local
+ * midnight (e.g. the result of {@link startOfGuildDay} or
+ * {@link startOfNextGuildWeek}); adding a fixed millisecond offset instead
+ * would drift by the DST delta whenever the interval crosses a transition —
+ * this reads the calendar date in `timeZone` first, so the result is always
+ * that timezone's actual midnight `days` later.
+ */
+function addGuildDays(instant, days, timeZone) {
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    });
+    const parts = new Map();
+    for (const { type, value } of formatter.formatToParts(instant)) {
+        if (type !== "literal") {
+            parts.set(type, value);
+        }
+    }
+    const year = Number(parts.get("year"));
+    const month = Number(parts.get("month"));
+    const day = Number(parts.get("day"));
+    const shiftedUtcCalendarDay = new Date(Date.UTC(year, month - 1, day + days));
+    return startOfGuildDay(shiftedUtcCalendarDay, timeZone);
+}
+//# sourceMappingURL=datetime.js.map

package/dist/datetime.js.map

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

package/dist/discord/api-errors.d.ts

@@ -0,0 +1,20 @@
+import { DiscordAPIError } from "discord.js";
+/**
+ * Narrow an unknown rejection to a Discord REST error. Adapters catch `unknown`,
+ * so every predicate below starts here rather than trusting a `code` property
+ * that any object could carry.
+ */
+export declare function isDiscordAPIError(error: unknown): error is DiscordAPIError;
+/**
+ * The targeted guild/channel/member/message/interaction is gone. Treat as a
+ * benign outcome: drop the stale reference instead of logging an incident.
+ */
+export declare function isUnknownResource(error: unknown): boolean;
+/**
+ * The bot lacks a permission or access to the resource. Actionable by a server
+ * admin, so it deserves a clear message rather than a generic incident.
+ */
+export declare function isMissingAccess(error: unknown): boolean;
+/** Discord is throttling us: back off and retry rather than surface a failure. */
+export declare function isRateLimited(error: unknown): boolean;
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/discord/api-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../../src/discord/api-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAC;AAkDjE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKvD;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQrD"}

package/dist/discord/api-errors.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDiscordAPIError = isDiscordAPIError;
+exports.isUnknownResource = isUnknownResource;
+exports.isMissingAccess = isMissingAccess;
+exports.isRateLimited = isRateLimited;
+const discord_js_1 = require("discord.js");
+/**
+ * Discord answers a rate limit with an HTTP status, not a JSON error code, so
+ * this one cannot come from {@link RESTJSONErrorCodes}.
+ */
+const TOO_MANY_REQUESTS_STATUS = 429;
+/**
+ * Codes meaning "the entity you asked about no longer exists". They are benign:
+ * a channel was deleted, a member left, a message was removed, an interaction
+ * token expired. The right reaction is to clean up local state, never to alert.
+ */
+const UNKNOWN_RESOURCE_CODES = new Set([
+    discord_js_1.RESTJSONErrorCodes.UnknownAccount,
+    discord_js_1.RESTJSONErrorCodes.UnknownApplication,
+    discord_js_1.RESTJSONErrorCodes.UnknownChannel,
+    discord_js_1.RESTJSONErrorCodes.UnknownGuild,
+    discord_js_1.RESTJSONErrorCodes.UnknownIntegration,
+    discord_js_1.RESTJSONErrorCodes.UnknownInvite,
+    discord_js_1.RESTJSONErrorCodes.UnknownMember,
+    discord_js_1.RESTJSONErrorCodes.UnknownMessage,
+    discord_js_1.RESTJSONErrorCodes.UnknownPermissionOverwrite,
+    discord_js_1.RESTJSONErrorCodes.UnknownRole,
+    discord_js_1.RESTJSONErrorCodes.UnknownToken,
+    discord_js_1.RESTJSONErrorCodes.UnknownUser,
+    discord_js_1.RESTJSONErrorCodes.UnknownEmoji,
+    discord_js_1.RESTJSONErrorCodes.UnknownWebhook,
+    discord_js_1.RESTJSONErrorCodes.UnknownBan,
+    discord_js_1.RESTJSONErrorCodes.UnknownGuildTemplate,
+    discord_js_1.RESTJSONErrorCodes.UnknownSticker,
+    discord_js_1.RESTJSONErrorCodes.UnknownInteraction,
+    discord_js_1.RESTJSONErrorCodes.UnknownApplicationCommand,
+    discord_js_1.RESTJSONErrorCodes.UnknownVoiceState,
+    discord_js_1.RESTJSONErrorCodes.UnknownStageInstance,
+]);
+/** Codes meaning the bot is simply not allowed to do this — actionable by an admin. */
+const MISSING_ACCESS_CODES = new Set([
+    discord_js_1.RESTJSONErrorCodes.MissingAccess,
+    discord_js_1.RESTJSONErrorCodes.MissingPermissions,
+]);
+/** Codes Discord uses for a per-resource throttle, alongside the HTTP 429 status. */
+const RATE_LIMIT_CODES = new Set([
+    discord_js_1.RESTJSONErrorCodes.ChannelSendRateLimit,
+    discord_js_1.RESTJSONErrorCodes.ServerSendRateLimit,
+    discord_js_1.RESTJSONErrorCodes.ServiceResourceIsBeingRateLimited,
+]);
+/**
+ * Narrow an unknown rejection to a Discord REST error. Adapters catch `unknown`,
+ * so every predicate below starts here rather than trusting a `code` property
+ * that any object could carry.
+ */
+function isDiscordAPIError(error) {
+    return error instanceof discord_js_1.DiscordAPIError;
+}
+/**
+ * The targeted guild/channel/member/message/interaction is gone. Treat as a
+ * benign outcome: drop the stale reference instead of logging an incident.
+ */
+function isUnknownResource(error) {
+    if (!isDiscordAPIError(error)) {
+        return false;
+    }
+    return typeof error.code === "number" && UNKNOWN_RESOURCE_CODES.has(error.code);
+}
+/**
+ * The bot lacks a permission or access to the resource. Actionable by a server
+ * admin, so it deserves a clear message rather than a generic incident.
+ */
+function isMissingAccess(error) {
+    if (!isDiscordAPIError(error)) {
+        return false;
+    }
+    return typeof error.code === "number" && MISSING_ACCESS_CODES.has(error.code);
+}
+/** Discord is throttling us: back off and retry rather than surface a failure. */
+function isRateLimited(error) {
+    if (!isDiscordAPIError(error)) {
+        return false;
+    }
+    if (error.status === TOO_MANY_REQUESTS_STATUS) {
+        return true;
+    }
+    return typeof error.code === "number" && RATE_LIMIT_CODES.has(error.code);
+}
+//# sourceMappingURL=api-errors.js.map

package/dist/discord/api-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.js","sourceRoot":"","sources":["../../src/discord/api-errors.ts"],"names":[],"mappings":";;AAuDA,8CAEC;AAMD,8CAKC;AAMD,0CAKC;AAGD,sCAQC;AA1FD,2CAAiE;AAEjE;;;GAGG;AACH,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC;;;;GAIG;AACH,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAC3D,+BAAkB,CAAC,cAAc;IACjC,+BAAkB,CAAC,kBAAkB;IACrC,+BAAkB,CAAC,cAAc;IACjC,+BAAkB,CAAC,YAAY;IAC/B,+BAAkB,CAAC,kBAAkB;IACrC,+BAAkB,CAAC,aAAa;IAChC,+BAAkB,CAAC,aAAa;IAChC,+BAAkB,CAAC,cAAc;IACjC,+BAAkB,CAAC,0BAA0B;IAC7C,+BAAkB,CAAC,WAAW;IAC9B,+BAAkB,CAAC,YAAY;IAC/B,+BAAkB,CAAC,WAAW;IAC9B,+BAAkB,CAAC,YAAY;IAC/B,+BAAkB,CAAC,cAAc;IACjC,+BAAkB,CAAC,UAAU;IAC7B,+BAAkB,CAAC,oBAAoB;IACvC,+BAAkB,CAAC,cAAc;IACjC,+BAAkB,CAAC,kBAAkB;IACrC,+BAAkB,CAAC,yBAAyB;IAC5C,+BAAkB,CAAC,iBAAiB;IACpC,+BAAkB,CAAC,oBAAoB;CACvC,CAAC,CAAC;AAEH,uFAAuF;AACvF,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC;IACzD,+BAAkB,CAAC,aAAa;IAChC,+BAAkB,CAAC,kBAAkB;CACrC,CAAC,CAAC;AAEH,qFAAqF;AACrF,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IACrD,+BAAkB,CAAC,oBAAoB;IACvC,+BAAkB,CAAC,mBAAmB;IACtC,+BAAkB,CAAC,iCAAiC;CACpD,CAAC,CAAC;AAEH;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC/C,OAAO,KAAK,YAAY,4BAAe,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC/C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,KAAc;IAC7C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC;AAED,kFAAkF;AAClF,SAAgB,aAAa,CAAC,KAAc;IAC3C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,wBAAwB,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC"}

package/dist/discord/channel-exporter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Port for handing a channel to whatever export/archive pipeline is wired up at
+ * the composition root, before the channel is otherwise disposed of.
+ *
+ * This is the seam that lets one feature use another's capability without
+ * importing it: a module that closes channels can ask for the content to be
+ * archived first, while knowing nothing about who archives it — or whether
+ * anyone does. The composition root decides what implements this, exactly as it
+ * does for `Logger` and `DatabaseConnection`.
+ */
+export interface ChannelExportOptions {
+    /** A caller-chosen base name (no extension) for the produced archive file. */
+    readonly fileName?: string;
+}
+/**
+ * Where one export actually ended up.
+ *
+ * Reported rather than assumed, because a caller usually has to tell the person
+ * who triggered the export where to find the result — and because an
+ * implementation may have a preferred destination it could not reach. The two
+ * destinations are deliberately coarse: `discord`, meaning the archive was
+ * posted as a message attachment, and `cloud`, meaning it was uploaded
+ * somewhere and only a link came back.
+ */
+export interface ChannelExportOutcome {
+    readonly destinationUsed: "discord" | "cloud";
+    /** True when cloud delivery was configured, failed, and Discord took over. */
+    readonly fellBackFromCloud: boolean;
+    readonly cloudUrl?: string;
+}
+export interface ChannelExporter {
+    /**
+     * Export `channelId`'s content and deliver the result.
+     *
+     * `deliverToChannelId` is where a Discord-delivered archive is posted — also
+     * the fallback when cloud delivery is configured but fails. `guildId` is what
+     * an implementation resolves that guild's destination preference from, so the
+     * caller does not have to know one exists.
+     */
+    exportChannel(channelId: string, deliverToChannelId: string, guildId: string, options?: ChannelExportOptions): Promise<ChannelExportOutcome>;
+}
+//# sourceMappingURL=channel-exporter.d.ts.map

package/dist/discord/channel-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-exporter.d.ts","sourceRoot":"","sources":["../../src/discord/channel-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,eAAe,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9C,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC/B;;;;;;;OAOG;IACH,aAAa,CACZ,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACjC"}

package/dist/discord/channel-exporter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=channel-exporter.js.map

package/dist/discord/channel-exporter.js.map

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

package/dist/discord/command/autocomplete-dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { Interaction } from "discord.js";
+import type { SlashCommand } from "../../discord/command/types";
+import type { InteractionDispatcher } from "../../discord/interaction/interaction-router";
+import type { Logger } from "../../logger";
+/**
+ * The slice of the command registry this dispatcher needs. Depending on a
+ * one-method port rather than on `CommandRouter` keeps the two dispatchers
+ * decoupled while sharing a single registration — the alternative, a second map
+ * of commands, would drift the moment a command is registered in only one.
+ */
+export interface CommandLookup {
+    get(name: string): SlashCommand | undefined;
+}
+/**
+ * Answers option autocomplete requests. It is an {@link InteractionDispatcher}
+ * aggregated by the shared {@link InteractionRouter}, never a second
+ * `client.on("interactionCreate")` — the whole app keeps exactly one listener.
+ */
+export declare class AutocompleteDispatcher implements InteractionDispatcher {
+    private readonly commands;
+    private readonly logger;
+    constructor(commands: CommandLookup, logger: Logger);
+    /** Claim autocomplete interactions; ignore everything else. */
+    handle(interaction: Interaction): Promise<boolean>;
+}
+//# sourceMappingURL=autocomplete-dispatcher.d.ts.map

package/dist/discord/command/autocomplete-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,qBAAqB;IAElE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM;IAGhC,+DAA+D;IACzD,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA0BxD"}

package/dist/discord/command/autocomplete-dispatcher.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutocompleteDispatcher = void 0;
+/**
+ * Answers option autocomplete requests. It is an {@link InteractionDispatcher}
+ * aggregated by the shared {@link InteractionRouter}, never a second
+ * `client.on("interactionCreate")` — the whole app keeps exactly one listener.
+ */
+class AutocompleteDispatcher {
+    commands;
+    logger;
+    constructor(commands, logger) {
+        this.commands = commands;
+        this.logger = logger;
+    }
+    /** Claim autocomplete interactions; ignore everything else. */
+    async handle(interaction) {
+        if (!interaction.isAutocomplete()) {
+            return false;
+        }
+        const command = this.commands.get(interaction.commandName);
+        if (!command?.autocomplete) {
+            return false;
+        }
+        // A failing suggestion must never surface to the user: Discord shows no
+        // error for autocomplete, it just leaves the box spinning until it times
+        // out. Swallow, log, and let the command reply with an empty list.
+        try {
+            await command.autocomplete(interaction);
+        }
+        catch (error) {
+            this.logger.error({
+                command: interaction.commandName,
+                err: error instanceof Error ? error.message : String(error),
+            }, "Autocomplete handler failed");
+        }
+        return true;
+    }
+}
+exports.AutocompleteDispatcher = AutocompleteDispatcher;
+//# sourceMappingURL=autocomplete-dispatcher.js.map

package/dist/discord/command/autocomplete-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete-dispatcher.js","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":";;;AAeA;;;;GAIG;AACH,MAAa,sBAAsB;IAEhB;IACA;IAFlB,YACkB,QAAuB,EACvB,MAAc;QADd,aAAQ,GAAR,QAAQ,CAAe;QACvB,WAAM,GAAN,MAAM,CAAQ;IAC7B,CAAC;IAEJ,+DAA+D;IAC/D,KAAK,CAAC,MAAM,CAAC,WAAwB;QACpC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACd,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,mEAAmE;QACnE,IAAI,CAAC;YACJ,MAAM,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAChB;gBACC,OAAO,EAAE,WAAW,CAAC,WAAW;gBAChC,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC3D,EACD,6BAA6B,CAC7B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AAjCD,wDAiCC"}

package/dist/discord/command/autocomplete.d.ts

@@ -0,0 +1,18 @@
+import type { AutocompleteInteraction } from "discord.js";
+import { type CompiledSubcommand } from "../../discord/command/create-command";
+import type { Options } from "../../discord/command/options";
+/**
+ * Answer a focused option's autocomplete request.
+ *
+ * Nothing here is allowed to throw: Discord surfaces no error for a failed
+ * autocomplete, it just leaves the input spinning until it times out, so an
+ * empty list is the only sane failure mode. The caller logs; the user keeps
+ * typing.
+ */
+export declare function respondWithSuggestions(interaction: AutocompleteInteraction, options: Options): Promise<void>;
+/**
+ * The options a given autocomplete interaction applies to: the focused option
+ * belongs to the invoked subcommand, not to the command as a whole.
+ */
+export declare function resolveRouteOptions(interaction: AutocompleteInteraction, routes: Map<string, CompiledSubcommand>, flatOptions: Options | null): Options;
+//# sourceMappingURL=autocomplete.d.ts.map

package/dist/discord/command/autocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,KAAK,kBAAkB,EAAY,MAAM,kCAAkC,CAAC;AACrF,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAWjE;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,WAAW,EAAE,uBAAuB,EACpC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAsBf;AAWD;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,uBAAuB,EACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACvC,WAAW,EAAE,OAAO,GAAG,IAAI,GACzB,OAAO,CAUT"}

package/dist/discord/command/autocomplete.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.respondWithSuggestions = respondWithSuggestions;
+exports.resolveRouteOptions = resolveRouteOptions;
+const create_command_1 = require("../../discord/command/create-command");
+/**
+ * Serving option autocomplete. Kept beside the DSL because resolving *which*
+ * option is focused needs the same route table `createCommand` builds — the
+ * dispatcher only decides that an interaction is an autocomplete request.
+ */
+/** Discord refuses more than this many suggestions in one response. */
+const MAX_CHOICES = 25;
+/**
+ * Answer a focused option's autocomplete request.
+ *
+ * Nothing here is allowed to throw: Discord surfaces no error for a failed
+ * autocomplete, it just leaves the input spinning until it times out, so an
+ * empty list is the only sane failure mode. The caller logs; the user keeps
+ * typing.
+ */
+async function respondWithSuggestions(interaction, options) {
+    const focused = interaction.options.getFocused(true);
+    const option = options[focused.name];
+    const resolver = option?.autocomplete;
+    if (!resolver) {
+        await interaction.respond([]);
+        return;
+    }
+    // The resolver is the only part that can fail (it usually hits a database).
+    // Answering an empty list keeps the picker responsive; rethrowing after the
+    // response lets the dispatcher log the cause without leaving the user hanging.
+    let choices;
+    try {
+        choices = await resolver(interaction);
+    }
+    catch (error) {
+        await interaction.respond([]);
+        throw error;
+    }
+    await interaction.respond(truncate(choices));
+}
+/**
+ * Discord rejects the whole response when it carries more than 25 choices, so a
+ * resolver returning more is trimmed rather than failing outright — a partial
+ * list is still useful to the user typing.
+ */
+function truncate(choices) {
+    return choices.slice(0, MAX_CHOICES);
+}
+/**
+ * The options a given autocomplete interaction applies to: the focused option
+ * belongs to the invoked subcommand, not to the command as a whole.
+ */
+function resolveRouteOptions(interaction, routes, flatOptions) {
+    if (flatOptions) {
+        return flatOptions;
+    }
+    const group = interaction.options.getSubcommandGroup(false);
+    const name = interaction.options.getSubcommand(false);
+    if (name === null) {
+        return {};
+    }
+    return routes.get((0, create_command_1.routeKey)(group, name))?.options ?? {};
+}
+//# sourceMappingURL=autocomplete.js.map

package/dist/discord/command/autocomplete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete.js","sourceRoot":"","sources":["../../../src/discord/command/autocomplete.ts"],"names":[],"mappings":";;AAqBA,wDAyBC;AAeD,kDAcC;AA1ED,qEAAqF;AAGrF;;;;GAIG;AAEH,uEAAuE;AACvE,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;;;;;GAOG;AACI,KAAK,UAAU,sBAAsB,CAC3C,WAAoC,EACpC,OAAgB;IAEhB,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,MAAM,EAAE,YAAY,CAAC;IAEtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,OAAO;IACR,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,+EAA+E;IAC/E,IAAI,OAA0B,CAAC;IAC/B,IAAI,CAAC;QACJ,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,KAAK,CAAC;IACb,CAAC;IAED,MAAM,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,OAA0B;IAC3C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAClC,WAAoC,EACpC,MAAuC,EACvC,WAA2B;IAE3B,IAAI,WAAW,EAAE,CAAC;QACjB,OAAO,WAAW,CAAC;IACpB,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAA,yBAAQ,EAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC;AACzD,CAAC"}

package/dist/discord/command/context.d.ts

@@ -0,0 +1,33 @@
+import { type ChatInputCommandInteraction, type EmbedBuilder } from "discord.js";
+import type { Options, Values } from "../../discord/command/options";
+import type { Presenter } from "../../discord/presenter";
+import { type Locale, type TranslationParams, type Translator } from "../../i18n";
+import type { Logger } from "../../logger";
+/**
+ * The handler-facing surface of a dispatched subcommand: the raw interaction,
+ * the parsed & typed options, the locale resolved for this interaction, a
+ * translate helper bound to it, and convenience responders that route through
+ * the injected {@link Presenter}.
+ */
+export interface Context<O extends Options> {
+    readonly interaction: ChatInputCommandInteraction;
+    readonly options: Values<O>;
+    /** Reply language: user's client locale → guild locale → configured default. */
+    readonly locale: Locale;
+    /** Translate a catalog key for this interaction's locale. */
+    t(key: string, params?: TranslationParams): string;
+    reply(embed: EmbedBuilder): Promise<void>;
+    confirm(message: string): Promise<void>;
+    error(message: string): Promise<void>;
+    deny(message: string): Promise<void>;
+}
+/**
+ * Deliver an embed regardless of the interaction's lifecycle state, and never
+ * throw: a failed delivery (e.g. an expired/unknown interaction, code 10062)
+ * must not escape a handler and reach the client's unhandled `error` event,
+ * which would crash the process. Visibility on a deferred interaction is fixed
+ * at deferReply time, so editReply carries no flags.
+ */
+export declare function sendEmbed(interaction: ChatInputCommandInteraction, embed: EmbedBuilder, ephemeral: boolean, logger: Logger): Promise<void>;
+export declare function createContext<O extends Options>(interaction: ChatInputCommandInteraction, options: Values<O>, ephemeral: boolean, presenter: Presenter, logger: Logger, translator: Translator): Context<O>;
+//# sourceMappingURL=context.d.ts.map

package/dist/discord/command/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/discord/command/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,2BAA2B,EAAE,KAAK,YAAY,EAAgB,MAAM,YAAY,CAAC;AAC/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,KAAK,MAAM,EAAiB,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,OAAO;IACzC,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACnD,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC9B,WAAW,EAAE,2BAA2B,EACxC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAC9C,WAAW,EAAE,2BAA2B,EACxC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAClB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GACpB,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/discord/command/context.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendEmbed = sendEmbed;
+exports.createContext = createContext;
+const discord_js_1 = require("discord.js");
+const i18n_1 = require("../../i18n");
+/**
+ * Deliver an embed regardless of the interaction's lifecycle state, and never
+ * throw: a failed delivery (e.g. an expired/unknown interaction, code 10062)
+ * must not escape a handler and reach the client's unhandled `error` event,
+ * which would crash the process. Visibility on a deferred interaction is fixed
+ * at deferReply time, so editReply carries no flags.
+ */
+async function sendEmbed(interaction, embed, ephemeral, logger) {
+    const flags = ephemeral ? discord_js_1.MessageFlags.Ephemeral : undefined;
+    try {
+        if (interaction.deferred) {
+            await interaction.editReply({ embeds: [embed] });
+            return;
+        }
+        if (interaction.replied) {
+            await interaction.followUp({ embeds: [embed], flags });
+            return;
+        }
+        await interaction.reply({ embeds: [embed], flags });
+    }
+    catch (error) {
+        logger.error({
+            commandName: interaction.commandName,
+            interactionId: interaction.id,
+            err: error instanceof Error ? error.message : String(error),
+        }, "Failed to deliver interaction response");
+    }
+}
+function createContext(interaction, options, ephemeral, presenter, logger, translator) {
+    const locale = (0, i18n_1.resolveLocale)([interaction.locale, interaction.guildLocale], translator.defaultLocale);
+    return {
+        interaction,
+        options,
+        locale,
+        t: (key, params) => translator.translate(locale, key, params),
+        reply: (embed) => sendEmbed(interaction, embed, ephemeral, logger),
+        confirm: (message) => sendEmbed(interaction, presenter.confirmation(message, locale), ephemeral, logger),
+        error: (message) => sendEmbed(interaction, presenter.error(message, locale), ephemeral, logger),
+        deny: (message) => sendEmbed(interaction, presenter.denial(message, locale), ephemeral, logger),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/discord/command/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/discord/command/context.ts"],"names":[],"mappings":";;AAgCA,8BA2BC;AAED,sCAuBC;AApFD,2CAA+F;AAG/F,iCAA6F;AAsB7F;;;;;;GAMG;AACI,KAAK,UAAU,SAAS,CAC9B,WAAwC,EACxC,KAAmB,EACnB,SAAkB,EAClB,MAAc;IAEd,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,yBAAY,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7D,IAAI,CAAC;QACJ,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAC1B,MAAM,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjD,OAAO;QACR,CAAC;QACD,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO;QACR,CAAC;QACD,MAAM,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,CAAC,KAAK,CACX;YACC,WAAW,EAAE,WAAW,CAAC,WAAW;YACpC,aAAa,EAAE,WAAW,CAAC,EAAE;YAC7B,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC3D,EACD,wCAAwC,CACxC,CAAC;IACH,CAAC;AACF,CAAC;AAED,SAAgB,aAAa,CAC5B,WAAwC,EACxC,OAAkB,EAClB,SAAkB,EAClB,SAAoB,EACpB,MAAc,EACd,UAAsB;IAEtB,MAAM,MAAM,GAAG,IAAA,oBAAa,EAC3B,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,EAC7C,UAAU,CAAC,aAAa,CACxB,CAAC;IACF,OAAO;QACN,WAAW;QACX,OAAO;QACP,MAAM;QACN,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;QAC7D,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC;QAClE,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CACpB,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC;QACnF,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC;QAC/F,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC;KAC/F,CAAC;AACH,CAAC"}