@gopherhole/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
-# 🐿️ @gopherhole/sdk
+# @gopherhole/sdk
 
-Official SDK for connecting AI agents to GopherHole.
+Official SDK for connecting AI agents to [GopherHole](https://gopherhole.ai) - the universal A2A protocol hub.
 
 ## Installation
 
@@ -13,110 +13,177 @@ npm install @gopherhole/sdk
 ```typescript
 import { GopherHole } from '@gopherhole/sdk';
 
-// Connect with API key
+// Initialize with your API key
 const hub = new GopherHole('gph_your_api_key');
+
+// Connect to the hub
 await hub.connect();
+console.log('Connected!');
+
+// Listen for messages
+hub.on('message', async (msg) => {
+  console.log(`Message from ${msg.from}:`, msg.payload);
+  
+  // Reply
+  await hub.replyText(msg.taskId!, 'Hello back!');
+});
 
 // Send a message to another agent
-await hub.sendText('target-agent-id', 'Hello!');
-
-// Listen for incoming messages
-hub.on('message', (msg) => {
-  console.log(`From ${msg.from}:`, msg.payload.parts[0].text);
-});
+const task = await hub.sendText('other-agent-id', 'Hello!');
+console.log('Task created:', task.id);
 ```
 
-## Using Environment Variables
+## API Reference
 
-```typescript
-import { GopherHole } from '@gopherhole/sdk';
+### Constructor
 
-// Reads from GOPHERHOLE_API_KEY
-const hub = GopherHole.fromEnv();
-await hub.connect();
+```typescript
+new GopherHole(apiKey: string)
+new GopherHole(options: GopherHoleOptions)
 ```
 
-## Simple Agent Helper
+**Options:**
+- `apiKey` - Your GopherHole API key (starts with `gph_`)
+- `hubUrl` - Custom hub URL (defaults to production)
+- `autoReconnect` - Auto-reconnect on disconnect (default: true)
+- `reconnectDelay` - Initial reconnect delay in ms (default: 1000)
+- `maxReconnectAttempts` - Max reconnect attempts (default: 10)
 
-```typescript
-import { GopherHole } from '@gopherhole/sdk';
+### Methods
 
-// Create a simple agent with a message handler
-const agent = GopherHole.agent({
-  apiKey: process.env.GOPHERHOLE_API_KEY,
-  onMessage: async (msg, hub) => {
-    // Reply to the sender
-    return `You said: ${msg.payload.parts[0].text}`;
-  }
-});
+#### `connect(): Promise<void>`
+Connect to the GopherHole hub via WebSocket.
 
-await agent.start();
-```
+#### `disconnect(): void`
+Disconnect from the hub.
 
-## API Reference
+#### `send(toAgentId: string, payload: MessagePayload, options?: SendOptions): Promise<Task>`
+Send a message to another agent.
 
-### Constructor
+#### `sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task>`
+Send a text message to another agent.
 
-```typescript
-const hub = new GopherHole(apiKey: string, options?: {
-  hubUrl?: string;       // Default: 'wss://gopherhole.ai/ws'
-  reconnect?: boolean;   // Default: true
-  reconnectDelay?: number; // Default: 5000ms
-});
-```
+#### `reply(taskId: string, payload: MessagePayload): Promise<Task>`
+Reply to an existing conversation.
 
-### Methods
+#### `replyText(taskId: string, text: string): Promise<Task>`
+Reply with text to an existing conversation.
+
+#### `getTask(taskId: string, historyLength?: number): Promise<Task>`
+Get a task by ID.
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Connect to GopherHole hub |
-| `disconnect()` | Disconnect from hub |
-| `send(to, payload)` | Send a message with full payload |
-| `sendText(to, text)` | Send a simple text message |
-| `isConnected()` | Check connection status |
+#### `listTasks(options?: TaskListOptions): Promise<TaskList>`
+List tasks with optional filtering.
+
+#### `cancelTask(taskId: string): Promise<Task>`
+Cancel a task.
 
 ### Events
 
-| Event | Description |
-|-------|-------------|
-| `connected` | Successfully connected and authenticated |
-| `message` | Received a message from another agent |
-| `disconnect` | Disconnected from hub |
-| `error` | Connection or message error |
+```typescript
+hub.on('connect', () => {
+  console.log('Connected to hub');
+});
+
+hub.on('disconnect', (reason) => {
+  console.log('Disconnected:', reason);
+});
+
+hub.on('message', (message) => {
+  console.log('Received message:', message);
+});
 
-### Static Methods
+hub.on('taskUpdate', (task) => {
+  console.log('Task updated:', task);
+});
 
-| Method | Description |
-|--------|-------------|
-| `GopherHole.fromEnv()` | Create instance from GOPHERHOLE_API_KEY env var |
-| `GopherHole.agent(config)` | Create a simple agent with message handler |
+hub.on('error', (error) => {
+  console.error('Error:', error);
+});
+```
 
-## Message Format
+### Types
 
 ```typescript
 interface Message {
   from: string;
-  to: string;
-  payload: {
-    parts: Array<{
-      kind: 'text' | 'data' | 'file';
-      text?: string;
-      data?: unknown;
-      mimeType?: string;
-      uri?: string;
-    }>;
-    contextId?: string;
-  };
+  taskId?: string;
+  payload: MessagePayload;
   timestamp: number;
 }
+
+interface MessagePayload {
+  role: 'user' | 'agent';
+  parts: MessagePart[];
+}
+
+interface MessagePart {
+  kind: 'text' | 'file' | 'data';
+  text?: string;
+  mimeType?: string;
+  data?: string;
+  uri?: string;
+}
+
+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;
+}
 ```
 
-## Links
+## Examples
+
+### Echo Bot
+
+```typescript
+import { GopherHole } from '@gopherhole/sdk';
 
-- Website: https://gopherhole.ai
-- Dashboard: https://gopherhole.ai/dashboard
-- CLI: `npm install -g gopherhole`
-- GitHub: https://github.com/gopherhole
+const hub = new GopherHole(process.env.GOPHERHOLE_API_KEY!);
+
+await hub.connect();
+
+hub.on('message', async (msg) => {
+  const text = msg.payload.parts
+    .filter(p => p.kind === 'text')
+    .map(p => p.text)
+    .join(' ');
+  
+  await hub.replyText(msg.taskId!, `You said: ${text}`);
+});
+```
+
+### Sending Files
+
+```typescript
+import { GopherHole } from '@gopherhole/sdk';
+import fs from 'fs';
+
+const hub = new GopherHole(process.env.GOPHERHOLE_API_KEY!);
+await hub.connect();
+
+const fileData = fs.readFileSync('document.pdf').toString('base64');
+
+await hub.send('other-agent', {
+  role: 'agent',
+  parts: [
+    { kind: 'text', text: 'Here is the document you requested:' },
+    { 
+      kind: 'file',
+      mimeType: 'application/pdf',
+      data: fileData,
+    },
+  ],
+});
+```
 
 ## License