spearkit 0.3.0 → 0.3.1

package/docs/client.md

@@ -0,0 +1,207 @@
+# Client
+
+`SpearClient` is a discord.js `Client` with command, event and component
+registries — plus interaction routing — wired up for you. You construct it the
+same way you construct a discord.js client, register your handlers, log in, and
+(optionally) push your slash commands to Discord.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+```
+
+## Constructing a client
+
+`new SpearClient(options?)` takes the same options as discord.js'
+`ClientOptions`, except `intents` may be omitted: it defaults to
+`Intents.default` (just the `Guilds` intent, enough for slash commands and
+interactions).
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+// Explicit preset.
+const a = new SpearClient({ intents: Intents.messages });
+
+// Omitted — falls back to Intents.default.
+const b = new SpearClient();
+```
+
+The options type is exported as `SpearClientOptions` (`Partial<ClientOptions>`),
+so every other discord.js option (`partials`, `presence`, `sweepers`, …) is
+available.
+
+### Intents presets
+
+`Intents` is a set of ready-made arrays of `GatewayIntentBits`. Pass one as
+`intents`, or compose your own array of `GatewayIntentBits` if you need
+something in between.
+
+| Preset | Contents |
+| ------ | -------- |
+| `Intents.none` | `[]` |
+| `Intents.default` | `[Guilds]` |
+| `Intents.guilds` | `[Guilds, GuildMembers]` |
+| `Intents.messages` | `[Guilds, GuildMessages, MessageContent]` |
+| `Intents.all` | Every intent, including privileged ones. |
+
+`Intents.messages` includes `MessageContent`, and `Intents.guilds` includes
+`GuildMembers` — both are **privileged intents**. You must enable them in the
+Discord developer portal for your application, otherwise the gateway will reject
+the connection. `Intents.all` includes every privileged intent for the same
+reason.
+
+```ts
+import { SpearClient, GatewayIntentBits } from "spearkit";
+
+// A custom intent set, mixing a preset idea with explicit bits.
+const client = new SpearClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+});
+```
+
+## The three registries
+
+Every client owns three registries, each populated by `register` (or `load`):
+
+| Registry | Property | Holds |
+| -------- | -------- | ----- |
+| `CommandRegistry` | `client.commands` | Slash commands; dispatches chat-input and autocomplete interactions. |
+| `EventRegistry` | `client.events` | Event listeners; attached to the client automatically. |
+| `ComponentRegistry` | `client.components` | Buttons, selects and modals; routes component interactions by custom id. |
+
+You rarely touch them directly — `register` routes items into the right one —
+but they are public if you need to inspect or manipulate them (e.g.
+`client.commands.size`, `client.commands.toJSON()`).
+
+## Registering handlers
+
+`client.register(...items)` accepts commands, events and components in a single
+call and routes each to its registry by kind. The accepted union is exported as
+`Registerable` (`SlashCommand | EventDef | ComponentDef`). It returns the client
+for chaining.
+
+```ts
+import { SpearClient, command, event, button, option } from "spearkit";
+
+const client = new SpearClient();
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const ready = event("clientReady", (c) => {
+  console.log(`Logged in as ${c.user.tag}`); // c: Client<true>
+});
+
+const ping = button({
+  id: "ping:{n}",
+  label: "Ping",
+  run: (ctx) => ctx.reply(`pong #${ctx.params.n}`), // n: string
+});
+
+// Commands, events and components in one call.
+client.register(greet, ready, ping);
+```
+
+## Plugins
+
+`client.use(...plugins)` installs one or more plugins, awaiting each plugin's
+`setup`. It is async and returns the client.
+
+```ts
+import { SpearClient } from "spearkit";
+import { statsPlugin } from "./plugins/stats.js";
+
+const client = new SpearClient();
+await client.use(statsPlugin);
+```
+
+See [Plugins](./plugins.md) for authoring `SpearPlugin`s.
+
+## File-based loading
+
+`client.load(dir, options?)` recursively imports a directory and registers every
+command, event and component it exports. It returns the number of items
+registered.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+const count = await client.load("./src/commands");
+console.log(`Loaded ${count} handlers`);
+```
+
+See [File-based loading](./loading.md) for the layout and `LoadOptions`.
+
+## Starting and deploying
+
+`client.start(token?)` logs in. If you omit the token it falls back to the
+`DISCORD_TOKEN` environment variable, and throws if neither is present.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+// Pass a token explicitly…
+await client.start("your-token");
+
+// …or set DISCORD_TOKEN and call start() with no argument.
+await client.start();
+```
+
+`client.deployCommands({ guildId })` pushes the registered slash commands to
+Discord using the client's own authenticated REST connection — there is no
+separate token or application id to supply. Because it reads the application id
+from the logged-in client, it **must run after the client is ready**. Pass a
+`guildId` to deploy instantly to a single guild (ideal for development); omit it
+to deploy globally.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+// …register commands…
+
+await client.start(); // uses DISCORD_TOKEN
+
+// Deploy once the client is ready.
+client.once("clientReady", async () => {
+  await client.deployCommands({ guildId: process.env.GUILD_ID });
+});
+```
+
+## Everything discord.js still works
+
+`SpearClient` extends discord.js `Client`, so the full client surface is
+available unchanged. spearkit adds registries on top — it never hides what is
+underneath:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+client.on("guildCreate", (guild) => console.log(`Joined ${guild.name}`));
+client.ws.on("VOICE_SERVER_UPDATE", () => {});
+
+await client.start();
+
+console.log(client.application?.id); // application
+console.log(client.user?.tag); // user
+console.log(client.rest); // REST manager (used by deployCommands)
+
+await client.destroy(); // graceful shutdown
+```
+
+## See also
+
+- [Commands](./commands.md) — defining slash commands you register here.
+- [Plugins](./plugins.md) — bundling features for `client.use`.
+- [File-based loading](./loading.md) — populating the client from a directory.

package/docs/commands.md

@@ -0,0 +1,198 @@
+# Commands
+
+Slash commands in spearkit are defined as a single object: the metadata, the typed
+options, and the handler all live together. spearkit serialises them for discord
+and routes incoming interactions to the right handler for you.
+
+## A first command
+
+```ts
+import { command } from "spearkit";
+
+export const ping = command({
+  name: "ping",
+  description: "Check latency",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+Register it on a client (`client.register(ping)`) and deploy it (see
+[Deployment](#deployment)). That's the whole loop.
+
+## The command context
+
+The handler receives a `CommandContext`. It wraps the discord.js
+`ChatInputCommandInteraction` and adds ergonomic accessors and reply helpers.
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.options` | Resolved, fully-typed option values (see [Options](./options.md)). |
+| `ctx.commandName` | The invoked command name. |
+| `ctx.subcommand` | The invoked subcommand name, or `null`. |
+| `ctx.showModal(modal)` | Present a modal in response. |
+| `ctx.user` / `ctx.member` / `ctx.guild` / `ctx.guildId` / `ctx.channel` / `ctx.channelId` / `ctx.locale` | Actor and location accessors. |
+| `ctx.reply` / `ctx.replyEphemeral` / `ctx.defer` / `ctx.editReply` / `ctx.followUp` / `ctx.send` / `ctx.error` | Reply helpers (see [Contexts](./context.md)). |
+| `ctx.interaction` | The raw discord.js interaction, for anything not wrapped. |
+
+```ts
+import { command, option } from "spearkit";
+
+export const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    times: option.integer({ description: "Repeat count", minValue: 1, maxValue: 5 }),
+  },
+  run: (ctx) => {
+    ctx.options.text;  // string
+    ctx.options.times; // number | undefined
+    return ctx.reply({
+      content: ctx.options.text.repeat(ctx.options.times ?? 1),
+      ephemeral: true,
+    });
+  },
+});
+```
+
+Options are covered in depth in [Options](./options.md).
+
+## Command metadata
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export const purge = command({
+  name: "purge",
+  description: "Delete recent messages",
+  guildOnly: true,                                  // only usable in guilds
+  nsfw: false,                                      // age-restricted command
+  defaultMemberPermissions: PermissionFlagsBits.ManageMessages, // who sees it by default
+  nameLocalizations: { tr: "temizle" },             // localized name
+  descriptionLocalizations: { tr: "Mesajları sil" },
+  run: (ctx) => ctx.reply("…"),
+});
+```
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `guildOnly` | `boolean` | Restricts the command to guild contexts. |
+| `nsfw` | `boolean` | Marks the command age-restricted. |
+| `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate (members without it don't see the command). |
+| `nameLocalizations` / `descriptionLocalizations` | `LocalizationMap` | Per-locale name/description. |
+
+## Subcommands and groups
+
+For commands with subcommands, use `commandGroup` together with `subcommand`
+and (optionally) `subcommandGroup`. Each subcommand has its own typed options
+and handler; spearkit routes to the right one automatically.
+
+```ts
+import { commandGroup, subcommand, subcommandGroup, option } from "spearkit";
+
+export const admin = commandGroup({
+  name: "admin",
+  description: "Administration",
+  guildOnly: true,
+  // Direct subcommands: /admin say
+  subcommands: {
+    say: subcommand({
+      description: "Make the bot say something",
+      options: { message: option.string({ description: "Message", required: true }) },
+      run: (ctx) => ctx.reply(ctx.options.message),
+    }),
+  },
+  // Grouped subcommands: /admin users ban
+  groups: {
+    users: subcommandGroup({
+      description: "Manage users",
+      subcommands: {
+        ban: subcommand({
+          description: "Ban a member",
+          options: {
+            target: option.user({ description: "Member", required: true }),
+            reason: option.string({ description: "Reason" }),
+          },
+          run: (ctx) =>
+            ctx.reply(`Banned ${ctx.options.target.tag}: ${ctx.options.reason ?? "no reason"}`),
+        }),
+      },
+    }),
+  },
+});
+```
+
+Inside a subcommand handler, `ctx.options` is typed from *that subcommand's*
+options. There is no `switch (subcommand)` to write — spearkit dispatches by the
+invoked subcommand group/name.
+
+## The command registry
+
+`client.commands` is a `CommandRegistry`. You usually feed it through
+`client.register(...)`, but you can use it directly:
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry();
+registry.add(ping, echo, admin);
+
+registry.get("ping");   // SlashCommand | undefined
+registry.names;         // string[]
+registry.size;          // number
+registry.remove("ping"); // boolean
+registry.toJSON();      // REST payloads for all commands
+```
+
+`SpearClient` calls `registry.handle(interaction)` and
+`registry.handleAutocomplete(interaction)` for you on every interaction.
+
+### Error handling
+
+If a handler throws, spearkit catches it. By default it emits the client's `error`
+event and replies with an ephemeral "something went wrong" message. Override
+that:
+
+```ts
+client.commands.onError((error, interaction) => {
+  console.error(`/${interaction.commandName} failed`, error);
+  if (!interaction.replied && !interaction.deferred) {
+    return interaction.reply({ content: "Command failed.", ephemeral: true });
+  }
+});
+```
+
+## Deployment
+
+Commands must be registered with discord before they appear. spearkit gives you two
+ways.
+
+**From the client** (uses the client's authenticated REST; call after ready):
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId for global
+```
+
+**Standalone** (a separate deploy script, no running client needed):
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry().add(ping, echo, admin);
+await registry.deploy({
+  token: process.env.DISCORD_TOKEN,
+  applicationId: process.env.DISCORD_APP_ID,
+  guildId: process.env.GUILD_ID, // optional
+});
+```
+
+Guild deploys apply **instantly** and are ideal during development. Global
+deploys (no `guildId`) can take up to an hour to propagate.
+
+## See also
+
+- [Options](./options.md) — typed option builders, choices, autocomplete.
+- [Components](./components.md) — buttons, selects, modals.
+- [Client](./client.md) — registering and deploying from the client.
+- [Contexts](./context.md) — the reply helpers every handler shares.

package/docs/components.md

@@ -0,0 +1,274 @@
+# 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"`.
+
+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. |
+
+### 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.