# Getting Started with Kitten

hi! welcome to kitten, this guide will help you get started.

## table of contents

- [bootstrapping](#bootstrapping)
- [logging](#logging)
- [defining your first command](#defining-your-first-command)
- [adding subcommands](#adding-subcommands)
- [context menus](#context-menus)
- [interactive components](#interactive-components)
- [adding autocomplete](#adding-autocomplete)
- [static choices](#static-choices)
- [localisation & other available configurations](#localisation--other-available-configurations)
- [using middleware](#using-middleware)
- [using afterware](#using-afterware)
- [handling errors](#handling-errors)
- [registering our commands and components](#registering-our-commands-and-components)

## bootstrapping

to get started, we need to initialise a new discord.js Client as you normally
would, and then pass it to a new Kitten instance.

```ts
import { Client, GatewayIntentBits } from "discord.js";
import { Kitten } from "kitten";

const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const kitten = new Kitten(client);
```

next, we'll attach an event listener to the client's `clientReady` event, and
call `kitten.sync()` to register our commands with the Discord API, we'll also
log the client in.

```ts
client.once("clientReady", async () => {
	// in development, it's recommened to sync commands to a single guild for
	// faster updates
	const isDev = process.env.NODE_ENV === "development";

	await kitten.sync({
		guildId: isDev ? process.env.GUILD_ID : undefined,
	});
});

await client.login(process.env.DISCORD_TOKEN);
```

and we're ready to start building out some commands and components!

## logging

kitten extends Node's native `EventEmitter` and does not enforce any specific
logging library. instead, it emits typed events (`debug`, `info`, `warn`, and
`error`) which you can handle however you like. kitten will not log on its own.

```ts
// subscribe to events for logging and diagnostics
kitten.on("debug", (message, data) => {
	console.debug(`[DEBUG] ${message}`, data ?? "");
});

kitten.on("info", (message, data) => {
	console.info(`[INFO] ${message}`, data ?? "");
});

kitten.on("warn", (message, data) => {
	console.warn(`[WARN] ${message}`, data ?? "");
});

// hook into execution errors
kitten.on("error", (message, data) => {
	console.error(`[ERROR] ${message}`, data ?? "");
});
```

## defining your first command

commands are defined using `kitten.command`, options are defined dynamically
which gives you type-safe parameters directly inside of your command's `run`
callback, so you can do away with `interaction.options.getString("param")`.

```ts
const whoisCommand = kitten.command("whois", {
	description: "get information about a user",
	options: {
		user: option.user.required("the user to get information about"),
		ephemeral: option.boolean.optional("whether the response should be ephemeral"),
	},
	async run(interaction, { user, ephemeral }) {
		await interaction.reply({
			content: `User ID: ${user.id}`,
			ephemeral: ephemeral ?? false,
		});
	},
});
```

if you view the type definitions for `user` and `ephemeral`, you'll notice that
they're both appropriately typed.

## adding subcommands

if your command has multiple sub-actions, you can chain `.subcommand` definitions.

```ts
const configCommand = kitten.command("config", {
	description: "configure bot settings",
});

configCommand.subcommand("set", {
	description: "Set a configuration value",
	options: {
		key: option.string.required("the setting key"),
		value: option.string.required("the value"),
	},
	async run(interaction, { key, value }) {
		await interaction.reply(`set ${key} to ${value}`);
	},
});
```

## context menus

kitten supports both User and Message context menu commands with strict type
inference for your targets.

```ts
const reportUser = kitten.userContextMenu("Report User", {
	async run(interaction, ctx) {
		const targetUser = interaction.targetUser; // typed as User
		await interaction.reply({ content: `reporting ${targetUser.username}...` });
	},
});

const bookmarkMessage = kitten.messageContextMenu("bookmark message", {
	async run(interaction, ctx) {
		const targetMessage = interaction.targetMessage; // typed as Message
		await interaction.reply({ content: `bookmarked: "${targetMessage.content}"` });
	},
});
```

## interactive components

kitten simplifies routing and parsing custom IDs for buttons, select menus, and
modals. when you define a component, you define the schema of the payload you
want to store in its `customId`.

```ts
const closeTicketButton = kitten.button("close-ticket", {
	options: {
		ticketId: option.string(),
	},
	async run(interaction, { ticketId }) {
		// ticketId: strign | undefined
		await interaction.reply(`closing ticket: ${ticketId}`);
	},
});
```

instead of instantiating standard discord.js builders and setting their custom IDs manually, you can use the built-in type-safe builders directly on your component instance:

```ts
const button = closeTicketButton
	.button({ ticketId: "67" }) // customId serialises to `close-ticket:67`
	.setLabel("close ticket")
	.setStyle(ButtonStyle.Danger);
```

kitten will automatically match incoming interactions to the `close-ticket`
handler, and parse the `ticketId` parameter for you. just like with commands.

modals and select menus work similarly.

```ts
const modal = myModal.modal({ foo: "bar" }); // customId serialises to `my-modal:bar`

const selectMenu = mySelectMenu.selectMenu({ foo: "baz" }); // id = `my-select-menu:baz`
```

note! custom IDs must be 100 characters or less, so be mindful of how much data
you store in them.

kitten will throw a `CustomIdTooLongError` if you exceed this limit.

## adding autocomplete

you can define autocomplete logic directly within your option definitions.
kitten handles routing the autocomplete interaction and running your helper.

let's go back to our `config set` subcommand and add an autocomplete helper to
the `key` option.

```ts
configCommand.subcommand("set", {
	description: "Set a configuration value",
	options: {
		key: option.string("the option key", {
			required: true,
			async autocomplete(interaction, value) {
				// `value` is the current string the user has typed
				const keys = ["prefix", "welcomeMessage", "modLogChannel"];
				const matches = keys.filter((key) => key.startsWith(value)).slice(0, 25);

				// and we return an array of objects with `name` and `value` properties
				// with a max of 25 results.
				return matches.map((key) => ({ name: key, value: key }));
			},
		}),

		value: option.string.required("the value"),
	},
	async run(interaction, { key, value }) {
		await interaction.reply(`set ${key} to ${value}`);
	},
});
```

## static choices

in addition to async `autocomplete` functions, command options can define static
choice lists directly. Discord will then present these choices to the user as a
dropdown list.

```ts
const dbDriverOption = option.string("database driver", {
	required: true,
	choices: [
		{ name: "PostgreSQL", value: "postgres" },
		{ name: "SQLite", value: "sqlite" },
	],
});
```

## localisation & other available configurations

kitten supports multi-locale configuration, NSFW toggles, and member permission
definitions across options, choices, top-level commands, subcommands, and
subcommand groups.

```ts
import { PermissionFlagsBits } from "discord.js";

const configCommand = kitten.command("config", {
	description: "configure bot settings",
	nameLocalizations: {
		fr: "configuration",
		"es-ES": "ajustes",
	},
	defaultMemberPermissions: PermissionFlagsBits.Administrator,
	nsfw: false,
});

configCommand.subcommand("set", {
	description: "set a configuration value",
	nameLocalizations: {
		fr: "definir",
	},
	options: {
		key: option.string("the setting key", {
			required: true,
			nameLocalizations: {
				fr: "clef",
			},
			choices: [
				{
					name: "Prefix",
					value: "prefix",
					nameLocalizations: { fr: "Préfixe" },
				},
			],
		}),
	},
	async run(interaction, { key }) {
		await interaction.reply(`setting updated: ${key}`);
	},
});
```

## using middleware

when building larger bots, you often need to fetch database records, check
permissions, or rate limit commands.

kitten's middleware builder lets you chain pre-execution checks and pass their
results down as typed context.

```ts
const base = kitten.builder();

const authorised = base
	.use(async (interaction) => {
		const user = await db.getUser(interaction.user.id);

		if (!user) {
			await interaction.reply({ content: "no account found.", ephemeral: true });
			throw new HaltExecution();
		}

		return { user };
	})
	.use(async (interaction, context) => {
		if (!context.user.moderator) {
			await interaction.reply({
				content: "you are not authorised to use this command.",
				ephemeral: true,
			});

			throw new HaltExecution();
		}

		return {};
	});
```

```ts
const banCommand = authorised.command("ban", {
	description: "ban a user",
	options: {
		user: option.user.required("the user to ban"),
	},
	async run(interaction, args, context) {
		// context: { user: { id: string; moderator: boolean; ... } }
		await banUser(args.user.id, context.user.id);
		await interaction.reply(`banned ${args.user.username} (${args.user.id})`);
	},
});
```

## using afterware

where middleware runs _before_ execution to compile context, afterware runs
_after_ execution (in a safe `finally` block) regardless of whether your
interaction succeeded, threw an exception, or was halted.

### strict typings

you can specify the expected return type of your interaction handlers by passing
a generic type to `.after()`. this ensures:

- the `result` parameter inside your afterware is strictly typed as
  `Res | undefined`.
- TypeScript will enforce at compile-time that any commands built from this
  builder _must_ return a type assignable to your declared generic.

```ts
interface PaymentResult {
	receiptId: string;
	amount: number;
	status: "completed" | "flagged";
}

const payBuilder = kitten
	.builder()
	.use((interaction, ctx) => {
		return {
			startTime: performance.now(),
			requestId: `req_${Math.random().toString(36).substring(2, 9)}`,
		};
	})
	.after<PaymentResult>(async (interaction, ctx, error, result) => {
		const duration = performance.now() - ctx.startTime;

		console.log(`[req ${ctx.requestId}] processed in ${duration.toFixed(2)}ms`);

		if (error) {
			console.error(`[req ${ctx.requestId}] payment failed:`, error);
			return;
		}

		// result is strictly typed as: PaymentResult | undefined
		if (result) {
			console.log(
				`[req ${ctx.requestId}] payment successful! receiptId:${result.receiptId}, amount:$${result.amount / 100}`,
			);
		}
	});

const payCommand = payBuilder.command("pay", {
	description: "process a payment.",
	options: {
		amount: option.integer.required("the billing amount in USD"),
	},
	async run(interaction, { amount }, ctx) {
		const receiptId = await processPayment(amount);

		await interaction.reply({
			content: `payment processed! receipt ID: ${receiptId}`,
			ephemeral: true,
		});

		return {
			receiptId,
			amount,
			status: "completed",
		};
	},
});
```

## handling errors

kitten implements a multi-level, context-aware error propagation pipeline. if an
error is thrown in middleware or command, your accumulated context up to that point
is preserved and supplied to the handler.

kitten searches for handlers up the chain:

1. local error handlers defined on the command/component configuration.
2. builder-level error handlers configured via `.onError()`.
3. global error handler configured on your `Kitten` instance.

if a handler resolves without throwing, propagation stops. if it throws, that
new error is propagated up to the next tier.

if kitten experiences an uncaught error, it will log it to the console and
reply with a generic error message to the user.

### global error handler

note that context here is just typed as `any` since it's not known what the
context will be at this point. though, we could possibly make use of type
narrowing here in future.

```ts
const kitten = new Kitten(client, {
	onError(err, interaction, ctx) {
		console.error("uncaught global exception:", err);
	},
});

kitten.onError((err, interaction, ctx) => {
	console.error("uncaught global exception:", err);
});
```

### builder-level error handler

```ts
const accountGroup = kitten
	.builder()
	.use(async (interaction) => {
		const account = await whatever();
		return { account };
	})
	.onError(async (err, interaction, ctx) => {
		// ctx.account is accessible if the error occurred after resolved.
		console.error(`failure on account: ${ctx.account?.id}`, err);
		if (interaction.isRepliable()) {
			await interaction.reply({
				content: "command could not be processed.",
				flags: ["Ephemeral"],
			});
		}
	});
```

### local error handler

```ts
accountGroup.command("account", {
	description: "manage your account",
	options: {
		username: option.string({
			description: "your username",
			required: true,
		}),
	},
	onError(err, interaction, ctx) {
		// handles only failures specific to this command.
		console.warn(`failed to execute command for ${ctx.account?.id}`, err);
	},
	async run(interaction, { amount }, ctx) {
		await whatever2();
		await interaction.reply("Invoice paid successfully!");
	},
});
```

## registering our commands and components

and we're almost there! the final step is to register our commands and
components with kitten.

you should register all of your commands and components before calling
`kitten.sync()`, otherwise they won't be registered with the Discord API.

```ts
kitten.register({
	commands: [whoisCommand, configCommand, banCommand, reportUser, bookmarkMessage],
	components: [closeTicketButton],
});
```

## all done!