@usecrow/client

Headless client for Crow AI agents. Framework-agnostic TypeScript client with streaming, authentication, tool calling, and conversation management.

Installation

npm install @usecrow/client

Quick Start

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

// Identify user with JWT from your backend
client.identify({
  token: 'jwt-from-your-backend',
  name: 'John Doe',
  email: '[email protected]',
});

// Reset on logout
client.resetUser();

Client-Side Tools

Register tools that execute in the browser with results flowing back to the agent:

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

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

// 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

// 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:

import type {
  CrowClientConfig,
  Message,
  StreamEvent,
  ToolHandler,
  ToolResult,
} from '@usecrow/client';

License

MIT