spearkit 0.3.0 → 0.3.1

package/docs/context.md

@@ -0,0 +1,201 @@
+# Contexts
+
+Every spearkit handler — command, button, select, modal — receives a context
+object. They all share `BaseContext`, which smooths over discord.js'
+reply/defer/edit/follow-up state machine and exposes the common
+actor/location accessors. Learn it once and it applies everywhere.
+
+```ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "hello",
+  description: "Say hello",
+  options: { name: option.string({ description: "Name", required: true }) },
+  run: (ctx) => ctx.reply(`Hi, ${ctx.options.name}!`),
+});
+```
+
+`CommandContext`, `ButtonContext`, `StringSelectContext`, modal contexts and the
+rest extend `BaseContext`, adding their own specifics (e.g. `ctx.options`,
+`ctx.params`, `ctx.fields`) on top of everything below.
+
+## Reply helpers
+
+| Method | Returns | Behaviour |
+| ------ | ------- | --------- |
+| `reply(input)` | `Promise<InteractionResponse>` | Send the initial response. |
+| `replyEphemeral(input)` | `Promise<InteractionResponse>` | Reply, hidden to everyone but the invoking user. |
+| `defer({ ephemeral })` | `Promise<InteractionResponse>` | Acknowledge now, respond later via `editReply`. |
+| `editReply(input)` | `Promise<Message>` | Edit the original (or deferred) response. |
+| `followUp(input)` | `Promise<Message>` | Add a message after the initial response. |
+| `send(input)` | `Promise<void>` | State-aware: replies, edits, or follows up automatically. |
+| `error(message)` | `Promise<void>` | State-aware ephemeral message. |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "demo",
+  description: "Reply helpers",
+  run: async (ctx) => {
+    await ctx.reply("Working on it…");
+    await ctx.followUp("…almost done.");
+  },
+});
+```
+
+### `send` is the one most handlers need
+
+`send` inspects the interaction state and does the right thing:
+
+- not yet answered → `reply`
+- already deferred → `editReply`
+- already replied → `followUp`
+
+This means you can call `send` without tracking whether you deferred, which is
+ideal for shared helpers that may run before or after a `defer`.
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "report",
+  description: "Generate a report",
+  run: async (ctx) => {
+    await ctx.defer(); // acknowledge while we do slow work
+    const data = await buildReport();
+    await ctx.send(data); // sees the deferred state → edits the reply
+  },
+});
+```
+
+### `error` for ephemeral failures
+
+`error(message)` sends a state-aware, always-ephemeral message — perfect for
+validation failures that only the invoking user should see.
+
+```ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "kick",
+  description: "Kick a member",
+  options: { who: option.user({ description: "Member", required: true }) },
+  run: async (ctx) => {
+    if (!ctx.guild) return ctx.error("This command only works in a server.");
+    await ctx.reply(`Kicked ${ctx.options.who}.`);
+  },
+});
+```
+
+## The `{ ephemeral: true }` shortcut
+
+discord.js represents an ephemeral reply with `flags: MessageFlags.Ephemeral`.
+spearkit lets you write the more obvious `{ ephemeral: true }` on any reply payload
+and maps it to that flag for you. The input type is `ReplyInput`
+(`string | ReplyData`), where `ReplyData` is discord.js'
+`InteractionReplyOptions` plus the optional `ephemeral` boolean.
+
+```ts
+import { command, EmbedBuilder } from "spearkit";
+
+export default command({
+  name: "secret",
+  description: "Only you can see this",
+  run: (ctx) =>
+    ctx.reply({
+      embeds: [new EmbedBuilder().setTitle("Just for you")],
+      ephemeral: true, // mapped to MessageFlags.Ephemeral
+    }),
+});
+```
+
+`replyEphemeral(input)` is sugar for the same thing, accepting either a string
+or a payload:
+
+```ts
+await ctx.replyEphemeral("Saved.");
+await ctx.replyEphemeral({ embeds: [embed] });
+```
+
+If you set `flags` yourself, spearkit preserves them and adds the ephemeral flag
+rather than overwriting it.
+
+### Exported helpers
+
+spearkit exports the two functions it uses internally, so you can normalise reply
+input yourself (e.g. in a plugin or shared utility):
+
+- `normalizeReply(input: ReplyInput): InteractionReplyOptions` — converts a
+  string or `ReplyData` into a discord.js reply payload, applying the ephemeral
+  flag mapping.
+- `asEphemeral(input: ReplyInput): ReplyData` — marks any input ephemeral,
+  regardless of how it was passed.
+
+```ts
+import { normalizeReply, asEphemeral } from "spearkit";
+
+normalizeReply("hi");
+// → { content: "hi" }
+
+normalizeReply({ content: "hi", ephemeral: true });
+// → { content: "hi", flags: MessageFlags.Ephemeral }
+
+asEphemeral("hidden");
+// → { content: "hidden", ephemeral: true }
+```
+
+## Accessors
+
+`BaseContext` forwards the common interaction fields so you do not reach through
+`ctx.interaction` for everyday data:
+
+| Accessor | Description |
+| -------- | ----------- |
+| `interaction` | The raw discord.js interaction. |
+| `client` | The `SpearClient` (typed as the interaction's client). |
+| `user` | The invoking `User`. |
+| `member` | The invoking guild member (or `null` outside a guild). |
+| `guild` | The `Guild`, or `null` in DMs. |
+| `guildId` | The guild id, or `null`. |
+| `channel` | The channel the interaction came from. |
+| `channelId` | The channel id. |
+| `locale` | The user's locale. |
+| `deferred` | Whether the interaction is already deferred. |
+| `replied` | Whether the interaction already received an initial response. |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "whereami",
+  description: "Report context",
+  run: (ctx) =>
+    ctx.reply(
+      ctx.guild
+        ? `In ${ctx.guild.name} (#${ctx.channelId}), locale ${ctx.locale}.`
+        : "We're in a DM.",
+    ),
+});
+```
+
+`deferred` and `replied` let you branch when you are not using `send`:
+
+```ts
+import { button } from "spearkit";
+
+export default button({
+  id: "refresh",
+  label: "Refresh",
+  run: async (ctx) => {
+    if (ctx.replied || ctx.deferred) await ctx.followUp("Refreshed.");
+    else await ctx.reply("Refreshed.");
+  },
+});
+```
+
+## See also
+
+- [Commands](./commands.md) — `CommandContext`, options and `showModal`.
+- [Components](./components.md) — button, select and modal contexts.

package/docs/cooldown.md

@@ -0,0 +1,124 @@
+# Cooldowns
+
+Rate-limit commands per user, per role, per guild, per channel or globally.
+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/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.