@botport/core/index.d.ts

Unified framework for Discord bot products, published by BotPort. Combines docky and framework functionality.

import { Client, Collection, SlashCommandBuilder, Interaction } from 'discord.js';

// Environment configuration types
export interface EnvironmentConfig {
  loadAddons: boolean;
  isDebug: boolean;
}

export function validateEnvironmentVariables(): string[];
export function getProjectDirectory(): string;
export const loadAddons: boolean;
export const isDebug: boolean;

// Command structure types
export interface CommandInfo {
  name?: string;
  version?: string;
  mainfile?: string;
  type?: string;
  [key: string]: string | undefined;
}

export interface Command {
  data: SlashCommandBuilder;
  execute: (interaction: Interaction, client?: Client) => Promise<void>;
  info?: CommandInfo;
}

export interface AddonInfo {
  name?: string;
  version?: string;
  mainfile?: string;
  type?: string;
  [key: string]: string | undefined;
}

export interface Addon {
  execute: (client: Client) => Promise<void>;
}

export interface Event {
  name: string;
  once?: boolean;
  execute: (...args: any[]) => Promise<void>;
}

// Member data types
export interface MemberData {
  userId: string;
  username: string;
  roles: string;
  formattedJoinedAt: string;
}

// Bot setup functions (from docky)
export function setupBot(): Promise<Client>;

// Loader functions
export function loadCommands(client: Client): Promise<boolean>;
export function loadEvents(client: Client): Promise<void>;
export function loadAddonsIfEnabled(client: Client): Promise<void>;

// Registration functions
export function registerCommands(client: Client): Promise<void>;

// Utility functions
export function parseInfoFile(filePath: string): CommandInfo | AddonInfo | null;

// Core framework types and exports
export interface Logger {
  info(msg: string, ...args: any[]): void;
  i(msg: string, ...args: any[]): void;
  warn(msg: string, ...args: any[]): void;
  error(msg: string, ...args: any[]): void;
  debug(msg: string, ...args: any[]): void;
  success(msg: string, ...args: any[]): void;
  log(msg: string, ...args: any[]): void;
}

export const logger: Logger;

export interface Database {
  query(sql: string, params?: any[]): Promise<any>;
  execute(sql: string, params?: any[]): Promise<any>;
}

export const db: Database;
export function initDatabases(): Promise<void>;

export class ErrorHandler {
  static handle(error: Error, context?: any): void;
  static handleError(error: any, context: string, logger: any): void;
  static handleAndCheckCritical(
    error: any,
    context: string,
    logger: any
  ): boolean;
  static getErrorExplanation(error: any): {
    title: string;
    description: string;
    solution: string;
    severity: string;
  };
  static addErrorMapping(code: string, errorInfo: any): void;
  static isCritical(error: any): boolean;
}

export interface InteractionContext {
  [key: string]: any;
}

export function handleInteraction(
  interaction: InteractionContext,
  client: Client,
  logger?: Logger
): Promise<void>;

export function logBanner(): void;

// ============================================
// PROTECTION SYSTEM TYPES
// ============================================

/**
 * Request Tracker - Prevents duplicate request processing
 */
export interface RequestTrackerStats {
  active: number;
  requests: string[];
}

export interface ActiveRequest {
  key: string;
  elapsed: number;
}

export interface RequestTrackerWrapOptions {
  duration?: number;
  data?: string;
  throwOnDuplicate?: boolean;
}

export interface RequestTracker {
  /**
   * Check if a request is currently being processed
   */
  isProcessing(userId: string, action: string, data?: string): boolean;
  
  /**
   * Mark a request as being processed
   */
  mark(userId: string, action: string, duration?: number, data?: string): void;
  
  /**
   * Manually release a request
   */
  release(userId: string, action: string, data?: string): void;
  
  /**
   * Wrap a function with automatic request tracking
   */
  wrap<T>(
    userId: string, 
    action: string, 
    fn: () => Promise<T>, 
    options?: RequestTrackerWrapOptions
  ): Promise<T>;
  
  /**
   * Get all currently processing requests
   */
  getActive(): ActiveRequest[];
  
  /**
   * Get statistics
   */
  getStats(): RequestTrackerStats;
  
  /**
   * Clear all tracked requests
   */
  clear(): void;
}

/**
 * User Limiter - Rate limiting for user actions
 */
export interface RateLimitConfig {
  max: number;
  window: number;
}

export interface RateCheckResult {
  allowed: boolean;
  remaining: number;
  retryAfter: number;
  resetAt: number;
}

export interface RateLimitStatus {
  count: number;
  max: number;
  remaining: number;
  resetIn: number;
  resetAt: number;
}

export interface UserLimiterStats {
  totalEntries: number;
  activeUsers: number;
  byAction: Record<string, number>;
}

export interface UserLimiter {
  /**
   * Check if user is rate limited for an action
   */
  check(userId: string, action: string, customLimit?: RateLimitConfig): RateCheckResult;
  
  /**
   * Set a custom limit for an action
   */
  setLimit(action: string, max: number, window: number): void;
  
  /**
   * Reset limits for a user
   */
  reset(userId: string, action?: string): void;
  
  /**
   * Get current limit status for a user and action
   */
  getStatus(userId: string, action: string): RateLimitStatus | null;
  
  /**
   * Get statistics
   */
  getStats(): UserLimiterStats;
  
  /**
   * Clear all limits
   */
  clear(): void;
}

/**
 * Protect - Convenience wrapper combining both protections
 */
export interface ProtectOptions {
  checkDuplicate?: boolean;
  checkRateLimit?: boolean;
  customLimit?: RateLimitConfig;
  duration?: number;
  data?: string;
}

export function protect<T>(
  userId: string,
  action: string,
  fn: () => Promise<T>,
  options?: ProtectOptions
): Promise<T>;

// Export protection utilities
export const requestTracker: RequestTracker;
export const userLimiter: UserLimiter;

// ============================================
// FRAMEWORK CLASS
// ============================================

export interface BotFrameworkOptions {
  showBanner?: boolean;
  autoInstall?: boolean;
  verbose?: boolean;
  silent?: boolean;
  [key: string]: any;
}

export class BotFramework {
  logger: Logger;
  options: BotFrameworkOptions;
  initialized: boolean;
  requestTracker: RequestTracker;
  userLimiter: UserLimiter;

  constructor(options?: BotFrameworkOptions);
  initialize(): Promise<void>;
  getDatabase(): Database;
  getErrorHandler(): typeof ErrorHandler;
  getLogger(): Logger;
  
  /**
   * Get request tracker instance
   */
  getRequestTracker(): RequestTracker;
  
  /**
   * Get user limiter instance
   */
  getUserLimiter(): UserLimiter;
  
  /**
   * Convenience method for protected execution
   */
  protect<T>(
    userId: string,
    action: string,
    fn: () => Promise<T>,
    options?: ProtectOptions
  ): Promise<T>;
  
  handleInteraction(
    interaction: InteractionContext,
    client: Client,
    logger?: Logger
  ): Promise<void>;
}

export default BotFramework;

// Extend Discord.js Client type to include commands collection
declare module 'discord.js' {
  interface Client {
    commands: Collection<string, Command>;
    requestTracker?: RequestTracker;
    userLimiter?: UserLimiter;
  }
}

// Module declarations for individual exports
declare module "@botport/core/lib/database/db" {
  export interface Database {
    query(sql: string, params?: any[]): Promise<any>;
    execute(sql: string, params?: any[]): Promise<any>;
  }

  export const db: Database;
  export function initDatabases(): Promise<void>;
}

declare module "@botport/core/lib/handlers/errors" {
  export class ErrorHandler {
    static handle(error: Error, context?: any): void;
    static handleError(error: any, context: string, logger: any): void;
    static handleAndCheckCritical(
      error: any,
      context: string,
      logger: any
    ): boolean;
    static getErrorExplanation(error: any): {
      title: string;
      description: string;
      solution: string;
      severity: string;
    };
    static addErrorMapping(code: string, errorInfo: any): void;
    static isCritical(error: any): boolean;
  }
}

declare module "@botport/core/lib/handlers/interactions" {
  export function handleInteraction(
    interaction: any,
    client: any,
    logger?: any
  ): Promise<void>;
}

declare module "@botport/core/lib/logger" {
  export interface Logger {
    info(msg: string, ...args: any[]): void;
    i(msg: string, ...args: any[]): void;
    warn(msg: string, ...args: any[]): void;
    error(msg: string, ...args: any[]): void;
    debug(msg: string, ...args: any[]): void;
    success(msg: string, ...args: any[]): void;
    log(msg: string, ...args: any[]): void;
  }

  const logger: Logger;
  export default logger;
}

declare module "@botport/core/lib/essentials/banner" {
  export default function logBanner(): void;
}

// Protection utilities module declarations
declare module "@botport/core/lib/utils/requestTracker" {
  import { RequestTracker } from '@botport/core';
  const requestTracker: RequestTracker;
  export default requestTracker;
}

declare module "@botport/core/lib/utils/userLimiter" {
  import { UserLimiter } from '@botport/core';
  const userLimiter: UserLimiter;
  export default userLimiter;
}

declare module "@botport/core/lib/utils/protect" {
  import { ProtectOptions } from '@botport/core';
  export default function protect<T>(
    userId: string,
    action: string,
    fn: () => Promise<T>,
    options?: ProtectOptions
  ): Promise<T>;
}