spearkit 0.3.0 → 0.4.0

package/docs/auto-defer.md

@@ -0,0 +1,74 @@
+# Auto-defer
+
+The single most common discord.js error is
+`DiscordAPIError[10062]: Unknown interaction`. An interaction token is valid for
+only **3 seconds** before your first response; any handler that awaits a database
+query or an HTTP call risks blowing past that window, after which the interaction
+is dead and every reply throws.
+
+Auto-defer removes the footgun: spearkit arms a timer when your handler starts
+and, if you haven't responded in time, calls `deferReply()` for you. The timer is
+cancelled the instant your handler replies or defers itself.
+
+## Per command
+
+```ts
+import { command, option } from "spearkit";
+
+export const weather = command({
+  name: "weather",
+  description: "Look up the weather",
+  autoDefer: true, // defers automatically if the handler takes too long
+  options: { city: option.string({ description: "City", required: true }) },
+  run: async (ctx) => {
+    const report = await fetchWeather(ctx.options.city); // slow
+    await ctx.send(`Weather in ${ctx.options.city}: ${report}`);
+  },
+});
+```
+
+> With auto-defer on, respond via `ctx.send(...)` or `ctx.editReply(...)`, not
+> `ctx.reply(...)` — the initial reply slot may already be taken by the
+> auto-defer. `ctx.send` is state-aware and always does the right thing.
+
+## Options
+
+`autoDefer` accepts `true` (defaults) or an object:
+
+```ts
+command({
+  name: "report",
+  description: "Generate a report",
+  autoDefer: { ephemeral: true, delayMs: 1500 },
+  run: async (ctx) => ctx.send("…"),
+});
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `ephemeral` | `false` | Defer as a hidden ("thinking…") response. |
+| `delayMs` | `2000` | How long to wait before the safety defer fires. Kept under the 3s cutoff. |
+
+## Client-wide default
+
+Apply auto-defer to **every** slash command and context menu; each handler can
+still override with its own `autoDefer`.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ autoDefer: true });
+```
+
+## Scope
+
+Auto-defer covers slash commands and context menus (answered with `deferReply`).
+Component handlers (buttons/selects) usually respond instantly with `update`, so
+they're not auto-deferred — call `ctx.deferUpdate()` yourself if a component
+handler does slow work.
+
+## Lower-level helpers
+
+`normalizeAutoDefer(input)` resolves `true`/object/`undefined` into an
+`AutoDeferConfig`; `armAutoDefer(interaction, config)` arms the timer and returns
+a cancel function. Both are exported for custom dispatch.

package/docs/client.md

@@ -0,0 +1,245 @@
+# Client
+
+`SpearClient` is a discord.js `Client` with command, event and component
+registries — plus interaction routing — wired up for you. You construct it the
+same way you construct a discord.js client, register your handlers, log in, and
+(optionally) push your slash commands to Discord.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+```
+
+## Constructing a client
+
+`new SpearClient(options?)` takes the same options as discord.js'
+`ClientOptions`, except `intents` may be omitted: it defaults to
+`Intents.default` (just the `Guilds` intent, enough for slash commands and
+interactions).
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+// Explicit preset.
+const a = new SpearClient({ intents: Intents.messages });
+
+// Omitted — falls back to Intents.default.
+const b = new SpearClient();
+```
+
+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
+
+`Intents` is a set of ready-made arrays of `GatewayIntentBits`. Pass one as
+`intents`, or compose your own array of `GatewayIntentBits` if you need
+something in between.
+
+| Preset | Contents |
+| ------ | -------- |
+| `Intents.none` | `[]` |
+| `Intents.default` | `[Guilds]` |
+| `Intents.guilds` | `[Guilds, GuildMembers]` |
+| `Intents.messages` | `[Guilds, GuildMessages, MessageContent]` |
+| `Intents.all` | Every intent, including privileged ones. |
+
+`Intents.messages` includes `MessageContent`, and `Intents.guilds` includes
+`GuildMembers` — both are **privileged intents**. You must enable them in the
+Discord developer portal for your application, otherwise the gateway will reject
+the connection. `Intents.all` includes every privileged intent for the same
+reason.
+
+```ts
+import { SpearClient, GatewayIntentBits } from "spearkit";
+
+// A custom intent set, mixing a preset idea with explicit bits.
+const client = new SpearClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+});
+```
+
+## 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, 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";
+
+const client = new SpearClient();
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const ready = event("clientReady", (c) => {
+  console.log(`Logged in as ${c.user.tag}`); // c: Client<true>
+});
+
+const ping = button({
+  id: "ping:{n}",
+  label: "Ping",
+  run: (ctx) => ctx.reply(`pong #${ctx.params.n}`), // n: string
+});
+
+// Commands, events and components in one call.
+client.register(greet, ready, ping);
+```
+
+## Plugins
+
+`client.use(...plugins)` installs one or more plugins, awaiting each plugin's
+`setup`. It is async and returns the client.
+
+```ts
+import { SpearClient } from "spearkit";
+import { statsPlugin } from "./plugins/stats.js";
+
+const client = new SpearClient();
+await client.use(statsPlugin);
+```
+
+See [Plugins](./plugins.md) for authoring `SpearPlugin`s.
+
+## File-based loading
+
+`client.load(dir, options?)` recursively imports a directory and registers every
+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";
+
+const client = new SpearClient();
+const count = await client.load("./src/commands");
+console.log(`Loaded ${count} handlers`);
+```
+
+See [File-based loading](./loading.md) for the layout and `LoadOptions`.
+
+## Starting and deploying
+
+`client.start(token?)` logs in. If you omit the token it falls back to the
+`DISCORD_TOKEN` environment variable, and throws if neither is present.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+// Pass a token explicitly…
+await client.start("your-token");
+
+// …or set DISCORD_TOKEN and call start() with no argument.
+await client.start();
+```
+
+`client.deployCommands({ guildId })` pushes the registered slash commands to
+Discord using the client's own authenticated REST connection — there is no
+separate token or application id to supply. Because it reads the application id
+from the logged-in client, it **must run after the client is ready**. Pass a
+`guildId` to deploy instantly to a single guild (ideal for development); omit it
+to deploy globally.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+// …register commands…
+
+await client.start(); // uses DISCORD_TOKEN
+
+// Deploy once the client is ready.
+client.once("clientReady", async () => {
+  await client.deployCommands({ guildId: process.env.GUILD_ID });
+});
+```
+
+## 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
+available unchanged. spearkit adds registries on top — it never hides what is
+underneath:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+client.on("guildCreate", (guild) => console.log(`Joined ${guild.name}`));
+client.ws.on("VOICE_SERVER_UPDATE", () => {});
+
+await client.start();
+
+console.log(client.application?.id); // application
+console.log(client.user?.tag); // user
+console.log(client.rest); // REST manager (used by deployCommands)
+
+await client.destroy(); // graceful shutdown
+```
+
+## See also
+
+- [Commands](./commands.md) — defining slash commands you register here.
+- [Plugins](./plugins.md) — bundling features for `client.use`.
+- [File-based loading](./loading.md) — populating the client from a directory.

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

@@ -0,0 +1,203 @@
+# Commands
+
+Slash commands in spearkit are defined as a single object: the metadata, the typed
+options, and the handler all live together. spearkit serialises them for discord
+and routes incoming interactions to the right handler for you.
+
+## A first command
+
+```ts
+import { command } from "spearkit";
+
+export const ping = command({
+  name: "ping",
+  description: "Check latency",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+Register it on a client (`client.register(ping)`) and deploy it (see
+[Deployment](#deployment)). That's the whole loop.
+
+## The command context
+
+The handler receives a `CommandContext`. It wraps the discord.js
+`ChatInputCommandInteraction` and adds ergonomic accessors and reply helpers.
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.options` | Resolved, fully-typed option values (see [Options](./options.md)). |
+| `ctx.commandName` | The invoked command name. |
+| `ctx.subcommand` | The invoked subcommand name, or `null`. |
+| `ctx.showModal(modal)` | Present a modal in response. |
+| `ctx.user` / `ctx.member` / `ctx.guild` / `ctx.guildId` / `ctx.channel` / `ctx.channelId` / `ctx.locale` | Actor and location accessors. |
+| `ctx.reply` / `ctx.replyEphemeral` / `ctx.defer` / `ctx.editReply` / `ctx.followUp` / `ctx.send` / `ctx.error` | Reply helpers (see [Contexts](./context.md)). |
+| `ctx.interaction` | The raw discord.js interaction, for anything not wrapped. |
+
+```ts
+import { command, option } from "spearkit";
+
+export const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    times: option.integer({ description: "Repeat count", minValue: 1, maxValue: 5 }),
+  },
+  run: (ctx) => {
+    ctx.options.text;  // string
+    ctx.options.times; // number | undefined
+    return ctx.reply({
+      content: ctx.options.text.repeat(ctx.options.times ?? 1),
+      ephemeral: true,
+    });
+  },
+});
+```
+
+Options are covered in depth in [Options](./options.md).
+
+## Command metadata
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export const purge = command({
+  name: "purge",
+  description: "Delete recent messages",
+  guildOnly: true,                                  // only usable in guilds
+  nsfw: false,                                      // age-restricted command
+  defaultMemberPermissions: PermissionFlagsBits.ManageMessages, // who sees it by default
+  nameLocalizations: { tr: "temizle" },             // localized name
+  descriptionLocalizations: { tr: "Mesajları sil" },
+  run: (ctx) => ctx.reply("…"),
+});
+```
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `guildOnly` | `boolean` | Restricts the command to guild contexts. |
+| `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
+
+For commands with subcommands, use `commandGroup` together with `subcommand`
+and (optionally) `subcommandGroup`. Each subcommand has its own typed options
+and handler; spearkit routes to the right one automatically.
+
+```ts
+import { commandGroup, subcommand, subcommandGroup, option } from "spearkit";
+
+export const admin = commandGroup({
+  name: "admin",
+  description: "Administration",
+  guildOnly: true,
+  // Direct subcommands: /admin say
+  subcommands: {
+    say: subcommand({
+      description: "Make the bot say something",
+      options: { message: option.string({ description: "Message", required: true }) },
+      run: (ctx) => ctx.reply(ctx.options.message),
+    }),
+  },
+  // Grouped subcommands: /admin users ban
+  groups: {
+    users: subcommandGroup({
+      description: "Manage users",
+      subcommands: {
+        ban: subcommand({
+          description: "Ban a member",
+          options: {
+            target: option.user({ description: "Member", required: true }),
+            reason: option.string({ description: "Reason" }),
+          },
+          run: (ctx) =>
+            ctx.reply(`Banned ${ctx.options.target.tag}: ${ctx.options.reason ?? "no reason"}`),
+        }),
+      },
+    }),
+  },
+});
+```
+
+Inside a subcommand handler, `ctx.options` is typed from *that subcommand's*
+options. There is no `switch (subcommand)` to write — spearkit dispatches by the
+invoked subcommand group/name.
+
+## The command registry
+
+`client.commands` is a `CommandRegistry`. You usually feed it through
+`client.register(...)`, but you can use it directly:
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry();
+registry.add(ping, echo, admin);
+
+registry.get("ping");   // SlashCommand | undefined
+registry.names;         // string[]
+registry.size;          // number
+registry.remove("ping"); // boolean
+registry.toJSON();      // REST payloads for all commands
+```
+
+`SpearClient` calls `registry.handle(interaction)` and
+`registry.handleAutocomplete(interaction)` for you on every interaction.
+
+### Error handling
+
+If a handler throws, spearkit catches it. By default it emits the client's `error`
+event and replies with an ephemeral "something went wrong" message. Override
+that:
+
+```ts
+client.commands.onError((error, interaction) => {
+  console.error(`/${interaction.commandName} failed`, error);
+  if (!interaction.replied && !interaction.deferred) {
+    return interaction.reply({ content: "Command failed.", ephemeral: true });
+  }
+});
+```
+
+## Deployment
+
+Commands must be registered with discord before they appear. spearkit gives you two
+ways.
+
+**From the client** (uses the client's authenticated REST; call after ready):
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId for global
+```
+
+**Standalone** (a separate deploy script, no running client needed):
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry().add(ping, echo, admin);
+await registry.deploy({
+  token: process.env.DISCORD_TOKEN,
+  applicationId: process.env.DISCORD_APP_ID,
+  guildId: process.env.GUILD_ID, // optional
+});
+```
+
+Guild deploys apply **instantly** and are ideal during development. Global
+deploys (no `guildId`) can take up to an hour to propagate.
+
+## See also
+
+- [Options](./options.md) — typed option builders, choices, autocomplete.
+- [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`.