npm package: @journeyrewards/hive-vercel
Description: Vercel/Next.js SDK for Journey Hive Agent Orchestration
Latest version: 1.2.1

# @journeyrewards/hive-vercel

Vercel/Next.js SDK for the Journey Hive Agent Orchestration API. Provides React hooks, ready-to-use components, and server-side helpers for building AI-powered applications with Next.js.

## Installation

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

## Quick Start

### Provider Setup

Wrap your application with `JourneyHiveProvider`:

```tsx
import { JourneyHiveProvider } from '@journeyrewards/hive-vercel';

export default function App({ children }) {
  return (
    <JourneyHiveProvider apiKey="jh_live_..." baseUrl="https://your-api.com">
      {children}
    </JourneyHiveProvider>
  );
}
```

### Streaming Responses with `useResponse`

```tsx
import { useResponse } from '@journeyrewards/hive-vercel';

function ChatInput() {
  const { streamedText, isStreaming, isLoading, error, send } = useResponse({
    agent_id: 'your-agent-id',
  });

  return (
    <div>
      <button onClick={() => send('Hello, agent!')}>Send</button>
      {isLoading && <p>Loading...</p>}
      {isStreaming && <p>Streaming: {streamedText}</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}
```

### Chat Interface with `useConversation`

```tsx
import { useConversation } from '@journeyrewards/hive-vercel';

function Chat({ conversationId }) {
  const { messages, isLoading, sendMessage } = useConversation(conversationId);

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content[0]?.text}
        </div>
      ))}
      <button onClick={() => sendMessage('Hello!')}>Send</button>
    </div>
  );
}
```

### Agent Management

```tsx
import { useAgent, useAgents } from '@journeyrewards/hive-vercel';

function AgentList() {
  const { agents, isLoading } = useAgents();

  if (isLoading) return <p>Loading agents...</p>;
  return agents.map((a) => <div key={a.id}>{a.name}</div>);
}

function AgentDetail({ id }) {
  const { agent, update } = useAgent(id);

  return (
    <div>
      <h1>{agent?.name}</h1>
      <button onClick={() => update({ personality_notes: 'Be friendly' })}>
        Update
      </button>
    </div>
  );
}
```

## Server-Side Usage

### API Route Handler

Create a Next.js API route that proxies requests to Journey Hive:

```ts
// pages/api/journey-hive.ts
import { createJourneyHiveHandler } from '@journeyrewards/hive-vercel/server';

export default createJourneyHiveHandler({
  apiKey: process.env.JOURNEY_HIVE_API_KEY!,
  baseUrl: process.env.JOURNEY_HIVE_BASE_URL,
  allowedAgentIds: ['agent-1', 'agent-2'],
});
```

### Server Client

```ts
import { JourneyHiveServerClient } from '@journeyrewards/hive-vercel/server';

const client = new JourneyHiveServerClient({
  apiKey: process.env.JOURNEY_HIVE_API_KEY!,
});

// In getServerSideProps or API routes
const agents = await client.listAgents();
const response = await client.createResponse({
  agent_id: 'your-agent-id',
  input: 'Hello!',
});
```

### API Key Validation

```ts
import { verifyApiKey } from '@journeyrewards/hive-vercel/server';

if (!verifyApiKey(apiKey)) {
  throw new Error('Invalid API key format');
}
```

## Components

### ResponseStream

Renders streaming text with a typing indicator:

```tsx
import { ResponseStream } from '@journeyrewards/hive-vercel';

<ResponseStream
  agentId="your-agent-id"
  input="Tell me a story"
  onComplete={(text) => console.log('Done:', text)}
  className="my-stream"
/>
```

### ConversationView

Full conversation interface with message history and input:

```tsx
import { ConversationView } from '@journeyrewards/hive-vercel';

<ConversationView
  conversationId="conv-123"
  className="my-chat"
/>
```

### MessageBubble

Single message display:

```tsx
import { MessageBubble } from '@journeyrewards/hive-vercel';

<MessageBubble role="user" content="Hello!" timestamp={1700000000} />
<MessageBubble role="assistant" content="Hi there!" />
```

### AgentStatus

Agent status badge:

```tsx
import { AgentStatus } from '@journeyrewards/hive-vercel';

<AgentStatus agent={agent} />
```

## API Reference

### Hooks

| Hook | Returns | Description |
|------|---------|-------------|
| `useJourneyHive()` | `client` | Access the Journey Hive client instance |
| `useResponse(params?)` | `{ data, isLoading, isStreaming, streamedText, error, send }` | Send messages with streaming support |
| `useConversation(id)` | `{ conversation, messages, isLoading, error, sendMessage }` | Manage a conversation |
| `useAgent(id)` | `{ agent, isLoading, error, update }` | Fetch and update an agent |
| `useAgents()` | `{ agents, isLoading, error }` | List all available agents |

### Server Exports

| Export | Description |
|--------|-------------|
| `createJourneyHiveHandler(config)` | Creates a Next.js API route handler |
| `JourneyHiveServerClient` | Server-side API client (no React) |
| `verifyApiKey(key)` | Validates API key format |

## License

MIT