spearkit 0.3.1 → 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

@@ -1,9 +1,9 @@
 # File-based loading
 
 Instead of importing and registering every handler by hand, you can keep one
-command, event or component 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 or component.
+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`
 
@@ -36,8 +36,10 @@ await client.deployCommands({ guildId: process.env.GUILD_ID });
 
 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`), or a component (`button`, `stringSelect`, `modal`, …). Other
-exports (helpers, constants, types) are ignored. So both of these are picked up:
+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

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/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/prefix.md

@@ -31,6 +31,25 @@ new SpearClient({
 });
 ```
 
+### 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.
@@ -79,6 +98,8 @@ client.register(ping);
 | `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
@@ -92,6 +113,7 @@ adds the parsed arguments plus reply helpers.
 | `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. |
@@ -113,6 +135,38 @@ export const echo = prefixCommand({
 `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

package/docs/scheduler.md

@@ -6,7 +6,7 @@ outlive your bot.
 
 ## Define a task
 
-Provide exactly one of `cron` or `interval`:
+Provide exactly one of `cron` or `interval` (if both are set, the interval is used):
 
 ```ts
 import { task } from "spearkit";
@@ -55,7 +55,7 @@ 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`, `@monthly`, `@weekly`, `@daily`, `@hourly`.
+Aliases: `@yearly`/`@annually`, `@monthly`, `@weekly`, `@daily`/`@midnight`, `@hourly`.
 
 ```ts
 task({ name: "report", cron: "@daily", run: () => {} });
@@ -71,6 +71,30 @@ 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`:

package/docs/shutdown.md

@@ -0,0 +1,42 @@
+# Graceful shutdown
+
+A `Ctrl-C` or a container stop sends your process a signal. If you don't handle
+it, the process dies mid-flight — the gateway connection, scheduler timers, and
+any open database handles are reaped abruptly. Graceful shutdown runs an optional
+cleanup hook, calls `client.destroy()` (which also stops spearkit's scheduler),
+then exits — with a hard timeout so a wedged shutdown can't hang forever.
+
+## On a SpearClient
+
+```ts
+client.enableGracefulShutdown({
+  onShutdown: () => db.close(), // flush state before we exit
+});
+await client.start();
+```
+
+Progress is logged through `client.logger`. The method returns a disposer that
+removes the signal handlers (useful for tests / hot-reload).
+
+## Standalone
+
+`gracefulShutdown(client, options)` works with any object that has a `destroy()`
+method:
+
+```ts
+import { gracefulShutdown } from "spearkit";
+
+gracefulShutdown(client, { onShutdown: () => db.close() });
+```
+
+## Options
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `signals` | `["SIGINT", "SIGTERM"]` | Signals to listen for. |
+| `timeoutMs` | `10000` | Force-exit if shutdown exceeds this. |
+| `onShutdown` | — | Runs before `destroy()`; receives the signal. |
+| `exit` | `true` | Call `process.exit()` when done (set `false` in tests). |
+| `logger` | — | `{ info?, error? }` progress logger. |
+
+Shutdown runs **once** — repeated signals during teardown are ignored.

package/docs/store.md

@@ -0,0 +1,90 @@
+# Key-value store & settings
+
+Almost every community bot needs to remember *something* per guild — a custom
+prefix, a mod-log channel, a welcome message — and reaches for a database on day
+one. spearkit ships a dependency-free `KeyValueStore` interface with two
+backends, plus a typed per-guild settings helper. Swap in Redis/SQL later by
+implementing the same interface.
+
+## Stores
+
+```ts
+import { JsonStore, MemoryStore } from "spearkit";
+
+const dev = new MemoryStore();             // in-memory, great for tests
+const prod = new JsonStore("data/db.json"); // durable JSON file
+```
+
+Both implement `KeyValueStore`:
+
+```ts
+await store.set("key", { any: "json" });
+await store.get<{ any: string }>("key"); // typed read, or undefined
+await store.has("key");
+await store.delete("key");                // → boolean (existed?)
+await store.keys();                       // → string[]
+await store.clear();
+```
+
+`MemoryStore` deep-clones on read and write, so callers can't mutate stored
+state. `JsonStore` serves reads from an in-memory cache and commits writes
+atomically (temp file + rename) through a queue — a crash mid-write can't corrupt
+the file, and concurrent writes don't interleave.
+
+## Typed per-guild settings
+
+`createSettings` wraps a store with defaults. `get` always returns a complete
+object; `set` persists *only* the overrides, so widening `defaults` later is
+safe.
+
+```ts
+import { JsonStore, createSettings } from "spearkit";
+
+const settings = createSettings({
+  store: new JsonStore("data/guilds.json"),
+  defaults: { prefix: "!", modLogChannelId: null as string | null },
+});
+
+const cfg = await settings.get(guildId);          // { prefix, modLogChannelId }
+await settings.set(guildId, { prefix: "?" });     // shallow-merged + persisted
+await settings.reset(guildId);                    // back to defaults
+```
+
+Pass `namespace` to keep several settings groups in one store:
+
+```ts
+const guilds = createSettings({ store, defaults: { prefix: "!" }, namespace: "guild" });
+const users = createSettings({ store, defaults: { xp: 0 }, namespace: "user" });
+```
+
+## Dynamic per-guild prefix
+
+A stored prefix is only useful if prefix commands respect it. `prefix.dynamic`
+resolves extra prefix(es) per message — combine it with `createSettings` for true
+per-guild prefixes:
+
+```ts
+const client = new SpearClient({
+  prefix: {
+    dynamic: async (message) =>
+      message.guildId ? (await settings.get(message.guildId)).prefix : null,
+  },
+});
+```
+
+The resolver runs on every candidate message, so keep it fast (cache or use the
+in-memory `JsonStore` cache). Returned prefixes are tried *in addition* to any
+static `prefix`. See [Prefix commands](./prefix.md) for the rest of the prefix
+system.
+
+## Namespacing a raw store
+
+`namespaced(store, prefix)` returns a `KeyValueStore` whose keys are
+transparently prefixed — handy for sharing one file across features:
+
+```ts
+import { namespaced } from "spearkit";
+
+const tags = namespaced(store, "tags");
+await tags.set("hello", "world"); // stored under "tags:hello"
+```

package/docs/usage.md

@@ -1,7 +1,8 @@
 # Usage tracking
 
-Usage tracking records **who used what**: every successful command, component,
-and prefix-command invocation becomes a `UsageEvent` that spearkit can persist to a
+Usage tracking records **who used what**: every command, component, context-menu
+and prefix-command invocation — successful or errored — becomes a `UsageEvent`
+that spearkit can persist to a
 store and/or mirror into a Discord channel. Turn it on with the client's `usage`
 option.
 
@@ -13,13 +14,14 @@ independent sinks:
 | | Logger | Usage tracking |
 | --- | --- | --- |
 | Question | *What is the bot doing?* (diagnostics) | *Who used which feature?* (audit) |
-| Content | Free-form messages, levels, errors, internals | Structured `UsageEvent`s for successful uses |
+| Content | Free-form messages, levels, errors, internals | Structured `UsageEvent`s for every completed use (with its `outcome`) |
 | Sinks | Console / your log pipeline | A database store and/or a Discord channel |
 | Configured by | the `logger` option | the `usage` option |
 
-A failed or errored command shows up in your **logs**; it is not recorded as a
-usage event. Reach for the [logger](./logging.md) for debugging, and usage
-tracking for analytics, audit trails, and "top commands" dashboards.
+Both successes and handler errors are recorded as usage events — an error carries
+`outcome: "error"` and an `errorMessage` — so usage is a complete audit trail.
+The [logger](./logging.md) is for debugging; usage tracking is for analytics,
+audit trails, and "top commands" dashboards.
 
 ## Enabling it
 
@@ -37,8 +39,9 @@ const client = new SpearClient({
 });
 ```
 
-Once enabled, spearkit auto-tracks every successful command, component, and prefix
-command — you write no tracking code in your handlers.
+Once enabled, spearkit auto-tracks every command, component, context-menu and
+prefix-command invocation — successes and errors alike — with no tracking code in
+your handlers.
 
 ## The usage event
 
@@ -46,15 +49,22 @@ Each tracked use is a `UsageEvent`:
 
 ```ts
 interface UsageEvent {
-  type: "command" | "prefix" | "component" | "event";
-  name: string;            // command/component/event name
+  type: UsageType;         // "command" | "prefix" | "component" | "event"
+  name: string;            // command / component / event name
   userId?: string;
   userTag?: string;
   guildId?: string | null;
   channelId?: string | null;
   detail?: string;         // free-form extra detail
+  outcome?: UsageOutcome;  // "success" | "error"
+  durationMs?: number;     // handler wall-clock time
+  options?: Readonly<Record<string, UsageMetaValue>>; // snapshot of typed options
+  errorMessage?: string;   // set when outcome === "error"
   timestamp: Date;
 }
+type UsageType = "command" | "prefix" | "component" | "event";
+type UsageOutcome = "success" | "error";
+type UsageMetaValue = string | number | boolean | null;
 ```
 
 ## Stores (the database)