@ezzi/base 1.0.0

package/dist/creators/manager.d.ts

@@ -0,0 +1,6 @@
+import type { EzziApp } from "../app.js";
+export declare abstract class BaseManager {
+    readonly logs: string[];
+    readonly app: EzziApp;
+    constructor(app: EzziApp);
+}

package/dist/creators/manager.js

@@ -0,0 +1,12 @@
+// src/creators/manager.ts
+class BaseManager {
+  logs;
+  app;
+  constructor(app) {
+    this.app = app;
+    this.logs = [];
+  }
+}
+export {
+  BaseManager
+};

package/dist/creators/responders/emit.d.ts

@@ -0,0 +1,12 @@
+import type { GenericResponderInteraction } from "./manager.js";
+export type WithCustomId<T> = T & {
+    customId: string;
+};
+type EmitResponderInteraction = Omit<GenericResponderInteraction, "customId">;
+interface EmitResponderData {
+    customId: string;
+    interaction: EmitResponderInteraction;
+}
+export declare function emitResponder(customId: string, interaction: EmitResponderInteraction): void;
+export declare function emitResponder(data: EmitResponderData): void;
+export {};

package/dist/creators/responders/emit.js

@@ -0,0 +1,10 @@
+// src/creators/responders/emit.ts
+import { EzziApp } from "../../app.js";
+function emitResponder(a, b) {
+  const { customId, interaction } = typeof a === "string" ? { customId: a, interaction: b } : a;
+  const app = EzziApp.getInstance();
+  app.responders.onResponder(Object.assign(interaction, { customId }));
+}
+export {
+  emitResponder
+};

package/dist/creators/responders/manager.d.ts

@@ -0,0 +1,14 @@
+import type { CacheType, ChatInputCommandInteraction, MessageComponentInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, UserContextMenuCommandInteraction } from "discord.js";
+import { BaseManager } from "../manager.js";
+import type { WithCustomId } from "./emit.js";
+import { Responder, ResponderType } from "./responder.js";
+export type GenericResponder = Responder<string, readonly ResponderType[], any, CacheType>;
+export type GenericResponderInteraction = MessageComponentInteraction | ModalSubmitInteraction | WithCustomId<ChatInputCommandInteraction> | WithCustomId<UserContextMenuCommandInteraction> | WithCustomId<MessageContextMenuCommandInteraction>;
+export declare class ResponderManager extends BaseManager {
+    private get config();
+    private readonly router;
+    set(responder: GenericResponder): void;
+    getHandler(type: ResponderType, customId: string): import("rou3").MatchedRoute<GenericResponder> | undefined;
+    private getType;
+    onResponder(interaction: GenericResponderInteraction): Promise<void>;
+}

package/dist/creators/responders/manager.js

@@ -0,0 +1,61 @@
+// src/creators/responders/manager.ts
+import { styleText } from "node:util";
+import { Router } from "../../utils/router.js";
+import { BaseManager } from "../manager.js";
+import { ResponderType } from "./responder.js";
+
+class ResponderManager extends BaseManager {
+  get config() {
+    return this.app.config.responders;
+  }
+  router = new Router;
+  set(responder) {
+    const path = responder.data.customId;
+    for (const type of new Set(responder.data.types)) {
+      this.router.add(type, path, responder);
+      this.logs.push([
+        styleText("greenBright", `▸ ${type}`),
+        styleText("gray", `>`),
+        styleText(["blue", "underline"], path),
+        styleText("green", "✓")
+      ].join(" "));
+    }
+  }
+  getHandler(type, customId) {
+    return this.router.find(type, customId);
+  }
+  getType(interaction) {
+    return interaction.isButton() ? ResponderType.Button : interaction.isChatInputCommand() ? ResponderType.ChatInput : interaction.isMessageContextMenuCommand() ? ResponderType.MessageContextMenu : interaction.isUserContextMenuCommand() ? ResponderType.UserContextMenu : interaction.isStringSelectMenu() ? ResponderType.StringSelect : interaction.isChannelSelectMenu() ? ResponderType.ChannelSelect : interaction.isRoleSelectMenu() ? ResponderType.RoleSelect : interaction.isUserSelectMenu() ? ResponderType.UserSelect : interaction.isMentionableSelectMenu() ? ResponderType.MentionableSelect : interaction.isModalSubmit() && interaction.isFromMessage() ? ResponderType.ModalComponent : interaction.isModalSubmit() ? ResponderType.Modal : undefined;
+  }
+  async onResponder(interaction) {
+    const { middleware, onError, onNotFound } = this.config;
+    const responderType = this.getType(interaction);
+    if (!responderType) {
+      onNotFound?.(interaction);
+      return;
+    }
+    const handler = this.getHandler(responderType, interaction.customId);
+    if (!handler) {
+      onNotFound?.(interaction);
+      return;
+    }
+    const data = handler.data.data;
+    const params = handler.params && data.parse ? data.parse(handler.params) : handler.params ?? {};
+    let isBlock = false;
+    const block = () => isBlock = true;
+    if (middleware)
+      await middleware(interaction, block, params);
+    if (isBlock)
+      return;
+    await data.run(interaction, params).catch((err) => {
+      if (onError) {
+        onError(err, interaction, params);
+        return;
+      }
+      throw err;
+    });
+  }
+}
+export {
+  ResponderManager
+};

package/dist/creators/responders/responder.d.ts

@@ -0,0 +1,45 @@
+import type { ButtonInteraction, CacheType, ChannelSelectMenuInteraction, ChatInputCommandInteraction, MentionableSelectMenuInteraction, MessageContextMenuCommandInteraction, ModalMessageModalSubmitInteraction, ModalSubmitInteraction, RoleSelectMenuInteraction, StringSelectMenuInteraction, UserContextMenuCommandInteraction, UserSelectMenuInteraction } from "discord.js";
+import { type InferRouteParams } from "rou3";
+import type { NotEmptyArray, Prettify, UniqueArray } from "../../utils/types.js";
+import type { WithCustomId } from "./emit.js";
+export declare enum ResponderType {
+    Button = "button",
+    StringSelect = "select.string",
+    UserSelect = "select.user",
+    RoleSelect = "select.role",
+    ChannelSelect = "select.channel",
+    MentionableSelect = "select.mentionable",
+    Modal = "modal",
+    ModalComponent = "modal.component",
+    ChatInput = "command.chat.input",
+    UserContextMenu = "command.context.user",
+    MessageContextMenu = "command.context.message"
+}
+export type ResponderInteraction<Type extends ResponderType, Cache extends CacheType> = {
+    [ResponderType.Button]: ButtonInteraction<Cache>;
+    [ResponderType.StringSelect]: StringSelectMenuInteraction<Cache>;
+    [ResponderType.UserSelect]: UserSelectMenuInteraction<Cache>;
+    [ResponderType.RoleSelect]: RoleSelectMenuInteraction<Cache>;
+    [ResponderType.ChannelSelect]: ChannelSelectMenuInteraction<Cache>;
+    [ResponderType.MentionableSelect]: MentionableSelectMenuInteraction<Cache>;
+    [ResponderType.Modal]: ModalSubmitInteraction<Cache>;
+    [ResponderType.ModalComponent]: ModalMessageModalSubmitInteraction<Cache>;
+    [ResponderType.ChatInput]: WithCustomId<ChatInputCommandInteraction<Cache>>;
+    [ResponderType.UserContextMenu]: WithCustomId<UserContextMenuCommandInteraction<Cache>>;
+    [ResponderType.MessageContextMenu]: WithCustomId<MessageContextMenuCommandInteraction<Cache>>;
+}[Type];
+type ResolveParams<Path extends string, Parsed> = Prettify<Parsed extends {
+    [x: string | number | symbol]: any;
+} ? Parsed : InferRouteParams<Path>>;
+export interface ResponderData<Path extends string, Types extends readonly ResponderType[], out Parsed, Cache extends CacheType> {
+    customId: Path;
+    types: NotEmptyArray<UniqueArray<Types>>;
+    cache?: Cache;
+    parse?(this: void, params: InferRouteParams<Path>): Parsed;
+    run(this: void, interaction: ResponderInteraction<Types[number], Cache>, params: ResolveParams<Path, Parsed>): Promise<void>;
+}
+export declare class Responder<Path extends string, Types extends readonly ResponderType[], out Parsed, Cache extends CacheType> {
+    readonly data: ResponderData<Path, Types, Parsed, Cache>;
+    constructor(data: ResponderData<Path, Types, Parsed, Cache>);
+}
+export {};

package/dist/creators/responders/responder.js

@@ -0,0 +1,26 @@
+// src/creators/responders/responder.ts
+var ResponderType;
+((ResponderType2) => {
+  ResponderType2["Button"] = "button";
+  ResponderType2["StringSelect"] = "select.string";
+  ResponderType2["UserSelect"] = "select.user";
+  ResponderType2["RoleSelect"] = "select.role";
+  ResponderType2["ChannelSelect"] = "select.channel";
+  ResponderType2["MentionableSelect"] = "select.mentionable";
+  ResponderType2["Modal"] = "modal";
+  ResponderType2["ModalComponent"] = "modal.component";
+  ResponderType2["ChatInput"] = "command.chat.input";
+  ResponderType2["UserContextMenu"] = "command.context.user";
+  ResponderType2["MessageContextMenu"] = "command.context.message";
+})(ResponderType ||= {});
+
+class Responder {
+  data;
+  constructor(data) {
+    this.data = data;
+  }
+}
+export {
+  ResponderType,
+  Responder
+};

package/dist/creators/setup.d.ts

@@ -0,0 +1,25 @@
+import { ApplicationCommandType, type CacheType, type ClientEvents, type PermissionResolvable } from "discord.js";
+import { type BaseCommandsConfig, type BaseEventsConfig, type BaseRespondersConfig } from "../app.js";
+import { type AppCommandData, type CommandType } from "./commands/command.js";
+import { type EventData } from "./events/event.js";
+import { Responder, type ResponderData, type ResponderType } from "./responders/responder.js";
+export interface SetupCreatorsOptions {
+    commands?: Partial<BaseCommandsConfig> & {
+        defaultMemberPermissions?: PermissionResolvable[];
+        defaultBotPermissions?: PermissionResolvable[];
+    };
+    responders?: Partial<BaseRespondersConfig>;
+    events?: Partial<BaseEventsConfig>;
+}
+/**
+ * Initializes the Ezzi command/event/responder creation system.
+ *
+ * This function configures the Ezzi application’s internal registries
+ * for commands, events, and responders, and returns a set of factory
+ * functions used to create each type of component.
+ */
+export declare function setupCreators(options?: SetupCreatorsOptions): {
+    createCommand<T extends CommandType = ApplicationCommandType.ChatInput, P extends boolean = false, R = void>(data: AppCommandData<T, P, R>): any;
+    createEvent<EventName extends keyof ClientEvents>(data: EventData<EventName>): void;
+    createResponder<Path extends string, const Types extends readonly ResponderType[], Schema, Cache extends CacheType = CacheType>(data: ResponderData<Path, Types, Schema, Cache>): Responder<string, readonly ResponderType[], unknown, CacheType>;
+};

package/dist/creators/setup.js

@@ -0,0 +1,86 @@
+// src/creators/setup.ts
+import {
+  ApplicationCommandOptionType,
+  ApplicationCommandType
+} from "discord.js";
+import {
+  EzziApp
+} from "../app.js";
+import { Event } from "./events/event.js";
+import {
+  Responder
+} from "./responders/responder.js";
+function setupCreators(options = {}) {
+  const app = EzziApp.getInstance();
+  app.config.commands = { ...options.commands ?? {} };
+  app.config.commands.guilds ??= [];
+  app.config.responders = { ...options.responders ?? {} };
+  app.config.events = { ...options.events ?? {} };
+  if (process.env.GUILD_ID?.length) {
+    app.config.commands.guilds.push(process.env.GUILD_ID);
+  }
+  const defaultMemberPerms = options.commands?.defaultMemberPermissions;
+  const defaultBotPerms = options.commands?.defaultBotPermissions;
+  return {
+    createCommand(data) {
+      const currentApp = EzziApp.getInstance();
+      if (defaultMemberPerms) {
+        data.defaultMemberPermissions ??= defaultMemberPerms;
+      }
+      if (defaultBotPerms && !data.botPermissions?.length) {
+        data.botPermissions = defaultBotPerms;
+      }
+      const resolved = currentApp.commands.set(data);
+      if (typeof currentApp.commands.addLog === "function") {
+        currentApp.commands.addLog(resolved);
+      }
+      if (resolved.type !== ApplicationCommandType.ChatInput) {
+        return resolved;
+      }
+      const commandName = resolved.name;
+      const createSubcommand = (group) => (subData) => {
+        const subApp = EzziApp.getInstance();
+        if (defaultBotPerms && !subData.botPermissions?.length) {
+          subData = { ...subData, botPermissions: defaultBotPerms };
+        }
+        subApp.commands.addModule(commandName, {
+          ...subData,
+          group,
+          type: ApplicationCommandOptionType.Subcommand
+        });
+      };
+      return Object.assign(data, {
+        ...resolved,
+        group(groupData) {
+          const groupApp = EzziApp.getInstance();
+          if (defaultBotPerms && !groupData.botPermissions?.length) {
+            groupData = { ...groupData, botPermissions: defaultBotPerms };
+          }
+          groupApp.commands.addModule(commandName, {
+            ...groupData,
+            type: ApplicationCommandOptionType.SubcommandGroup
+          });
+          return { subcommand: createSubcommand(groupData.name) };
+        },
+        subcommand: createSubcommand()
+      });
+    },
+    createEvent(data) {
+      const currentApp = EzziApp.getInstance();
+      const resolved = new Event({
+        ...data,
+        once: data.event === "ready" || data.event === "clientReady" ? true : data.once
+      });
+      return currentApp.events.add(resolved);
+    },
+    createResponder(data) {
+      const currentApp = EzziApp.getInstance();
+      const responderInstance = new Responder(data);
+      currentApp.responders.set(responderInstance);
+      return responderInstance;
+    }
+  };
+}
+export {
+  setupCreators
+};

package/dist/env.d.ts

@@ -0,0 +1,25 @@
+import type { StandardSchemaV1 } from "./standard-schema.js";
+/**
+ * Validates the current process environment variables using a StandardSchema.
+ *
+ * This function executes the schema validation against `process.env`
+ * and ensures all required environment variables follow the expected shape.
+ * @example
+ * // "env.ts" — Using Zod
+ * import { z } from "zod";
+ * import { validateEnv } from "@ezzi/base";
+ *
+ * export const env = await validateEnv(z.object({
+ *     BOT_TOKEN: z.string("BOT_TOKEN is required").min(1)
+ * }).passthrough());
+ *
+ * @example
+ * // "env.ts" — Using ArkType
+ * import { type } from "arktype";
+ * import { validateEnv } from "@ezzi/base";
+ *
+ * export const env = await validateEnv(type({
+ *     BOT_TOKEN: "string > 0"
+ * }));
+ */
+export declare function validateEnv<const T extends StandardSchemaV1>(schema: T): Promise<StandardSchemaV1.InferOutput<T>>;

package/dist/env.js

@@ -0,0 +1,15 @@
+// src/env.ts
+import { format, styleText } from "node:util";
+async function validateEnv(schema) {
+  const result = await schema["~standard"].validate(process.env);
+  if (result.issues) {
+    console.log(result.issues.map((issue) => format(styleText("red", "✖︎ ENV VAR %s ➜ %s"), styleText("bold", issue.path?.join(".") ?? ""), styleText("gray", issue.message))).join(`
+`));
+    process.exit(1);
+  }
+  console.log(styleText("dim", "☰ Environment variables validated ✓"));
+  return result.value;
+}
+export {
+  validateEnv
+};

package/dist/error.d.ts

@@ -0,0 +1,7 @@
+import { Client } from "discord.js";
+export declare class EzziError extends Error {
+    constructor(message: string);
+}
+export declare class RunBlockError {
+}
+export declare function baseErrorHandler(error: any, client?: Client): Promise<void>;

package/dist/error.js

@@ -0,0 +1,78 @@
+// src/error.ts
+import {
+  codeBlock,
+  parseWebhookURL,
+  REST,
+  Routes,
+  TextDisplayBuilder,
+  time
+} from "discord.js";
+import console from "node:console";
+import { styleText } from "node:util";
+
+class EzziError extends Error {
+  constructor(message) {
+    super(message);
+  }
+}
+
+class RunBlockError {
+}
+async function baseErrorHandler(error, client) {
+  if (client?.user)
+    console.log(client.user.displayName);
+  const text = [];
+  const hightlight = (text2) => text2.replace(/\(([^)]+)\)/g, (_, match) => [
+    styleText("gray", "("),
+    styleText("cyan", match),
+    styleText("gray", ")")
+  ].join(""));
+  if ("message" in error)
+    text.push(styleText("red", `${error.message}`));
+  if ("stack" in error) {
+    const formated = `${error.stack}`.replaceAll(process.cwd(), ".").replaceAll("at ", styleText("gray", "at "));
+    text.push(hightlight(formated));
+  }
+  console.log(text.join(`
+`));
+  const url = process.env.WEBHOOK_LOGS_URL;
+  if (!url)
+    return;
+  const data = parseWebhookURL(url);
+  if (!data)
+    return;
+  const rest = new REST;
+  if (process.env.BOT_TOKEN)
+    rest.setToken(process.env.BOT_TOKEN);
+  try {
+    const username = client?.user?.username;
+    rest.post(Routes.webhook(data.id, data.token), {
+      body: {
+        flags: ["IsComponentsV2"],
+        components: [
+          new TextDisplayBuilder({
+            content: [
+              codeBlock("ansi", text.join(`
+`)),
+              time(new Date, "R")
+            ].join(`
+`)
+          })
+        ],
+        withComponents: true,
+        avatarURL: client?.user?.displayAvatarURL({ size: 512 }),
+        username: username ? `${username} logs` : "Logs"
+      }
+    }).catch(console.error);
+  } catch {
+    console.log();
+    console.error("ENV VAR → %s Invalid webhook url", styleText(["bold", "underline"], "WEBHOOK_LOGS_URL"));
+    console.log();
+    console.warn("Unable to send logs to webhook because the url is invalid");
+  }
+}
+export {
+  baseErrorHandler,
+  RunBlockError,
+  EzziError
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./bootstrap.js";
+export * from "./creators/index.js";
+export * from "./env.js";
+export * from "./version.js";
+export * from "./creators/commands/command.js";
+export * from "./creators/commands/context.js";
+export * from "./creators/events/event.js";
+export * from "./creators/responders/responder.js";
+export * from "./tools/index.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+// src/index.ts
+export * from "./bootstrap.js";
+export * from "./creators/index.js";
+export * from "./env.js";
+export * from "./version.js";
+export * from "./creators/commands/command.js";
+export * from "./creators/commands/context.js";
+export * from "./creators/events/event.js";
+export * from "./creators/responders/responder.js";
+export * from "./tools/index.js";

package/dist/modules.d.ts

@@ -0,0 +1,9 @@
+export interface ModuleImported {
+    module: any;
+    filepath: string;
+}
+/**
+ * Dynamically loads modules using glob patterns, returning each imported module
+ * along with its file path.
+ */
+export declare function loadModules(meta: ImportMeta, modules?: string[]): Promise<ModuleImported[]>;

package/dist/modules.js

@@ -0,0 +1,18 @@
+// src/modules.ts
+import { join } from "node:path";
+import { glob } from "tinyglobby";
+async function loadModules(meta, modules = []) {
+  const ignore = modules.filter((path) => path.charAt(0) == "!").map((path) => path.slice(1));
+  const filepaths = await glob(modules, { cwd: meta.dirname, ignore });
+  const loadedModules = [];
+  for (const path of filepaths) {
+    await import("file://" + join(meta.dirname, path)).then((imported) => loadedModules.push({
+      module: imported,
+      filepath: path
+    }));
+  }
+  return loadedModules;
+}
+export {
+  loadModules
+};

package/dist/standard-schema.d.ts

@@ -0,0 +1,59 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./parseCommand.js";
+export * from "./logger.js";

package/dist/tools/index.js

@@ -0,0 +1,3 @@
+// src/tools/index.ts
+export * from "./parseCommand.js";
+export * from "./logger.js";

package/dist/tools/logger.d.ts

@@ -0,0 +1,12 @@
+type LogParams = [message?: any, ...params: any[]];
+declare function log(...params: LogParams): void;
+declare function success(...params: LogParams): void;
+declare function warn(...params: LogParams): void;
+declare function error(...params: LogParams): void;
+export declare const logger: {
+    log: typeof log;
+    success: typeof success;
+    warn: typeof warn;
+    error: typeof error;
+};
+export {};

package/dist/tools/logger.js

@@ -0,0 +1,23 @@
+// src/tools/logger.ts
+import chalk from "chalk";
+function log(...params) {
+  return console.log(...params);
+}
+function success(...params) {
+  return log(chalk.green(`✓`), ...params);
+}
+function warn(...params) {
+  return console.warn(chalk.yellow(`▲`), ...params);
+}
+function error(...params) {
+  return console.error(chalk.red(`✖︎`), ...params);
+}
+var logger = {
+  log,
+  success,
+  warn,
+  error
+};
+export {
+  logger
+};

package/dist/tools/parseCommand.d.ts

@@ -0,0 +1,15 @@
+import { Client, type LocalizationMap } from "discord.js";
+export interface ParsedCommand {
+    id: string | null;
+    name: string;
+    description: string;
+    category: string;
+    options: string;
+    slash: {
+        id: string;
+        name: string;
+    } | null;
+    localizations?: LocalizationMap;
+    aliases?: string[];
+}
+export declare function parseCommands(client: Client): ParsedCommand[];