spearkit 0.3.0 → 0.4.0

package/docs/cooldown.md

@@ -0,0 +1,125 @@
+# Cooldowns
+
+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.
+
+## Per-command
+
+Pass a number (milliseconds) or a full config to any command:
+
+```ts
+import { command } from "spearkit";
+
+export const daily = command({
+  name: "daily",
+  description: "Claim your daily reward",
+  cooldown: 86_400_000, // once per day, per user
+  run: (ctx) => ctx.reply("Reward claimed!"),
+});
+```
+
+## Client-wide default
+
+A default applies to every command; a command's own `cooldown` overrides it.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ cooldown: { duration: 3000 } });
+```
+
+## Scope
+
+`scope` controls what the cooldown is keyed on. Default `"user"`.
+
+```ts
+command({
+  name: "announce",
+  description: "Post an announcement",
+  cooldown: { duration: 60_000, scope: "guild" }, // one per guild per minute
+  run: (ctx) => ctx.reply("Announced."),
+});
+```
+
+| Scope | Keyed on |
+| --- | --- |
+| `user` | the invoking user (default) |
+| `guild` | the guild |
+| `channel` | the channel |
+| `global` | everyone shares one bucket |
+
+## Exemptions — who waits and who doesn't
+
+`exempt` lists users and roles that bypass the cooldown entirely.
+
+```ts
+command({
+  name: "purge",
+  description: "Bulk delete",
+  cooldown: {
+    duration: 10_000,
+    exempt: { roles: ["111111111111111111"], users: ["222222222222222222"] },
+  },
+  run: (ctx) => ctx.reply("Purged."),
+});
+```
+
+## Per-role / per-user overrides
+
+`overrides` gives specific roles or users a different duration (milliseconds).
+A user override beats role overrides; among matching roles the most lenient
+(shortest) duration wins. Use `0` to effectively disable the wait for them.
+
+```ts
+command({
+  name: "search",
+  description: "Search the archive",
+  cooldown: {
+    duration: 10_000, // everyone else
+    overrides: {
+      roles: { "333333333333333333": 2_000 }, // VIP role: 2s
+      users: { "444444444444444444": 0 }, // this user: no wait
+    },
+  },
+  run: (ctx) => ctx.reply("Searching…"),
+});
+```
+
+## The message
+
+`message` customises what blocked users see — a string, or a function of the
+remaining milliseconds.
+
+```ts
+command({
+  name: "spin",
+  description: "Spin the wheel",
+  cooldown: {
+    duration: 5_000,
+    message: (ms) => `Hold on — ${Math.ceil(ms / 1000)}s to go.`,
+  },
+  run: (ctx) => ctx.reply("🎡"),
+});
+```
+
+## The manager
+
+`client.cooldowns` is the shared `CooldownManager` (also used by
+[prefix commands](./prefix.md)). Use it directly for custom flows:
+
+```ts
+const result = client.cooldowns.consume("vote", 5_000, {
+  userId: "1",
+  roleIds: [],
+  guildId: null,
+  channelId: null,
+});
+if (!result.allowed) console.log(`wait ${result.remaining}ms`);
+```
+
+`consume` records the use and returns `{ allowed: true }` or
+`{ allowed: false, remaining }`. `peek` checks without recording; `reset` and
+`clear` drop tracked cooldowns.

package/docs/env.md

@@ -0,0 +1,130 @@
+# Environment & dotenv
+
+spearkit includes a tiny, dependency-free `.env` loader and a typed reader over
+`process.env`, so a bot needs no extra dotenv dependency. The client auto-loads
+`.env` on `start()`, and the same helpers are exported for your own use.
+
+## Loading a `.env` file
+
+`loadEnv(options?)` reads a `.env` file and merges it into `process.env`. By
+default it reads `.env` from the current working directory. Variables already
+present in `process.env` win unless you pass `override: true`. A missing file is
+ignored — it simply returns `{}` — so it is safe to call unconditionally.
+
+```ts
+import { loadEnv } from "spearkit";
+
+const parsed = loadEnv();                       // reads ./.env
+loadEnv({ path: ".env.local" });                // a different file
+loadEnv({ override: true });                    // let the file win over existing vars
+```
+
+`loadEnv` returns the parsed key/value pairs it read from the file:
+
+```ts
+import { loadEnv } from "spearkit";
+
+const parsed = loadEnv(); // ParsedEnv = Record<string, string>
+console.log(Object.keys(parsed));
+```
+
+## Parsing without touching `process.env`
+
+`parseEnv(text)` parses `.env`-formatted text into a flat object and never
+mutates `process.env`. It understands single/double quotes, a leading `export `,
+`#` comments, and `\n`/`\r`/`\t` escapes inside double quotes.
+
+```ts
+import { parseEnv } from "spearkit";
+
+const vars = parseEnv(`
+# a comment
+export TOKEN="abc#notacomment"
+GREETING="line one\nline two"
+RAW='no $escapes here'
+`);
+
+vars.TOKEN;    // "abc#notacomment"
+vars.GREETING; // "line one\nline two" (real newline)
+vars.RAW;      // "no $escapes here"
+```
+
+## The typed `env` reader
+
+`env` reads from `process.env` with coercion and optional fallbacks. Empty
+strings count as missing.
+
+```ts
+import { env } from "spearkit";
+
+env.string("REGION");            // string | undefined
+env.string("REGION", "eu");      // string (fallback when missing)
+
+env.number("PORT");              // number | undefined
+env.number("PORT", 3000);        // number (fallback when missing or non-numeric)
+
+env.boolean("DEBUG");            // boolean | undefined
+env.boolean("DEBUG", false);     // boolean
+
+env.require("DISCORD_TOKEN");    // string, throws if missing or empty
+```
+
+`env.boolean` treats `true`/`1`/`yes`/`on` as `true` and `false`/`0`/`no`/`off`
+as `false` (case-insensitive); anything else yields the fallback. `env.require`
+throws a descriptive error when the variable is missing or empty — use it for
+values your bot cannot run without.
+
+```ts
+import { loadEnv, env } from "spearkit";
+
+loadEnv();
+const token = env.require("DISCORD_TOKEN"); // guaranteed string
+const port = env.number("PORT", 8080);      // number
+const verbose = env.boolean("VERBOSE", false);
+```
+
+## Auto-loading on the client
+
+`SpearClient` calls `loadEnv()` for you inside `client.start()`, so `.env` is
+picked up before login. That means `await client.start()` finds
+`DISCORD_TOKEN` from `.env` without any extra wiring:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+async function main(): Promise<void> {
+  await client.start(); // loads .env, then reads DISCORD_TOKEN
+}
+
+void main();
+```
+
+### The `dotenv` option
+
+Control the auto-load with the `dotenv` construction option:
+
+```ts
+import { SpearClient } from "spearkit";
+
+// Default: load ./.env on start.
+new SpearClient({ dotenv: true });
+
+// Disable auto-loading entirely (e.g. env is provided by the platform).
+new SpearClient({ dotenv: false });
+
+// Customize: same shape as loadEnv's options.
+new SpearClient({ dotenv: { path: ".env.production", override: true } });
+```
+
+| `dotenv` value | Effect |
+| -------------- | ------ |
+| `true` / omitted | Load `.env` from the cwd on `start()`. |
+| `false` | Skip auto-loading; `process.env` is used as-is. |
+| `{ path?, override? }` | Load with those `loadEnv` options. |
+
+## See also
+
+- [Client](./client.md) — the `dotenv` and other construction options.
+- [Logging](./logging.md) — structured logging that pairs with `env`-driven config.

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.

package/docs/events.md

@@ -0,0 +1,152 @@
+# Events
+
+`event()` defines a reusable, loadable discord.js event listener with a
+fully-typed handler. The handler's arguments are inferred from discord.js'
+`ClientEvents`, so you never annotate them by hand. Register an event with the
+client and spearkit attaches the listener for you.
+
+```ts
+import { event } from "spearkit";
+
+export default event("messageCreate", (message) => {
+  if (message.author.bot) return;
+  // message is fully typed as Message
+});
+```
+
+## Defining an event
+
+`event` has two forms. The positional form takes the event name and handler:
+
+```ts
+import { event } from "spearkit";
+
+const onMessage = event("messageCreate", (message) => {
+  // message: Message
+  console.log(message.content);
+});
+
+const onReady = event("clientReady", (client) => {
+  // client: Client<true> — the ready client
+  console.log(`Logged in as ${client.user.tag}`);
+});
+```
+
+The object form (`EventConfig`) additionally accepts `once`, which runs the
+handler at most once and then auto-detaches:
+
+```ts
+import { event } from "spearkit";
+
+const onceReady = event({
+  name: "clientReady",
+  once: true,
+  run: (client) => {
+    // client: Client<true>
+    console.log(`Ready as ${client.user.tag}`);
+  },
+});
+```
+
+Both forms return an `EventDef` — a type-erased, ready-to-attach listener
+(`{ name, once, attach, detach }`). Register it like anything else:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+client.register(onMessage, onReady);
+```
+
+### Handlers are fully typed from `ClientEvents`
+
+The event name drives the parameter types. There is nothing to import or
+annotate — picking `"messageCreate"` types the argument as `Message`, picking
+`"guildMemberAdd"` types it as `GuildMember`, and so on. The handler type is
+exported as `EventHandler<E>` (`(...args: ClientEvents[E]) => Awaitable<void>`).
+
+```ts
+import { event } from "spearkit";
+
+const onJoin = event("guildMemberAdd", (member) => {
+  // member: GuildMember
+  void member.roles.add("123456789012345678");
+});
+
+const onReaction = event("messageReactionAdd", (reaction, user) => {
+  // reaction: MessageReaction | PartialMessageReaction
+  // user: User | PartialUser
+  console.log(`${user.id} reacted with ${reaction.emoji.name}`);
+});
+```
+
+### Intents are required
+
+An event only fires if the client connected with the matching gateway intents.
+For example, `messageCreate` with message content needs `Intents.messages` (or
+at least the `GuildMessages` / `MessageContent` bits); `guildMemberAdd` needs
+`GuildMembers`. See [Client](./client.md) for the intent presets.
+
+## Errors are routed, not fatal
+
+If a handler throws synchronously or rejects a returned promise, spearkit catches
+it and emits it on the client's `error` event instead of crashing the process.
+Listen for `error` to log or report failures centrally:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+client.on("error", (err) => {
+  console.error("A handler failed:", err);
+});
+```
+
+## Inline listeners still work
+
+Because spearkit re-exports discord.js, the plain `client.on(...)` / `client.once(...)`
+listeners work exactly as before — they are the same methods. Reach for them for
+quick, inline, client-local listeners:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+client.on("guildCreate", (guild) => console.log(`Joined ${guild.name}`));
+```
+
+Use `event()` when you want a listener that is **reusable and loadable** — a
+self-contained module you can export, register from anywhere, or pick up via
+`client.load(...)`. Note that inline `client.on` listeners do **not** get the
+automatic error-routing that `event()` handlers do.
+
+## The `EventRegistry`
+
+`client.events` is an `EventRegistry`. The client attaches it automatically at
+construction and again when you `register` an event, so you usually never call
+its methods directly. They are available for advanced control:
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `add(...defs)` | `this` | Register one or more `EventDef`s (and attach them to already-attached clients). |
+| `size` | `number` | Number of registered listeners. |
+| `attachAll(client)` | `void` | Attach every registered listener to a client. |
+| `detachAll(client)` | `void` | Detach every registered listener from a client. |
+
+```ts
+import { SpearClient, event } from "spearkit";
+
+const client = new SpearClient();
+client.events.add(event("warn", (info) => console.warn(info)));
+
+console.log(client.events.size); // 1
+
+// Detach all spearkit-managed listeners (e.g. before a hot reload).
+client.events.detachAll(client);
+```
+
+## See also
+
+- [Client](./client.md) — registering events and the required intents.
+- [File-based loading](./loading.md) — one event per file, auto-registered.

package/docs/getting-started.md

@@ -0,0 +1,147 @@
+# Getting started
+
+spearkit is **discord.js++**: it re-exports the entire discord.js surface and adds a
+fully type-safe layer for events, slash commands and interactive components. This
+page takes you from an empty folder to a running bot that responds to a slash
+command.
+
+## Install
+
+spearkit sits alongside discord.js, so install both:
+
+```bash
+npm install spearkit discord.js
+```
+
+Everything in your code imports from `"spearkit"` — including the plain discord.js
+symbols, which spearkit re-exports unchanged.
+
+## Credentials you need
+
+Create an application in the [Discord Developer Portal](https://discord.com/developers/applications)
+and collect three values:
+
+| Value | Where to find it | Used for |
+| ----- | ---------------- | -------- |
+| Bot token | Application → **Bot** → *Reset Token* | `client.start(token)` |
+| Application id | Application → **General Information** → *Application ID* | command deployment (spearkit reads it from the client once ready) |
+| Test guild id | Right-click your server in Discord (with Developer Mode on) → *Copy Server ID* | guild-scoped deploy |
+
+Keep the token secret. The examples below read these from the environment
+(`DISCORD_TOKEN`, `GUILD_ID`).
+
+## Your first 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 to greet", required: true }),
+  },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // ctx.options.who: User
+});
+
+const ready = event("clientReady", (c) => console.log(`Online as ${c.user.tag}`));
+
+client.register(greet, ready);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+What each step does:
+
+1. **`new SpearClient({ intents })`** — a discord.js `Client` with command, event
+   and component routing wired up. `Intents.default` is `[Guilds]`, enough for
+   slash commands and interactions.
+2. **`command({ ... })`** — defines a leaf slash command. Required options resolve
+   to their value type (`who` is a `User`); optional options would resolve to
+   `value | undefined`.
+3. **`client.register(...)`** — routes each item to the matching registry
+   (commands, events, components) by its kind.
+4. **`client.start(token)`** — logs in. With no argument it falls back to the
+   `DISCORD_TOKEN` environment variable.
+5. **`client.deployCommands({ guildId })`** — pushes your command definitions to
+   Discord over the client's own authenticated REST connection. Must run after the
+   client is ready (i.e. after `start`).
+
+### Guild vs global deploy
+
+`deployCommands` takes an optional `guildId`:
+
+- **Guild deploy** (`{ guildId }`) registers commands in a single server. Changes
+  appear **instantly** — ideal while developing.
+- **Global deploy** (omit `guildId`) registers commands across every server the
+  bot is in. Propagation can take up to an hour.
+
+```ts
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // instant, one guild
+await client.deployCommands();                                  // global, slow to propagate
+```
+
+You only need to deploy when your command *definitions* change (names,
+descriptions, options) — not on every restart.
+
+## Suggested project layout
+
+As a bot grows, give each command, event and component its own file:
+
+```
+my-bot/
+  src/
+    index.ts          # construct the client, register/load, start, deploy
+    commands/
+      greet.ts
+      ping.ts
+    events/
+      ready.ts
+    components/
+      vote.ts
+  package.json
+  tsconfig.json
+```
+
+A module exports a command, event or component as a default or named export:
+
+```ts
+// src/commands/ping.ts
+import { command } from "spearkit";
+
+export default command({
+  name: "ping",
+  description: "Check that the bot is alive",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+You can wire the pieces up explicitly with `register`, or let spearkit discover them
+with `client.load` (see [File-based loading](./loading.md)).
+
+## Running it
+
+**With tsx** (run TypeScript directly, great for development):
+
+```bash
+npx tsx src/index.ts
+```
+
+**Compiled JavaScript** (for production):
+
+```bash
+npx tsc            # emit JS into dist/ per your tsconfig
+node dist/index.js
+```
+
+Note that `client.load` imports **compiled JavaScript**, so if you use file-based
+loading you must build before running the compiled output. Explicit `register`
+calls work the same under `tsx` or `node`.
+
+## See also
+
+- [Client](./client.md) — `SpearClient`, intents, `register`, `start`, deployment.
+- [Commands](./commands.md) — slash commands, subcommands, options, deployment.