npm package: @journeyrewards/hive-sdk
Description: TypeScript SDK for the Journey Hive Agent Orchestration API
Latest version: 1.2.1

# @journeyrewards/hive-sdk

TypeScript SDK for the [Journey Hive](https://journey-hive.replit.app) Agent Orchestration API.

## Installation

```bash
npm install @journeyrewards/hive-sdk
```

## Quick Start

```typescript
import { JourneyHiveClient } from "@journeyrewards/hive-sdk";

const client = new JourneyHiveClient({
  apiKey: "jh_live_...",
});

// Send a message (uses default controller agent if configured)
const response = await client.responses.create({
  input: "What rooms are available tonight?",
});

console.log(response.output[0].content[0]);
```

## Configuration

```typescript
const client = new JourneyHiveClient({
  apiKey: "jh_live_...",
  baseUrl: "https://your-instance.replit.app", // optional
  timeout: 30000,                               // optional, ms
  defaultAgentId: "uuid-of-your-agent",         // optional
  debug: true,                                  // optional, logs requests
});
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | required | Your API key (starts with `jh_live_` or `jh_test_`) |
| `baseUrl` | `string` | `https://journey-hive.replit.app` | API base URL |
| `timeout` | `number` | `30000` | Request timeout in milliseconds |
| `defaultAgentId` | `string` | `undefined` | Default agent ID for requests without `agent_id` |
| `debug` | `boolean` | `false` | Enable request/response logging |

## Sending Messages

### Synchronous

```typescript
const response = await client.responses.create({
  input: "Check me in to room 304",
  agent_id: "optional-if-default-configured",
});

console.log(response.output[0].content[0].text);
```

### Streaming (SSE)

```typescript
const stream = await client.responses.create({
  input: "Tell me about today's arrivals",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
  if (event.type === "response.completed") {
    console.log("\n\nTokens used:", event.usage.total_tokens);
  }
}
```

### With Conversation Context

```typescript
const conv = await client.conversations.create({});

const r1 = await client.responses.create({
  input: "I need to check in a guest",
  conversation_id: conv.id,
});

const r2 = await client.responses.create({
  input: "The guest name is John Smith, confirmation #12345",
  conversation_id: conv.id,
});
```

### Idempotency

```typescript
const response = await client.responses.create({
  input: "Process payment for room 304",
  idempotency_key: "payment-304-2024-01-15",
});
```

## Conversations

```typescript
// List conversations with cursor pagination
const list = await client.conversations.list({ limit: 20 });

if (list.has_more && list.next_cursor) {
  const next = await client.conversations.list({
    limit: 20,
    cursor: list.next_cursor,
  });
}

// Get conversation messages
const messages = await client.conversations.messages(conv.id);

// Close a conversation
await client.conversations.close(conv.id);
```

## Agents

```typescript
const agents = await client.agents.list();
const agent = await client.agents.get("agent-uuid");
```

## Usage & Analytics

```typescript
const usage = await client.usage.get(7);
console.log(`Total requests: ${usage.total_requests}`);
console.log(`Total tokens: ${usage.total_tokens}`);
```

## Error Handling

```typescript
import { JourneyHiveError, AuthenticationError, RateLimitError } from "@journeyrewards/hive-sdk";

try {
  await client.responses.create({ input: "Hello" });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("Rate limited, retrying...");
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (err instanceof JourneyHiveError) {
    console.log(`API Error: ${err.message} (${err.code})`);
  }
}
```

## Debug Mode

```typescript
const client = new JourneyHiveClient({
  apiKey: "jh_live_...",
  debug: true,
});

// Logs:
// [JourneyHive >>>] 2024-01-15T10:30:00.000Z POST /v1/responses { ... }
// [JourneyHive <<<] 200 /v1/responses [req_id: abc123]
```

## API Reference

| Method | HTTP | Description |
|--------|------|-------------|
| `responses.create(params)` | `POST /v1/responses` | Create a response (stream or sync) |
| `responses.get(id)` | `GET /v1/responses/:id` | Retrieve a response |
| `conversations.create(params)` | `POST /v1/conversations` | Create a conversation |
| `conversations.get(id)` | `GET /v1/conversations/:id` | Get conversation details |
| `conversations.list(params?)` | `GET /v1/conversations` | List conversations |
| `conversations.messages(id)` | `GET /v1/conversations/:id/messages` | Get conversation messages |
| `conversations.close(id)` | `DELETE /v1/conversations/:id` | Close a conversation |
| `agents.list()` | `GET /v1/agents` | List available agents |
| `agents.get(id)` | `GET /v1/agents/:id` | Get agent details |
| `agents.update(id, params)` | `PATCH /v1/agents/:id` | Update agent configuration |
| `usage.get(days?)` | `GET /v1/usage` | Get usage statistics |

## Stream Event Types

| Event Type | Description |
|------------|-------------|
| `response.created` | Response object created |
| `response.in_progress` | Agent is processing |
| `response.output_item.added` | New output item started |
| `response.output_text.delta` | Incremental text chunk |
| `response.output_text.done` | Full text output complete |
| `response.content_part.done` | Content part finalized |
| `response.output_item.done` | Output item finalized |
| `response.completed` | Response fully complete with usage |
| `response.failed` | Response generation failed |

## License

MIT