spearkit 0.3.1 → 0.4.0

package/docs/client.md

@@ -28,9 +28,10 @@ const a = new SpearClient({ intents: Intents.messages });
 const b = new SpearClient();
 ```
 
-The options type is exported as `SpearClientOptions` (`Partial<ClientOptions>`),
-so every other discord.js option (`partials`, `presence`, `sweepers`, …) is
-available.
+The options type is exported as `SpearClientOptions` — `Partial<ClientOptions> &
+SpearOptions`. Every discord.js option (`partials`, `presence`, `sweepers`, …) is
+available, plus spearkit's own: `logger`, `dotenv`, `cooldown`, `prefix`, `usage`,
+`embeds`, `guards` and `autoDefer` (each covered in its own guide).
 
 ### Intents presets
 
@@ -61,26 +62,38 @@ const client = new SpearClient({
 });
 ```
 
-## The three registries
-
-Every client owns three registries, each populated by `register` (or `load`):
-
-| Registry | Property | Holds |
-| -------- | -------- | ----- |
-| `CommandRegistry` | `client.commands` | Slash commands; dispatches chat-input and autocomplete interactions. |
-| `EventRegistry` | `client.events` | Event listeners; attached to the client automatically. |
-| `ComponentRegistry` | `client.components` | Buttons, selects and modals; routes component interactions by custom id. |
-
-You rarely touch them directly — `register` routes items into the right one —
-but they are public if you need to inspect or manipulate them (e.g.
-`client.commands.size`, `client.commands.toJSON()`).
+## Registries and subsystems
+
+Every client owns a set of registries and subsystems, each populated by
+`register` (or `load`) or configured by an option:
+
+| Member | Type | Holds / does |
+| ------ | ---- | ------------ |
+| `client.commands` | `CommandRegistry` | Slash commands; dispatches chat-input and autocomplete interactions. |
+| `client.events` | `EventRegistry` | Event listeners; attached to the client automatically. |
+| `client.components` | `ComponentRegistry` | Buttons, selects and modals; routed by custom-id namespace. |
+| `client.contextMenus` | `ContextMenuRegistry` | User / message context-menu ("Apps") commands. |
+| `client.prefix` | `PrefixRegistry` | Prefix (text) commands, dispatched from `messageCreate`. |
+| `client.scheduler` | `TaskScheduler` | Cron / interval tasks; started on ready, stopped on `destroy`. |
+| `client.cooldowns` | `CooldownManager` | Shared rate-limit state across commands and prefix commands. |
+| `client.usage` | `UsageTracker` | Records who used what to a store and/or channel. |
+| `client.logger` | `Logger` | Structured, scoped logger used across spearkit. |
+| `client.embeds` | `Embeds` | Preset embed factory behind `ctx.success/error/...`. |
+
+You rarely touch the registries directly — `register` routes items into the right
+one — but they are public for inspection and advanced control (e.g.
+`client.commands.size`, `client.commands.toJSON()`). Each subsystem has its own
+guide: [Cooldowns](./cooldown.md), [Scheduled tasks](./scheduler.md),
+[Prefix commands](./prefix.md), [Context menus](./context-menus.md),
+[Logging](./logging.md), [Usage tracking](./usage.md), [Guards](./guards.md).
 
 ## Registering handlers
 
-`client.register(...items)` accepts commands, events and components in a single
-call and routes each to its registry by kind. The accepted union is exported as
-`Registerable` (`SlashCommand | EventDef | ComponentDef`). It returns the client
-for chaining.
+`client.register(...items)` accepts commands, events, components, context-menu
+commands, prefix commands and scheduled tasks in a single call and routes each to
+its registry by kind. The accepted union is exported as `Registerable`
+(`SlashCommand | EventDef | ComponentDef | ScheduledTask | PrefixCommand |
+ContextMenuCommand`). It returns the client for chaining.
 
 ```ts
 import { SpearClient, command, event, button, option } from "spearkit";
@@ -126,8 +139,8 @@ See [Plugins](./plugins.md) for authoring `SpearPlugin`s.
 ## File-based loading
 
 `client.load(dir, options?)` recursively imports a directory and registers every
-command, event and component it exports. It returns the number of items
-registered.
+spearkit-registrable export it finds — commands, events, components, scheduled
+tasks and prefix commands. It returns the number of items registered.
 
 ```ts
 import { SpearClient } from "spearkit";
@@ -177,6 +190,31 @@ client.once("clientReady", async () => {
 });
 ```
 
+## Reliability: auto-defer and graceful shutdown
+
+A slow handler that doesn't respond within Discord's 3-second window dies with
+`Unknown interaction` (10062). Set `autoDefer` to have spearkit `deferReply()`
+automatically just before that window closes — per handler (`command({ autoDefer:
+true })`, `userCommand`/`messageCommand`) or for every slash + context-menu
+handler at once:
+
+```ts
+const client = new SpearClient({ autoDefer: true });
+// or { ephemeral: true, delayMs: 1500 } for a hidden defer / earlier fire.
+```
+
+With auto-defer on, respond via `ctx.send(...)` or `ctx.editReply(...)` — the
+initial reply slot may already be taken by the safety defer.
+
+`client.enableGracefulShutdown(options?)` closes the bot cleanly on `SIGINT` /
+`SIGTERM`: it runs an optional `onShutdown` hook, calls `destroy()` (stopping the
+scheduler and gateway), and exits, with a hard timeout so a wedged shutdown can't
+hang. It returns a disposer that removes the signal handlers.
+
+```ts
+client.enableGracefulShutdown({ onShutdown: () => db.close() });
+```
+
 ## Everything discord.js still works
 
 `SpearClient` extends discord.js `Client`, so the full client surface is

package/docs/collectors.md

@@ -0,0 +1,65 @@
+# Collectors
+
+discord.js collectors are powerful but fiddly: you wire an event emitter, set a
+`time`, write a `filter`, remember that dismissed modals need their own timeout,
+and translate the "timed out" rejection into something you can branch on.
+spearkit collapses the common cases to a single `await` that resolves to the
+result — or `null` on timeout.
+
+Beyond these, see the [pagination and confirm helpers](./api-reference.md#pagination--confirmation)
+for ready-made paged lists and yes/no gates.
+
+## Wait for a message ("type your answer")
+
+`ctx.awaitMessageFrom(userId?, options?)` waits for the next message in the
+current channel from a user (defaults to the invoking user):
+
+```ts
+await ctx.reply("What's your favourite colour?");
+const answer = await ctx.awaitMessageFrom(ctx.user.id, { time: 30_000 });
+if (answer === null) return ctx.followUp("Timed out.");
+await ctx.followUp(`Nice — ${answer.content}!`);
+```
+
+The standalone `awaitMessage(channel, options)` does the same for any text
+channel; `options` takes `{ filter, time }` (default `time` 60s).
+
+## Wait for a modal submission
+
+`ctx.awaitModal(modal, options?)` (on command and component contexts) shows a
+modal and waits for the submission — scoped to the same user and that modal's
+custom-id, always bounded — sidestepping the "Unknown interaction after a
+cancelled modal" trap:
+
+```ts
+import { modal, textInput } from "spearkit";
+
+const form = modal({
+  id: "feedback",
+  title: "Feedback",
+  fields: { text: textInput({ label: "Your feedback", required: true }) },
+  run: (ctx) => ctx.replyEphemeral("thanks"), // routed fallback
+});
+
+const submitted = await ctx.awaitModal(form.build(), { time: 120_000 });
+if (submitted === null) return; // dismissed or timed out
+await submitted.reply({ content: submitted.fields.getTextInputValue("text"), ephemeral: true });
+```
+
+This is the inline alternative to registering a separate modal handler and
+threading state through its custom-id.
+
+## Wait for a component click
+
+`awaitComponent(message, options)` waits for the next button/select interaction
+on a message. `options` takes `{ filter, time, componentType }`. You must still
+acknowledge the returned interaction (`update`/`deferUpdate`/`reply`):
+
+```ts
+import { awaitComponent } from "spearkit";
+
+const sent = await ctx.channel!.send({ content: "Pick one", components: [row] });
+const click = await awaitComponent(sent, { time: 15_000 });
+if (click === null) return;
+await click.update("Got it!");
+```

package/docs/commands.md

@@ -80,6 +80,9 @@ export const purge = command({
 | `nsfw` | `boolean` | Marks the command age-restricted. |
 | `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate (members without it don't see the command). |
 | `nameLocalizations` / `descriptionLocalizations` | `LocalizationMap` | Per-locale name/description. |
+| `cooldown` | `number \| CooldownConfig` | Rate-limit the command (a number is milliseconds). See [Cooldowns](./cooldown.md). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. See [Guards](./guards.md). |
+| `autoDefer` | `boolean \| { ephemeral?, delayMs? }` | Auto-`deferReply()` if the handler is slow (>~2s), preventing `Unknown interaction`. Respond via `ctx.send`/`ctx.editReply`. |
 
 ## Subcommands and groups
 
@@ -196,3 +199,5 @@ deploys (no `guildId`) can take up to an hour to propagate.
 - [Components](./components.md) — buttons, selects, modals.
 - [Client](./client.md) — registering and deploying from the client.
 - [Contexts](./context.md) — the reply helpers every handler shares.
+- [Cooldowns](./cooldown.md) — rate-limit a command with `cooldown`.
+- [Guards](./guards.md) — gate a command with `guards`.

package/docs/components.md

@@ -72,6 +72,10 @@ const docs = linkButton({ url: "https://example.com", label: "Docs" });
 `style` accepts the string names `"Primary"`, `"Secondary"`, `"Success"`,
 `"Danger"`, or the `ButtonStyle` enum. It defaults to `"Secondary"`.
 
+All component builders (`button`, the five selects, and `modal`) also accept
+`guards?: readonly Guard[]` — preconditions evaluated before the handler runs.
+See [Guards](./guards.md).
+
 The `ButtonContext` adds, on top of the shared [reply helpers](./context.md):
 
 | Member | Description |
@@ -202,6 +206,9 @@ namespace automatically. The `ComponentRegistry` API:
 | `size` | Number registered. |
 | `onError(handler)` | Set the error handler. |
 | `handle(interaction)` | Route an interaction; returns `true` if matched. |
+| `setDefaultGuards(guards)` | Guards run before each component's own guards. |
+
+`setLogger` and `setUsageHook` also exist; the client wires all three for you.
 
 ### Error handling
 

package/docs/context-menus.md

@@ -0,0 +1,121 @@
+# Context-menu commands
+
+Context-menu commands are the right-click **"Apps"** actions Discord shows on a
+user or a message. spearkit makes them first-class: define one with `userCommand`
+or `messageCommand`, register it like anything else, and deploy it alongside your
+slash commands. The handler gets a typed `targetUser` or `targetMessage`.
+
+```ts
+import { userCommand } from "spearkit";
+
+export const whois = userCommand({
+  name: "Who is this?",
+  run: (ctx) => ctx.replyEphemeral(`That's ${ctx.targetUser.tag}.`),
+});
+```
+
+`name` is the label shown in the Apps menu (no description — Discord does not show
+one for context-menu commands).
+
+## User vs message commands
+
+| Builder | Appears on | Target context |
+| ------- | ---------- | -------------- |
+| `userCommand` | a user (right-click → Apps) | `ctx.targetUser`, `ctx.targetMember` |
+| `messageCommand` | a message (right-click → Apps) | `ctx.targetMessage` |
+
+```ts
+import { messageCommand } from "spearkit";
+
+export const report = messageCommand({
+  name: "Report message",
+  run: (ctx) =>
+    ctx.replyEphemeral(`Reported message ${ctx.targetMessage.id}.`),
+});
+```
+
+Both handler contexts extend the shared [`BaseContext`](./context.md), so
+`ctx.reply`, `ctx.replyEphemeral`, `ctx.defer`, `ctx.success/error/...` and the
+usual accessors are all available.
+
+## Metadata, cooldowns and guards
+
+Both builders accept the same metadata, plus a `cooldown` and `guards`:
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `name` | `string` | The Apps-menu label. |
+| `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate. |
+| `nsfw` | `boolean` | Marks the command age-restricted. |
+| `guildOnly` | `boolean` | Restricts it to guild contexts. |
+| `nameLocalizations` | `LocalizationMap` | Per-locale label. |
+| `cooldown` | `number \| CooldownConfig` | Rate limit (shares `client.cooldowns`). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. |
+| `autoDefer` | `boolean \| { ephemeral?, delayMs? }` | Auto-`deferReply()` if the handler is slow, preventing `Unknown interaction`. |
+
+```ts
+import { userCommand, guildOnly, requireUserPermissions, PermissionFlagsBits } from "spearkit";
+
+export const warn = userCommand({
+  name: "Warn user",
+  guildOnly: true,
+  cooldown: 5_000,
+  guards: [requireUserPermissions(PermissionFlagsBits.ModerateMembers)],
+  run: (ctx) => ctx.replyEphemeral(`Warned ${ctx.targetUser.tag}.`),
+});
+```
+
+See [Cooldowns](./cooldown.md) and [Guards](./guards.md) for the shared options.
+
+## Registering and deploying
+
+Register context-menu commands like everything else with `client.register(...)`.
+They route automatically — spearkit dispatches user- and message-context-menu
+interactions to the matching command.
+
+```ts
+client.register(whois, report, warn);
+```
+
+Because context menus and slash commands deploy to the same Discord endpoint,
+push them together with `deployAllCommands` once you mix the two — it sends both
+in a single request. (`deployCommands` is slash-only.)
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployAllCommands({ guildId: process.env.GUILD_ID }); // slash + menus
+```
+
+`deployAllCommands` also supports a `dryRun` flag and a `strategy: "diff"` that
+skips the PUT when the remote set already matches — handy in CI:
+
+```ts
+// Preview without touching Discord:
+const result = await client.deployAllCommands({ guildId, dryRun: true });
+// → { skipped: true, reason: "dry-run", body: [...] }
+
+// Only deploy when something changed:
+await client.deployAllCommands({ guildId, strategy: "diff" });
+```
+
+## The registry
+
+`client.contextMenus` is a `ContextMenuRegistry`. The client wires it to the
+logger and cooldown manager and routes interactions for you, so you rarely touch
+it directly:
+
+```ts
+client.contextMenus.size;   // number registered
+client.contextMenus.all();  // ContextMenuCommand[]
+client.contextMenus.toJSON(); // REST payloads (also included by deployAllCommands)
+```
+
+Note: context-menu commands are **not** picked up by `client.load(...)`
+directory loading — register them explicitly with `client.register(...)`.
+
+## See also
+
+- [Commands](./commands.md) — slash commands.
+- [Client](./client.md) — `deployAllCommands` and registration.
+- [Guards](./guards.md) / [Cooldowns](./cooldown.md) — the shared preconditions.
+- [Contexts](./context.md) — the reply helpers every handler shares.

package/docs/context.md

@@ -30,7 +30,9 @@ rest extend `BaseContext`, adding their own specifics (e.g. `ctx.options`,
 | `editReply(input)` | `Promise<Message>` | Edit the original (or deferred) response. |
 | `followUp(input)` | `Promise<Message>` | Add a message after the initial response. |
 | `send(input)` | `Promise<void>` | State-aware: replies, edits, or follows up automatically. |
-| `error(message)` | `Promise<void>` | State-aware ephemeral message. |
+| `error(input, options?)` | `Promise<void>` | State-aware preset error embed; ephemeral by default. |
+| `success` / `info` / `warn` `(input, options?)` | `Promise<void>` | State-aware preset embeds. |
+| `replyError` / `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `Promise<InteractionResponse>` | Initial-reply preset embeds. |
 
 ```ts
 import { command } from "spearkit";
@@ -72,7 +74,8 @@ export default command({
 
 ### `error` for ephemeral failures
 
-`error(message)` sends a state-aware, always-ephemeral message — perfect for
+`error(input, options?)` sends a state-aware preset **error embed** — ephemeral
+by default (pass `{ ephemeral: false }` to make it public) — perfect for
 validation failures that only the invoking user should see.
 
 ```ts
@@ -89,6 +92,40 @@ export default command({
 });
 ```
 
+## Preset embeds
+
+`BaseContext` builds consistent, colored embeds from `client.embeds` (or a shared
+default). Each takes an `EmbedPresetInput` — a plain string, or a structured body
+(`{ title?, description?, fields?, footer?, ... }`) — and an optional
+`{ ephemeral? }`.
+
+| Method | Sends via | Default visibility |
+| ------ | --------- | ------------------ |
+| `success(input, options?)` | `send` (state-aware) | public |
+| `info(input, options?)` | `send` (state-aware) | public |
+| `warn(input, options?)` | `send` (state-aware) | public |
+| `error(input, options?)` | `send` (state-aware) | **ephemeral** |
+| `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `reply` (initial only) | public |
+| `replyError(input, options?)` | `reply` (initial only) | **ephemeral** |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "save",
+  description: "Save settings",
+  run: async (ctx) => {
+    await ctx.success("Settings saved.");            // green embed, public
+    await ctx.warn({ title: "Heads up", description: "Quota is almost full." });
+    // error defaults to ephemeral; make it public with { ephemeral: false }:
+    // await ctx.error("Failed to save.", { ephemeral: false });
+  },
+});
+```
+
+Configure the colors/icons with the client `embeds` option; see the
+[API reference](./api-reference.md#embeds--preset-replies).
+
 ## The `{ ephemeral: true }` shortcut
 
 discord.js represents an ephemeral reply with `flags: MessageFlags.Ephemeral`.
@@ -164,6 +201,7 @@ asEphemeral("hidden");
 | `locale` | The user's locale. |
 | `deferred` | Whether the interaction is already deferred. |
 | `replied` | Whether the interaction already received an initial response. |
+| `botPermissions` | The bot's resolved permissions in the channel (`PermissionsBitField`, zero-fetch). |
 
 ```ts
 import { command } from "spearkit";
@@ -195,6 +233,60 @@ export default button({
 });
 ```
 
+## Permission preflights
+
+`BaseContext` reads the permissions Discord already attached to the interaction —
+no extra fetches — so you can check before attempting a privileged action:
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export default command({
+  name: "slowmode",
+  description: "Set slowmode",
+  run: async (ctx) => {
+    const missing = ctx.botMissing(PermissionFlagsBits.ManageChannels);
+    if (missing.length > 0) return ctx.error(`I'm missing: ${missing.join(", ")}`);
+    // …apply slowmode…
+  },
+});
+```
+
+- `ctx.botPermissions` — the bot's `PermissionsBitField` in the current channel.
+- `ctx.botMissing(required)` — permission names the bot lacks here (`[]` if none).
+- `ctx.userMissing(required)` — permission names the invoking user lacks here.
+
+For role-hierarchy and moderation preflights (acting on self/owner, comparing top
+roles) see `moderationCheck` and the permission helpers in the
+[API reference](./api-reference.md#permissions--moderation).
+
+## Awaiting input
+
+When a flow needs a follow-up message or a modal, the context wraps discord.js
+collectors so you skip the boilerplate. Both resolve to `null` on timeout.
+
+```ts
+import { command, modal, textInput } from "spearkit";
+
+const nameModal = modal({ id: "name", title: "Your name", fields: { name: textInput({ label: "Name" }) }, run: () => {} });
+
+export default command({
+  name: "setup",
+  description: "Interactive setup",
+  run: async (ctx) => {
+    // Wait for the user to type an answer in this channel:
+    const reply = await ctx.awaitMessageFrom(ctx.user.id, { time: 30_000 });
+    if (reply === null) return ctx.error("Timed out.");
+    // Or show a modal and await its submission:
+    const submission = await ctx.awaitModal(nameModal);
+    if (submission !== null) await submission.reply(`Hi, ${submission.fields.getTextInputValue("name")}!`);
+  },
+});
+```
+
+The standalone `awaitMessage`, `awaitComponent` and `showAndAwaitModal` helpers
+are also exported; see the [API reference](./api-reference.md#collectors).
+
 ## See also
 
 - [Commands](./commands.md) — `CommandContext`, options and `showModal`.

package/docs/cooldown.md

@@ -1,6 +1,7 @@
 # Cooldowns
 
-Rate-limit commands per user, per role, per guild, per channel or globally.
+Rate-limit commands per user, per guild, per channel, or globally — with per-role
+and per-user exemptions and overrides.
 Cooldowns are enforced automatically by command dispatch: when an actor is
 still on cooldown, spearkit replies (ephemerally) with a message and the
 handler does not run.

package/docs/errors.md

@@ -0,0 +1,73 @@
+# Discord API errors
+
+discord.js reports REST failures as `DiscordAPIError` with a numeric `code`
+(`10008` "Unknown Message", `50013` "Missing Permissions", `50007` "Cannot send
+DMs to this user", …). Catching *everything* turns recoverable failures — a
+deleted message, a closed DM — into crashes or scary stack traces. spearkit gives
+you named codes, a type-narrowing predicate, and a friendly explanation.
+
+## Recognise and recover
+
+`isDiscordError(err, code?)` narrows the throw and optionally matches a code
+(or a list). Perfect for "ignore this one, re-throw the rest":
+
+```ts
+import { DiscordErrorCode, isDiscordError } from "spearkit";
+
+try {
+  await message.delete();
+} catch (err) {
+  if (isDiscordError(err, DiscordErrorCode.UnknownMessage)) return; // already gone
+  throw err;
+}
+```
+
+```ts
+// match any of several codes
+if (isDiscordError(err, [DiscordErrorCode.UnknownChannel, DiscordErrorCode.MissingAccess])) {
+  return;
+}
+```
+
+## Friendly messages
+
+`explainDiscordError(err)` returns an end-user-appropriate sentence for a
+recognised failure, or `null` otherwise (fall back to a generic message + log):
+
+```ts
+import { explainDiscordError } from "spearkit";
+
+catch (err) {
+  await ctx.error(explainDiscordError(err) ?? "Something went wrong.");
+}
+```
+
+spearkit already routes its own command/context-menu errors through
+`explainDiscordError`, so a handler that throws `Missing Permissions` shows the
+user *"I'm missing the permissions needed to do that."* instead of a generic
+error.
+
+## Named codes
+
+`DiscordErrorCode` is a curated map of the codes bots actually hit:
+
+| Name | Code | When |
+| --- | --- | --- |
+| `UnknownChannel` | 10003 | Channel gone/invisible |
+| `UnknownMessage` | 10008 | Message deleted |
+| `UnknownMember` | 10007 | Member left |
+| `UnknownInteraction` | 10062 | Token expired (the 3s window) |
+| `MissingAccess` | 50001 | No access to the resource |
+| `CannotSendMessagesToThisUser` | 50007 | DMs closed / blocked |
+| `MissingPermissions` | 50013 | Missing a permission |
+| `InteractionHasAlreadyBeenAcknowledged` | 40060 | Double-acked |
+
+(See the type for the full set — it mirrors discord.js' `RESTJSONErrorCodes`.)
+
+## Transport & rate-limit errors
+
+- `isHTTPError(err)` — a transport-level `HTTPError` (timeout, 5xx, aborted): an
+  HTTP status with no Discord JSON code.
+- `isRateLimitError(err)` — a `DiscordAPIError` with HTTP status `429`.
+  `explainDiscordError` handles this case first, returning a "try again in a
+  moment" message.