spearkit 0.3.0 → 0.4.0

package/.claude/skills/spearkit/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: spearkit
+description: >-
+  Write and edit Discord bots built with the spearkit package ("discord.js++"):
+  type-safe slash commands, options, subcommands, autocomplete, buttons / select
+  menus / modals with custom-id routing, events, cooldowns, scheduled tasks,
+  prefix commands, guards, context menus, pagination / confirm, preset embeds,
+  structured logging, usage tracking and dotenv. Use whenever a file imports from
+  "spearkit", or when asked to build or modify a Discord bot, slash command,
+  button, select menu, modal, autocomplete, or interaction handler in a spearkit
+  project.
+---
+
+# spearkit
+
+spearkit is a developer-experience-first layer over [discord.js](https://discord.js.org).
+It **re-exports the entire discord.js surface** (so it is a drop-in replacement)
+and adds a fully type-safe API: handlers never see `any`/`unknown`. Install with
+`npm install spearkit discord.js`.
+
+When a task needs more than this file, load
+[`reference/cheatsheet.md`](reference/cheatsheet.md) (every exported symbol + ready
+recipes). The package also ships `llms-full.txt` (all docs in one file) and a
+`docs/` folder; in a consumer project they sit under `node_modules/spearkit/`.
+
+## Non-negotiable rules
+
+1. **Import only from `"spearkit"`** — spearkit's helpers *and* every discord.js
+   symbol (`Client`, `EmbedBuilder`, `GatewayIntentBits`, `REST`, `Routes`,
+   `PermissionFlagsBits`, …). Never add a separate `import … from "discord.js"`.
+2. **Use `SpearClient`** (extends discord.js `Client`; routes interactions).
+   `intents` is optional → defaults to `Intents.default` (`[Guilds]`).
+3. **Co-locate** definition + handler in one object; `client.register(...)` it.
+   **Never** write an `interactionCreate` switch or parse custom ids by hand —
+   spearkit routes commands by name and components by custom-id namespace.
+4. **Lifecycle order:** `register(...)` → `await client.start(token)` →
+   `await client.deployCommands({ guildId })`. Deploy **after** `start()`; deploy
+   only when command *definitions* change (not every restart).
+5. **The ready event is `clientReady`**, not `ready` (discord.js v14.16 rename).
+6. **Trust inference.** Required options are non-nullable, optional ones are
+   `T | undefined`, `choices` narrow to a literal union, custom-id `{param}`s and
+   modal field keys are typed. Do not cast; do not annotate handler args.
+7. **Hidden replies:** `ctx.replyEphemeral(...)` or `ctx.reply({ content, ephemeral: true })`
+   (spearkit normalizes `ephemeral`). Do not hand-set message flags.
+
+## Minimal bot
+
+```ts
+import { SpearClient, Intents, command, option, event } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // ctx.options.who: User
+});
+
+client.register(greet, event("clientReady", (c) => console.log(c.user.tag)));
+await client.start(process.env.DISCORD_TOKEN);              // falls back to DISCORD_TOKEN
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId → global (slow)
+```
+
+## Pick the right tool
+
+- **Slash command** → `command()`; **typed inputs** → `option.*`; **grouped** → `commandGroup` + `subcommand`; **type-ahead** → `option.string({ autocomplete })`.
+- **Right-click on a user/message** → `userCommand` / `messageCommand`; **`!text` command** → `prefixCommand` (+ typed `args`).
+- **Button** → `button`; **URL button** → `linkButton`; **dropdown** → `stringSelect`; **pick user/role/channel/mentionable** → `userSelect` / `roleSelect` / `channelSelect` / `mentionableSelect`; **form** → `modal` + `textInput`; **carry data** → custom-id `{param}`.
+- **Paged list** → `paginate`; **yes/no gate** → `confirm`.
+- **Reply** → `ctx.reply` / `replyEphemeral`; **>3s work** → `ctx.defer()` then `editReply`; **styled embed** → `ctx.success/error/info/warn`.
+- **Gateway events** → `event(...)`; **rate-limit** → `cooldown`; **role/permission/owner gate** → guards; **cron/interval** → `task` / `client.schedule`; **logs** → `client.logger` + sinks; **usage tracking** → `usage`; **typed env / `.env`** → `env.*`.
+- **Reusable bundle** → `definePlugin` + `client.use`; **file-per-handler** → `client.load`; **deploy** → `client.deployCommands` / `deployAllCommands`.
+- **Primitives** — per-key lock → `KeyedLock`; null-safe fetch → `safeFetch.*`; durations → `formatDuration` / `parseDuration`; timestamps → `discordTimestamp`; cache / rate-limit → `MemoryCache`; config files → `loadConfig`.
+
+## Recipes
+
+### Slash command with typed options
+
+```ts
+const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),     // string
+    times: option.integer({ description: "Count", minValue: 1, maxValue: 5 }),// number | undefined
+    mode: option.string({
+      description: "Visibility",
+      choices: [{ name: "Everyone", value: "public" }, { name: "Just me", value: "private" }],
+    }),                                                                       // "public" | "private" | undefined
+  },
+  run: (ctx) =>
+    ctx.reply({
+      content: ctx.options.text.repeat(ctx.options.times ?? 1),
+      ephemeral: ctx.options.mode === "private",
+    }),
+});
+```
+
+Option builders: `option.string|integer|number|boolean|user|channel|role|mentionable|attachment`.
+Co-located autocomplete: `option.string({ autocomplete: (ctx) => choices.filter(c => c.startsWith(ctx.value)).map(c => ({ name: c, value: c })) })`.
+
+### Subcommands
+
+```ts
+import { commandGroup, subcommand, subcommandGroup, option } from "spearkit";
+
+commandGroup({
+  name: "admin", description: "Admin tools", guildOnly: true,
+  subcommands: {
+    say: subcommand({
+      description: "Speak",
+      options: { message: option.string({ description: "Text", required: true }) },
+      run: (ctx) => ctx.reply(ctx.options.message),
+    }),
+  },
+  groups: {
+    users: subcommandGroup({
+      description: "Manage users",
+      subcommands: {
+        ban: subcommand({
+          description: "Ban", options: { target: option.user({ description: "Who", required: true }) },
+          run: (ctx) => ctx.reply(`Banned ${ctx.options.target.tag}`),
+        }),
+      },
+    }),
+  },
+});
+```
+
+### Components (button / select / modal)
+
+```ts
+import { button, stringSelect, modal, textInput, row } from "spearkit";
+
+const vote = button({
+  id: "vote:{choice}",                 // {choice} → typed param
+  label: "Yes", style: "Success",      // "Primary" | "Secondary" | "Success" | "Danger"
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // ctx.params.choice: string
+});
+
+const colour = stringSelect({
+  id: "colour",
+  options: [{ label: "Red", value: "red" }, { label: "Blue", value: "blue" }],
+  run: (ctx) => ctx.replyEphemeral(ctx.values.join(", ")),     // ctx.values: string[]
+});
+
+const feedback = modal({
+  id: "feedback:{ticket}",
+  title: "Feedback",
+  fields: {
+    summary: textInput({ label: "Summary", required: true }),
+    detail: textInput({ label: "Details", style: "Paragraph" }),
+  },
+  run: (ctx) => ctx.reply(`#${ctx.params.ticket}: ${ctx.fields.summary}`), // params + fields typed
+});
+
+client.register(vote, colour, feedback);
+
+// build() requires exactly the {param}s the id declares (ids cap at 100 chars):
+await channel.send({ content: "Choose:", components: [row(vote.build({ choice: "yes" })), row(colour.build())] });
+```
+
+Component builders: `button`, `linkButton`, `stringSelect`, `userSelect`,
+`roleSelect`, `channelSelect`, `mentionableSelect`, `modal` (+ `textInput`), `row`.
+Component context: `ctx.params`, `ctx.update`, `ctx.deferUpdate`, `ctx.showModal`,
+`ctx.message`; selects add `ctx.values` (+ `ctx.users/roles/channels/members`);
+modals add `ctx.fields`.
+
+### Guards, cooldown, context menus, pagination/confirm
+
+```ts
+import { command, requireAnyRole, guildOnly, userCommand, paginate, confirm } from "spearkit";
+
+const purge = command({
+  name: "purge", description: "Delete messages",
+  guards: [guildOnly(), requireAnyRole(["MOD_ROLE_ID"])],
+  cooldown: { duration: 10_000, scope: "user" },
+  run: (ctx) => ctx.replySuccess("Done"),
+});
+
+const report = userCommand({ name: "Report", run: (ctx) => ctx.replyEphemeral(`Reported ${ctx.targetUser.tag}`) });
+
+await paginate(ctx.interaction, items, {
+  pageSize: 10,
+  render: (slice, { page, pages }) =>
+    new EmbedBuilder().setTitle(`Page ${page + 1}/${pages}`).setDescription(slice.join("\n")),
+});
+
+const { confirmed } = await confirm(ctx.interaction, {
+  body: "Reset everything?", confirm: { label: "Reset", style: "Danger" },
+});
+if (!confirmed) return ctx.error("Cancelled.");
+```
+
+Guards usable on `command`/`prefixCommand`/`button`/`userCommand`/`messageCommand`
+configs, or client-wide via `new SpearClient({ guards: [...] })`.
+
+## Context (every handler)
+
+`reply` · `replyEphemeral` · `defer({ ephemeral? })` · `editReply` · `followUp` ·
+`send` (state-aware) · `error(msg)` · preset embeds `success/info/warn/error`
+(+ `replySuccess/Info/Warn/Error`) · accessors `client/user/member/guild/guildId/
+channel/channelId/locale` · state `deferred/replied`. Commands add `ctx.options`,
+`ctx.commandName`, `ctx.subcommand`, `ctx.showModal`.
+
+## Subsystems (configured on `SpearClient` options)
+
+- **Cooldowns** — `command({ cooldown: number | CooldownConfig })` or
+  `new SpearClient({ cooldown })`; scopes `user|guild|channel|global`, plus
+  `exempt`/`overrides`.
+- **Scheduled tasks** — `task({ name, cron?, interval?, runOnStart?, run })`,
+  `client.schedule(...)`, `client.scheduler.delay/followUp/reconcile`, `cron(expr)`.
+- **Prefix commands** — `prefixCommand({ name, aliases?, cooldown?, guards?, args?, run })`
+  + `new SpearClient({ prefix: "!" })`. Typed args:
+  `args: (a) => a.snowflake("target").duration("d").rest("reason")` → `ctx.options`.
+  Reading **other users'** content needs the privileged `MessageContent` intent —
+  use `Intents.messages` and enable it in the Developer Portal.
+- **Context menus** — `userCommand`/`messageCommand`; deploy with slash commands
+  via `client.deployAllCommands({ guildId, strategy: "diff", dryRun? })`.
+- **Logging** — `client.logger`; `new SpearClient({ logger: { level, transports: [consoleSink, jsonlSink(path), webhookSink({ url })] } })`.
+- **Usage tracking** — `new SpearClient({ usage: { store?, channel?, format? } })`;
+  `MemoryUsageStore`, `JsonFileUsageStore`.
+- **Env** — `.env` auto-loads on `start()`; read with `env.string/number/boolean/require`.
+- **Plugins** — `definePlugin({ name, setup(client) })`, then `await client.use(plugin)`.
+- **File-based loading** — `await client.load(dir)`. Imports **compiled JS**
+  (default extensions `.js/.mjs/.cjs`); build before running compiled output.
+- **Primitives** — `KeyedLock`, `safeFetch.{member,channel,message,user,guild,role,try}`,
+  `formatDuration`/`parseDuration`/`discordTimestamp`/`relativeTimestamp`,
+  `MemoryCache`, `loadConfig`.
+
+## Mistakes to avoid
+
+- Importing from `"discord.js"` (use `"spearkit"`).
+- Listening on `"ready"` instead of `"clientReady"`.
+- `deployCommands()` before `start()`, or deploying on every restart.
+- Hand-rolling an `interactionCreate` switch or splitting custom ids manually.
+- Passing wrong/missing params to `component.build(...)` (typed; pass exactly the
+  declared `{param}`s).
+- Forgetting the `MessageContent` intent when prefix commands must read other
+  users' messages.
+
+## Verify your work
+
+In a spearkit repo, run `npm run typecheck` (and `npm test`) — option values,
+custom-id params and modal fields are statically checked, so a type error usually
+means the definition and handler disagree.

package/.claude/skills/spearkit/reference/cheatsheet.md

@@ -0,0 +1,329 @@
+# spearkit cheatsheet
+
+Condensed map of every spearkit export. All importable from `"spearkit"` alongside
+the full discord.js surface. For prose and edge cases, read the package's
+`llms-full.txt` or `docs/`.
+
+## Use cases — reach for
+
+**Bot setup & lifecycle**
+
+| Want to… | Reach for |
+| --- | --- |
+| Start a bot and connect | `new SpearClient({ intents })` + `await client.start(token)` |
+| Choose gateway intents | `Intents.none / default / guilds / messages / all` |
+| Wire up handlers | `client.register(...)`; one file per handler → `client.load(dir)` |
+| Push commands to Discord | `client.deployCommands({ guildId })`; slash + menus, safe CI → `client.deployAllCommands({ strategy: "diff", dryRun })` |
+| Package a reusable feature | `definePlugin(...)` + `client.use(...)` |
+| Migrate an existing discord.js bot | import from `"spearkit"`, swap `Client` → `SpearClient` |
+
+**Commands & input**
+
+| Want to… | Reach for |
+| --- | --- |
+| A slash command | `command({ name, description, run })` |
+| Typed inputs to a command | `options: { x: option.string/integer/number/boolean/user/channel/role/mentionable/attachment(...) }` |
+| Group many commands under one name | `commandGroup` + `subcommand` / `subcommandGroup` |
+| Suggest values while the user types | `option.string({ autocomplete })` |
+| A right-click "Apps" action on a user/message | `userCommand` / `messageCommand` |
+| A classic `!text` command | `prefixCommand(...)` + `new SpearClient({ prefix })` |
+| Parse `!cmd` arguments into typed values | `args: (a) => a.snowflake().duration().rest()` → `ctx.options` |
+
+**Interactivity (components)**
+
+| Want to… | Reach for |
+| --- | --- |
+| A clickable button | `button({ id, run })` → `row(btn.build(...))` |
+| A URL button (no handler) | `linkButton` |
+| A dropdown of fixed options | `stringSelect` |
+| Pick users / roles / channels / mentionables | `userSelect` / `roleSelect` / `channelSelect` / `mentionableSelect` |
+| A form with text fields | `modal` + `textInput` |
+| Carry data through a component | custom-id params `id: "x:{id}"` → `ctx.params.id` |
+| A paged list with next/prev | `paginate(...)` |
+| An "Are you sure?" yes/no gate | `confirm(...)` |
+
+**Replies & UX**
+
+| Want to… | Reach for |
+| --- | --- |
+| Reply, public or hidden | `ctx.reply(...)` / `ctx.replyEphemeral(...)` |
+| Work that takes >3s | `ctx.defer()` then `ctx.editReply(...)` |
+| A styled success/error/info/warn embed | `ctx.success/error/info/warn(...)` |
+| "Reply, edit, or follow-up — whichever fits" | `ctx.send(...)` |
+
+**Cross-cutting concerns**
+
+| Want to… | Reach for |
+| --- | --- |
+| React to gateway events | `event(name, run)`; once on startup → `event("clientReady", ...)` |
+| Rate-limit a command/handler | `cooldown` (per-command or client-wide) |
+| Restrict by role / permission / owner / guild | guards: `requireAnyRole` / `requireUserPermissions` / `requireOwner` / `guildOnly` |
+| Run jobs on cron or interval | `task({ cron \| interval })` / `client.schedule(...)` |
+| Delay once / staged follow-ups / recover on restart | `client.scheduler.delay` / `followUp` / `reconcile` |
+| Structured logs to file/webhook | `client.logger` + `consoleSink` / `jsonlSink` / `webhookSink` |
+| Track who used what | `new SpearClient({ usage })` + `MemoryUsageStore` / `JsonFileUsageStore` |
+| Read typed env / load `.env` | `env.string/number/boolean/require` (auto-loaded on `start()`) |
+
+**Utilities (primitives)**
+
+| Want to… | Reach for |
+| --- | --- |
+| Stop concurrent runs per key (e.g. per user) | `KeyedLock` |
+| Fetch that returns `null` instead of throwing | `safeFetch.{member,channel,message,user,guild,role}` |
+| Format/parse `"1h30m"` durations | `formatDuration` / `parseDuration` |
+| Render `<t:…>` Discord timestamps | `discordTimestamp` / `relativeTimestamp` |
+| In-memory cache / counters / rate-limit window | `MemoryCache` |
+| Load JSON/JSON5/YAML config | `loadConfig` |
+
+## Client
+
+```ts
+new SpearClient(options?: Partial<ClientOptions> & SpearOptions) // intents optional → Intents.default; SpearOptions: logger/dotenv/cooldown/prefix/usage/embeds/guards
+client.commands   // CommandRegistry
+client.events     // EventRegistry
+client.components // ComponentRegistry
+client.register(...items)            // route SlashCommand | EventDef | ComponentDef | PrefixCommand | ContextMenu | ScheduledTask
+client.use(...plugins): Promise<this>
+client.load(dir, options?): Promise<number>            // imports compiled JS (.js/.mjs/.cjs)
+client.start(token?): Promise<this>                    // login; falls back to DISCORD_TOKEN
+client.deployCommands({ guildId? }): Promise<DeployResult>      // after start()
+client.deployAllCommands({ guildId?, applicationId?, strategy?: "diff", dryRun? }) // slash + context menus
+client.schedule(taskConfig); client.scheduler          // TaskScheduler
+client.enableGracefulShutdown({ onShutdown?, timeoutMs? }): () => void  // clean SIGINT/SIGTERM teardown
+client.cooldowns; client.prefix; client.usage; client.logger; client.embeds; client.contextMenus
+new SpearClient({ autoDefer: true })   // default auto-defer for slash + context-menu handlers
+
+const Intents = { none: [], default: [Guilds], guilds: [Guilds, GuildMembers],
+                  messages: [Guilds, GuildMessages, MessageContent], all: /* every intent */ }
+```
+
+## Commands & options
+
+```ts
+command({ name, description, options?, defaultMemberPermissions?, nsfw?, guildOnly?,
+          nameLocalizations?, descriptionLocalizations?, guards?, cooldown?, autoDefer?, run })
+commandGroup({ name, description, subcommands?, groups?, defaultMemberPermissions?, nsfw?, guildOnly?, ... })
+subcommand({ description, options?, run, ... })
+subcommandGroup({ description, subcommands, ... })
+
+option.string({ description, required?, choices?, minLength?, maxLength?, autocomplete? })   // string
+option.integer({ description, required?, choices?, minValue?, maxValue?, autocomplete? })    // number
+option.number(...)   // number
+option.boolean(...)  // boolean
+option.user(...)     // User
+option.channel({ ..., channelTypes? }) // channel union
+option.role(...)     // Role | APIRole
+option.mentionable(...) // user/role/member
+option.attachment(...)  // Attachment
+
+// choices: { name, value, nameLocalizations? }[]   (value narrows the resolved type to a literal union)
+// autocomplete: (ctx: AutocompleteContext) => Awaitable<OptionChoice[]>   ctx.value / ctx.respond(...)
+```
+
+`CommandContext`: `options`, `commandName`, `subcommand`, `showModal(modal)` + BaseContext.
+
+## Components
+
+```ts
+button({ id, label?, style?, emoji?, disabled?, guards?, run })   // style: "Primary"|"Secondary"|"Success"|"Danger"|ButtonStyle.*
+linkButton({ url, label?, emoji?, disabled? })                    // returns ButtonBuilder (no handler)
+stringSelect({ id, options, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+userSelect / roleSelect / mentionableSelect ({ id, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+channelSelect({ id, channelTypes?, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+modal({ id, title, fields, run })   // fields: Record<string, TextInputDef>
+textInput({ label, style?, placeholder?, required?, minLength?, maxLength?, value? }) // style: "Short"|"Paragraph"
+row(...components): ActionRowBuilder
+
+component.build(params?)  // requires exactly the {param}s in id; no args when none
+
+// id pattern: "name" or "name:{a}:{b}"   →  ctx.params.a, ctx.params.b (string)
+// MAX_CUSTOM_ID_LENGTH = 100
+```
+
+Contexts: `ButtonContext` (params); `StringSelectContext` (values, value);
+`UserSelectContext`/`MentionableSelectContext` (values, users, members[, roles]);
+`RoleSelectContext` (values, roles); `ChannelSelectContext` (values, channels);
+`ModalContext` (params, fields). All component contexts: `update`, `deferUpdate`,
+`showModal`, `message`, `customId`.
+
+## Events
+
+```ts
+event("clientReady", (c) => ...)              // name from discord.js ClientEvents (args inferred)
+event({ name, once?, run })
+// errors + rejections route to the client's "error" event
+```
+
+## Contexts (BaseContext — every handler)
+
+```ts
+reply(input) · replyEphemeral(input) · defer({ ephemeral? }) · editReply(input) ·
+followUp(input) · send(input)
+success(input) · info(input) · warn(input) · error(input)                 // preset embeds, state-aware
+replySuccess/replyInfo/replyWarn/replyError(input)
+client · user · member · guild · guildId · channel · channelId · locale · deferred · replied
+botPermissions · botMissing(perm) · userMissing(perm)                      // permission preflight (zero-fetch)
+awaitMessageFrom(userId?, { time?, filter? }) · awaitModal(modal, { time?, filter? })  // → T | null
+// ReplyInput = string | (InteractionReplyOptions & { ephemeral?: boolean })
+```
+
+## Guards
+
+```ts
+guildOnly(reason?) · dmOnly(reason?) · requireAnyRole(ids, reason?) · requireAllRoles(ids, reason?)
+requireOwner(ownerIds, reason?) · requireUserPermissions(perm, reason?) · requireBotPermissions(perm, reason?)
+guard(predicate) · denied(reason?)
+// per-handler: { guards: [...] } on command/prefixCommand/button/userCommand/messageCommand
+// client-wide:  new SpearClient({ guards: [...] })
+```
+
+## Cooldowns
+
+```ts
+command({ cooldown: number | CooldownConfig })
+new SpearClient({ cooldown: CooldownConfig })
+CooldownConfig = { duration, scope?: "user"|"guild"|"channel"|"global",
+                   exempt?: { users?, roles? }, overrides?: { users?, roles? },
+                   message?: string | ((remainingMs) => string) }
+```
+
+## Scheduler
+
+```ts
+task({ name, cron?, interval?, runOnStart?, run: (client) => ... })   // register() it
+client.schedule(config)
+cron(expr).next(from?: Date): Date
+client.scheduler.delay(name, ms, fn) -> { cancel() }
+client.scheduler.followUp(name, [10_000, 30_000], (i) => ...) -> { cancel() }
+client.scheduler.reconcile(name, async (client) => ...)   // once on ready
+```
+
+## Prefix commands
+
+```ts
+new SpearClient({ prefix: "!" | string[] | { prefix, mention?, ignoreBots?, caseInsensitive? } })
+prefixCommand({ name, aliases?, description?, cooldown?, guards?, args?, run })
+// PrefixContext: message, commandName, args: string[], rest: string, reply, send, options (when args used)
+prefixArgs() builder: .string(n) .integer(n) .number(n) .boolean(n) .snowflake(n) .duration(n) .rest(n)
+prefixCommand({ args: (a) => a.snowflake("target").duration("d").rest("reason"), run: (ctx) => ctx.options })
+// reading other users' content requires the privileged MessageContent intent (Intents.messages)
+```
+
+## Context menus
+
+```ts
+userCommand({ name, guards?, cooldown?, run: (ctx) => ctx.targetUser / ctx.targetMember })
+messageCommand({ name, guards?, cooldown?, run: (ctx) => ctx.targetMessage })
+// deploy with slash commands via client.deployAllCommands(...)
+```
+
+## Pagination & confirm
+
+```ts
+paginate(interaction, items, { render, pageSize?, user?, timeoutMs?, controls?: "prev-next"|"first-prev-next-last", ephemeral?, labels?, namespace? })
+buildPaginatorPage(items, page, options) -> { payload, pages }
+confirm(interaction, { body, title?, confirm?, cancel?, user?, timeoutMs?, ephemeral?, namespace? })
+  -> { confirmed: boolean, reason: "confirm"|"cancel"|"timeout", interaction? }
+```
+
+## Embeds
+
+```ts
+client.embeds.{ error|success|info|warn|build(level, input) }
+new Embeds(opts?); defaultEmbeds   // shared default used when client.embeds is unset
+new SpearClient({ embeds: { /* colors/icons per level */ } })
+// BaseContext exposes ctx.success/info/warn/error + replySuccess/Info/Warn/Error
+```
+
+## Logging
+
+```ts
+new Logger({ level, transports: [consoleSink, jsonlSink("./logs/bot.jsonl"), webhookSink({ url, minLevel: "error" })] })
+logger.debug/info/warn/error(message, { error?, data? }); logger.child(scope); logger.setLevel(level); logger.enabled(level)
+logger.addTransport(sink); logger.setTransports([sinks])
+new SpearClient({ logger: { level: "debug" } })   // client.logger
+```
+
+## Usage tracking
+
+```ts
+new SpearClient({ usage: { store?, channel?, format? } })   // client.usage
+MemoryUsageStore  // record, all, size, byUser(id), clear
+JsonFileUsageStore(path)
+// UsageEvent { type: "command"|"prefix"|"component"|"event", name, userId?, userTag?, guildId?, channelId?,
+//              detail?, outcome?: "success"|"error", durationMs?, errorMessage?, options?, timestamp }
+```
+
+## Env
+
+```ts
+loadEnv({ path?, override? }); parseEnv(content)
+env.string(k, fallback?) · env.number(k, fallback?) · env.boolean(k, fallback?) · env.require(k)
+// SpearClient auto-loads .env on start(); configure/disable via the `dotenv` option
+```
+
+## Plugins & loading
+
+```ts
+definePlugin({ name, setup(client) }); await client.use(plugin)
+collectModules(dir, options?); loadInto(client, dir, options?)
+client.load(dir, { extensions?: readonly string[], recursive? })  // defaults [.js,.mjs,.cjs], true
+```
+
+## Primitives
+
+```ts
+new KeyedLock(); lock.tryAcquire(key, ttl?); lock.run(key, fn, { onBusy?, ttl? }); lock.isHeld(key); lock.forget(key); lock.dispose()
+safeFetch.{ member, channel, message, user, guild, role, try }  // each returns T | null
+withSafeTimeout(promise, ms)  // T | null
+formatDuration(ms, { locale?: string | custom-labels, largest?, units? })  // "en"|"en-US"|"en-GB"|"tr"|"tr-TR" or a custom label set
+parseDuration(input): number | null
+discordTimestamp(date, style?: "t"|"T"|"d"|"D"|"f"|"F"|"R"); relativeTimestamp(date)
+new MemoryCache()  // CacheStore: get/set/delete/has/increment/rateLimit/clear (TTL + counters + fixed-window rate limit)
+loadConfig({ file, parser?, schema?, encoding? }); loadConfigAsync(opts)   // JSON/JSON5/YAML
+lookup(table, resourceName?) -> (key) => value
+```
+
+## Reliability, permissions, storage & collectors
+
+```ts
+// Auto-defer — dodge "Unknown interaction" (10062) on slow handlers
+command({ autoDefer: true | { ephemeral?, delayMs? } }); new SpearClient({ autoDefer: true })
+armAutoDefer(interaction, config) -> cancel(); normalizeAutoDefer(input); DEFAULT_AUTO_DEFER_DELAY_MS = 2000
+
+// Graceful shutdown
+client.enableGracefulShutdown({ signals?, timeoutMs?, exit?, onShutdown?, logger? }) -> dispose()
+gracefulShutdown(client, options)   // standalone variant
+
+// Permissions & moderation
+missingPermissions(channel, who, required) -> PermissionsString[]; botMissingPermissions(channel, required)
+hasPermissions(channel, who, required); compareRoles(a, b); canActOn(actor, target); formatPermissions(perm)
+moderationCheck({ moderator, target, me?, action? }) -> { ok: true } | { ok: false, reason }
+
+// Persistent storage + per-guild settings
+new MemoryStore(); new JsonStore(path)   // KeyValueStore: get/set/has/delete/keys/clear
+namespaced(store, prefix)
+createSettings({ store, defaults, namespace? }) -> { defaults, store, get(id), set(id, patch), reset(id) }
+
+// Collectors (all resolve null on timeout)
+awaitMessage(channel, { filter?, time? }); awaitComponent(message, { filter?, time?, componentType? })
+showAndAwaitModal(interaction, modal, { time?, filter? })
+
+// Discord errors
+isDiscordError(err, DiscordErrorCode.UnknownMessage?); isHTTPError(err); isRateLimitError(err)
+explainDiscordError(err) -> string | null; DiscordErrorCode.{ UnknownMessage, UnknownInteraction, MissingPermissions, ... }
+
+// Message formatting
+truncate(text, max, suffix?); chunkMessage(text, { max? }) -> string[]; MESSAGE_CHARACTER_LIMIT = 2000
+
+// Dynamic prefixes
+new SpearClient({ prefix: { prefix?, dynamic: (message) => string | string[] | null } })
+```
+
+## Error handling
+
+```ts
+client.commands.onError((error, interaction) => interaction.reply({ content: "Oops.", flags: 64 }))
+client.components.onError((error, interaction) => console.error(error))
+// handler errors never crash the process; uncaught ones flow through client.logger
+```