@journeyrewards/hive-sdk 1.0.0

package/README.md

@@ -0,0 +1,202 @@
+# @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

package/dist/index.d.mts

@@ -0,0 +1,273 @@
+interface JourneyHiveConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    defaultAgentId?: string;
+    debug?: boolean;
+}
+interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+}
+type ContentPart = {
+    type: "output_text";
+    text: string;
+} | {
+    type: "tool_use";
+    name: string;
+    arguments: Record<string, unknown>;
+};
+interface OutputItem {
+    id: string;
+    type: "message";
+    role: string;
+    content: ContentPart[];
+}
+interface Response {
+    id: string;
+    object: "response";
+    status: string;
+    agent_id: string;
+    conversation_id: string;
+    output: OutputItem[];
+    usage: Usage;
+    created_at: number;
+    metadata?: Record<string, unknown>;
+}
+interface Conversation {
+    id: string;
+    object: "conversation";
+    agent_id: string;
+    status: string;
+    channel: string;
+    external_user_id: string | null;
+    created_at: number;
+    updated_at: number;
+    metadata?: Record<string, unknown>;
+}
+interface Message {
+    id: string;
+    object: "message";
+    role: string;
+    content: ContentPart[];
+    created_at: number;
+    metadata?: Record<string, unknown>;
+}
+interface Agent {
+    id: string;
+    object: "agent";
+    name: string;
+    slug: string;
+    type: string;
+    status: string;
+    external_access: string;
+    model: string;
+    created_at: number;
+    metadata?: Record<string, unknown>;
+}
+interface ListResponse<T> {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string | null;
+}
+interface PaginationParams {
+    cursor?: string;
+    limit?: number;
+}
+interface InputItem {
+    role?: string;
+    content?: string;
+    text?: string;
+}
+interface CreateResponseParams {
+    agent_id?: string;
+    input: string | InputItem[];
+    conversation_id?: string;
+    stream?: boolean;
+    instructions?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+interface CreateConversationParams {
+    agent_id?: string;
+    external_user_id?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+interface UpdateAgentParams {
+    soul_template?: string;
+    personality_notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ListConversationsParams extends PaginationParams {
+    agent_id?: string;
+    status?: string;
+}
+interface ListAgentsParams extends PaginationParams {
+}
+interface ListMessagesParams extends PaginationParams {
+}
+interface UsageRequest {
+    endpoint: string;
+    method: string;
+    status_code: number;
+    tokens_used: number;
+    latency_ms: number;
+    created_at: number;
+}
+interface UsageSummary {
+    object: string;
+    period_days: number;
+    total_requests: number;
+    total_tokens: number;
+    avg_latency_ms: number;
+    recent_requests: UsageRequest[];
+}
+interface ResponseCreatedEvent {
+    type: "response.created";
+    id: string;
+    object: "response";
+    status: string;
+    agent_id: string;
+    conversation_id: string;
+    created_at: number;
+    output: OutputItem[];
+    usage: Usage | null;
+}
+interface ResponseInProgressEvent {
+    type: "response.in_progress";
+    message: string;
+}
+interface OutputItemAddedEvent {
+    type: "response.output_item.added";
+    output_index: number;
+    item: OutputItem;
+}
+interface OutputTextDeltaEvent {
+    type: "response.output_text.delta";
+    output_index: number;
+    content_index: number;
+    delta: string;
+}
+interface OutputTextDoneEvent {
+    type: "response.output_text.done";
+    output_index: number;
+    content_index: number;
+    text: string;
+}
+interface ContentPartDoneEvent {
+    type: "response.content_part.done";
+    output_index: number;
+    content_index: number;
+    part: ContentPart;
+}
+interface OutputItemDoneEvent {
+    type: "response.output_item.done";
+    output_index: number;
+    item: OutputItem;
+}
+interface ResponseCompletedEvent {
+    type: "response.completed";
+    id: string;
+    object: "response";
+    status: string;
+    agent_id: string;
+    conversation_id: string;
+    output: OutputItem[];
+    usage: Usage;
+    created_at: number;
+    metadata?: Record<string, unknown>;
+}
+interface ResponseFailedEvent {
+    type: "response.failed";
+    error: {
+        message: string;
+        type: string;
+        code: string;
+    };
+}
+type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | OutputItemAddedEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ContentPartDoneEvent | OutputItemDoneEvent | ResponseCompletedEvent | ResponseFailedEvent;
+
+declare class JourneyHiveClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private defaultAgentId?;
+    private debug;
+    responses: ResponsesAPI;
+    conversations: ConversationsAPI;
+    agents: AgentsAPI;
+    usage: UsageAPI;
+    constructor(config: JourneyHiveConfig);
+    getDefaultAgentId(): string | undefined;
+    private log;
+    _fetch(path: string, options?: RequestInit & {
+        retries?: number;
+        idempotencyKey?: string;
+    }): Promise<globalThis.Response>;
+}
+declare class ResponsesAPI {
+    private client;
+    constructor(client: JourneyHiveClient);
+    private resolveAgentId;
+    create(params: CreateResponseParams & {
+        stream: true;
+    }): Promise<AsyncGenerator<StreamEvent>>;
+    create(params: CreateResponseParams & {
+        stream?: false;
+    }): Promise<Response>;
+    create(params: CreateResponseParams): Promise<Response | AsyncGenerator<StreamEvent>>;
+    get(id: string): Promise<Response>;
+}
+declare class ConversationsAPI {
+    private client;
+    constructor(client: JourneyHiveClient);
+    private resolveAgentId;
+    create(params: CreateConversationParams): Promise<Conversation>;
+    get(id: string): Promise<Conversation>;
+    list(params?: ListConversationsParams): Promise<ListResponse<Conversation>>;
+    messages(id: string, params?: ListMessagesParams): Promise<ListResponse<Message>>;
+    close(id: string): Promise<void>;
+}
+declare class AgentsAPI {
+    private client;
+    constructor(client: JourneyHiveClient);
+    list(params?: ListAgentsParams): Promise<ListResponse<Agent>>;
+    get(id: string): Promise<Agent>;
+    update(id: string, params: UpdateAgentParams): Promise<Agent>;
+}
+declare class UsageAPI {
+    private client;
+    constructor(client: JourneyHiveClient);
+    get(days?: number): Promise<UsageSummary>;
+}
+
+declare class JourneyHiveError extends Error {
+    status: number;
+    type: string;
+    code: string;
+    constructor(status: number, type: string, code: string, message: string);
+}
+declare class AuthenticationError extends JourneyHiveError {
+    constructor(code: string, message: string);
+}
+declare class RateLimitError extends JourneyHiveError {
+    constructor(code: string, message: string);
+}
+declare class NotFoundError extends JourneyHiveError {
+    constructor(code: string, message: string);
+}
+declare class PermissionError extends JourneyHiveError {
+    constructor(code: string, message: string);
+}
+declare function parseErrorResponse(status: number, body: {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string;
+    };
+}): JourneyHiveError;
+
+export { type Agent, AuthenticationError, type ContentPart, type ContentPartDoneEvent, type Conversation, type CreateConversationParams, type CreateResponseParams, type InputItem, JourneyHiveClient, type JourneyHiveConfig, JourneyHiveError, type ListAgentsParams, type ListConversationsParams, type ListMessagesParams, type ListResponse, type Message, NotFoundError, type OutputItem, type OutputItemAddedEvent, type OutputItemDoneEvent, type OutputTextDeltaEvent, type OutputTextDoneEvent, type PaginationParams, PermissionError, RateLimitError, type Response, type ResponseCompletedEvent, type ResponseCreatedEvent, type ResponseFailedEvent, type ResponseInProgressEvent, type StreamEvent, type UpdateAgentParams, type Usage, type UsageRequest, type UsageSummary, parseErrorResponse };