ragatanga-mcp-sdk/dist/hooks/index.d.mts

SDK for integrating with the Ragatanga Management Control Plane (MCP) with Next.js 15, React 19, WebSocket and Arrow IPC support

import React, { ReactNode } from 'react';
import { MCPClient } from '../client/index.mjs';
import { M as MCPOptions, b as MCPResponse, O as OntologySummary, c as OntologyMetadata } from '../types-CmbeEBKR.mjs';
import { MCPWebSocket, WebSocketStatus, WebSocketMessage, WebSocketSubscription } from '../client/websocket.mjs';
import { MCPSSEClient } from '../client/sse.mjs';
import MCPArrowClient from '../client/arrow-ipc.mjs';
import { MCPError } from '../errors/index.mjs';
import { SWRConfiguration } from 'swr';
import { z } from 'zod';
import '../fetcher-4o7PbX4n.mjs';

/**
 * Transport type for MCP connections
 */
type MCPTransport = 'websocket' | 'sse' | 'arrow' | 'none';
/**
 * Re-export the MCPContext for internal use by hooks
 */
declare const MCPContext: React.Context<MCPContextValue | undefined>;
/**
 * Extended error handler callback
 */
type MCPErrorHandler = (error: MCPError | Error, source?: string) => void;
/**
 * Context value provided by MCPProvider
 */
interface MCPContextValue {
    client: MCPClient;
    webSocket: MCPWebSocket | null;
    sseClient: MCPSSEClient | null;
    arrowClient: MCPArrowClient | null;
    options: MCPOptions;
    isInitialized: boolean;
    transport: MCPTransport;
    onError: (handler: MCPErrorHandler) => () => void;
    reconnect: () => void;
}
/**
 * Props for the provider component
 */
interface MCPProviderProps {
    options: MCPOptions;
    children: ReactNode;
    transport?: MCPTransport;
    defaultHeaders?: Record<string, string>;
    suspense?: boolean;
    onError?: MCPErrorHandler;
    errorBoundary?: boolean;
    autoReconnect?: boolean;
    webSocketUrl?: string;
    sseUrl?: string;
    arrowUrl?: string;
    enableWebSocket?: boolean;
    enableSSE?: boolean;
    enableArrow?: boolean;
}
/**
 * MCP Provider component
 *
 * Provides a configured MCP client to all child components
 */
declare function MCPProvider({ options, children, transport, defaultHeaders, suspense, onError, errorBoundary, autoReconnect, webSocketUrl, sseUrl, arrowUrl, enableWebSocket, enableSSE, enableArrow }: MCPProviderProps): JSX.Element;
/**
 * Hook to access the MCP client from context
 * Must be used within an MCPProvider
 */
declare function useMCPClient(): MCPClient;
/**
 * Hook to access the MCP WebSocket from context
 * Must be used within an MCPProvider with transport="websocket"
 */
declare function useMCPWebSocket(): MCPWebSocket;
/**
 * Hook to access the MCP SSE client from context
 * Must be used within an MCPProvider with transport="sse"
 */
declare function useMCPSSE(): MCPSSEClient;
/**
 * Hook to access the MCP Arrow IPC client from context
 * Must be used within an MCPProvider with transport="arrow"
 */
declare function useMCPArrow(): MCPArrowClient;
/**
 * Hook to access the full MCP context
 * Must be used within an MCPProvider
 */
declare function useMCPContext(): MCPContextValue;
/**
 * Hook to register an error handler
 */
declare function useMCPErrorHandler(handler: MCPErrorHandler): void;
/**
 * Higher-order component to wrap components with MCPProvider
 */
declare function withMCP<P extends object>(Component: React.ComponentType<P>, options: MCPOptions, providerProps?: Omit<MCPProviderProps, 'options' | 'children'>): React.FC<P>;

interface UseQueryOptions<T = any> extends SWRConfiguration {
    client?: MCPClient;
    path: string;
    params?: Record<string, any>;
    schema?: z.ZodType<T>;
    cacheKey?: string;
    suspense?: boolean;
    enabled?: boolean;
}
interface UseQueryResult<T> {
    data: T | undefined;
    isValidating: boolean;
    isLoading: boolean;
    error: MCPError | null;
    refetch: () => Promise<T | undefined>;
    invalidate: () => void;
}
/**
 * Enhanced query hook with SWR for data fetching
 * Supports type validation, caching, and suspense
 */
declare function useQuery<T = any>({ client: externalClient, path, params, schema, enabled, suspense, cacheKey, ...swrOptions }: UseQueryOptions<T>): UseQueryResult<T>;

type MutationMethod = 'post' | 'put' | 'delete';
interface UseMutationOptions<T, D = any> {
    client?: MCPClient;
    path: string;
    method?: MutationMethod;
    schema?: z.ZodType<T>;
    onSuccess?: (data: T, variables?: D) => void | Promise<void>;
    onError?: (error: MCPError, variables?: D) => void | Promise<void>;
    onSettled?: (data?: T, error?: MCPError, variables?: D) => void | Promise<void>;
}
interface MutationResult<T, D = any> {
    data: T | undefined;
    error: MCPError | null;
    isLoading: boolean;
    reset: () => void;
    mutate: (mutationData?: D) => Promise<MCPResponse<T> | undefined>;
}
/**
 * Enhanced mutation hook for data mutations (POST, PUT, DELETE)
 * Supports type validation and various callbacks
 */
declare function useMutation<T, D = any>({ client: externalClient, path, method, schema, onSuccess, onError, onSettled }: UseMutationOptions<T, D>): MutationResult<T, D>;

interface UseOntologiesOptions {
    /**
     * Optional MCP client instance. If not provided, will use client from context.
     */
    client?: MCPClient;
}
declare function useOntologies(options?: UseOntologiesOptions): {
    ontologies: OntologySummary[];
    isLoading: boolean;
    error: MCPError | null;
    isUploading: boolean;
    uploadError: MCPError | null;
    isDeleteLoading: boolean;
    deleteError: MCPError | null;
    fetchOntologies: () => Promise<OntologySummary[]>;
    uploadOntology: (file: File, name?: string) => Promise<OntologyMetadata | null>;
    deleteOntology: (id: string) => Promise<void>;
    getOntologyDetails: (id: string) => Promise<OntologyMetadata | null>;
};

interface UseWebSocketOptions {
    client?: MCPWebSocket;
    path?: string;
    autoConnect?: boolean;
    onOpen?: (event: Event) => void;
    onMessage?: (data: string, messageType?: string) => void;
    onError?: (event: Event) => void;
    onClose?: (event: CloseEvent) => void;
    onHeartbeat?: (latency: number) => void;
    messageHandlers?: Record<string, (data: any) => void>;
    maxReconnectAttempts?: number;
    reconnectDelay?: number;
    heartbeatInterval?: number;
}
interface UseWebSocketResult {
    status: WebSocketStatus;
    isConnected: boolean;
    isConnecting: boolean;
    isReconnecting: boolean;
    messages: string[];
    lastMessage: string | null;
    connect: () => void;
    disconnect: () => void;
    send: (message: WebSocketMessage) => boolean;
    resolveUri: (uri: string, depth?: number) => boolean;
    clearMessages: () => void;
    subscribe: <T = any>(type: string, callback: (data: T) => void) => WebSocketSubscription;
    latency: number | null;
}
/**
 * Enhanced WebSocket hook for real-time communication
 */
declare function useWebSocket({ client: externalClient, path, autoConnect, onOpen, onMessage, onError, onClose, onHeartbeat, messageHandlers, maxReconnectAttempts, reconnectDelay, heartbeatInterval }?: UseWebSocketOptions): UseWebSocketResult;

interface UseSSEOptions {
    client?: MCPSSEClient;
    endpoint?: string;
    eventTypes?: string[];
    reconnectTimeout?: number;
    autoConnect?: boolean;
    onOpen?: (event: Event) => void;
    onError?: (event: Event) => void;
    onEvent?: (event: MessageEvent) => void;
    eventHandlers?: Record<string, (event: MessageEvent) => void>;
}
interface UseSSEResult {
    isConnected: boolean;
    events: MessageEvent[];
    lastEvent: MessageEvent | null;
    connect: () => void;
    disconnect: () => void;
}
/**
 * React hook for SSE (Server-Sent Events) integration
 */
declare function useSSE({ client: externalClient, endpoint, eventTypes, reconnectTimeout, autoConnect, onOpen, onError, onEvent, eventHandlers }?: UseSSEOptions): UseSSEResult;

export { MCPContext, type MCPErrorHandler, MCPProvider, type MCPTransport, useMCPArrow, useMCPClient, useMCPContext, useMCPErrorHandler, useMCPSSE, useMCPWebSocket, useMutation, useOntologies, useQuery, useSSE, useWebSocket, withMCP };