@azurioh/discord-kernel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Cunin
+
+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

@@ -0,0 +1,77 @@
+# @azurioh/discord-kernel
+
+The framework half of a Discord bot, without the bot: a command DSL, guards,
+interaction routing, composed components, localisation, and the ports an
+application implements. It knows discord.js and nothing else — no database, no
+logger implementation, no opinion about what your bot does.
+
+Built for Clean Architecture with vertically-sliced feature modules: the kernel
+is the innermost ring, and the fact that it is a package rather than a folder is
+what enforces that — an outer ring simply is not in its dependency graph.
+
+```bash
+pnpm add @azurioh/discord-kernel discord.js
+```
+
+`discord.js` is a **peer dependency**, never a dependency: two copies of the
+library in one tree would break every `instanceof` the gateway relies on.
+
+## What is in it
+
+| Area | What it gives you |
+| ---- | ----------------- |
+| `discord/command/` | `createCommand` (flat or grouped), typed options, guards (`allOf`/`anyOf`, permissions, roles, cooldowns), the per-interaction `Context`, autocomplete, the `CommandRouter` |
+| `discord/interaction/` | `createButton`, `createModal`, the four typed select menus (`createStringSelect`, `createChannelSelect`, `createRoleSelect`, `createUserSelect`), the `InteractionRouter`/`InteractionDispatcher` seam |
+| `discord/components/` | `ComponentRouter` for persistent `customId` routing, and collector-backed screens: `paginator`, `interactive-message`, `settings-editor` |
+| `discord/events/` | `createEvent` and the `EventRouter` — the one place `client.on` is called |
+| `discord/ui/` | Embeds with Discord's size limits handled, `createCard` containers, a configurable palette, a colour-input parser |
+| `i18n/` | Catalogs (`{ en, fr? }`, `en` mandatory), a registry that fails the boot on a duplicate key, per-interaction locale resolution |
+| `authz/` | An `Authorizer` port with `viewer`/`editor` grants and a `requireLevel` guard |
+| `errors/` | `BusinessError` and friends, carrying an optional translation key beside the English source |
+| `scheduler/` | A `Scheduler` port and a node-cron implementation |
+| Ports | `Logger`, `DatabaseConnection`, `Presenter`, `Clock`, `ChannelExporter` — declared here, implemented by your app |
+
+Every path is imported directly; there is no root barrel:
+
+```ts
+import { createCommand } from "@azurioh/discord-kernel/discord/command/create-command";
+import type { Logger } from "@azurioh/discord-kernel/logger";
+import { type Catalog, createTranslator } from "@azurioh/discord-kernel/i18n";
+```
+
+## What is deliberately not in it
+
+- **A database.** `DatabaseConnection` is a lifecycle port — connect, close — and
+  nothing more. Query APIs differ too much between engines to abstract usefully,
+  so an adapter exposes its own and your repositories are the only code that
+  touches it.
+- **A logger.** `Logger` is a port; pino, Sentry or `console` live in your app.
+- **A configuration shape.** The kernel ships env-reading primitives
+  (`requireEnv`, `enumEnv`, …); which keys exist is your composition root's call.
+- **A palette.** Embeds render in Discord's blurple until you say otherwise, so a
+  bot never starts out wearing someone else's identity.
+
+## Making it yours
+
+Two things are global by nature — a bot has one look, decided once — and are set
+from the composition root before any module is constructed:
+
+```ts
+import { configureEmbedColors } from "@azurioh/discord-kernel/discord/ui/colors";
+import { registerColorAliases } from "@azurioh/discord-kernel/discord/ui/color-input";
+
+configureEmbedColors({ brand: 0xf3c909 });
+registerColorAliases({ gold: "#f3c909", or: "#f3c909" });
+```
+
+Everything else is injected: your modules are factories receiving a container
+you define, so nothing in the kernel is reachable as a singleton.
+
+## Requirements
+
+Node 22.12+, discord.js 14.27+, TypeScript 5.9. The published build is
+CommonJS with declaration files, resolved through explicit subpath `exports`.
+
+## License
+
+MIT

package/dist/authz/authorizer.d.ts

@@ -0,0 +1,45 @@
+/** Permission tiers, lowest to highest. `editor` implies `viewer`. */
+export type PermissionLevel = "viewer" | "editor";
+/** Numeric rank for comparing levels (`editor` ≥ `viewer`). */
+export declare const LEVEL_RANK: Record<PermissionLevel, number>;
+/** A single grant: either a role or a user, at a given level. */
+export interface PermissionGrant {
+    readonly targetType: "role" | "user";
+    readonly targetId: string;
+    readonly level: PermissionLevel;
+}
+/** The full set of grants, split by target kind for cheap resolution. */
+export interface PermissionGrants {
+    readonly roles: Record<string, PermissionLevel>;
+    readonly users: Record<string, PermissionLevel>;
+}
+/**
+ * Cross-cutting authorization port for feature-level permission tiers (as
+ * opposed to Discord's own per-command `defaultMemberPermissions`/guild
+ * permissions, which gate *visibility* and native capabilities). A module
+ * grants a role or a user a level; a guard checks whether a member meets the
+ * level required for an action.
+ *
+ * Deliberately has no notion of "admin": a bot-wide administrator bypass is a
+ * Discord permission concern, composed at the guard level with
+ * `anyOf(createPermissionGuard([Administrator]), requireLevel(...))` — keeping
+ * this port focused on the one thing it owns, feature-level grants.
+ */
+export interface Authorizer {
+    /** Whether the user (directly, or via one of their roles) meets `required`. */
+    meetsLevel(userId: string, roleIds: readonly string[], required: PermissionLevel): Promise<boolean>;
+    grantRole(roleId: string, level: PermissionLevel): Promise<void>;
+    grantUser(userId: string, level: PermissionLevel): Promise<void>;
+    /** Returns whether a grant existed to remove. */
+    revokeRole(roleId: string): Promise<boolean>;
+    /** Returns whether a grant existed to remove. */
+    revokeUser(userId: string): Promise<boolean>;
+    listGrants(): Promise<PermissionGrants>;
+}
+/**
+ * Shared resolution used by every adapter: a direct user grant wins over role
+ * grants; otherwise the highest matching role level applies. Returns whether
+ * the resolved level meets `required`.
+ */
+export declare function meetsResolvedLevel(grants: PermissionGrants, userId: string, roleIds: readonly string[], required: PermissionLevel): boolean;
+//# sourceMappingURL=authorizer.d.ts.map

package/dist/authz/authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.d.ts","sourceRoot":"","sources":["../../src/authz/authorizer.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElD,+DAA+D;AAC/D,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAGtD,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CAChC;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IAC1B,+EAA+E;IAC/E,UAAU,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,iDAAiD;IACjD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,iDAAiD;IACjD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,QAAQ,EAAE,eAAe,GACvB,OAAO,CAeT"}

package/dist/authz/authorizer.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEVEL_RANK = void 0;
+exports.meetsResolvedLevel = meetsResolvedLevel;
+/** Numeric rank for comparing levels (`editor` ≥ `viewer`). */
+exports.LEVEL_RANK = {
+    viewer: 1,
+    editor: 2,
+};
+/**
+ * Shared resolution used by every adapter: a direct user grant wins over role
+ * grants; otherwise the highest matching role level applies. Returns whether
+ * the resolved level meets `required`.
+ */
+function meetsResolvedLevel(grants, userId, roleIds, required) {
+    const userLevel = grants.users[userId];
+    let resolved = userLevel ?? null;
+    if (!resolved) {
+        for (const roleId of roleIds) {
+            const roleLevel = grants.roles[roleId];
+            if (roleLevel && (!resolved || exports.LEVEL_RANK[roleLevel] > exports.LEVEL_RANK[resolved])) {
+                resolved = roleLevel;
+            }
+        }
+    }
+    if (!resolved) {
+        return false;
+    }
+    return exports.LEVEL_RANK[resolved] >= exports.LEVEL_RANK[required];
+}
+//# sourceMappingURL=authorizer.js.map

package/dist/authz/authorizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.js","sourceRoot":"","sources":["../../src/authz/authorizer.ts"],"names":[],"mappings":";;;AAuDA,gDAoBC;AAxED,+DAA+D;AAClD,QAAA,UAAU,GAAoC;IAC1D,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;CACT,CAAC;AA2CF;;;;GAIG;AACH,SAAgB,kBAAkB,CACjC,MAAwB,EACxB,MAAc,EACd,OAA0B,EAC1B,QAAyB;IAEzB,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,QAAQ,GAA2B,SAAS,IAAI,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,SAAS,IAAI,CAAC,CAAC,QAAQ,IAAI,kBAAU,CAAC,SAAS,CAAC,GAAG,kBAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;gBAC9E,QAAQ,GAAG,SAAS,CAAC;YACtB,CAAC;QACF,CAAC;IACF,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,kBAAU,CAAC,QAAQ,CAAC,IAAI,kBAAU,CAAC,QAAQ,CAAC,CAAC;AACrD,CAAC"}

package/dist/authz/require-level-guard.d.ts

@@ -0,0 +1,23 @@
+import type { BaseInteraction } from "discord.js";
+import type { Authorizer, PermissionLevel } from "../authz/authorizer";
+import type { Guard } from "../discord/command/guard";
+import type { LocalizedText } from "../i18n";
+/**
+ * Role IDs held by the interacting member, resolved without a network call:
+ * `interaction.member.roles` is either the cached `GuildMemberRoleManager` (a
+ * cached-guild interaction) or a plain array of IDs (the raw API shape for an
+ * uncached one) — both are handled so the guard never has to fetch the member.
+ *
+ * Typed on the base `Interaction`, not on the command flavour a guard takes: a
+ * control clicked inside a message carries the member exactly the same way, and
+ * a rule that has to hold on both paths must be able to ask both.
+ */
+export declare function memberRoleIds(interaction: BaseInteraction): string[];
+/**
+ * Deny unless the member meets `required` on the injected {@link Authorizer}
+ * (directly, or via one of their roles). Compose with a Discord-permission
+ * guard through `anyOf(...)` when a bot-wide administrator bypass is wanted —
+ * this guard alone knows nothing about Discord permissions.
+ */
+export declare function requireLevel(authz: Authorizer, required: PermissionLevel, denyMessage: LocalizedText): Guard;
+//# sourceMappingURL=require-level-guard.d.ts.map

package/dist/authz/require-level-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-level-guard.d.ts","sourceRoot":"","sources":["../../src/authz/require-level-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,EAAE,CAOpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,aAAa,GACxB,KAAK,CAOP"}

package/dist/authz/require-level-guard.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memberRoleIds = memberRoleIds;
+exports.requireLevel = requireLevel;
+/**
+ * Role IDs held by the interacting member, resolved without a network call:
+ * `interaction.member.roles` is either the cached `GuildMemberRoleManager` (a
+ * cached-guild interaction) or a plain array of IDs (the raw API shape for an
+ * uncached one) — both are handled so the guard never has to fetch the member.
+ *
+ * Typed on the base `Interaction`, not on the command flavour a guard takes: a
+ * control clicked inside a message carries the member exactly the same way, and
+ * a rule that has to hold on both paths must be able to ask both.
+ */
+function memberRoleIds(interaction) {
+    const member = interaction.member;
+    if (!member || typeof member !== "object" || !("roles" in member)) {
+        return [];
+    }
+    const roles = member.roles;
+    return Array.isArray(roles) ? roles : Array.from(roles.cache.keys());
+}
+/**
+ * Deny unless the member meets `required` on the injected {@link Authorizer}
+ * (directly, or via one of their roles). Compose with a Discord-permission
+ * guard through `anyOf(...)` when a bot-wide administrator bypass is wanted —
+ * this guard alone knows nothing about Discord permissions.
+ */
+function requireLevel(authz, required, denyMessage) {
+    return {
+        async check(interaction) {
+            const ok = await authz.meetsLevel(interaction.user.id, memberRoleIds(interaction), required);
+            return ok ? { ok: true } : { ok: false, message: denyMessage };
+        },
+    };
+}
+//# sourceMappingURL=require-level-guard.js.map

package/dist/authz/require-level-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-level-guard.js","sourceRoot":"","sources":["../../src/authz/require-level-guard.ts"],"names":[],"mappings":";;AAeA,sCAOC;AAQD,oCAWC;AApCD;;;;;;;;;GASG;AACH,SAAgB,aAAa,CAAC,WAA4B;IACzD,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IAClC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,EAAE,CAAC;IACX,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAC3B,KAAiB,EACjB,QAAyB,EACzB,WAA0B;IAE1B,OAAO;QACN,KAAK,CAAC,KAAK,CAAC,WAA+B;YAC1C,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC7F,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;QAChE,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/clock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Abstraction over the current time. Injecting a clock (instead of calling
+ * `new Date()` directly) lets domain/application code be tested deterministically
+ * and keeps those layers free of ambient I/O.
+ */
+export interface Clock {
+    now(): Date;
+}
+/** The real clock, backed by the system time. */
+export declare const systemClock: Clock;
+/** A fixed clock for tests. */
+export declare function fixedClock(instant: Date): Clock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACrB,GAAG,IAAI,IAAI,CAAC;CACZ;AAED,iDAAiD;AACjD,eAAO,MAAM,WAAW,EAAE,KAEzB,CAAC;AAEF,+BAA+B;AAC/B,wBAAgB,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,KAAK,CAE/C"}

package/dist/clock.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.fixedClock = fixedClock;
+/** The real clock, backed by the system time. */
+exports.systemClock = {
+    now: () => new Date(),
+};
+/** A fixed clock for tests. */
+function fixedClock(instant) {
+    return { now: () => new Date(instant) };
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":";;;AAeA,gCAEC;AARD,iDAAiD;AACpC,QAAA,WAAW,GAAU;IACjC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;CACrB,CAAC;AAEF,+BAA+B;AAC/B,SAAgB,UAAU,CAAC,OAAa;IACvC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;AACzC,CAAC"}

package/dist/concurrency/keyed-queue.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Serialises asynchronous work per key while leaving distinct keys concurrent.
+ */
+export interface KeyedQueue {
+    /** Run `task` after every task already queued for `key` has settled. */
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+    /** Number of keys with work in flight — exposed so tests can assert no leak. */
+    readonly size: number;
+}
+/**
+ * Gateway handlers fire concurrently for the same entity (two rapid events on one
+ * channel, a member joining twice, an event replay after a resume), so
+ * read-modify-write logic keyed on that entity interleaves and corrupts state.
+ * Chaining per key restores ordering without a global lock, which would
+ * needlessly serialise unrelated guilds.
+ */
+export declare function createKeyedQueue(): KeyedQueue;
+//# sourceMappingURL=keyed-queue.d.ts.map

package/dist/concurrency/keyed-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-queue.d.ts","sourceRoot":"","sources":["../../src/concurrency/keyed-queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,wEAAwE;IACxE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAgC7C"}

package/dist/concurrency/keyed-queue.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeyedQueue = createKeyedQueue;
+/**
+ * Gateway handlers fire concurrently for the same entity (two rapid events on one
+ * channel, a member joining twice, an event replay after a resume), so
+ * read-modify-write logic keyed on that entity interleaves and corrupts state.
+ * Chaining per key restores ordering without a global lock, which would
+ * needlessly serialise unrelated guilds.
+ */
+function createKeyedQueue() {
+    const chains = new Map();
+    return {
+        get size() {
+            return chains.size;
+        },
+        run(key, task) {
+            const previous = chains.get(key) ?? Promise.resolve();
+            // The chain continues on the *settled* tail: a rejected task must not
+            // poison the queue for the tasks behind it, while `result` keeps the
+            // rejection observable by this caller alone.
+            const settledTail = previous.then(() => undefined, () => undefined);
+            const result = settledTail.then(task);
+            const tail = result.then(() => undefined, () => undefined);
+            chains.set(key, tail);
+            // Only the task that is still the tail may drop the entry, otherwise a
+            // later enqueue would be forgotten and the Map would grow unbounded.
+            void tail.then(() => {
+                if (chains.get(key) === tail) {
+                    chains.delete(key);
+                }
+            });
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=keyed-queue.js.map

package/dist/concurrency/keyed-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-queue.js","sourceRoot":"","sources":["../../src/concurrency/keyed-queue.ts"],"names":[],"mappings":";;AAiBA,4CAgCC;AAvCD;;;;;;GAMG;AACH,SAAgB,gBAAgB;IAC/B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEnD,OAAO;QACN,IAAI,IAAI;YACP,OAAO,MAAM,CAAC,IAAI,CAAC;QACpB,CAAC;QACD,GAAG,CAAI,GAAW,EAAE,IAAsB;YACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACtD,sEAAsE;YACtE,qEAAqE;YACrE,6CAA6C;YAC7C,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAChC,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CACf,CAAC;YACF,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CACvB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CACf,CAAC;YACF,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACtB,uEAAuE;YACvE,qEAAqE;YACrE,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;gBACnB,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;oBAC9B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpB,CAAC;YACF,CAAC,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QACf,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/concurrency/run-with-concurrency.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Runs every task in `items` through `worker`, never letting more than `limit`
+ * run at once, and resolves once all have settled. Results are returned in the
+ * same order as `items`, regardless of completion order.
+ *
+ * Exists so callers that must fan out many independent async calls (e.g.
+ * fetching a reaction's user list per distinct emoji across thousands of
+ * messages) can bound how many are in flight without going fully sequential —
+ * without pulling in an external dependency for what is, in essence, a small
+ * counter and a queue (the same shape of problem `keyed-queue.ts` already
+ * solves for *serialised* per-key work, just bounding *parallel* work here
+ * instead).
+ */
+export declare function runWithConcurrency<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=run-with-concurrency.d.ts.map

package/dist/concurrency/run-with-concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-concurrency.d.ts","sourceRoot":"","sources":["../../src/concurrency/run-with-concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC5C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Bd"}

package/dist/concurrency/run-with-concurrency.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithConcurrency = runWithConcurrency;
+/**
+ * Runs every task in `items` through `worker`, never letting more than `limit`
+ * run at once, and resolves once all have settled. Results are returned in the
+ * same order as `items`, regardless of completion order.
+ *
+ * Exists so callers that must fan out many independent async calls (e.g.
+ * fetching a reaction's user list per distinct emoji across thousands of
+ * messages) can bound how many are in flight without going fully sequential —
+ * without pulling in an external dependency for what is, in essence, a small
+ * counter and a queue (the same shape of problem `keyed-queue.ts` already
+ * solves for *serialised* per-key work, just bounding *parallel* work here
+ * instead).
+ */
+async function runWithConcurrency(items, limit, worker) {
+    if (items.length === 0) {
+        return [];
+    }
+    // `noUncheckedIndexedAccess` makes every `results[i]` a possible `undefined`
+    // at the type level; asserting it away here is correct because every index
+    // is written exactly once below, before this array is ever returned.
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function runNext() {
+        const currentIndex = nextIndex;
+        nextIndex += 1;
+        if (currentIndex >= items.length) {
+            return;
+        }
+        const item = items[currentIndex];
+        results[currentIndex] = await worker(item, currentIndex);
+        await runNext();
+    }
+    const workerCount = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: workerCount }, runNext));
+    return results;
+}
+//# sourceMappingURL=run-with-concurrency.js.map

package/dist/concurrency/run-with-concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-concurrency.js","sourceRoot":"","sources":["../../src/concurrency/run-with-concurrency.ts"],"names":[],"mappings":";;AAaA,gDA8BC;AA3CD;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,kBAAkB,CACvC,KAAmB,EACnB,KAAa,EACb,MAA8C;IAE9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,qEAAqE;IACrE,MAAM,OAAO,GAAG,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAQ,CAAC;IAClD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,OAAO;QACrB,MAAM,YAAY,GAAG,SAAS,CAAC;QAC/B,SAAS,IAAI,CAAC,CAAC;QACf,IAAI,YAAY,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAClC,OAAO;QACR,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAM,CAAC;QACtC,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QACzD,MAAM,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IAEhE,OAAO,OAAO,CAAC;AAChB,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generic, dependency-free helpers for reading and validating environment
+ * variables. The concrete application config (which keys exist, their defaults)
+ * is assembled by the composition root in `bootstrap/config.ts` — the core only
+ * provides the primitives so any bot can declare its own shape.
+ */
+type Env = Record<string, string | undefined>;
+/** Read a required variable, throwing {@link MissingEnvError} when absent. */
+export declare function requireEnv(key: string, env?: Env): string;
+/** Read an optional variable, returning `fallback` (or `undefined`) when absent. */
+export declare function optionalEnv(key: string, fallback?: string, env?: Env): string | undefined;
+/** Read a boolean variable (`true`/`1`/`yes` are truthy). */
+export declare function boolEnv(key: string, fallback: boolean, env?: Env): boolean;
+/** Read a variable constrained to a fixed set of values. */
+export declare function enumEnv<const T extends readonly string[]>(key: string, allowed: T, fallback: T[number], env?: Env): T[number];
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,GAAiB,GAAG,MAAM,CAMtE;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAC1B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,GAAE,GAAiB,GACpB,MAAM,GAAG,SAAS,CAMpB;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAE,GAAiB,GAAG,OAAO,CAMvF;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,EACxD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,EACnB,GAAG,GAAE,GAAiB,GACpB,CAAC,CAAC,MAAM,CAAC,CASX"}

package/dist/config/env.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Generic, dependency-free helpers for reading and validating environment
+ * variables. The concrete application config (which keys exist, their defaults)
+ * is assembled by the composition root in `bootstrap/config.ts` — the core only
+ * provides the primitives so any bot can declare its own shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireEnv = requireEnv;
+exports.optionalEnv = optionalEnv;
+exports.boolEnv = boolEnv;
+exports.enumEnv = enumEnv;
+const errors_1 = require("../config/errors");
+/** Read a required variable, throwing {@link MissingEnvError} when absent. */
+function requireEnv(key, env = process.env) {
+    const value = env[key];
+    if (value === undefined || value.trim() === "") {
+        throw new errors_1.MissingEnvError(key);
+    }
+    return value;
+}
+/** Read an optional variable, returning `fallback` (or `undefined`) when absent. */
+function optionalEnv(key, fallback, env = process.env) {
+    const value = env[key];
+    if (value === undefined || value.trim() === "") {
+        return fallback;
+    }
+    return value;
+}
+/** Read a boolean variable (`true`/`1`/`yes` are truthy). */
+function boolEnv(key, fallback, env = process.env) {
+    const value = env[key]?.trim().toLowerCase();
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    return value === "true" || value === "1" || value === "yes";
+}
+/** Read a variable constrained to a fixed set of values. */
+function enumEnv(key, allowed, fallback, env = process.env) {
+    const value = env[key]?.trim();
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    if (!allowed.includes(value)) {
+        throw new errors_1.InvalidEnvError(key, `one of ${allowed.join(", ")}`);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAOH,gCAMC;AAGD,kCAUC;AAGD,0BAMC;AAGD,0BAcC;AAlDD,4CAAmE;AAInE,8EAA8E;AAC9E,SAAgB,UAAU,CAAC,GAAW,EAAE,MAAW,OAAO,CAAC,GAAG;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,wBAAe,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,oFAAoF;AACpF,SAAgB,WAAW,CAC1B,GAAW,EACX,QAAiB,EACjB,MAAW,OAAO,CAAC,GAAG;IAEtB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAChD,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,6DAA6D;AAC7D,SAAgB,OAAO,CAAC,GAAW,EAAE,QAAiB,EAAE,MAAW,OAAO,CAAC,GAAG;IAC7E,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,KAAK,CAAC;AAC7D,CAAC;AAED,4DAA4D;AAC5D,SAAgB,OAAO,CACtB,GAAW,EACX,OAAU,EACV,QAAmB,EACnB,MAAW,OAAO,CAAC,GAAG;IAEtB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,wBAAe,CAAC,GAAG,EAAE,UAAU,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,KAAkB,CAAC;AAC3B,CAAC"}

package/dist/config/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Failures raised while reading environment variables. They live apart from the
+ * reading logic so a consumer can catch or re-map them without pulling in the
+ * `env` helpers, and so the helpers file stays focused on behaviour.
+ */
+/** Raised when a required environment variable is missing or empty. */
+export declare class MissingEnvError extends Error {
+    constructor(key: string);
+}
+/** Raised when an environment variable holds an invalid value. */
+export declare class InvalidEnvError extends Error {
+    constructor(key: string, expected: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/config/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/config/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uEAAuE;AACvE,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,GAAG,EAAE,MAAM;CAIvB;AAED,kEAAkE;AAClE,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAIzC"}

package/dist/config/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Failures raised while reading environment variables. They live apart from the
+ * reading logic so a consumer can catch or re-map them without pulling in the
+ * `env` helpers, and so the helpers file stays focused on behaviour.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidEnvError = exports.MissingEnvError = void 0;
+/** Raised when a required environment variable is missing or empty. */
+class MissingEnvError extends Error {
+    constructor(key) {
+        super(`Missing required environment variable: ${key}`);
+        this.name = "MissingEnvError";
+    }
+}
+exports.MissingEnvError = MissingEnvError;
+/** Raised when an environment variable holds an invalid value. */
+class InvalidEnvError extends Error {
+    constructor(key, expected) {
+        super(`Invalid environment variable ${key}: expected ${expected}`);
+        this.name = "InvalidEnvError";
+    }
+}
+exports.InvalidEnvError = InvalidEnvError;
+//# sourceMappingURL=errors.js.map

package/dist/config/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/config/errors.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,uEAAuE;AACvE,MAAa,eAAgB,SAAQ,KAAK;IACzC,YAAY,GAAW;QACtB,KAAK,CAAC,0CAA0C,GAAG,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AALD,0CAKC;AAED,kEAAkE;AAClE,MAAa,eAAgB,SAAQ,KAAK;IACzC,YAAY,GAAW,EAAE,QAAgB;QACxC,KAAK,CAAC,gCAAgC,GAAG,cAAc,QAAQ,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AALD,0CAKC"}

package/dist/datetime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+export declare function zonedWallClockToUtc(input: string, timeZone: string): Date;
+/** Whether `input` is a valid wall-clock datetime string. */
+export declare function isValidWallClock(input: string): boolean;
+/** `YYYY-MM-DD` of a date-only value, read in UTC (matches `Date`-only options). */
+export declare function dayString(date: Date): string;
+/** Start of `date`'s calendar day (00:00:00) anchored to `timeZone`. */
+export declare function startOfGuildDay(date: Date, timeZone: string): Date;
+/** End of `date`'s calendar day (23:59:59) anchored to `timeZone`. */
+export declare function endOfGuildDay(date: Date, timeZone: string): Date;
+/**
+ * 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.
+ */
+export declare function startOfNextGuildWeek(reference: Date, timeZone: string): Date;
+/**
+ * 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.
+ */
+export declare function addGuildDays(instant: Date, days: number, timeZone: string): Date;
+//# sourceMappingURL=datetime.d.ts.map

package/dist/datetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAiGA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAsBzE;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE5C;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAElE;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAsC5E;AACD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAkBhF"}