declare module 'ipdb' {
  /**
   * IPDB constructor options
   */
  export interface IPDBOptions {
    /**
     * Array of patch functions to transform result data
     */
    patches?: Array<(data: Record<string, any>) => void>
  }

  /**
   * Find query options
   */
  export interface FindOptions {
    /**
     * Language code (e.g., 'CN', 'EN')
     */
    language?: string

    /**
     * Query-specific patch functions
     */
    patches?: Array<(data: Record<string, any>) => void>
  }

  /**
   * Find result
   */
  export interface FindResult {
    /**
     * Status code: 0 = success, -1 = error
     */
    code: number

    /**
     * Geolocation data (only when code is 0)
     */
    data?: Record<string, any>

    /**
     * Error message (only when code is -1)
     */
    message?: string
  }

  /**
   * IPDB database metadata
   */
  export interface IPDBMetadata {
    /**
     * IP version support: 0x01 (IPv4), 0x02 (IPv6)
     */
    ip_version: number

    /**
     * Number of nodes
     */
    node_count: number

    /**
     * Language offset mapping
     */
    languages: Record<string, number>

    /**
     * Field names array
     */
    fields: string[]

    /**
     * IPv4 starting node index
     */
    v4node?: number
  }

  /**
   * IPDB IP database query class
   */
  export default class IPDB {
    /**
     * Database metadata
     */
    meta: IPDBMetadata

    /**
     * Binary data
     */
    data: Uint8Array | Buffer

    /**
     * Global patch functions
     */
    patches?: Array<(data: Record<string, any>) => void>

    /**
     * Create an IPDB instance
     *
     * @param data - Data source
     *   - Node.js: File path (string) or Buffer
     *   - Browser: ArrayBuffer or Uint8Array (loaded via Fetch/File API)
     * @param options - Constructor options
     *
     * @example Node.js - file path
     * ```typescript
     * const ipdb = new IPDB('./data/ipipfree.ipdb')
     * ```
     *
     * @example Node.js - Buffer
     * ```typescript
     * const fs = require('fs')
     * const buffer = fs.readFileSync('./data/ipipfree.ipdb')
     * const ipdb = new IPDB(buffer)
     * ```
     *
     * @example Browser - Fetch API
     * ```typescript
     * const response = await fetch('/data/ipipfree.ipdb')
     * const arrayBuffer = await response.arrayBuffer()
     * const ipdb = new IPDB(arrayBuffer)
     * ```
     *
     * @example Browser - File API
     * ```typescript
     * const file = event.target.files[0]
     * const arrayBuffer = await file.arrayBuffer()
     * const ipdb = new IPDB(arrayBuffer)
     * ```
     */
    constructor(
      data: string | Buffer | ArrayBuffer | Uint8Array,
      options?: IPDBOptions
    )

    /**
     * Query IP address geolocation information
     *
     * @param ip - IPv4 or IPv6 address string
     * @param options - Query options
     * @returns Query result object
     *
     * @example
     * ```typescript
     * const result = ipdb.find('8.8.8.8')
     * if (result.code === 0) {
     *   console.log(result.data.country_name) // Country name
     *   console.log(result.data.city_name)    // City name
     * } else {
     *   console.error(result.message)
     * }
     * ```
     */
    find(ip: string, options?: FindOptions): FindResult
  }

  /**
   * Named export
   */
  export { IPDB }
}