npm package: @meetloyd/client
Description: Official TypeScript SDK for MeetLoyd - The Platform for the Agentic Era
Author: MeetLoyd
Latest version: 0.1.0

# @meetloyd/client

Official TypeScript SDK for **MeetLoyd** - The Platform for the Agentic Era.

## Installation

```bash
npm install @meetloyd/client
# or
bun add @meetloyd/client
```

## Quick Start

```typescript
import { MeetLoyd } from '@meetloyd/client'

const client = new MeetLoyd({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.meetloyd.com', // optional, defaults to localhost:4000
})

// Execute an agent
const run = await client.agents.execute('agent_xyz', 'Hello, how can you help me?')
console.log(run.output)
```

## Features

### Agent Management

```typescript
// List all agents
const { agents } = await client.agents.list()

// Create an agent
const agent = await client.agents.create({
  name: 'Support Bot',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'You are a helpful support assistant.',
})

// Update an agent
await client.agents.update(agent.id, { name: 'Customer Support' })

// Pause/Resume
await client.agents.pause(agent.id)
await client.agents.resume(agent.id)

// Delete
await client.agents.delete(agent.id)
```

### Conversations with Streaming

```typescript
// Create a conversation
const conversation = await client.conversations.create({
  agentId: 'agent_xyz',
  title: 'Customer inquiry',
})

// Stream responses (real-time)
for await (const event of client.conversations.stream(conversation.id, 'What is 2+2?')) {
  switch (event.type) {
    case 'token':
      process.stdout.write(event.token)
      break
    case 'tool_call':
      console.log('\nTool called:', event.toolCall.name)
      break
    case 'done':
      console.log('\nTokens used:', event.data.tokenUsage.total)
      break
  }
}

// Or get the full response
const response = await client.conversations.send(conversation.id, 'Hello!')
console.log(response.content)
```

### Usage Tracking

```typescript
// Get usage summary
const summary = await client.usage.summary()
console.log(`Tokens used: ${summary.usage.tokens.quantity}`)
console.log(`Total cost: $${summary.usage.total.cost.toFixed(4)}`)

// Daily breakdown
const daily = await client.usage.daily(30) // Last 30 days
for (const day of daily.breakdown) {
  console.log(`${day.date}: ${day.tokens} tokens, $${day.cost.toFixed(4)}`)
}

// By agent
const byAgent = await client.usage.byAgent()
for (const agent of byAgent.breakdown) {
  console.log(`${agent.agentId}: ${agent.requests} requests`)
}
```

## API Reference

### `MeetLoyd`

The main client class.

```typescript
new MeetLoyd({
  apiKey: string,      // Your API key
  baseUrl?: string,    // API base URL (default: http://localhost:4000)
  timeout?: number,    // Request timeout in ms (default: 30000)
})
```

### `client.agents`

| Method | Description |
|--------|-------------|
| `list(options?)` | List all agents |
| `get(id)` | Get agent by ID |
| `create(data)` | Create a new agent |
| `update(id, data)` | Update an agent |
| `delete(id)` | Delete an agent |
| `execute(id, message, options?)` | Execute an agent |
| `runs(id, options?)` | Get execution history |
| `pause(id)` | Pause an agent |
| `resume(id)` | Resume an agent |

### `client.conversations`

| Method | Description |
|--------|-------------|
| `create(data)` | Create a conversation |
| `get(id)` | Get conversation with messages |
| `listByAgent(agentId, options?)` | List conversations for an agent |
| `delete(id)` | Delete a conversation |
| `stream(id, message, options?)` | Send message and stream response |
| `send(id, message, options?)` | Send message and get full response |

### `client.usage`

| Method | Description |
|--------|-------------|
| `summary()` | Get usage summary |
| `history(options?)` | Get detailed usage records |
| `daily(days?)` | Get daily breakdown |
| `byAgent()` | Get usage by agent |

## Error Handling

```typescript
import { MeetLoyd, MeetLoydError } from '@meetloyd/client'

try {
  await client.agents.get('invalid-id')
} catch (error) {
  if (error instanceof MeetLoydError) {
    console.log('Status:', error.status)
    console.log('Message:', error.message)
    console.log('Code:', error.code)
  }
}
```

## TypeScript

Full TypeScript support with exported types:

```typescript
import type { Agent, AgentRun, StreamEvent } from '@meetloyd/client'
```

## License

MIT