spearkit 0.3.0 → 0.4.0

package/docs/guards.md

@@ -0,0 +1,146 @@
+# Guards
+
+Guards are declarative **preconditions** that run before a handler. They work
+uniformly across slash commands, components (buttons, selects, modals), prefix
+commands and context-menu commands — and can also be applied client-wide. A
+guard returns `true` to allow the handler, or a denial (with an optional reason)
+to block it; spearkit replies with the reason and the handler never runs.
+
+```ts
+import { command, requireUserPermissions, PermissionFlagsBits } from "spearkit";
+
+export const purge = command({
+  name: "purge",
+  description: "Bulk-delete messages",
+  guards: [requireUserPermissions(PermissionFlagsBits.ManageMessages)],
+  run: (ctx) => ctx.reply("Purged."),
+});
+```
+
+## Where guards attach
+
+Pass `guards: [...]` to any handler definition, or set client-wide defaults that
+run before every handler's own guards.
+
+```ts
+import {
+  SpearClient,
+  command,
+  button,
+  prefixCommand,
+  userCommand,
+  guildOnly,
+} from "spearkit";
+
+// Per-handler — on commands, components, prefix and context-menu commands.
+command({ name: "kick", description: "…", guards: [guildOnly()], run: () => {} });
+button({ id: "del:{id}", guards: [guildOnly()], run: () => {} });
+prefixCommand({ name: "ban", guards: [guildOnly()], run: () => {} });
+userCommand({ name: "Report", guards: [guildOnly()], run: () => {} });
+
+// Client-wide — applied before each handler's own guards.
+const client = new SpearClient({ guards: [guildOnly()] });
+```
+
+Client-wide guards run first; if they pass, the handler's own guards run next.
+The first denial short-circuits the rest.
+
+## Built-in guards
+
+Each built-in returns a `Guard` and accepts an optional custom `reason`. When
+omitted, a sensible default message is used (shown below).
+
+| Guard | Denies unless… | Default reason |
+| ----- | -------------- | -------------- |
+| `guildOnly(reason?)` | used inside a guild | `"This can only be used in a server."` |
+| `dmOnly(reason?)` | used in a DM | `"This can only be used in DMs."` |
+| `requireAnyRole(roleIds, reason?)` | the member holds **any** of `roleIds` | `"You don't have permission to use this."` |
+| `requireAllRoles(roleIds, reason?)` | the member holds **every** id in `roleIds` | `"You're missing one of the required roles."` |
+| `requireOwner(ownerIds, reason?)` | the user id is in `ownerIds` | `"This is owner-only."` |
+| `requireUserPermissions(permission, reason?)` | the member has the Discord `permission` | `"You don't have permission to use this."` |
+| `requireBotPermissions(permission, reason?)` | the bot's member has the Discord `permission` | `"I don't have permission to do that here."` |
+
+```ts
+import {
+  command,
+  requireAnyRole,
+  requireBotPermissions,
+  PermissionFlagsBits,
+} from "spearkit";
+
+export const announce = command({
+  name: "announce",
+  description: "Post an announcement",
+  guards: [
+    requireAnyRole(["111111111111111111"], "Staff only."),
+    requireBotPermissions(PermissionFlagsBits.SendMessages),
+  ],
+  run: (ctx) => ctx.reply("Announced."),
+});
+```
+
+## Custom guards
+
+`guard(predicate)` wraps an inline predicate so a one-off check still types as a
+`Guard`. The predicate receives a `GuardContext` and returns a `GuardResult`;
+use `denied(reason?)` to build a denial.
+
+```ts
+import { command, guard, denied } from "spearkit";
+
+const cooldownOver = guard((ctx) =>
+  isReady(ctx.user.id) ? true : denied("Still warming up — try again soon."),
+);
+
+export const cast = command({
+  name: "cast",
+  description: "Cast a spell",
+  guards: [cooldownOver],
+  run: (ctx) => ctx.reply("✨"),
+});
+```
+
+`GuardContext` exposes the actor/location fields every handler shares, so the
+same guard works on commands, components, prefix and context-menu handlers:
+
+```ts
+interface GuardContext {
+  client: Client;
+  user: User;
+  member: GuildMember | APIInteractionGuildMember | null;
+  guild: Guild | null;
+  guildId: string | null;
+  channelId: string | null;
+}
+
+type GuardResult = boolean | { allowed: false; reason?: string };
+type Guard<TCtx extends GuardContext = GuardContext> = (ctx: TCtx) => Awaitable<GuardResult>;
+```
+
+## Running guards manually
+
+`runGuards(ctx, guards)` evaluates a list in order and short-circuits on the
+first denial — useful if you build your own dispatch on top of spearkit.
+
+```ts
+import { runGuards, guildOnly } from "spearkit";
+
+const result = await runGuards(ctx, [guildOnly()]);
+if (!result.allowed) {
+  // result.reason is the denial message (or undefined)
+}
+```
+
+`runGuards` resolves to `RunGuardsResult`:
+
+```ts
+type RunGuardsResult = { allowed: true } | { allowed: false; reason: string | undefined };
+```
+
+## See also
+
+- [Commands](./commands.md) — `guards` on slash commands.
+- [Components](./components.md) — `guards` on buttons, selects and modals.
+- [Prefix commands](./prefix.md) — `guards` on text commands.
+- [Context menus](./context-menus.md) — `guards` on "Apps" actions.
+- [Cooldowns](./cooldown.md) — the other built-in precondition.

package/docs/loading.md

@@ -0,0 +1,144 @@
+# File-based loading
+
+Instead of importing and registering every handler by hand, you can keep one
+handler per file and let spearkit discover them. The loader imports a directory,
+inspects each module's exports, and registers everything that is a command,
+event, component, scheduled task or prefix command.
+
+## `client.load`
+
+```ts
+load(dir: string, options?: LoadOptions): Promise<number>
+```
+
+`client.load` imports `dir` and registers every spearkit-registrable export it finds,
+resolving to the number of items registered.
+
+```ts
+import { fileURLToPath } from "node:url";
+import { SpearClient, Intents } from "spearkit";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+
+const client = new SpearClient({ intents: Intents.default });
+
+const loaded =
+  (await client.load(`${here}commands`)) +
+  (await client.load(`${here}events`)) +
+  (await client.load(`${here}components`));
+console.log(`Loaded ${loaded} modules.`);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+### What gets registered
+
+For every imported file, spearkit walks **all** of its exports — default *and*
+named — and registers each value that is a command (`command`, `commandGroup`),
+an event (`event`), a component (`button`, `stringSelect`, `modal`, …), a
+scheduled task (`task`) or a prefix command (`prefixCommand`). Other exports
+(helpers, constants, types) are ignored, and context-menu commands are **not**
+auto-detected — register those explicitly. So both of these are picked up:
+
+```ts
+// default export
+export default command({ name: "ping", description: "…", run: (ctx) => ctx.reply("pong") });
+```
+
+```ts
+// named export
+export const vote = button({ id: "vote:{choice}", label: "Vote", run: (ctx) => ctx.update(ctx.params.choice) });
+```
+
+### Options
+
+```ts
+interface LoadOptions {
+  extensions?: readonly string[]; // default: [".js", ".mjs", ".cjs"]
+  recursive?: boolean;            // default: true
+}
+```
+
+- **`extensions`** — which file extensions to import. By default the loader reads
+  `.js`, `.mjs` and `.cjs` — i.e. **compiled JavaScript**, not `.ts` source.
+- **`recursive`** — by default the loader descends into subdirectories. Pass
+  `recursive: false` to load only the top level.
+
+```ts
+await client.load(`${here}features`, { recursive: false });
+```
+
+> The loader imports compiled JavaScript. **Build your TypeScript first**, then run
+> (and load) the emitted output — `npx tsc && node dist/index.js`. Loading a
+> directory of `.ts` source files will not match the default extensions.
+
+## Standalone helpers
+
+`client.load` is the method form of `loadInto`. Both helpers are exported if you
+want to collect or register modules separately.
+
+```ts
+collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>
+loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>
+```
+
+- **`collectModules`** imports a directory and returns the registrable exports it
+  found, without touching any client. Use it to inspect, filter, or combine
+  modules before registering.
+- **`loadInto`** calls `collectModules` and then `client.register(...)` for you,
+  returning the count.
+
+```ts
+import { collectModules, loadInto } from "spearkit";
+
+// Inspect before registering:
+const items = await collectModules(`${here}commands`);
+console.log(`Found ${items.length} modules`);
+client.register(...items);
+
+// Or do both in one step:
+const count = await loadInto(client, `${here}events`);
+```
+
+## Example layout
+
+The `examples/file-based-loading` project keeps each handler in its own file:
+
+```
+file-based-loading/
+  index.ts            # construct client, load each folder, start, deploy
+  commands/
+    ping.ts           # export default command({ ... })
+    echo.ts           # export default command({ ... })
+  events/
+    ready.ts          # export default event("clientReady", ...)
+  components/
+    vote.ts           # export const vote = button({ ... })
+```
+
+A command file looks like this:
+
+```ts
+// commands/echo.ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    loud: option.boolean({ description: "Shout it" }),
+  },
+  // text: string, loud: boolean | undefined
+  run: (ctx) => ctx.reply(ctx.options.loud ? ctx.options.text.toUpperCase() : ctx.options.text),
+});
+```
+
+Build the project, then run the compiled `index.js`; `client.load` will import the
+emitted `.js` files and register `ping`, `echo`, `ready` and `vote` for you.
+
+## See also
+
+- [Client](./client.md) — `load`, `register`, and the registries the loader writes to.
+- [Events](./events.md) — the `event()` helper that event modules export.

package/docs/logging.md

@@ -0,0 +1,195 @@
+# Logging
+
+spearkit ships a small, dependency-free structured logger. Every client owns one
+at `client.logger`, and spearkit routes its own command, component, event, and
+gateway errors through it. You can use the same logger for your code, or build a
+standalone one.
+
+## A first logger
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // level "info", logs to the console
+log.info("bot starting");
+log.error("connection lost", { error: new Error("ECONNRESET") });
+```
+
+A logger is constructed from `LoggerOptions`:
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({
+  level: "debug",   // minimum severity to emit; default "info"
+  scope: "worker",  // a prefix attached to every entry
+  // sink: consoleSink (the default)
+});
+```
+
+## Levels
+
+There are four levels, lowest to highest: `debug`, `info`, `warn`, `error`. The
+logger emits an entry only if its level is at or above the configured threshold.
+The default threshold is **`info`**, so `debug` entries are suppressed until you
+lower it. A fifth threshold, `"silent"`, suppresses everything.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // threshold "info"
+log.debug("only visible at debug"); // suppressed by default
+log.info("visible");
+
+log.setLevel("debug");        // now debug entries are emitted too
+log.enabled("debug");         // true
+log.setLevel("silent");       // suppress everything
+```
+
+| Method | Level | Use for |
+| ------ | ----- | ------- |
+| `log.debug(msg, opts?)` | `debug` | Verbose diagnostics, off by default. |
+| `log.info(msg, opts?)` | `info` | Normal operational messages. |
+| `log.warn(msg, opts?)` | `warn` | Recoverable problems worth attention. |
+| `log.error(msg, opts?)` | `error` | Failures; attach the cause via `{ error }`. |
+
+`log.level` reads the current threshold, `log.setLevel(level)` changes it, and
+`log.enabled(level)` reports whether an entry of that level would be emitted —
+handy to guard expensive message construction.
+
+## Scopes and child loggers
+
+`log.child("scope")` returns a child logger whose entries carry an extra scope
+segment. A child **shares its parent's threshold and sink**, so changing the
+level on any logger in the tree affects them all.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({ scope: "app" });
+const db = log.child("db");      // scope "app:db"
+const cache = db.child("cache"); // scope "app:db:cache"
+
+db.info("connected");
+log.setLevel("debug");           // affects log, db, and cache
+cache.debug("warm");             // now emitted
+```
+
+spearkit uses this internally: the client creates `commands`, `components`,
+`events`, `scheduler`, `prefix`, and `usage` children off `client.logger`, so
+every subsystem's output is scoped and a single `setLevel` controls them all.
+
+## Structured `data` and `error`
+
+Both arguments live in the optional second parameter (`LogOptions`):
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger();
+
+log.info("command finished", {
+  data: { command: "ping", ms: 12, cached: true },
+});
+
+try {
+  throw new Error("kaboom");
+} catch (cause) {
+  log.error("handler failed", {
+    error: cause instanceof Error ? cause : new Error(String(cause)),
+    data: { command: "purge", guildId: "123" },
+  });
+}
+```
+
+`data` is a flat record of primitives (`string | number | boolean | bigint |
+null | undefined`). `error` is an `Error`; the default sink renders its stack.
+
+### Coercing unknown throws
+
+A `catch` binding is `unknown`. `toError(value)` turns any thrown value into an
+`Error` so it fits `{ error }`:
+
+```ts
+import { Logger, toError } from "spearkit";
+
+const log = new Logger();
+try {
+  JSON.parse("{");
+} catch (cause) {
+  log.error("parse failed", { error: toError(cause) });
+}
+```
+
+## Custom sinks
+
+A sink is `(entry: LogEntry) => void`. The default is `consoleSink`, which writes
+human-readable lines to the console (stderr for `warn`/`error`). Pass your own to
+route entries anywhere — JSON lines, a file, an aggregator:
+
+```ts
+import { Logger, type LogEntry } from "spearkit";
+
+const log = new Logger({
+  level: "debug",
+  sink: (entry: LogEntry) => {
+    process.stdout.write(
+      JSON.stringify({
+        level: entry.level,
+        message: entry.message,
+        scope: entry.scope,
+        at: entry.timestamp.toISOString(),
+        data: entry.data,
+        error: entry.error?.message,
+      }) + "\n",
+    );
+  },
+});
+
+log.child("commands").info("dispatched", { data: { name: "ping" } });
+```
+
+A `LogEntry` is the fully-resolved record handed to the sink:
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `level` | `LogLevel` | One of `debug`/`info`/`warn`/`error`. |
+| `message` | `string` | The log message. |
+| `scope` | `string \| undefined` | The accumulated scope, if any. |
+| `timestamp` | `Date` | When the entry was created. |
+| `error` | `Error \| undefined` | The attached error, if any. |
+| `data` | `Record<string, LogValue> \| undefined` | The structured metadata, if any. |
+
+## Configuring via the client
+
+Pass `logger` to `SpearClient`. Give it `LoggerOptions` to build one, or a
+`Logger` instance you already have:
+
+```ts
+import { SpearClient, Logger } from "spearkit";
+
+// Build from options:
+const a = new SpearClient({ logger: { level: "debug" } });
+
+// Or reuse an instance (e.g. one shared with non-Discord code):
+const shared = new Logger({ level: "info", scope: "svc" });
+const b = new SpearClient({ logger: shared });
+
+a.logger.info("ready");
+```
+
+The client logs all command, component, and event handler errors plus gateway
+errors through `client.logger`. Set `level: "debug"` to see dispatch traces from
+every subsystem:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ logger: { level: "debug" } });
+// client.logger.child("commands"), ".child('events')", etc. all log at debug now
+```
+
+## See also
+
+- [Client](./client.md) — the `logger` and other construction options.
+- [Environment & dotenv](./env.md) — load configuration before you start.

package/docs/messages.md

@@ -0,0 +1,35 @@
+# Messages & limits
+
+Discord caps a message's `content` at **2000 characters**. Long output — a log
+dump, a list, an AI response — silently fails or throws unless you split it.
+spearkit ships two helpers (in addition to the duration/timestamp formatters; see
+the [API reference](./api-reference.md)).
+
+## Split long output
+
+`chunkMessage(text, options?)` breaks text into chunks that each fit the limit,
+preferring line boundaries (and word boundaries for an over-long single line) so
+you never lose the tail:
+
+```ts
+import { chunkMessage } from "spearkit";
+
+const parts = chunkMessage(hugeLog); // default max = 2000
+await ctx.reply(parts[0] ?? "(empty)");
+for (const part of parts.slice(1)) await ctx.followUp(part);
+```
+
+Pass `{ max }` to target a smaller budget (e.g. inside a code block or embed
+description). `MESSAGE_CHARACTER_LIMIT` (2000) is exported as the default.
+
+## Truncate
+
+`truncate(text, max, suffix?)` cuts text to `max` characters, appending the
+suffix (default `…`) — the result, suffix included, never exceeds `max`:
+
+```ts
+import { truncate } from "spearkit";
+
+embed.setFooter({ text: truncate(reason, 100) });
+truncate("a very long reason", 10); // → "a very lo…"
+```

package/docs/migration.md

@@ -0,0 +1,160 @@
+# Migrating from discord.js
+
+spearkit re-exports the entire discord.js surface, so adopting it is not a rewrite —
+it is a one-line import change followed by *optional*, incremental cleanup. You can
+move to spearkit today and start using its ergonomic helpers whenever you like.
+
+## The drop-in story
+
+Change `from "discord.js"` to `from "spearkit"`. Nothing else has to change: every
+discord.js export is available under the same name with the same types.
+
+```ts
+// before
+import { Client, EmbedBuilder, GatewayIntentBits } from "discord.js";
+
+// after — identical behaviour
+import { Client, EmbedBuilder, GatewayIntentBits } from "spearkit";
+```
+
+The full classic surface is there — builders, enums, the REST client, route
+helpers, the `Events` map, and so on:
+
+```ts
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  Client,
+  EmbedBuilder,
+  Events,
+  GatewayIntentBits,
+  REST,
+  Routes,
+  SlashCommandBuilder,
+} from "spearkit";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+const pingCommand = new SlashCommandBuilder()
+  .setName("ping")
+  .setDescription("Replies with an embed and a button");
+
+client.once(Events.ClientReady, (c) => {
+  console.log(`Ready as ${c.user.tag}`);
+});
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (!interaction.isChatInputCommand()) return;
+  if (interaction.commandName !== "ping") return;
+
+  const embed = new EmbedBuilder().setTitle("Pong!").setDescription(`Latency: ${client.ws.ping}ms`);
+  const buttons = new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder().setCustomId("again").setLabel("Again").setStyle(ButtonStyle.Primary),
+  );
+  await interaction.reply({ embeds: [embed], components: [buttons] });
+});
+
+async function deploy(token: string, appId: string): Promise<void> {
+  const rest = new REST().setToken(token);
+  await rest.put(Routes.applicationCommands(appId), { body: [pingCommand.toJSON()] });
+}
+```
+
+This file is 100% classic discord.js — only the import source changed. It keeps
+working exactly as before.
+
+## Incremental adoption
+
+Once your imports point at spearkit, you can convert pieces one at a time. There is no
+big-bang migration; old and new styles coexist.
+
+1. **Swap the client.** Replace `new Client(...)` with `new SpearClient(...)`. It
+   *is* a discord.js `Client` (it extends it), so your existing `client.on`,
+   `client.once`, `client.ws`, `client.rest` code is unchanged — but now it also
+   routes interactions to spearkit's registries.
+
+   ```ts
+   import { SpearClient, Intents } from "spearkit";
+
+   const client = new SpearClient({ intents: Intents.default });
+   ```
+
+2. **Move commands to `command()`.** Replace a hand-written `SlashCommandBuilder`
+   plus its branch of the `interactionCreate` switch with a single co-located
+   definition. Option values become fully typed.
+3. **Move events to `event()`.** Replace `client.on(Events.X, ...)` listeners with
+   `event("x", ...)` definitions and register them.
+4. **Move components to spearkit builders.** Replace manual `ButtonBuilder` +
+   custom-id parsing with `button()`, `stringSelect()`, `modal()`, etc. — spearkit
+   routes them by custom-id namespace and decodes `{param}`s for you.
+
+Convert at whatever pace suits you; un-migrated handlers keep running through your
+existing `interactionCreate` listener.
+
+## Before and after
+
+The classic approach hand-routes every interaction through one big switch and
+parses custom ids by hand:
+
+```ts
+// discord.js: one listener routes everything by hand
+import { Client, Events, GatewayIntentBits } from "discord.js";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (interaction.isChatInputCommand()) {
+    if (interaction.commandName === "greet") {
+      const who = interaction.options.getUser("who", true);
+      await interaction.reply(`Hello ${who}!`);
+    }
+  } else if (interaction.isButton()) {
+    const [name, choice] = interaction.customId.split(":"); // manual parsing
+    if (name === "vote") {
+      await interaction.update({ content: `You chose ${choice}` });
+    }
+  }
+});
+```
+
+spearkit co-locates each command and component with its handler, and routes
+interactions for you — no switch, no manual id parsing:
+
+```ts
+// spearkit: each handler owns its definition; routing is automatic
+import { SpearClient, Intents, command, option, button, row } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who to greet", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const vote = button({
+  id: "vote:{choice}",                              // {choice} is a typed param
+  label: "Yes",
+  style: "Success",
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // choice: string
+});
+
+client.register(greet, vote);
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+
+// build() requires exactly the params the id pattern declares:
+await channel.send({ content: "Vote:", components: [row(vote.build({ choice: "yes" }))] });
+```
+
+The option value (`who`) and the custom-id param (`choice`) are inferred from the
+definitions — no casts, no `getUser`/`split` boilerplate, and no `interactionCreate`
+switch to maintain.
+
+## See also
+
+- [Getting started](./getting-started.md) — install spearkit and build a first bot.
+- [Commands](./commands.md) — define slash commands with typed options.
+- [Components](./components.md) — buttons, selects, modals and custom-id routing.