@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

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

Quick Start

Provider Setup

Wrap your application with JourneyHiveProvider:

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

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

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

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:

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

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

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:

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:

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

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

MessageBubble

Single message display:

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

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

AgentStatus

Agent status badge:

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