spearkit 0.3.0 → 0.4.0

package/docs/options.md

@@ -0,0 +1,163 @@
+# Options
+
+Slash command options are declared as a map of name → builder. spearkit infers the
+exact value type each option resolves to, so your handler's `ctx.options` is
+fully typed — no casts, no `any`, no manual `getString` calls.
+
+```ts
+import { command, option } from "spearkit";
+
+command({
+  name: "profile",
+  description: "Show a profile",
+  options: {
+    user: option.user({ description: "Whose profile", required: true }),
+    detailed: option.boolean({ description: "Show extra detail" }),
+  },
+  run: (ctx) => {
+    ctx.options.user;     // User
+    ctx.options.detailed; // boolean | undefined
+  },
+});
+```
+
+## Builders and resolved types
+
+| Builder | Resolved type | Type-specific config |
+| ------- | ------------- | -------------------- |
+| `option.string(config)` | `string` | `choices`, `minLength`, `maxLength`, `autocomplete` |
+| `option.integer(config)` | `number` | `choices`, `minValue`, `maxValue`, `autocomplete` |
+| `option.number(config)` | `number` | `choices`, `minValue`, `maxValue`, `autocomplete` |
+| `option.boolean(config)` | `boolean` | — |
+| `option.user(config)` | `User` | — |
+| `option.channel(config)` | channel union | `channelTypes` |
+| `option.role(config)` | `Role \| APIRole` | — |
+| `option.mentionable(config)` | user / role / member | — |
+| `option.attachment(config)` | `Attachment` | — |
+
+Every builder accepts the common config:
+
+```ts
+{
+  description: string;                        // required
+  required?: boolean;                         // default: false
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+```
+
+## Inference rules
+
+spearkit narrows the resolved type from your declaration:
+
+```ts
+options: {
+  // required → the value type, never undefined
+  name: option.string({ description: "Name", required: true }),     // string
+
+  // optional (default) → value | undefined
+  age: option.integer({ description: "Age" }),                      // number | undefined
+
+  // choices → a literal union of the choice values
+  size: option.string({
+    description: "Size",
+    choices: [
+      { name: "Small", value: "sm" },
+      { name: "Large", value: "lg" },
+    ],
+  }),                                                               // "sm" | "lg" | undefined
+}
+```
+
+- **Required** options resolve to the value type.
+- **Optional** options resolve to `value | undefined` (spearkit converts discord's
+  absent value to `undefined`, never `null`).
+- **`choices`** narrow string/integer/number options to a literal union of the
+  declared `value`s.
+
+```ts
+run: (ctx) => {
+  const name: string = ctx.options.name;
+  const age: number | undefined = ctx.options.age;
+  const size: "sm" | "lg" | undefined = ctx.options.size;
+};
+```
+
+## Numeric and length constraints
+
+```ts
+options: {
+  count: option.integer({ description: "How many", minValue: 1, maxValue: 100 }),
+  code: option.string({ description: "Code", minLength: 4, maxLength: 8 }),
+}
+```
+
+## Channel options
+
+Restrict the selectable channel types with `channelTypes` (from discord.js
+`ChannelType`):
+
+```ts
+import { option, ChannelType } from "spearkit";
+
+options: {
+  target: option.channel({
+    description: "A text or announcement channel",
+    channelTypes: [ChannelType.GuildText, ChannelType.GuildAnnouncement],
+  }),
+}
+```
+
+## Choices
+
+`choices` are `{ name, value }` pairs. `name` is shown to the user; `value` is
+what your handler receives (and what spearkit narrows the type to).
+
+```ts
+option.integer({
+  description: "Priority",
+  choices: [
+    { name: "Low", value: 1 },
+    { name: "High", value: 2 },
+  ],
+  // optional per-choice localization:
+  // choices: [{ name: "Low", value: 1, nameLocalizations: { tr: "Düşük" } }],
+}); // 1 | 2 | undefined
+```
+
+## Autocomplete
+
+Provide an `autocomplete` handler instead of fixed `choices` to suggest values
+as the user types. spearkit marks the option as autocompletable, routes the
+autocomplete interaction, and (for subcommands) finds the right option.
+
+```ts
+const fruits = ["apple", "apricot", "banana", "cherry"];
+
+option.string({
+  description: "Fruit",
+  required: true,
+  autocomplete: (ctx) =>
+    fruits
+      .filter((f) => f.startsWith(ctx.value))
+      .map((f) => ({ name: f, value: f })),
+});
+```
+
+The autocomplete handler receives an `AutocompleteContext`:
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.value` | The current partial value typed by the user. |
+| `ctx.focusedName` | The name of the option being completed. |
+| `ctx.commandName` | The command being completed. |
+| `ctx.client` / `ctx.user` / `ctx.guild` / `ctx.guildId` | Accessors. |
+| `ctx.respond(choices)` | Send suggestions (capped at discord's 25). |
+
+Returning the choices array (as above) is enough — spearkit calls `respond` for
+you. Returning `[]` shows no suggestions.
+
+## See also
+
+- [Commands](./commands.md) — using options inside commands and subcommands.
+- [Components](./components.md) — buttons, selects and modals.

package/docs/permissions.md

@@ -0,0 +1,68 @@
+# Permissions & hierarchy
+
+Moderation commands fail in two predictable ways: the bot lacks a permission in
+the channel (`Missing Permissions`, 50013), or the target sits above the bot (or
+the moderator) in the role list. Both are checkable *before* you act, so you can
+bail out with a clear message instead of a half-finished action and an exception.
+
+## Did the bot/user get the permissions? (zero-fetch)
+
+Every interaction carries the bot's and the invoker's resolved permissions for
+the current channel. `ctx.botMissing(...)` / `ctx.userMissing(...)` read them
+with no API calls and return the **missing** flag names:
+
+```ts
+import { PermissionFlagsBits, command, formatPermissions } from "spearkit";
+
+export const slowmode = command({
+  name: "slowmode",
+  description: "Set channel slowmode",
+  run: async (ctx) => {
+    const missing = ctx.botMissing(PermissionFlagsBits.ManageChannels);
+    if (missing.length > 0) return ctx.error(`I need: ${formatPermissions(missing)}`);
+    // …
+  },
+});
+```
+
+`formatPermissions(...)` renders flag names as a friendly list
+(`"Manage Channels, Ban Members"`).
+
+## Permissions in another channel
+
+For a channel other than the current one, use the standalone helpers:
+
+```ts
+import { botMissingPermissions, hasPermissions, missingPermissions } from "spearkit";
+
+const missing = botMissingPermissions(targetChannel, [PermissionFlagsBits.SendMessages]);
+if (missing.length > 0) return ctx.error("I can't post there.");
+
+// or for a specific member/role:
+hasPermissions(targetChannel, member, PermissionFlagsBits.ViewChannel); // boolean
+missingPermissions(targetChannel, role, [PermissionFlagsBits.Connect]); // PermissionsString[]
+```
+
+## Role hierarchy
+
+`moderationCheck(...)` validates both the moderator and the bot against a target,
+returning a ready-to-show reason on the first failing rule (self, server owner,
+moderator hierarchy, bot hierarchy):
+
+```ts
+import { moderationCheck } from "spearkit";
+
+const moderator = await ctx.guild!.members.fetch(ctx.user.id);
+const check = moderationCheck({ moderator, target, action: "ban" });
+if (!check.ok) return ctx.error(check.reason);
+await target.ban();
+```
+
+The `me` (bot) member defaults to `target.guild.members.me`; pass `me: null` to
+skip the bot check. `action` is the verb used in messages (default `"moderate"`).
+
+Lower-level primitives are exported too:
+
+- `canActOn(actor, target)` — boolean: not self, target isn't the owner, actor is
+  the owner or outranks the target.
+- `compareRoles(a, b)` — highest-role position comparison (`>0`, `<0`, `0`).

package/docs/plugins.md

@@ -0,0 +1,116 @@
+# Plugins
+
+A plugin is a named, reusable bundle of commands, events and components. It lets
+you package a feature once and install it into any `SpearClient` with a single
+call — useful for sharing functionality across bots or splitting a large bot into
+self-contained features.
+
+## Defining a plugin
+
+`definePlugin` is an identity helper: it returns the object you pass it, but gives
+it the `SpearPlugin` type and editor hints.
+
+```ts
+interface SpearPlugin {
+  name: string;
+  setup(client: SpearClient): Awaitable<void>;
+}
+```
+
+A plugin has a `name` and a `setup` function. `setup` receives the client and
+registers whatever the feature needs — commands, events, components — typically
+via `client.register`.
+
+```ts
+import { definePlugin, button, command, event, option, row } from "spearkit";
+
+export const moderation = definePlugin({
+  name: "moderation",
+  setup(client) {
+    const confirmKick = button({
+      id: "kick:{userId}",
+      label: "Confirm kick",
+      style: "Danger",
+      run: (ctx) => ctx.update(`Kicked <@${ctx.params.userId}> (demo).`), // userId: string
+    });
+
+    const warn = command({
+      name: "warn",
+      description: "Warn a member",
+      options: {
+        member: option.user({ description: "Member", required: true }),
+        reason: option.string({ description: "Reason" }),
+      },
+      run: (ctx) =>
+        ctx.reply({
+          // member: User, reason: string | undefined
+          content: `Warning ${ctx.options.member.tag}: ${ctx.options.reason ?? "no reason given"}`,
+          components: [row(confirmKick.build({ userId: ctx.options.member.id }))],
+          ephemeral: true,
+        }),
+    });
+
+    const ready = event("clientReady", (c) => console.log(`[moderation] ready on ${c.user.tag}`));
+
+    client.register(warn, confirmKick, ready);
+  },
+});
+```
+
+Everything declared inside `setup` is local to the plugin; only what you pass to
+`client.register` becomes active on the client.
+
+## Installing a plugin
+
+Install one or more plugins with `client.use`. It runs each plugin's `setup` in
+order and resolves to the client, so you can chain it with the rest of startup.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+import { moderation } from "./plugins/moderation.js";
+
+const client = new SpearClient({ intents: Intents.default });
+
+await client.use(moderation);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+`use` accepts several plugins at once:
+
+```ts
+await client.use(moderation, welcome, tickets);
+```
+
+## Asynchronous setup
+
+`setup` may be async — `client.use` awaits each one before moving to the next. Use
+this to load data, connect to a database, or fetch remote config before
+registering handlers.
+
+```ts
+export const tags = definePlugin({
+  name: "tags",
+  async setup(client) {
+    const store = await openTagStore(); // await anything you need first
+
+    client.register(
+      command({
+        name: "tag",
+        description: "Show a saved tag",
+        options: { name: option.string({ description: "Tag name", required: true }) },
+        run: (ctx) => ctx.reply(store.get(ctx.options.name) ?? "No such tag."),
+      }),
+    );
+  },
+});
+```
+
+Because `use` awaits `setup`, every plugin is fully installed before
+`client.start` runs.
+
+## See also
+
+- [Client](./client.md) — `register`, `use`, `start`, and the registries plugins write to.
+- [File-based loading](./loading.md) — discover commands, events and components from a directory instead of bundling them by hand.

package/docs/prefix.md

@@ -0,0 +1,234 @@
+# Prefix commands
+
+Alongside slash commands, spearkit can dispatch classic text/prefix commands like
+`!ping`. You define them with `prefixCommand`, enable them with the client's
+`prefix` option, and spearkit parses each `messageCreate` for you — matching the
+prefix, splitting arguments, and routing to the right handler.
+
+## Enabling prefix commands
+
+Prefix commands are off until you set the `prefix` option on the client. It
+accepts a string, an array of strings, or a `PrefixOptions` object:
+
+```ts
+import { Intents, SpearClient } from "spearkit";
+
+// A single prefix.
+new SpearClient({ intents: Intents.messages, prefix: "!" });
+
+// Several prefixes.
+new SpearClient({ intents: Intents.messages, prefix: ["!", "?"] });
+
+// Full control.
+new SpearClient({
+  intents: Intents.messages,
+  prefix: {
+    prefix: "!",
+    mention: true,         // also trigger on a leading @bot mention (default true)
+    ignoreBots: true,      // skip messages authored by bots (default true)
+    caseInsensitive: true, // match command names ignoring case (default true)
+  },
+});
+```
+
+### Dynamic (per-guild) prefixes
+
+Pass `dynamic` to resolve extra prefix(es) per message — for example a custom
+per-guild prefix from a database or [`createSettings`](./api-reference.md#persistent-storage).
+Dynamic prefixes are tried in addition to any static `prefix`; return
+`null`/`undefined` for none. It runs on every candidate message, so keep it fast
+(and cached).
+
+```ts
+new SpearClient({
+  intents: Intents.messages,
+  prefix: {
+    prefix: "!", // static fallback
+    dynamic: async (message) =>
+      message.guildId ? await settings.get(message.guildId).then((s) => s.prefix) : null,
+  },
+});
+```
+
+## You need the MessageContent intent
+
+Reading the text of other users' messages is a **privileged** gateway intent.
+Without `MessageContent` your bot still receives `messageCreate`, but
+`message.content` arrives empty for messages it was not mentioned in or did not
+author — so no prefix command will ever match.
+
+Use the `Intents.messages` preset, which includes `Guilds`, `GuildMessages`, and
+the privileged `MessageContent` bit:
+
+```ts
+import { Intents, SpearClient } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.messages, prefix: "!" });
+```
+
+You must also toggle **Message Content Intent** on for your application in the
+Discord Developer Portal, or the gateway will reject the connection.
+
+## Defining a command
+
+`prefixCommand` takes the command name, the handler, and a few optional fields:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const ping = prefixCommand({
+  name: "ping",
+  description: "Check that the bot is alive",
+  run: (ctx) => ctx.reply("Pong!"),
+});
+```
+
+Register it like anything else, with `client.register(...)`:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ prefix: "!" });
+client.register(ping);
+```
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `name` | `string` | The word after the prefix that triggers the command. |
+| `aliases` | `string[]` | Extra names that also trigger it. |
+| `description` | `string` | Human description, for your own help command. |
+| `cooldown` | `number \| CooldownConfig` | Per-user rate limit (a number is milliseconds). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. See [Guards](./guards.md). |
+| `args` | `(a) => PrefixArgsBuilder` | Typed argument schema; shapes `ctx.options`. See [Typed arguments](#typed-arguments). |
+| `run` | `(ctx: PrefixContext) => void \| Promise<void>` | The handler. |
+
+## The prefix context
+
+The handler receives a `PrefixContext`. It wraps the triggering `Message` and
+adds the parsed arguments plus reply helpers.
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.message` | The triggering discord.js `Message`. |
+| `ctx.commandName` | The matched name as the user typed it (an alias if they used one). |
+| `ctx.args` | Whitespace-split arguments after the command name (`string[]`). |
+| `ctx.rest` | The raw text after the command name (unsplit). |
+| `ctx.options` | Typed parsed arguments from the `args` schema (`{}` when none). |
+| `ctx.author` / `ctx.member` / `ctx.guild` / `ctx.guildId` / `ctx.channel` / `ctx.channelId` | Actor and location accessors. |
+| `ctx.reply(content)` | Reply to the triggering message. |
+| `ctx.send(content)` | Send a message to the same channel without a reply reference. |
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const echo = prefixCommand({
+  name: "echo",
+  description: "Repeat what you said",
+  run: (ctx) => {
+    if (ctx.args.length === 0) return ctx.reply("Give me something to echo.");
+    // `args` is split on whitespace; `rest` is the untouched remainder.
+    return ctx.reply(ctx.rest);
+  },
+});
+```
+
+`ctx.args` and `ctx.rest` are two views of the same input: `!say hello   world`
+gives `args === ["hello", "world"]` and `rest === "hello   world"`.
+
+## Typed arguments
+
+Pass an `args` schema to parse positional arguments into typed values. Chain
+builder methods — first token → first arg, second → second, and so on — and read
+the result from `ctx.options`. Each method requires a name and takes optional
+settings (`required`, `default`, and per-type bounds).
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const mute = prefixCommand({
+  name: "mute",
+  description: "Mute a member",
+  args: (a) =>
+    a
+      .snowflake("target", { required: true })       // raw id or <@mention> → string
+      .duration("duration", { required: true })      // "1h30m" → number (ms)
+      .rest("reason", { default: "No reason given" }), // remaining text → string
+  run: (ctx) => {
+    ctx.options.target;   // string
+    ctx.options.duration; // number
+    ctx.options.reason;   // string
+    return ctx.reply(`Muted <@${ctx.options.target}> for ${ctx.options.duration}ms.`);
+  },
+});
+```
+
+Builder methods: `.string`, `.integer`, `.number`, `.boolean`, `.snowflake`,
+`.duration`, `.rest`. A missing required argument — or a value that fails to
+parse — makes spearkit reply with an error and skip the handler. Without an `args`
+schema, `ctx.options` is `{}`; use `ctx.args` / `ctx.rest` for raw access.
+
+## Aliases
+
+List alternative names in `aliases`; any of them triggers the command, and
+`ctx.commandName` reports whichever the user typed:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const help = prefixCommand({
+  name: "help",
+  aliases: ["h", "commands"],
+  run: (ctx) => ctx.reply(`You used "${ctx.commandName}".`),
+});
+```
+
+## Cooldowns
+
+Prefix commands share the client's cooldown manager (`client.cooldowns`) with
+slash commands, so the API is identical. Pass `cooldown` as a number of
+milliseconds or a full `CooldownConfig`:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const daily = prefixCommand({
+  name: "daily",
+  description: "Claim your daily reward",
+  cooldown: 5_000, // one use per user per 5s
+  run: (ctx) => ctx.reply("Reward claimed! Come back soon."),
+});
+```
+
+When a user is on cooldown, spearkit replies with the remaining time and does not
+run the handler. A per-command `cooldown` overrides the client-wide `cooldown`
+default. See [Cooldowns](./cooldown.md) for scopes and configuration.
+
+## The prefix registry
+
+`client.prefix` is a `PrefixRegistry`. The client wires it to `messageCreate`,
+the logger, and the cooldown manager for you, so you rarely call it directly. It
+is available for introspection and advanced control:
+
+```ts
+client.prefix.get("ping");  // PrefixCommand | undefined (also resolves aliases)
+client.prefix.list();       // PrefixCommand[] (excludes aliases)
+client.prefix.size;         // number of commands
+```
+
+### Error handling
+
+If a handler throws, spearkit catches it, logs it, and calls your error hook if you
+set one — the process never crashes:
+
+```ts
+client.prefix.onError((error, message) => {
+  console.error(`prefix command failed in #${message.channelId}`, error);
+});
+```
+
+## See also
+
+- [Commands](./commands.md) — slash commands.
+- [Cooldowns](./cooldown.md) — the shared rate limiter.
+- [Usage tracking](./usage.md) — record who runs which prefix commands.
+- [Client](./client.md) — the `prefix` option and intent presets.

package/docs/scheduler.md

@@ -0,0 +1,111 @@
+# Scheduled tasks
+
+Run work on a cron schedule or a fixed interval. The client starts the
+scheduler when it becomes ready and stops it on `destroy()`, so timers never
+outlive your bot.
+
+## Define a task
+
+Provide exactly one of `cron` or `interval` (if both are set, the interval is used):
+
+```ts
+import { task } from "spearkit";
+
+export const heartbeat = task({
+  name: "heartbeat",
+  interval: 60_000, // every minute
+  runOnStart: true, // also run once on startup
+  run: (client) => client.logger.info("still alive"),
+});
+```
+
+Register it like anything else:
+
+```ts
+client.register(heartbeat);
+```
+
+Or define and register in one call:
+
+```ts
+client.schedule({
+  name: "cleanup",
+  cron: "0 3 * * *", // 03:00 local time, every day
+  run: async (client) => {
+    // …purge expired records…
+  },
+});
+```
+
+## Cron syntax
+
+Standard 5-field expressions, evaluated in the host's **local** time:
+
+```
+┌─ minute (0-59)
+│ ┌─ hour (0-23)
+│ │ ┌─ day of month (1-31)
+│ │ │ ┌─ month (1-12)
+│ │ │ │ ┌─ day of week (0-6, Sunday = 0)
+│ │ │ │ │
+* * * * *
+```
+
+Each field supports `*`, ranges (`1-5`), lists (`1,3,5`) and steps (`*/15`).
+When both day-of-month and day-of-week are restricted, a date matches if
+**either** does (standard cron behaviour).
+
+Aliases: `@yearly`/`@annually`, `@monthly`, `@weekly`, `@daily`/`@midnight`, `@hourly`.
+
+```ts
+task({ name: "report", cron: "@daily", run: () => {} });
+task({ name: "poll", cron: "*/5 * * * *", run: () => {} }); // every 5 minutes
+task({ name: "mondays", cron: "0 9 * * 1", run: () => {} }); // Mon 09:00
+```
+
+Compute the next run yourself with `cron`:
+
+```ts
+import { cron } from "spearkit";
+
+const next = cron("*/15 * * * *").next(new Date());
+```
+
+## One-shot jobs, follow-ups and on-ready recovery
+
+Beyond recurring tasks, the scheduler runs one-shot timers (they `unref()`
+themselves, so they never keep the process alive) and a once-on-ready reconciler.
+
+```ts
+// Run once after a delay; returns a cancel handle.
+const handle = client.scheduler.delay("remind", 10 * 60_000, async () => {
+  // …remind the moderator if nothing happened…
+});
+handle.cancel(); // true if it was still pending
+
+// A series of fires measured from "now"; the callback gets the fire index.
+client.scheduler.followUp("escalate", [10_000, 30_000, 60_000], (i) => {
+  // i = 0, then 1, then 2
+});
+
+// Run once the first time the scheduler starts (typically on clientReady) and
+// never again — ideal for restart recovery.
+client.scheduler.reconcile("voice-sessions", async (client) => {
+  // …close orphaned voice sessions, reapply cached state…
+});
+```
+
+## The scheduler
+
+`client.scheduler` is the `TaskScheduler`:
+
+```ts
+client.scheduler.size; // number of tasks
+client.scheduler.active; // started?
+client.scheduler.list(); // every task
+client.scheduler.remove("heartbeat"); // cancel + forget
+client.scheduler.stop(); // cancel all timers
+```
+
+Task errors are caught and logged through `client.logger` (scope `scheduler`),
+so a throwing task never crashes the process or stops future runs.