@journeyrewards/hive-sdk

TypeScript SDK for the Journey Hive Agent Orchestration API.

Installation

npm install @journeyrewards/hive-sdk

Quick Start

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

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

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)

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

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

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

Conversations

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

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

Usage & Analytics

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

Error Handling

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

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