spearkit 0.3.0 → 0.4.0

package/docs/components.md

@@ -0,0 +1,281 @@
+# Components
+
+Buttons, select menus and modals in spearkit follow one pattern: define the
+appearance, the **custom-id pattern**, and the handler in one place; register
+it; then `build()` the discord.js component to put in a message. spearkit decodes
+incoming interactions and routes them to your handler — no `interactionCreate`
+switch statements, no manual custom-id parsing.
+
+```ts
+import { button, row } from "spearkit";
+
+const vote = button({
+  id: "vote:{choice}",
+  label: "Yes",
+  style: "Success",
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // ctx.params.choice: string
+});
+
+client.register(vote); // or client.components.add(vote)
+
+await channel.send({
+  content: "Cast your vote:",
+  components: [row(vote.build({ choice: "yes" }))], // build() requires { choice }
+});
+```
+
+## Custom-id patterns
+
+The `id` is a pattern with the grammar `name` or `name:{param}` or
+`name:{a}:{b}`. The leading `name` is the routing **namespace**; each `{param}`
+becomes a positional value carried in the custom-id.
+
+- In the handler, params are available as a typed object: `ctx.params.choice`.
+- `build(params)` requires **exactly** those params and encodes them into the
+  custom-id.
+
+```ts
+const page = button({
+  id: "page:{id}:{dir}",
+  label: "Next",
+  run: (ctx) => ctx.update(`item ${ctx.params.id}, going ${ctx.params.dir}`),
+});
+
+page.build({ id: "42", dir: "next" }); // custom-id "page:42:next"
+```
+
+spearkit percent-escapes param values, so they may safely contain `:`. Custom-ids
+are limited to 100 characters (`MAX_CUSTOM_ID_LENGTH`); `build()` throws if you
+exceed it.
+
+For advanced use, the codec is exported directly: `compilePattern`,
+`buildCustomId`, `parseCustomId`, and `paramsFromValues`.
+
+## Buttons
+
+```ts
+import { button, linkButton, ButtonStyle } from "spearkit";
+
+const confirm = button({
+  id: "confirm:{action}",
+  label: "Confirm",
+  style: ButtonStyle.Danger,     // or the string "Danger"
+  emoji: "⚠️",
+  disabled: false,
+  run: (ctx) => ctx.update(`Confirmed: ${ctx.params.action}`),
+});
+
+// Link buttons have no handler and no custom-id:
+const docs = linkButton({ url: "https://example.com", label: "Docs" });
+```
+
+`style` accepts the string names `"Primary"`, `"Secondary"`, `"Success"`,
+`"Danger"`, or the `ButtonStyle` enum. It defaults to `"Secondary"`.
+
+All component builders (`button`, the five selects, and `modal`) also accept
+`guards?: readonly Guard[]` — preconditions evaluated before the handler runs.
+See [Guards](./guards.md).
+
+The `ButtonContext` adds, on top of the shared [reply helpers](./context.md):
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.params` | Decoded custom-id params. |
+| `ctx.update(input)` | Edit the message the button is on. |
+| `ctx.deferUpdate()` | Acknowledge without editing yet. |
+| `ctx.showModal(modal)` | Open a modal in response. |
+| `ctx.message` | The message the button belongs to. |
+| `ctx.customId` | The raw custom-id. |
+
+## Select menus
+
+There are five select builders. All share `placeholder`, `minValues`,
+`maxValues`, and `disabled`; the string select additionally takes `options`,
+and the channel select takes `channelTypes`.
+
+```ts
+import { stringSelect, channelSelect, ChannelType } from "spearkit";
+
+const colour = stringSelect({
+  id: "colour",
+  placeholder: "Pick a colour",
+  minValues: 1,
+  maxValues: 1,
+  options: [
+    { label: "Red", value: "red" },
+    { label: "Green", value: "green", description: "the calm one" },
+    { label: "Blue", value: "blue", default: true },
+  ],
+  run: (ctx) => ctx.reply({ content: `You picked ${ctx.values.join(", ")}`, ephemeral: true }),
+});
+
+const pickChannel = channelSelect({
+  id: "pick-channel",
+  channelTypes: [ChannelType.GuildText],
+  run: (ctx) => ctx.reply({ content: `${ctx.values.length} channel(s)`, ephemeral: true }),
+});
+```
+
+Each select context exposes the relevant resolved data:
+
+| Builder | Context | Extra accessors |
+| ------- | ------- | --------------- |
+| `stringSelect` | `StringSelectContext` | `values: string[]`, `value: string \| undefined` |
+| `userSelect` | `UserSelectContext` | `values`, `users`, `members` |
+| `roleSelect` | `RoleSelectContext` | `values`, `roles` |
+| `channelSelect` | `ChannelSelectContext` | `values`, `channels` |
+| `mentionableSelect` | `MentionableSelectContext` | `values`, `users`, `roles`, `members` |
+
+Select contexts also have `ctx.params`, `ctx.update`, `ctx.deferUpdate`,
+`ctx.showModal`, and the shared reply helpers.
+
+## Modals
+
+A modal declares its `fields` as a map of name → `textInput`. The submit handler
+receives the submitted values in `ctx.fields`, keyed (and typed) by those names,
+plus any custom-id params in `ctx.params`.
+
+```ts
+import { modal, textInput } from "spearkit";
+
+const feedback = modal({
+  id: "feedback:{ticket}",
+  title: "Feedback",
+  fields: {
+    summary: textInput({ label: "Summary", required: true }),
+    detail: textInput({ label: "Details", style: "Paragraph", maxLength: 2000 }),
+  },
+  run: (ctx) =>
+    ctx.reply({
+      // ctx.params.ticket: string, ctx.fields.summary / ctx.fields.detail: string
+      content: `#${ctx.params.ticket}: ${ctx.fields.summary}`,
+      ephemeral: true,
+    }),
+});
+```
+
+`textInput` config: `label` (required), `style` (`"Short"` default, or
+`"Paragraph"`, or a `TextInputStyle`), `placeholder`, `required`, `minLength`,
+`maxLength`, `value`.
+
+Open a modal from a command or a component handler with `showModal` — modals
+cannot be the *response* to another modal, but they can follow a command or a
+button/select:
+
+```ts
+import { command } from "spearkit";
+
+const ask = command({
+  name: "ask",
+  description: "Open the feedback form",
+  run: (ctx) => ctx.showModal(feedback.build({ ticket: "1234" })),
+});
+```
+
+## Action rows
+
+`row(...components)` wraps builders in an `ActionRowBuilder`. A row holds up to
+five buttons, or exactly one select menu.
+
+```ts
+import { row } from "spearkit";
+
+const components = [
+  row(confirm.build({ action: "delete" }), docs),
+  row(colour.build()),
+];
+await channel.send({ content: "Choose:", components });
+```
+
+## Registering and routing
+
+Register components like anything else:
+
+```ts
+client.register(vote, colour, feedback);
+// equivalently:
+client.components.add(vote, colour, feedback);
+```
+
+`SpearClient` routes every button, select and modal interaction to the matching
+namespace automatically. The `ComponentRegistry` API:
+
+| Member | Description |
+| ------ | ----------- |
+| `add(...defs)` | Register components (override by namespace). |
+| `size` | Number registered. |
+| `onError(handler)` | Set the error handler. |
+| `handle(interaction)` | Route an interaction; returns `true` if matched. |
+| `setDefaultGuards(guards)` | Guards run before each component's own guards. |
+
+`setLogger` and `setUsageHook` also exist; the client wires all three for you.
+
+### Error handling
+
+By default a throwing handler emits the client `error` event and replies with an
+ephemeral message. Customise it:
+
+```ts
+client.components.onError((error, interaction) => {
+  console.error("component failed", error);
+});
+```
+
+## End-to-end example
+
+```ts
+import {
+  SpearClient,
+  Intents,
+  command,
+  button,
+  stringSelect,
+  modal,
+  textInput,
+  row,
+} from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const open = button({
+  id: "open-form:{topic}",
+  label: "Open form",
+  style: "Primary",
+  run: (ctx) => ctx.showModal(form.build({ topic: ctx.params.topic })),
+});
+
+const rating = stringSelect({
+  id: "rating",
+  placeholder: "Rate us",
+  options: [
+    { label: "Good", value: "good" },
+    { label: "Bad", value: "bad" },
+  ],
+  run: (ctx) => ctx.reply({ content: `Thanks: ${ctx.value}`, ephemeral: true }),
+});
+
+const form = modal({
+  id: "form:{topic}",
+  title: "Tell us more",
+  fields: { body: textInput({ label: "Message", style: "Paragraph", required: true }) },
+  run: (ctx) => ctx.reply({ content: `[${ctx.params.topic}] ${ctx.fields.body}`, ephemeral: true }),
+});
+
+const panel = command({
+  name: "panel",
+  description: "Show the panel",
+  run: (ctx) =>
+    ctx.reply({
+      content: "How was it?",
+      components: [row(open.build({ topic: "support" })), row(rating.build())],
+    }),
+});
+
+client.register(panel, open, rating, form);
+```
+
+## See also
+
+- [Commands](./commands.md) — opening components from commands.
+- [Contexts](./context.md) — the reply/update helpers contexts share.
+- [Client](./client.md) — registration and routing.

package/docs/context-menus.md

@@ -0,0 +1,121 @@
+# Context-menu commands
+
+Context-menu commands are the right-click **"Apps"** actions Discord shows on a
+user or a message. spearkit makes them first-class: define one with `userCommand`
+or `messageCommand`, register it like anything else, and deploy it alongside your
+slash commands. The handler gets a typed `targetUser` or `targetMessage`.
+
+```ts
+import { userCommand } from "spearkit";
+
+export const whois = userCommand({
+  name: "Who is this?",
+  run: (ctx) => ctx.replyEphemeral(`That's ${ctx.targetUser.tag}.`),
+});
+```
+
+`name` is the label shown in the Apps menu (no description — Discord does not show
+one for context-menu commands).
+
+## User vs message commands
+
+| Builder | Appears on | Target context |
+| ------- | ---------- | -------------- |
+| `userCommand` | a user (right-click → Apps) | `ctx.targetUser`, `ctx.targetMember` |
+| `messageCommand` | a message (right-click → Apps) | `ctx.targetMessage` |
+
+```ts
+import { messageCommand } from "spearkit";
+
+export const report = messageCommand({
+  name: "Report message",
+  run: (ctx) =>
+    ctx.replyEphemeral(`Reported message ${ctx.targetMessage.id}.`),
+});
+```
+
+Both handler contexts extend the shared [`BaseContext`](./context.md), so
+`ctx.reply`, `ctx.replyEphemeral`, `ctx.defer`, `ctx.success/error/...` and the
+usual accessors are all available.
+
+## Metadata, cooldowns and guards
+
+Both builders accept the same metadata, plus a `cooldown` and `guards`:
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `name` | `string` | The Apps-menu label. |
+| `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate. |
+| `nsfw` | `boolean` | Marks the command age-restricted. |
+| `guildOnly` | `boolean` | Restricts it to guild contexts. |
+| `nameLocalizations` | `LocalizationMap` | Per-locale label. |
+| `cooldown` | `number \| CooldownConfig` | Rate limit (shares `client.cooldowns`). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. |
+| `autoDefer` | `boolean \| { ephemeral?, delayMs? }` | Auto-`deferReply()` if the handler is slow, preventing `Unknown interaction`. |
+
+```ts
+import { userCommand, guildOnly, requireUserPermissions, PermissionFlagsBits } from "spearkit";
+
+export const warn = userCommand({
+  name: "Warn user",
+  guildOnly: true,
+  cooldown: 5_000,
+  guards: [requireUserPermissions(PermissionFlagsBits.ModerateMembers)],
+  run: (ctx) => ctx.replyEphemeral(`Warned ${ctx.targetUser.tag}.`),
+});
+```
+
+See [Cooldowns](./cooldown.md) and [Guards](./guards.md) for the shared options.
+
+## Registering and deploying
+
+Register context-menu commands like everything else with `client.register(...)`.
+They route automatically — spearkit dispatches user- and message-context-menu
+interactions to the matching command.
+
+```ts
+client.register(whois, report, warn);
+```
+
+Because context menus and slash commands deploy to the same Discord endpoint,
+push them together with `deployAllCommands` once you mix the two — it sends both
+in a single request. (`deployCommands` is slash-only.)
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployAllCommands({ guildId: process.env.GUILD_ID }); // slash + menus
+```
+
+`deployAllCommands` also supports a `dryRun` flag and a `strategy: "diff"` that
+skips the PUT when the remote set already matches — handy in CI:
+
+```ts
+// Preview without touching Discord:
+const result = await client.deployAllCommands({ guildId, dryRun: true });
+// → { skipped: true, reason: "dry-run", body: [...] }
+
+// Only deploy when something changed:
+await client.deployAllCommands({ guildId, strategy: "diff" });
+```
+
+## The registry
+
+`client.contextMenus` is a `ContextMenuRegistry`. The client wires it to the
+logger and cooldown manager and routes interactions for you, so you rarely touch
+it directly:
+
+```ts
+client.contextMenus.size;   // number registered
+client.contextMenus.all();  // ContextMenuCommand[]
+client.contextMenus.toJSON(); // REST payloads (also included by deployAllCommands)
+```
+
+Note: context-menu commands are **not** picked up by `client.load(...)`
+directory loading — register them explicitly with `client.register(...)`.
+
+## See also
+
+- [Commands](./commands.md) — slash commands.
+- [Client](./client.md) — `deployAllCommands` and registration.
+- [Guards](./guards.md) / [Cooldowns](./cooldown.md) — the shared preconditions.
+- [Contexts](./context.md) — the reply helpers every handler shares.

package/docs/context.md

@@ -0,0 +1,293 @@
+# 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(input, options?)` | `Promise<void>` | State-aware preset error embed; ephemeral by default. |
+| `success` / `info` / `warn` `(input, options?)` | `Promise<void>` | State-aware preset embeds. |
+| `replyError` / `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `Promise<InteractionResponse>` | Initial-reply preset embeds. |
+
+```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(input, options?)` sends a state-aware preset **error embed** — ephemeral
+by default (pass `{ ephemeral: false }` to make it public) — 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}.`);
+  },
+});
+```
+
+## Preset embeds
+
+`BaseContext` builds consistent, colored embeds from `client.embeds` (or a shared
+default). Each takes an `EmbedPresetInput` — a plain string, or a structured body
+(`{ title?, description?, fields?, footer?, ... }`) — and an optional
+`{ ephemeral? }`.
+
+| Method | Sends via | Default visibility |
+| ------ | --------- | ------------------ |
+| `success(input, options?)` | `send` (state-aware) | public |
+| `info(input, options?)` | `send` (state-aware) | public |
+| `warn(input, options?)` | `send` (state-aware) | public |
+| `error(input, options?)` | `send` (state-aware) | **ephemeral** |
+| `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `reply` (initial only) | public |
+| `replyError(input, options?)` | `reply` (initial only) | **ephemeral** |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "save",
+  description: "Save settings",
+  run: async (ctx) => {
+    await ctx.success("Settings saved.");            // green embed, public
+    await ctx.warn({ title: "Heads up", description: "Quota is almost full." });
+    // error defaults to ephemeral; make it public with { ephemeral: false }:
+    // await ctx.error("Failed to save.", { ephemeral: false });
+  },
+});
+```
+
+Configure the colors/icons with the client `embeds` option; see the
+[API reference](./api-reference.md#embeds--preset-replies).
+
+## 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. |
+| `botPermissions` | The bot's resolved permissions in the channel (`PermissionsBitField`, zero-fetch). |
+
+```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.");
+  },
+});
+```
+
+## Permission preflights
+
+`BaseContext` reads the permissions Discord already attached to the interaction —
+no extra fetches — so you can check before attempting a privileged action:
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export default command({
+  name: "slowmode",
+  description: "Set slowmode",
+  run: async (ctx) => {
+    const missing = ctx.botMissing(PermissionFlagsBits.ManageChannels);
+    if (missing.length > 0) return ctx.error(`I'm missing: ${missing.join(", ")}`);
+    // …apply slowmode…
+  },
+});
+```
+
+- `ctx.botPermissions` — the bot's `PermissionsBitField` in the current channel.
+- `ctx.botMissing(required)` — permission names the bot lacks here (`[]` if none).
+- `ctx.userMissing(required)` — permission names the invoking user lacks here.
+
+For role-hierarchy and moderation preflights (acting on self/owner, comparing top
+roles) see `moderationCheck` and the permission helpers in the
+[API reference](./api-reference.md#permissions--moderation).
+
+## Awaiting input
+
+When a flow needs a follow-up message or a modal, the context wraps discord.js
+collectors so you skip the boilerplate. Both resolve to `null` on timeout.
+
+```ts
+import { command, modal, textInput } from "spearkit";
+
+const nameModal = modal({ id: "name", title: "Your name", fields: { name: textInput({ label: "Name" }) }, run: () => {} });
+
+export default command({
+  name: "setup",
+  description: "Interactive setup",
+  run: async (ctx) => {
+    // Wait for the user to type an answer in this channel:
+    const reply = await ctx.awaitMessageFrom(ctx.user.id, { time: 30_000 });
+    if (reply === null) return ctx.error("Timed out.");
+    // Or show a modal and await its submission:
+    const submission = await ctx.awaitModal(nameModal);
+    if (submission !== null) await submission.reply(`Hi, ${submission.fields.getTextInputValue("name")}!`);
+  },
+});
+```
+
+The standalone `awaitMessage`, `awaitComponent` and `showAndAwaitModal` helpers
+are also exported; see the [API reference](./api-reference.md#collectors).
+
+## See also
+
+- [Commands](./commands.md) — `CommandContext`, options and `showModal`.
+- [Components](./components.md) — button, select and modal contexts.