popii-framework 0.6.1-beta.0

package/dist/types.d.ts

@@ -0,0 +1,671 @@
+import type { ApplicationCommandOptionType, ApplicationCommandType, ApplicationIntegrationType, InteractionContextType, Client, LocaleString, User, GuildMember, Guild, TextBasedChannel, Attachment, Role, Message, Interaction, ClientEvents, MessageComponentInteraction, ModalSubmitInteraction, PermissionFlagsBits, Partials } from "discord.js";
+import type { APIInteractionGuildMember } from "discord-api-types/v10";
+export interface PopiiRedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: "PX", duration: number): Promise<unknown>;
+    set(key: string, value: string, mode: "PX", duration: number, flag: "NX"): Promise<string | null>;
+    zadd(key: string, score: number, member: string): Promise<unknown>;
+    zrangebyscore(key: string, min: number, max: number): Promise<string[]>;
+    zremrangebyscore(key: string, min: number, max: number): Promise<unknown>;
+    zrem(key: string, member: string): Promise<number>;
+    incr(key: string, expireMs: number): Promise<number>;
+    eval(script: string, numkeys: number, ...args: (string | number)[]): Promise<unknown>;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string): Promise<unknown>;
+    on(event: string, listener: (...args: any[]) => void): this;
+    disconnect(): void;
+}
+export interface PopLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+export interface PopOptions {
+    getString(name: string): string | null;
+    getUser(name: string): User | null;
+    getInteger(name: string): number | null;
+    getBoolean(name: string): boolean | null;
+    getAttachment(name: string): Attachment | null;
+    getChannel(name: string): TextBasedChannel | null;
+    getRole(name: string): Role | null;
+    getNumber(name: string): number | null;
+    getMentionable(name: string): User | Role | null;
+    getTargetUser(): User | null;
+    getTargetMessage(): Message | null;
+}
+export interface PopiiOption<TState = any, TInput = any, TLocals = Record<string, any>> {
+    name: string;
+    nameLocalizations?: Partial<Record<LocaleString, string>>;
+    description: string;
+    descriptionLocalizations?: Partial<Record<LocaleString, string>>;
+    type: ApplicationCommandOptionType;
+    required?: boolean;
+    autocomplete?: boolean | ((pop: Pop<TState, TInput, TLocals>) => Promise<void> | void);
+    options?: PopiiOption<TState, any, TLocals>[];
+    do?(pop: Pop<TState, TInput, TLocals>): Promise<void> | void;
+    guildOnly?: boolean;
+    ownerOnly?: boolean;
+    permissions?: (keyof typeof PermissionFlagsBits | bigint)[];
+    allowedRoles?: string[];
+    deniedRoles?: string[];
+    allowedChannels?: string[];
+    cooldown?: number | {
+        ms: number;
+        uses?: number;
+        scope?: "user" | "guild" | "global";
+    };
+    quota?: {
+        limit: number;
+        timeframe: number;
+        scope?: "user" | "guild" | "global";
+    };
+    middlewares?: PopiiMiddleware<TState, TInput, TLocals>[];
+    schema?: PopiiSchema;
+}
+export interface PopiiSchema<TInput = any> {
+    parse?: (data: any) => TInput;
+    parseAsync?: (data: any) => Promise<TInput>;
+}
+export interface PopiiStorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: "PX", duration: number): Promise<void>;
+    zadd(key: string, score: number, member: string): Promise<void>;
+    zrangebyscore(key: string, min: number, max: number): Promise<string[]>;
+    zremrangebyscore(key: string, min: number, max: number): Promise<void>;
+    zrem?(key: string, member: string): Promise<number>;
+    incr?(key: string, expireMs: number): Promise<number>;
+    setnx?(key: string, value: string, expireMs: number): Promise<boolean>;
+    del?(key: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/**
+ * Globally augmentable interface for strongly typing `pop.locals`.
+ *
+ * Declare this in any `.d.ts` file in your project to add typed properties
+ * that are accessible on `pop.locals` inside every command, snap, and middleware.
+ *
+ * @example
+ * ```ts
+ * // src/types.d.ts
+ * declare module "popii" {
+ *   interface PopiiLocals {
+ *     dbUser: { id: string; balance: number; premium: boolean };
+ *     guildConfig: Record<string, string>;
+ *   }
+ * }
+ * ```
+ */
+export interface PopiiLocals {
+}
+/**
+ * The base context object provided to all Popii event, command, snap, and task handlers.
+ *
+ * Every handler receives this as its first argument. It provides the client reference,
+ * localization helpers, a shared KV store (the Cooler), request-scoped caching,
+ * structured logging, and utilities for scheduling tasks and making HTTP requests.
+ *
+ * Commands and snaps receive the richer {@link Pop} subtype, which adds `reply()`,
+ * `defer()`, `options`, and other interaction-specific members.
+ *
+ * @category Context
+ *
+ * @example Accessing the client and logging in an event
+ * ```ts
+ * export default event(async (pop, guild) => {
+ *   pop.log.info(`Joined ${guild.name}`);
+ *   pop.client.discord.guilds.cache.size; // full discord.js access
+ * });
+ * ```
+ */
+export interface EventPop<TState = any, TLocals = PopiiLocals & Record<string, any>> {
+    client: PopiiClient<TState>;
+    locale: string;
+    log: PopLogger;
+    createAttachment(path: string, name?: string): any;
+    fetchJSON<T = unknown>(url: string | URL | Request, init?: RequestInit): Promise<T>;
+    fetchText(url: string | URL | Request, init?: RequestInit): Promise<string>;
+    fetchBuffer(url: string | URL | Request, init?: RequestInit): Promise<ArrayBuffer>;
+    fetchForm<T = unknown>(url: string | URL | Request, data: FormData, init?: RequestInit): Promise<T>;
+    cache<T>(key: string, ttlMs: number, fetcher: () => Promise<T> | T): Promise<T>;
+    translate(key: string, args?: Record<string, any>): string;
+    t(key: string, args?: Record<string, any>): string;
+    cooler: {
+        get<T = any>(key: string): Promise<T | null>;
+        set(key: string, value: any, ttlMs?: number): Promise<void>;
+        delete(key: string): Promise<void>;
+    };
+    pack(customId: string, data: any): string;
+    state: TState;
+    locals: TLocals;
+    guild: Guild | null;
+    channel: TextBasedChannel | null;
+    schedule(taskName: string, payload?: any, delayMs?: number): Promise<void>;
+}
+/**
+ * The full execution context provided to command and snap handlers.
+ *
+ * Extends {@link EventPop} with interaction-specific members: `reply()`, `defer()`,
+ * `options` (typed slash command arguments), `input` (schema-validated input),
+ * and references to the raw `interaction` and `message` objects.
+ *
+ * Use the `TInput` type parameter when you supply a `schema` to the command — the
+ * validated result is then available as `pop.input` with full type inference.
+ *
+ * @category Context
+ *
+ * @example Reply with an embed
+ * ```ts
+ * async do(pop) {
+ *   await pop.reply({
+ *     embeds: [{ title: "Hello!", description: `Hey ${pop.user.username}` }],
+ *     ephemeral: true
+ *   });
+ * }
+ * ```
+ *
+ * @example Defer a slow command
+ * ```ts
+ * async do(pop) {
+ *   await pop.defer();
+ *   const result = await someSlowOperation();
+ *   await pop.reply(result);
+ * }
+ * ```
+ */
+export interface Pop<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> extends EventPop<TState, TLocals> {
+    reply(payload: string | {
+        content?: string;
+        embeds?: any[];
+        components?: any[];
+        files?: any[];
+        ephemeral?: boolean;
+    }): Promise<any>;
+    defer(options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    respond(choices: {
+        name: string;
+        value: string | number;
+    }[]): Promise<void>;
+    respondFiltered(choices: {
+        name: string;
+        value: string | number;
+    }[], userInput: string): Promise<void>;
+    user: User;
+    member: GuildMember | APIInteractionGuildMember | null;
+    options: PopOptions;
+    input: TInput;
+    interaction?: Interaction | MessageComponentInteraction | ModalSubmitInteraction;
+    message?: Message;
+    snapMatches?: RegExpMatchArray | null;
+    snapData?: any;
+    targetMessage?: Message | null;
+    targetUser?: User | null;
+}
+export interface ComponentPop<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> extends Pop<TState, TInput, TLocals> {
+    interaction: MessageComponentInteraction | ModalSubmitInteraction;
+    message: Message<boolean>;
+}
+/** Standard middleware — receives the pop context and a `next` function. Call `next(err)` to forward an error. */
+export type PopiiRegularMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = (pop: Pop<TState, TInput, TLocals>, next: (err?: any) => Promise<void> | void) => Promise<void> | void;
+/**
+ * Error-handling middleware — receives the thrown error as the first argument.
+ * Popii detects error middlewares by arity (function.length === 3), matching the Express convention.
+ * Always declare all three parameters explicitly; do not use rest args or defaults that reduce arity.
+ */
+export type PopiiErrorMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = (err: any, pop: Pop<TState, TInput, TLocals>, next: (err?: any) => Promise<void> | void) => Promise<void> | void;
+export type PopiiMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = PopiiRegularMiddleware<TState, TInput, TLocals> | PopiiErrorMiddleware<TState, TInput, TLocals>;
+/** Standard component middleware — receives the component pop context and a `next` function. */
+export type ComponentRegularMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = (pop: ComponentPop<TState, TInput, TLocals>, next: (err?: any) => Promise<void> | void) => Promise<void> | void;
+/** Error-handling component middleware — detected by arity (function.length === 3). */
+export type ComponentErrorMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = (err: any, pop: ComponentPop<TState, TInput, TLocals>, next: (err?: any) => Promise<void> | void) => Promise<void> | void;
+export type ComponentMiddleware<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> = ComponentRegularMiddleware<TState, TInput, TLocals> | ComponentErrorMiddleware<TState, TInput, TLocals>;
+/**
+ * The full definition of a Popii command, including its metadata, options, guards, and handler.
+ *
+ * You don't usually interact with this interface directly — use the {@link command} builder
+ * function, which infers all types for you.
+ *
+ * @category Core API
+ */
+export interface PopiiCommandDefinition<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> {
+    name: string;
+    nameLocalizations?: Partial<Record<LocaleString, string>>;
+    description: string;
+    descriptionLocalizations?: Partial<Record<LocaleString, string>>;
+    type?: ApplicationCommandType;
+    slash?: boolean;
+    text?: boolean;
+    category?: string;
+    aliases?: string[];
+    usage?: string;
+    integrationTypes?: ApplicationIntegrationType[];
+    contexts?: InteractionContextType[];
+    quota?: {
+        limit: number;
+        timeframe: number;
+        scope?: "user" | "guild" | "global";
+    };
+    cooldown?: number | {
+        ms: number;
+        uses?: number;
+        scope?: "user" | "guild" | "global";
+    };
+    guildOnly?: boolean;
+    ownerOnly?: boolean;
+    premium?: boolean;
+    ephemeral?: boolean;
+    mutex?: boolean;
+    hidden?: boolean;
+    permissions?: (keyof typeof PermissionFlagsBits | bigint)[];
+    allowedRoles?: string[];
+    deniedRoles?: string[];
+    allowedChannels?: string[];
+    options?: PopiiOption<TState, any, TLocals>[];
+    autocomplete?(pop: Pop<TState, TInput, TLocals>): Promise<void> | void;
+    middlewares?: PopiiMiddleware<TState, TInput, TLocals>[];
+    schema?: PopiiSchema<TInput>;
+    /** Override the auto-defer threshold in ms. Defaults to 2000. */
+    deferAfter?: number;
+    do(pop: Pop<TState, TInput, TLocals>): Promise<void> | void;
+}
+/**
+ * The full definition of a Popii persistent component handler (Snap).
+ *
+ * You don't usually interact with this interface directly — use the {@link snap} builder
+ * function, which infers all types for you.
+ *
+ * @category Core API
+ */
+export interface PopiiComponentDefinition<TState = any, TInput = any, TLocals = PopiiLocals & Record<string, any>> {
+    customId: string | RegExp;
+    prefix?: string;
+    guildOnly?: boolean;
+    ownerOnly?: boolean;
+    premium?: boolean;
+    ephemeral?: boolean;
+    permissions?: (keyof typeof PermissionFlagsBits | bigint)[];
+    allowedRoles?: string[];
+    deniedRoles?: string[];
+    allowedChannels?: string[];
+    mutex?: boolean;
+    cooldown?: number | {
+        ms: number;
+        uses?: number;
+        scope?: "user" | "guild" | "global";
+    };
+    quota?: {
+        limit: number;
+        timeframe: number;
+        scope?: "user" | "guild" | "global";
+    };
+    expiresIn?: number;
+    middlewares?: ComponentMiddleware<TState, TInput, TLocals>[];
+    schema?: PopiiSchema<TInput>;
+    do(pop: ComponentPop<TState, TInput, TLocals>): Promise<void> | void;
+}
+export interface PopiiClient<TState = any> {
+    config: PopiiClientConfig<TState>;
+    commands: Map<string, PopiiCommandDefinition<TState>>;
+    snaps: Map<string | RegExp, PopiiComponentDefinition<TState>>;
+    activeEvents: Map<string, (...args: any[]) => void>;
+    locales: Map<string, Record<string, string>>;
+    middlewares: PopiiMiddleware<TState>[];
+    tasks: Map<string, PopiiTaskDefinition<TState>>;
+    activeTasks: any[];
+    redis?: PopiiRedisClient;
+    redisSub?: PopiiRedisClient;
+    storage?: PopiiStorageAdapter;
+    _cooldowns: Map<string, {
+        expires: number;
+        usages: number;
+        lastUpdate: number;
+    }>;
+    _quotas: Map<string, {
+        expires: number;
+        usages: number;
+    }>;
+    _mutexes: Map<string, boolean>;
+    _cacheStore: Map<string, {
+        expires: number;
+        value: any;
+    }>;
+    _cacheLocks?: Map<string, Promise<any>>;
+    _extensions?: Map<string, (pop: EventPop) => any>;
+    _cleanupInterval?: any;
+    _logRotationInterval?: any;
+    _delayedJobInterval?: any;
+    _sseBroadcastInterval?: any;
+    _webRateLimitInterval?: any;
+    _paginationInterval?: any;
+    _paginationSessions?: Map<string, {
+        embeds: any[];
+        timeoutMs: number;
+        expires: number;
+    }>;
+    _activeCollectors?: Map<string, any>;
+    _commandAnalytics?: Map<string, number>;
+    _broadcastListeners?: Map<string, ((data: any) => void)[]>;
+    _sseStreams?: Map<string, any>;
+    isShuttingDown: boolean;
+    activeExecutions: number;
+    _pendingTimeouts?: Set<ReturnType<typeof setTimeout>>;
+    _executePlugins?: PopiiPlugin[];
+    _errorPlugins?: PopiiPlugin[];
+    _disabledCommands: Set<string>;
+    _auditLogs: any[];
+    _terminalLogs?: string[];
+    _rateLimitLogs?: any[];
+    _blacklist: Set<string>;
+    global: {
+        emit(event: string, data?: any): Promise<void>;
+        on(event: string, listener: (data: any) => void): void;
+        off(event: string, listener: (data: any) => void): void;
+    };
+    state: TState;
+    discord: Client;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    reload(): Promise<void>;
+    schedule(taskName: string, payload?: any, delayMs?: number): Promise<void>;
+    broadcast(event: string, data: any): Promise<void>;
+    offBroadcast(event: string, listener: (data: any) => void): void;
+    onBroadcast(event: string, listener: (data: any) => void): void;
+    saveState(): Promise<void>;
+    isPremium(userId: string, guildId?: string | null): Promise<boolean>;
+    reloadPlugin(name: string): Promise<boolean>;
+    invalidate(key: string): Promise<void>;
+    extend(name: string, factory: (pop: EventPop) => any): void;
+    setPresence(status: string): Promise<void>;
+    getGuildConfig?(guildId: string): Promise<Record<string, any>>;
+    setGuildConfig?(guildId: string, config: Record<string, any>): Promise<void>;
+}
+export interface PopiiServerSetting {
+    id: string;
+    label: string;
+    description?: string;
+    type: "text" | "boolean" | "select" | "channel" | "role";
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    default?: any;
+    category?: string;
+    channelTypes?: number[];
+    paragraph?: boolean;
+}
+/**
+ * The definition of a scheduled background task.
+ *
+ * Use the {@link task} builder function to create one with full type inference.
+ * Tasks are auto-loaded from `src/tasks/` and can also be triggered on demand
+ * via `pop.schedule("task-name", payload, delayMs)`.
+ *
+ * @category Core API
+ */
+export interface PopiiTaskDefinition<TState = any> {
+    /** A unique name for this task. Used when scheduling it via `pop.schedule()`. */
+    name?: string;
+    /** Cron expression (e.g. `"0 9 * * *"` for every day at 9am). Omit for on-demand-only tasks. */
+    schedule?: string;
+    /** IANA timezone name (e.g. `"America/New_York"`). Defaults to UTC. */
+    timezone?: string;
+    /** Allow concurrent runs of this task. Defaults to `false` (skips if previous run is still active). */
+    overlap?: boolean;
+    /** Number of times to retry on failure. Defaults to `0`. */
+    retries?: number;
+    /** Milliseconds to wait between retries. Defaults to `1000`. */
+    retryDelay?: number;
+    /** Maximum execution time in ms before the run is considered timed out. */
+    timeoutMs?: number;
+    /** The function to run. `payload` is provided when triggered via `pop.schedule()`. */
+    run(client: PopiiClient<TState>, payload?: any): void | Promise<void>;
+}
+export type PopiiEventFunction<K extends keyof ClientEvents, TState = any> = (pop: EventPop<TState>, ...args: ClientEvents[K]) => void | Promise<void>;
+export interface PopiiPluginConfigField {
+    type: "string" | "number" | "boolean" | "select";
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    options?: string[];
+    /** Suggested environment variable name for this field. */
+    env?: string;
+}
+/**
+ * Metadata exported by community plugins for marketplace discovery.
+ * Place this in the `"popii"` field of your plugin's `package.json`.
+ *
+ * @category Plugins
+ */
+export interface PopiiPluginMeta {
+    displayName: string;
+    description: string;
+    category?: "core" | "features" | "integrations" | "utilities" | "ui";
+    keywords?: string[];
+    /** Named export of the plugin factory function. Defaults to `"default"`. */
+    export?: string;
+    requires?: string[];
+    conflicts?: string[];
+    configSchema?: Record<string, PopiiPluginConfigField>;
+}
+/**
+ * The interface all Popii plugins must implement.
+ *
+ * A plugin is a plain object returned from a factory function. It hooks into the client
+ * lifecycle via `setup`, `ready`, `reload`, and `cleanup`, and can also intercept every
+ * command execution via `onCommandExecute` and `onCommandError`.
+ *
+ * @category Plugins
+ *
+ * @example Minimal plugin
+ * ```ts
+ * import type { PopiiPlugin } from "popii";
+ *
+ * export function myPlugin(): PopiiPlugin {
+ *   return {
+ *     name: "my-plugin",
+ *     setup(client) {
+ *       // runs once at startup — register listeners, create DB tables, etc.
+ *     },
+ *     ready(client) {
+ *       // runs after Discord connects — safe to use client.discord.guilds.cache
+ *     },
+ *     cleanup(client) {
+ *       // runs on graceful shutdown — clear intervals, close connections
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export interface PopiiPlugin<TState = any> {
+    name: string;
+    /**
+     * Plugin names that must be loaded before this plugin.
+     * Popii throws at startup if any listed plugin is missing.
+     */
+    requires?: string[];
+    /**
+     * Plugin names this plugin cannot coexist with.
+     * Popii throws at startup if any listed plugin is also present.
+     */
+    conflicts?: string[];
+    /**
+     * Execution order during the setup lifecycle. Higher values run first.
+     * @default 0
+     */
+    priority?: number;
+    /**
+     * Declarative per-guild settings exposed in the web dashboard's server settings form.
+     * The category defaults to the plugin name if omitted.
+     */
+    settingsSchema?: PopiiServerSetting[];
+    /** Runs once at startup, before connecting to Discord. Register listeners and create DB tables here. */
+    setup(client: PopiiClient<TState>): void | Promise<void>;
+    /** Runs after the bot successfully connects to Discord. Safe to access guild and user caches. */
+    ready?(client: PopiiClient<TState>): void | Promise<void>;
+    /** Runs after a hot-reload. Re-wrap commands with middleware or refresh state here. */
+    reload?(client: PopiiClient<TState>): void | Promise<void>;
+    /** Runs on graceful shutdown. Clear intervals and close external connections here. */
+    cleanup?(client: PopiiClient<TState>): void | Promise<void>;
+    /** Called before every command or snap executes. Useful for analytics and tracing. */
+    onCommandExecute?(pop: Pop<TState>, command: PopiiCommandDefinition<TState> | PopiiComponentDefinition<TState>): void | Promise<void>;
+    /** Called when a command or snap throws an unhandled error. */
+    onCommandError?(error: unknown, pop: Pop<TState>): void | Promise<void>;
+    /** Called when a new `pop` context is created. Inject data into the context here. */
+    onContextCreate?(pop: EventPop<TState>): void;
+}
+/**
+ * Configuration passed to {@link popiiClient} when creating the bot.
+ *
+ * Only `token` is required. Everything else has sensible defaults.
+ *
+ * @category Core API
+ *
+ * @example Minimal setup
+ * ```ts
+ * const client = popiiClient({ token: process.env.DISCORD_TOKEN! });
+ * ```
+ *
+ * @example Full setup with common options
+ * ```ts
+ * const client = popiiClient({
+ *   token: process.env.DISCORD_TOKEN!,
+ *   devGuildId: process.env.DEV_GUILD_ID,
+ *   owners: ["your_discord_user_id"],
+ *   prefix: "!",
+ *   status: ["Serving {{guilds}} servers", "Try /help"],
+ *   plugins: [sqlitePlugin(), webPlugin(), errorHandlerPlugin()],
+ * });
+ * ```
+ */
+export interface PopiiClientConfig<TState = any> {
+    /** Your Discord bot token. Keep this in `.env` — never commit it. */
+    token: string;
+    /**
+     * Connection mode.
+     * - `"websocket"` (default) — standard Gateway connection.
+     * - `"http"` — HTTP interactions endpoint for serverless deployments. Requires `publicKey` and `port`.
+     */
+    mode?: "websocket" | "http";
+    /** Required when `mode` is `"http"`. Your application's public key from the Discord Developer Portal. */
+    publicKey?: string;
+    /** Port for the HTTP interactions server when `mode` is `"http"`. Defaults to `3000`. */
+    port?: number;
+    /**
+     * Enables legacy text commands. Provide a string prefix (e.g. `"!"`) or a function
+     * that returns the prefix(es) per message.
+     */
+    prefix?: string | ((message: Message) => string | string[] | Promise<string | string[] | null> | null);
+    /** Override the auto-detected Gateway intents. Popii infers intents from your event filenames by default. */
+    intents?: number[];
+    /** Redis connection URL (e.g. `"redis://localhost:6379"`). Enables Redis-backed storage and sharding coordination. */
+    redisUrl?: string;
+    /** Alternative to `redisUrl`. Pass a connection string or an ioredis options object. */
+    redis?: string | Record<string, unknown>;
+    /** Provide a custom storage adapter to replace the built-in in-process Map with any backend. */
+    storage?: PopiiStorageAdapter;
+    /** Override the auto-detected Discord.js Partials. Popii infers partials from your event filenames by default. */
+    partials?: Partials[];
+    /**
+     * A guild ID used to register slash commands during development.
+     * Guild commands sync instantly; global commands can take up to an hour.
+     * Remove or leave empty in production.
+     */
+    devGuildId?: string;
+    /** Called when a command or snap throws an error that is not caught by a middleware. */
+    onError?: (error: unknown, pop: Pop) => void | Promise<void>;
+    /** Called for unhandled promise rejections and uncaught exceptions not tied to a command. */
+    onGlobalError?: (error: unknown) => void | Promise<void>;
+    /** Discord user IDs that have bot-owner privileges (e.g. `ownerOnly: true` commands). */
+    owners?: string[];
+    /** Initial value for `pop.state` and `client.state`. Persisted to Redis/storage between restarts. */
+    state?: TState;
+    commands?: {
+        dir?: string;
+        /**
+         * Automatically maps nested folders into subcommands and subcommand groups.
+         * e.g. `src/commands/config/set.ts` becomes `/config set`.
+         *
+         * @default true
+         */
+        folderRouting?: boolean;
+        /**
+         * Automatically sync Slash Commands to Discord on startup.
+         * Disable this in production to prevent rate-limits, and use `popii sync` instead.
+         * @default true
+         */
+        autoSync?: boolean;
+    };
+    /**
+     * Configure or disable the built-in `/help` command.
+     * Set to `false` to disable it entirely, or an object to customise the command name and aliases.
+     */
+    help?: boolean | {
+        enabled?: boolean;
+        command?: string;
+        aliases?: string[];
+    };
+    /**
+     * Bot status/activity string. Pass an array to rotate between multiple statuses.
+     * Supports template tokens: `{{guilds}}`, `{{users}}`, `{{shardId}}`.
+     */
+    status?: string | string[];
+    /** Interval in ms between status rotations when `status` is an array. Defaults to 30000. */
+    statusInterval?: number;
+    /** Plugins to load. Plugins run in list order (highest `priority` first within that order). */
+    plugins?: PopiiPlugin<TState>[];
+    /**
+     * When `true`, Popii scans `node_modules` for installed `popii-plugin-*` packages
+     * (identified by a `"popii"` field in their `package.json`) and loads them automatically.
+     * Explicitly registered plugins in `plugins` always take precedence.
+     * @default false
+     */
+    autoDiscover?: boolean;
+    pluginConfig?: Record<string, unknown>;
+    /** Override the directory Popii scans for event files. Defaults to `"./src/events"`. */
+    events?: {
+        dir?: string;
+    };
+    /** Override the directory Popii scans for snap files. Defaults to `"./src/snaps"`. */
+    snaps?: {
+        dir?: string;
+    };
+    /** Override the directory Popii scans for middleware files. Defaults to `"./src/middlewares"`. */
+    middlewares?: {
+        dir?: string;
+    };
+    /** Override the directory Popii scans for task files. Defaults to `"./src/tasks"`. */
+    tasks?: {
+        dir?: string;
+    };
+    /**
+     * Localization configuration.
+     * - `dir` — directory containing `<locale>.json` files. Defaults to `"./src/locales"`.
+     * - `default` — fallback locale code. Defaults to `"en-US"`.
+     * - `url` — remote URL to fetch locale files from (fetched at startup).
+     */
+    locales?: {
+        dir?: string;
+        default?: string;
+        url?: string;
+    };
+    /** Custom logger implementation. Defaults to the built-in Popii logger. */
+    logger?: PopLogger;
+    /** Write logs to rotating files in `./logs/`. Defaults to `false`. */
+    fileLogging?: boolean;
+    /** Emit log lines as newline-delimited JSON instead of human-readable text. */
+    structuredLogs?: boolean;
+    /**
+     * Controls how rotating status messages are coordinated across shards.
+     * - `'local'` (default): each shard rotates independently.
+     * - `'coordinated'`: shard 0 leads rotation and broadcasts the active status
+     *   to all other shards via Redis pub/sub or IPC so they all show the same string.
+     * Supports template tokens: `{{shardId}}`, `{{guilds}}`, `{{users}}`.
+     */
+    presenceStrategy?: "local" | "coordinated";
+    /** TTL in milliseconds for persisted bot state in Redis/storage. Defaults to 90 days. */
+    stateTtlMs?: number;
+    serverSettings?: PopiiServerSetting[];
+}
+//# sourceMappingURL=types.d.ts.map