@gopherhole/sdk 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,67 +1,499 @@
-import { EventEmitter } from 'events';
-export interface GopherHoleOptions {
+import { EventEmitter } from 'eventemitter3';
+
+/**
+ * A2A Protocol Types
+ * Based on Google's Agent-to-Agent Protocol specification
+ */
+interface AgentCard {
+    name: string;
+    description?: string;
+    url: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    version: string;
+    documentationUrl?: string;
+    capabilities: AgentCapabilities;
+    authentication?: AgentAuthentication;
+    defaultInputModes?: InputMode[];
+    defaultOutputModes?: OutputMode[];
+    skills?: AgentSkill$1[];
+}
+interface AgentCapabilities {
+    streaming?: boolean;
+    pushNotifications?: boolean;
+    stateTransitionHistory?: boolean;
+}
+interface AgentAuthentication {
+    schemes: string[];
+    credentials?: string;
+}
+interface AgentSkill$1 {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: ContentMode[];
+    outputModes?: ContentMode[];
+}
+/**
+ * Content mode - MIME type string or legacy shorthand
+ * Examples: 'text/plain', 'text/markdown', 'application/json', 'image/png'
+ * Legacy: 'text', 'file', 'data' (still supported for backwards compat)
+ */
+type ContentMode = string;
+type InputMode = ContentMode;
+type OutputMode = ContentMode;
+interface A2AMessage {
+    role: 'user' | 'agent';
+    parts: Part[];
+    metadata?: Record<string, unknown>;
+}
+type Part = TextPart | FilePart | DataPart;
+interface TextPart {
+    kind: 'text';
+    text: string;
+}
+interface FilePart {
+    kind: 'file';
+    file: FileContent;
+}
+interface DataPart {
+    kind: 'data';
+    data: DataContent;
+}
+interface FileContent {
+    name?: string;
+    mimeType?: string;
+    bytes?: string;
+    uri?: string;
+}
+interface DataContent {
+    mimeType: string;
+    data: string;
+}
+interface A2ATask {
+    id: string;
+    contextId: string;
+    status: A2ATaskStatus;
+    history?: A2AMessage[];
+    artifacts?: A2AArtifact[];
+    metadata?: Record<string, unknown>;
+}
+interface A2ATaskStatus {
+    state: TaskState;
+    timestamp: string;
+    message?: A2AMessage;
+}
+type TaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled' | 'rejected' | 'auth-required';
+interface A2AArtifact {
+    name?: string;
+    description?: string;
+    parts: Part[];
+    index?: number;
+    append?: boolean;
+    lastChunk?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+    id: string | number;
+}
+interface JsonRpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    result?: T;
+    error?: JsonRpcError;
+    id: string | number;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+declare const JsonRpcErrorCodes: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly TaskNotFound: -32001;
+    readonly TaskNotCancelable: -32002;
+    readonly PushNotificationNotSupported: -32003;
+    readonly UnsupportedOperation: -32004;
+    readonly ContentTypeNotSupported: -32005;
+    readonly InvalidAgentCard: -32006;
+};
+interface PushNotificationConfig {
+    url: string;
+    token?: string;
+    authentication?: {
+        scheme: string;
+        credentials?: string;
+    };
+}
+interface TaskPushNotificationConfig {
+    id: string;
+    taskId: string;
+    url: string;
+    token?: string;
+    authentication?: {
+        scheme: string;
+        credentials?: string;
+    };
+}
+interface MessageSendConfiguration {
+    agentId?: string;
+    contextId?: string;
+    historyLength?: number;
+    pushNotificationConfig?: PushNotificationConfig;
+    blocking?: boolean;
+    acceptedOutputModes?: OutputMode[];
+}
+interface TaskQueryConfiguration {
+    id: string;
+    historyLength?: number;
+}
+interface TaskListConfiguration {
+    contextId?: string;
+    pageSize?: number;
+    pageToken?: string;
+    sortOrder?: 'asc' | 'desc';
+    includeArtifacts?: boolean;
+}
+interface TaskStatusUpdateEvent {
+    type: 'status';
+    taskId: string;
+    contextId: string;
+    status: A2ATaskStatus;
+    final: boolean;
+}
+interface TaskArtifactUpdateEvent {
+    type: 'artifact';
+    taskId: string;
+    contextId: string;
+    artifact: A2AArtifact;
+}
+type TaskEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+
+interface GopherHoleOptions {
+    /** API key (starts with gph_) */
+    apiKey: string;
+    /** Hub URL (defaults to production) */
     hubUrl?: string;
-    reconnect?: boolean;
+    /** Agent card to register on connect */
+    agentCard?: AgentCardConfig;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
     reconnectDelay?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+}
+/** Agent card configuration for registration */
+interface AgentCardConfig {
+    name: string;
+    description?: string;
+    url?: string;
+    version?: string;
+    skills?: AgentSkillConfig[];
 }
-export interface Message {
+/** Skill configuration */
+interface AgentSkillConfig {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+interface Message {
     from: string;
-    to: string;
+    taskId?: string;
     payload: MessagePayload;
     timestamp: number;
 }
-export interface MessagePayload {
+interface MessagePayload {
+    role: 'user' | 'agent';
     parts: MessagePart[];
-    contextId?: string;
 }
-export interface MessagePart {
-    kind: 'text' | 'data' | 'file';
+interface MessagePart {
+    kind: 'text' | 'file' | 'data';
     text?: string;
-    data?: unknown;
     mimeType?: string;
+    data?: string;
     uri?: string;
 }
-export declare class GopherHole extends EventEmitter {
+interface Task {
+    id: string;
+    contextId: string;
+    status: TaskStatus;
+    history?: MessagePayload[];
+    artifacts?: Artifact[];
+}
+interface TaskStatus {
+    state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled' | 'rejected';
+    timestamp: string;
+    message?: string;
+}
+interface Artifact {
+    name: string;
+    mimeType: string;
+    data?: string;
+    uri?: string;
+}
+interface SendOptions {
+    /** Existing context/conversation ID */
+    contextId?: string;
+    /** Push notification URL */
+    pushNotificationUrl?: string;
+    /** History length to include */
+    historyLength?: number;
+}
+type EventMap = {
+    connect: () => void;
+    disconnect: (reason: string) => void;
+    error: (error: Error) => void;
+    message: (message: Message) => void;
+    taskUpdate: (task: Task) => void;
+};
+declare class GopherHole extends EventEmitter<EventMap> {
     private apiKey;
     private hubUrl;
+    private apiUrl;
     private ws;
-    private reconnect;
+    private autoReconnect;
     private reconnectDelay;
-    private authenticated;
-    private pendingMessages;
-    private messageCounter;
-    agentId: string | null;
-    constructor(apiKey: string, options?: GopherHoleOptions);
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingInterval;
+    private agentId;
+    private agentCard;
+    constructor(apiKeyOrOptions: string | GopherHoleOptions);
+    /**
+     * Update agent card (sends to hub if connected)
+     */
+    updateCard(card: AgentCardConfig): Promise<void>;
+    /**
+     * Connect to the GopherHole hub via WebSocket
+     */
     connect(): Promise<void>;
+    /**
+     * Disconnect from the hub
+     */
+    disconnect(): void;
+    /**
+     * Send a message to another agent
+     */
+    send(toAgentId: string, payload: MessagePayload, options?: SendOptions): Promise<Task>;
+    /**
+     * Send a text message to another agent
+     */
+    sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task>;
+    /**
+     * Get a task by ID
+     */
+    getTask(taskId: string, historyLength?: number): Promise<Task>;
+    /**
+     * List tasks
+     */
+    listTasks(options?: {
+        contextId?: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<{
+        tasks: Task[];
+        nextPageToken?: string;
+        totalSize: number;
+    }>;
+    /**
+     * Cancel a task
+     */
+    cancelTask(taskId: string): Promise<Task>;
+    /**
+     * Reply to a message/task (sends back to the original caller)
+     */
+    reply(taskId: string, payload: MessagePayload, toAgentId?: string): Promise<Task>;
+    /**
+     * Reply with text
+     */
+    replyText(taskId: string, text: string): Promise<Task>;
+    /**
+     * Make a JSON-RPC call to the A2A endpoint
+     */
+    private rpc;
+    /**
+     * Handle incoming WebSocket messages
+     */
     private handleMessage;
-    send(to: string, payload: MessagePayload): Promise<{
-        id: string;
-        timestamp: number;
+    /**
+     * Start ping interval
+     */
+    private startPing;
+    /**
+     * Stop ping interval
+     */
+    private stopPing;
+    /**
+     * Schedule reconnection
+     */
+    private scheduleReconnect;
+    /**
+     * Get connection state
+     */
+    get connected(): boolean;
+    /**
+     * Get the agent ID (available after connect)
+     */
+    get id(): string | null;
+    /**
+     * Discover public agents with comprehensive search
+     */
+    discover(options?: DiscoverOptions): Promise<DiscoverResult>;
+    /**
+     * Search agents with fuzzy matching on description
+     */
+    searchAgents(query: string, options?: Omit<DiscoverOptions, 'query'>): Promise<DiscoverResult>;
+    /**
+     * Find agents by category
+     */
+    findByCategory(category: string, options?: Omit<DiscoverOptions, 'category'>): Promise<DiscoverResult>;
+    /**
+     * Find agents by tag
+     */
+    findByTag(tag: string, options?: Omit<DiscoverOptions, 'tag'>): Promise<DiscoverResult>;
+    /**
+     * Find agents by skill tag (searches within agent skills)
+     */
+    findBySkillTag(skillTag: string, options?: Omit<DiscoverOptions, 'skillTag'>): Promise<DiscoverResult>;
+    /**
+     * Find agents that support a specific input/output mode
+     */
+    findByContentMode(mode: string, options?: Omit<DiscoverOptions, 'contentMode'>): Promise<DiscoverResult>;
+    /**
+     * Get top-rated agents
+     */
+    getTopRated(limit?: number): Promise<DiscoverResult>;
+    /**
+     * Get most popular agents (by usage)
+     */
+    getPopular(limit?: number): Promise<DiscoverResult>;
+    /**
+     * Get featured/curated agents
+     */
+    getFeatured(): Promise<{
+        featured: PublicAgent[];
     }>;
-    sendText(to: string, text: string, contextId?: string): Promise<{
-        id: string;
-        timestamp: number;
+    /**
+     * Get available categories
+     */
+    getCategories(): Promise<{
+        categories: AgentCategory[];
     }>;
-    disconnect(): void;
-    isConnected(): boolean;
     /**
-     * Create a GopherHole instance from environment variables
-     * Reads GOPHERHOLE_API_KEY and optionally GOPHERHOLE_HUB_URL
+     * Get detailed info about a public agent
+     */
+    getAgentInfo(agentId: string): Promise<AgentInfoResult>;
+    /**
+     * Rate an agent (requires authentication)
      */
-    static fromEnv(options?: Omit<GopherHoleOptions, 'hubUrl'>): GopherHole;
+    rateAgent(agentId: string, rating: number, review?: string): Promise<RatingResult>;
     /**
-     * Create a simple agent with a message handler
+     * Get best agent for a task using smart matching
+     * Searches by query and returns the top-rated match
      */
-    static agent(config: {
-        apiKey?: string;
-        hubUrl?: string;
-        onMessage: (msg: Message, hub: GopherHole) => Promise<string | MessagePayload | void> | string | MessagePayload | void;
-        onConnect?: (hub: GopherHole) => void;
-        onError?: (err: Error, hub: GopherHole) => void;
-    }): {
-        start: () => Promise<void>;
-        stop: () => void;
-        hub: GopherHole;
+    findBestAgent(query: string, options?: {
+        category?: string;
+        minRating?: number;
+        pricing?: 'free' | 'paid' | 'any';
+    }): Promise<PublicAgent | null>;
+    /**
+     * Find agents similar to a given agent
+     */
+    findSimilar(agentId: string, limit?: number): Promise<DiscoverResult>;
+}
+interface DiscoverOptions {
+    /** Search query (fuzzy matches name, description, tags) */
+    query?: string;
+    /** Filter by category */
+    category?: string;
+    /** Filter by tag */
+    tag?: string;
+    /** Filter by skill tag (searches within agent skills) */
+    skillTag?: string;
+    /** Filter by content mode (MIME type, e.g., 'text/markdown', 'image/png') */
+    contentMode?: string;
+    /** Sort order */
+    sort?: 'rating' | 'popular' | 'recent';
+    /** Max results (default 20, max 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+}
+interface DiscoverResult {
+    agents: PublicAgent[];
+    count: number;
+    offset: number;
+}
+interface PublicAgent {
+    id: string;
+    name: string;
+    description: string | null;
+    category: string | null;
+    tags: string[];
+    pricing: 'free' | 'paid' | 'contact';
+    avgRating: number;
+    ratingCount: number;
+    tenantName: string;
+    websiteUrl: string | null;
+    docsUrl: string | null;
+}
+interface AgentCategory {
+    name: string;
+    count: number;
+}
+interface AgentInfoResult {
+    agent: PublicAgent & {
+        agentCard: {
+            name: string;
+            description?: string;
+            skills?: AgentSkill[];
+        } | null;
+        stats: {
+            avgRating: number;
+            ratingCount: number;
+            totalMessages: number;
+            successRate: number;
+            avgResponseTime: number;
+        };
     };
+    reviews: AgentReview[];
+}
+/** Full A2A skill schema */
+interface AgentSkill {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+interface AgentReview {
+    rating: number;
+    review: string;
+    created_at: number;
+    reviewer_name: string;
+}
+interface RatingResult {
+    success: boolean;
+    avgRating: number;
+    ratingCount: number;
 }
-export default GopherHole;
+
+export { type A2AArtifact, type A2AMessage, type A2ATask, type A2ATaskStatus, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentReview, type AgentSkill, type AgentSkillConfig, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, type GopherHoleOptions, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest, type JsonRpcResponse, type Message, type MessagePart, type MessagePayload, type MessageSendConfiguration, type OutputMode, type Part, type PublicAgent, type PushNotificationConfig, type RatingResult, type SendOptions, type Task, type TaskArtifactUpdateEvent, type TaskEvent, type TaskListConfiguration, type TaskPushNotificationConfig, type TaskQueryConfiguration, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default };