index.d.ts

// Type definitions for api-ape
// Project: https://github.com/codemeasandwich/api-ape

import { Server as HttpServer } from 'http'
import { IncomingMessage } from 'http'

/**
 * WebSocket instance type (compatible with ws library and native implementations)
 */
export interface ApeWebSocket {
    send(data: string | Buffer): void
    close(code?: number, reason?: string): void
    on(event: 'message', handler: (data: Buffer) => void): this
    on(event: 'close', handler: () => void): this
    on(event: 'error', handler: (err: Error) => void): this
    readonly readyState: number
    readonly CONNECTING: 0
    readonly OPEN: 1
    readonly CLOSING: 2
    readonly CLOSED: 3
}

// =============================================================================
// SERVER TYPES
// =============================================================================

/**
 * Controller context available as `this` inside controller functions
 */
export interface ControllerContext {
    /** Publish to channel subscribers */
    publish(channel: string, data: any): void
    /** Get count of connected clients */
    online(): number
    /** Get array of connected clientIds */
    getClients(): string[]
    /** Unique ID of the calling client (generated by api-ape) */
    clientId: string
    /** Session ID from cookie (set by outer framework, may be null) */
    sessionId: string | null
    /** Original HTTP request */
    req: IncomingMessage
    /** WebSocket instance */
    socket: ApeWebSocket
    /** Parsed user-agent info */
    agent: {
        browser: { name?: string; version?: string }
        os: { name?: string; version?: string }
        device: { type?: string; vendor?: string; model?: string }
    }
    /** Custom embedded values from onConnect */
    [key: string]: any
}

/**
 * Controller function type
 */
export type ControllerFunction<T = any, R = any> = (
    this: ControllerContext,
    data: T
) => R | Promise<R>

/**
 * Send function provided to onConnect
 */
export type SendFunction = {
    (type: string, data: any): void
    toString(): string
}

/**
 * After hook returned from onReceive/onSend
 */
export type AfterHook = (err: Error | null, result: any) => void

/**
 * Connection lifecycle hooks returned from onConnect
 */
export interface ConnectionHandlers {
    /** Values to embed into controller context */
    embed?: Record<string, any>
    /** Called before processing incoming message, return after hook */
    onReceive?: (queryId: string, data: any, type: string) => AfterHook | void
    /** Called before sending message, return after hook */
    onSend?: (data: any, type: string) => AfterHook | void
    /** Called on error */
    onError?: (errorString: string) => void
    /** Called when client disconnects */
    onDisconnect?: () => void
}

/**
 * onConnect callback signature
 */
export type OnConnectCallback = (
    socket: ApeWebSocket,
    req: IncomingMessage,
    send: SendFunction
) => ConnectionHandlers | void

/**
 * Server options for ape()
 */
export interface ApeServerOptions {
    /** Directory containing controller files */
    where: string
    /** Connection lifecycle hook */
    onConnect?: OnConnectCallback
}

// =============================================================================
// 🌲 FOREST - DISTRIBUTED MESH TYPES
// =============================================================================

/**
 * Supported database client types for Forest adapters
 */
export type ForestDatabaseClient =
    | RedisClient
    | MongoClient
    | PostgresPool
    | SupabaseClient
    | FirebaseDatabase
    | ForestCustomAdapter

/** Redis client (node-redis or ioredis) */
export interface RedisClient {
    duplicate(): RedisClient
    publish(channel: string, message: string): Promise<number>
    subscribe(channel: string): Promise<void>
    on(event: string, handler: (...args: any[]) => void): void
}

/** MongoDB client */
export interface MongoClient {
    db(name?: string): any
}

/** PostgreSQL pool (pg) */
export interface PostgresPool {
    query(text: string, values?: any[]): Promise<any>
    connect(): Promise<any>
}

/** Supabase client */
export interface SupabaseClient {
    from(table: string): any
    channel(name: string): any
    removeChannel(channel: any): Promise<void>
}

/** Firebase Realtime Database */
export interface FirebaseDatabase {
    ref(path: string): any
    goOnline?(): void
    app?: any
}

/**
 * Forest adapter instance interface
 */
export interface ForestAdapterInstance {
    /** This server's unique ID */
    readonly serverId: string

    /** Join the distributed mesh */
    join(serverId?: string): Promise<void>

    /** Leave the mesh and cleanup */
    leave(): Promise<void>

    /** Client-to-server lookup operations */
    lookup: {
        /** Register a client on this server */
        add(clientId: string): Promise<void>
        /** Find which server owns a client */
        read(clientId: string): Promise<string | null>
        /** Remove a client mapping (must own it) */
        remove(clientId: string): Promise<void>
    }

    /** Inter-server channel operations */
    channels: {
        /** Push message to a server's channel (empty string = broadcast) */
        push(serverId: string, message: any): Promise<void>
        /** Subscribe to a server's channel, returns unsubscribe function */
        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
    }
}

/**
 * Custom adapter interface for implementing your own Forest adapter
 */
export interface ForestCustomAdapter {
    join(serverId: string): Promise<void>
    leave(): Promise<void>
    lookup: {
        add(clientId: string): Promise<void>
        read(clientId: string): Promise<string | null>
        remove(clientId: string): Promise<void>
    }
    channels: {
        push(serverId: string, message: any): Promise<void>
        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
    }
}

/**
 * Options for joinVia()
 */
export interface ForestOptions {
    /** Prefix for keys/tables (default: 'apes') */
    namespace?: string
    /** Custom server ID (default: auto-generated) */
    serverId?: string
}

/**
 * Initialize api-ape on a Node.js HTTP/HTTPS server
 * 
 * V3 Breaking Change:
 * Old: const ape = require('api-ape')
 * New: const { ape } = require('api-ape')
 */
declare function ape(server: HttpServer, options: ApeServerOptions): void

declare namespace ape {
    /**
     * Publish to channel subscribers
     * Supports chained syntax: ape.publish.channel.name(data)
     * Or direct call: ape.publish('/channel', data)
     */
    export const publish: {
        (channel: string, data: any): void
        [key: string]: any
    }

    /**
     * Read-only Map of connected clients
     * Each ClientWrapper provides: clientId, sessionId, embed, agent, send(type, data)
     */
    export const clients: ReadonlyMap<string, ClientWrapper>

    // =========================================================================
    // 🌲 FOREST - DISTRIBUTED MESH
    // =========================================================================

    /**
     * Join the distributed mesh for multi-server coordination.
     * Pass any supported database client - APE auto-detects the type.
     * 
     * @example
     * // Redis
     * ape.joinVia(redisClient);
     * 
     * // With options
     * ape.joinVia(mongoClient, { namespace: 'myapp', serverId: 'srv-1' });
     * 
     * // Custom adapter
     * ape.joinVia({ join, leave, lookup, channels });
     */
    export function joinVia(client: ForestDatabaseClient, options?: ForestOptions): Promise<ForestAdapterInstance>

    /**
     * Leave the distributed mesh gracefully.
     * Removes all client mappings and unsubscribes from channels.
     */
    export function leaveCluster(): Promise<void>

    /**
     * Current Forest adapter instance (null if not joined)
     */
    export const cluster: ForestAdapterInstance | null

    /**
     * This server's ID in the cluster (null if not joined)
     */
    export const serverId: string | null

    // Browser client methods (available when imported in browser context)
    /** Subscribe to broadcasts from the server */
    export function on<T = any>(type: string, handler: (message: { err?: Error; type: string; data: T }) => void): void
    /** Subscribe to connection state changes. Returns unsubscribe function. */
    export function onConnectionChange(handler: (state: 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected') => void): () => void
    /** Current transport type (read-only) */
    export const transport: 'websocket' | 'polling' | null

    /** Call any server function dynamically (browser only) */
    export function message<T = any, R = any>(data?: T): Promise<R>
}

// =============================================================================
// SERVER-SIDE CLIENT (api - same interface as browser)
// =============================================================================

/**
 * Server-side client for connecting to other api-ape servers
 * 100% identical interface to the browser client
 * 
 * @example
 * import api from 'api-ape'
 * 
 * // Configure connection (or set APE_SERVER env)
 * api.connect('other-server', 3000)  // → ws://other-server:3000/api/ape
 * 
 * // Same usage as browser
 * const result = await api.hello('World')
 * api.on('message', (data) => console.log(data))
 */
export interface ApeServerClient extends ApeSender {
    /** Subscribe to broadcasts from the remote server */
    on<T = any>(type: string, handler: MessageHandler<T>): void
    on(handler: MessageHandler): void
    /** Subscribe to connection state changes */
    onConnectionChange(handler: (state: ConnectionState) => void): () => void
    /** Connect to a server using host and port */
    connect(host: string, port: number): void
    /** Close the connection */
    close(): void
    /** Current transport type (read-only) */
    readonly transport: 'websocket' | null
}

/**
 * The api client - works identically on browser and server
 */
declare const api: ApeServerClient

// Named export for V3 (Server usage: const { ape } = require('api-ape'))
export { ape, api }

// Default export: api client (same interface on browser and server)
export default api

// =============================================================================
// BROWSER CLIENT (Default export in browser context)
// =============================================================================

/**
 * Unified browser client - auto-initializing Proxy that buffers calls until ready.
 * 
 * In browser context (via bundler or direct import), `import api from 'api-ape'`
 * returns this client instead of the server function.
 * 
 * Usage:
 *   import api from 'api-ape'
 *   api.message({ text: 'Hello!' })  // Buffered until connected
 *   api.on('message', (data) => {})  // Listen for broadcasts
 *   api.onConnectionChange((state) => {}) // Connection state updates
 */
export interface ApeBrowserClient extends ApeSender {
    /** Subscribe to broadcasts from the server */
    on<T = any>(type: string, handler: MessageHandler<T>): void

    /** Subscribe to connection state changes. Returns unsubscribe function. */
    onConnectionChange(handler: (state: ConnectionState) => void): () => void

    /** Current transport type (read-only) */
    readonly transport: TransportType | null
}

// =============================================================================
// CLIENT TYPES
// =============================================================================

/**
 * Connection state enum values
 */
export type ConnectionState = 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected' | 'closing'

/**
 * Connection state enum object
 */
export declare const ConnectionState: {
    Offline: 'offline'
    Walled: 'walled'
    Disconnected: 'disconnected'
    Connecting: 'connecting'
    Connected: 'connected'
    Closing: 'closing'
}

/**
 * Message received from server
 */
export interface ReceivedMessage<T = any> {
    err?: Error | string
    type: string
    data: T
}

/**
 * Message handler callback
 */
export type MessageHandler<T = any> = (message: ReceivedMessage<T>) => void

/**
 * Proxy-based sender - any property access creates a callable path
 * Example: sender.users.list() calls type="/users/list"
 */
export interface ApeSender {
    [key: string]: ApeSender & (<T = any, R = any>(data?: T) => Promise<R>)
}

/**
 * Set receiver for specific message type or all messages
 */
export type SetOnReceiver = {
    (type: string, handler: MessageHandler): void
    (handler: MessageHandler): void
}

/**
 * Connected client interface
 */
export interface ApeClient {
    sender: ApeSender
    setOnReceiver: SetOnReceiver
    /** Subscribe to connection state changes. Returns unsubscribe function. */
    onConnectionChange: (handler: (state: ConnectionState) => void) => () => void
    /** Current transport type (read-only) */
    readonly transport: TransportType | null
}

/**
 * Transport type for connection
 */
export type TransportType = 'websocket' | 'polling'

/**
 * Connect socket function with configuration methods
 */
export interface ConnectSocket {
    (): ApeClient
    /** Enable auto-reconnection on disconnect */
    autoReconnect(): void
    /** Connection state enum */
    ConnectionState: typeof ConnectionState
}

/**
 * Client module default export
 */
declare const connectSocket: ConnectSocket

export { connectSocket }

// =============================================================================
// CLIENTS MODULE
// =============================================================================

export declare const clients: ReadonlyMap<string, ClientWrapper>

/**
 * Chainable send function for client.send
 * Supports both direct and chained syntax:
 * - client.send('news/banking', data)
 * - client.send.news.banking(data)
 */
export interface ClientSendFunction {
    /** Direct call: send(type, data) */
    (type: string, data: any): void
    /** Chained access for path building */
    [key: string]: ClientSendFunction & ((data?: any) => void)
}

/**
 * Client wrapper providing client info and send function
 */
export interface ClientWrapper {
    /** Unique client identifier */
    readonly clientId: string
    /** Session ID from cookie (set by outer framework) */
    readonly sessionId: string | null
    /** Embedded values from onConnect */
    readonly embed: Record<string, any>
    /** Parsed user-agent info */
    readonly agent: {
        browser: { name?: string; version?: string }
        os: { name?: string; version?: string }
        device: { type?: string; vendor?: string; model?: string }
    }
    /**
     * Send a message to this specific client
     * Supports both direct and chained syntax:
     * - client.send('news/banking', data)
     * - client.send.news.banking(data)
     */
    send: ClientSendFunction
}