@usecrow/client 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# @usecrow/client
+
+Headless client for [Crow](https://usecrow.ai) AI agents. Framework-agnostic TypeScript client with streaming, authentication, tool calling, and conversation management.
+
+## Installation
+
+```bash
+npm install @usecrow/client
+```
+
+## Quick Start
+
+```typescript
+import { CrowClient } from '@usecrow/client';
+
+const client = new CrowClient({
+  productId: 'YOUR_PRODUCT_ID',
+  apiUrl: 'https://api.usecrow.org',
+});
+
+// Send message and stream response
+for await (const event of client.sendMessage('Hello!')) {
+  if (event.type === 'content') {
+    console.log(event.text);
+  }
+}
+```
+
+## Features
+
+### Identity / Authentication
+
+```typescript
+// Identify user with JWT from your backend
+client.identify({
+  token: 'jwt-from-your-backend',
+  name: 'John Doe',
+  email: 'john@example.com',
+});
+
+// Reset on logout
+client.resetUser();
+```
+
+### Client-Side Tools
+
+Register tools that execute in the browser with results flowing back to the agent:
+
+```typescript
+client.registerTools({
+  addToCart: async ({ productId, quantity }) => {
+    await cartApi.add(productId, quantity);
+    return { status: 'success', data: { cartCount: 3 } };
+  },
+  
+  getCurrentPage: async () => {
+    return { status: 'success', data: { path: window.location.pathname } };
+  },
+});
+```
+
+### Streaming Events
+
+```typescript
+for await (const event of client.sendMessage('Help me checkout')) {
+  switch (event.type) {
+    case 'content':
+      // Text content chunk
+      updateUI(event.accumulated);
+      break;
+    case 'thinking':
+      // Reasoning/thinking trace
+      showReasoning(event.content);
+      break;
+    case 'tool_call_start':
+      // Server-side tool started
+      showToolStatus(event.toolName);
+      break;
+    case 'client_tool_call':
+      // Client-side tool requested
+      // (automatically executed if registered)
+      break;
+    case 'done':
+      // Stream complete
+      break;
+  }
+}
+```
+
+### Conversation Management
+
+```typescript
+// Get conversation history (for verified users)
+const conversations = await client.getConversations();
+
+// Load and switch to a conversation
+await client.switchConversation(conversationId);
+
+// Start new conversation
+client.clearMessages();
+```
+
+### Context
+
+```typescript
+// Set context data sent with messages
+client.setContext({
+  page: '/checkout',
+  cartTotal: 99.99,
+});
+```
+
+## API Reference
+
+### `CrowClient`
+
+#### Constructor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `productId` | `string` | Yes | Your Crow product ID |
+| `apiUrl` | `string` | No | API URL (default: `https://api.usecrow.org`) |
+| `model` | `string` | No | Default model to use |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `sendMessage(content)` | Send message, returns async generator of events |
+| `send(content)` | Send message and wait for complete response |
+| `stop()` | Stop current generation |
+| `identify(options)` | Identify user with JWT |
+| `resetUser()` | Reset user identity |
+| `registerTools(handlers)` | Register client-side tools |
+| `setContext(data)` | Set context data |
+| `clearMessages()` | Clear messages, start new conversation |
+| `getConversations()` | Get conversation list (verified users) |
+| `loadHistory(id)` | Load conversation history |
+| `switchConversation(id)` | Switch to different conversation |
+| `destroy()` | Clean up resources |
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `messages` | `Message[]` | Current messages |
+| `isLoading` | `boolean` | Whether currently streaming |
+| `conversationId` | `string \| null` | Current conversation ID |
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  CrowClientConfig,
+  Message,
+  StreamEvent,
+  ToolHandler,
+  ToolResult,
+} from '@usecrow/client';
+```
+
+## License
+
+MIT
+