feat: Enhance documentation and type definitions across CommandKit and related plugins

- Added detailed JSDoc comments to various classes and methods in CommandKitPluginRuntime and CompilerPluginRuntime for better clarity and understanding.
- Introduced new interfaces and types to improve type safety and documentation in the i18n package.
- Enhanced the legacy commands and validations with comprehensive comments to clarify their purpose and usage.
- Removed unused utility functions and improved existing ones with better documentation.
- Updated Redis plugin to include documentation for the creation of new instances.
- Overall improvements to the structure and readability of the codebase through consistent documentation practices.

Author: twlite

packages/ai/src/ai-context-worker.ts

@@ -4,6 +4,9 @@ import { AiContext } from './context';
 
 const worker = new AsyncLocalStorage<{ message: Message; ctx: AiContext }>();
 
+/**
+ * @private
+ */
 export function getAiWorkerContext(): { message: Message; ctx: AiContext } {
   const ctx = worker.getStore();
 
@@ -16,6 +19,9 @@ export function getAiWorkerContext(): { message: Message; ctx: AiContext } {
   return ctx;
 }
 
+/**
+ * @private
+ */
 export function runInAiWorkerContext<R, F extends (...args: any[]) => R>(
   ctx: AiContext,
   message: Message,

packages/ai/src/context.ts

@@ -9,21 +9,46 @@ export interface AiContextOptions<
   commandkit: CommandKit;
 }
 
+/**
+ * Represents the context in which an AI command is executed.
+ * This includes the parameters passed to the command, the message that triggered it,
+ * and the CommandKit instance associated with the command.
+ */
 export class AiContext<
   T extends Record<string, unknown> = Record<string, unknown>,
 > {
+  /**
+   * The parameters passed to the AI command.
+   */
   public params!: T;
+  /**
+   * The message that triggered the AI command.
+   */
   public message!: Message;
+  /**
+   * The client instance associated with the AI command.
+   */
   public client!: Client;
+  /**
+   * The CommandKit instance associated with the AI command.
+   */
   public commandkit!: CommandKit;
 
+  /**
+   * Creates a new instance of AiContext.
+   * @param options - The options for the AI context, including the message, parameters, and CommandKit instance.
+   */
   public constructor(options: AiContextOptions<T>) {
     this.params = options.params;
     this.message = options.message;
     this.commandkit = options.commandkit;
     this.client = options.commandkit.client;
   }
 
+  /**
+   * Sets the parameters for the AI context.
+   * @param params - The parameters to set.
+   */
   public setParams(params: T): void {
     this.params = params;
   }

packages/ai/src/index.ts

@@ -1,6 +1,11 @@
 import { AiPlugin } from './plugin';
 import { AiPluginOptions } from './types';
 
+/**
+ * Defines the AI plugin for the application.
+ * @param options The options for the AI plugin
+ * @returns The AI plugin instance
+ */
 export function ai(options?: AiPluginOptions) {
   return new AiPlugin(options ?? {});
 }

packages/ai/src/plugin.ts

@@ -16,21 +16,51 @@ type WithAI<T extends LoadedCommand> = T & {
   tool: Tool;
 };
 
+/**
+ * Represents the configuration options for the AI plugin scoped to a specific command.
+ */
 export interface AiConfig {
+  /**
+   * A description of the AI functionality provided by this command. If not given, the command's description will be used.
+   */
   description?: string;
+  /**
+   * A zod schema defining the parameters that the AI command accepts.
+   */
   parameters: any;
 }
 
 let messageFilter: MessageFilter | null = null;
 let selectAiModel: SelectAiModel | null = null;
 let generateSystemPrompt: ((message: Message) => Promise<string>) | undefined;
 
+/**
+ * Represents the configuration options for the AI model.
+ */
 export interface ConfigureAI {
+  /**
+   * A filter function that determines whether a message should be processed by the AI.
+   * CommandKit invokes this function before processing the message.
+   */
   messageFilter?: MessageFilter;
+  /**
+   * A function that selects the AI model to use based on the message.
+   * This function should return a promise that resolves to an object containing the model and options.
+   */
   selectAiModel?: SelectAiModel;
+  /**
+   * A function that generates a system prompt based on the message.
+   * This function should return a promise that resolves to a string containing the system prompt.
+   * If not provided, a default system prompt will be used.
+   */
   systemPrompt?: (message: Message) => Promise<string>;
 }
 
+/**
+ * Configures the AI plugin with the provided options.
+ * This function allows you to set a message filter, select an AI model, and generate a system prompt.
+ * @param config The configuration options for the AI plugin.
+ */
 export function configureAI(config: ConfigureAI): void {
   if (config.messageFilter) {
     messageFilter = config.messageFilter;

packages/ai/src/types.ts

@@ -2,18 +2,41 @@ import { LanguageModelV1, ProviderMetadata } from 'ai';
 import { Message } from 'discord.js';
 import { AiContext } from './context';
 
+/**
+ * Function type for filtering commands based on their name.
+ * @param commandName - The name of the command to filter.
+ * @returns A boolean indicating whether the command should be included in the filter.
+ */
 export type CommandFilterFunction = (commandName: string) => boolean;
 
+/**
+ * Function type for filtering messages before they are processed by the AI.
+ * @param message - The message to filter.
+ * @returns A promise that resolves to a boolean indicating whether the message should be processed.
+ */
 export type MessageFilter = (message: Message) => Promise<boolean>;
 
+/**
+ * Function type for selecting an AI model based on the message.
+ * @param message - The message to base the model selection on.
+ * @returns A promise that resolves to an object containing the selected model and optional metadata.
+ */
 export type SelectAiModel = (message: Message) => Promise<{
   model: LanguageModelV1;
   options?: ProviderMetadata;
   objectMode?: boolean;
 }>;
 
+/**
+ * Options for the AI plugin.
+ */
 export interface AiPluginOptions {}
 
+/**
+ * Represents a command that can be executed by the AI.
+ * @param T - The type of parameters that the command accepts.
+ * @param ctx - The AI context in which the command is executed, including the message and parameters.
+ */
 export type AiCommand<T extends Record<string, unknown>> = (
   ctx: AiContext<T>,
 ) => Promise<unknown> | unknown;

packages/analytics/src/posthog/index.ts

@@ -1,5 +1,10 @@
 import { PostHogPlugin, PostHogPluginOptions } from './plugin';
 
+/**
+ * Defines the PostHog plugin for the application.
+ * @param options The options for the PostHog plugin
+ * @returns The PostHog plugin instance
+ */
 export function posthog(options: PostHogPluginOptions) {
   return new PostHogPlugin(options);
 }

packages/analytics/src/posthog/plugin.ts

@@ -2,9 +2,21 @@ import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
 import { PostHog, PostHogOptions } from 'posthog-node';
 import { PostHogProvider } from './provider';
 
+/**
+ * Options for the PostHog plugin.
+ */
 export interface PostHogPluginOptions {
+  /**
+   * The PostHog API key and options.
+   */
   posthogOptions: {
+    /**
+     * The PostHog API key.
+     */
     apiKey: string;
+    /**
+     * Additional options for the PostHog client.
+     */
     options?: PostHogOptions;
   };
 }

packages/analytics/src/posthog/provider.ts

@@ -6,6 +6,10 @@ import {
   IdentifyEvent,
 } from 'commandkit/analytics';
 
+/**
+ * PostHog analytics provider for CommandKit.
+ * This provider allows you to track events and identify users using PostHog.
+ */
 export class PostHogProvider implements AnalyticsProvider {
   public readonly name = 'PostHog';
   public constructor(public readonly posthog: PostHog) {}

packages/analytics/src/umami/index.ts

@@ -1,5 +1,10 @@
 import { UmamiPlugin, UmamiPluginOptions } from './plugin';
 
+/**
+ * Defines the Umami plugin for the application.
+ * @param options The options for the Umami plugin
+ * @returns The Umami plugin instance
+ */
 export function umami(options: UmamiPluginOptions) {
   return new UmamiPlugin(options);
 }

packages/analytics/src/umami/plugin.ts

@@ -2,7 +2,13 @@ import { UmamiOptions, Umami } from '@umami/node';
 import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
 import { UmamiProvider } from './provider';
 
+/**
+ * Options for the Umami plugin.
+ */
 export interface UmamiPluginOptions {
+  /**
+   * The Umami API options.
+   */
   umamiOptions: UmamiOptions;
 }