npm package: @journeyrewards/hive-react-native
Description: React Native SDK for Journey Hive Agent Orchestration
Latest version: 1.2.1

# @journeyrewards/hive-react-native

React Native SDK for the Journey Hive Agent Orchestration API. Provides hooks, streaming support, and offline capabilities for building AI-powered mobile applications.

## Installation

### Expo

```bash
npx expo install @journeyrewards/hive-react-native
```

### Bare React Native

```bash
npm install @journeyrewards/hive-react-native
```

No native module linking is required. The SDK uses pure JavaScript with React Native-compatible fetch APIs.

## Quick Start

### Provider Setup

Wrap your app with `JourneyHiveProvider`:

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

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

### Streaming Chat Example

```tsx
import { View, Text, TextInput, TouchableOpacity } from 'react-native';
import { useResponse } from '@journeyrewards/hive-react-native';
import { useState } from 'react';

function ChatScreen() {
  const [input, setInput] = useState('');
  const { streamedText, isStreaming, isLoading, error, send } = useResponse({
    agent_id: 'your-agent-id',
  });

  const handleSend = () => {
    if (input.trim()) {
      send(input.trim());
      setInput('');
    }
  };

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <View style={{ flex: 1 }}>
        {streamedText ? <Text>{streamedText}</Text> : null}
        {isLoading && !isStreaming ? <Text>Loading...</Text> : null}
        {error ? <Text style={{ color: 'red' }}>{error.message}</Text> : null}
      </View>
      <View style={{ flexDirection: 'row', gap: 8 }}>
        <TextInput
          value={input}
          onChangeText={setInput}
          placeholder="Type a message..."
          style={{ flex: 1, borderWidth: 1, borderColor: '#ccc', padding: 8, borderRadius: 8 }}
        />
        <TouchableOpacity onPress={handleSend} style={{ padding: 12, backgroundColor: '#007AFF', borderRadius: 8 }}>
          <Text style={{ color: 'white' }}>Send</Text>
        </TouchableOpacity>
      </View>
    </View>
  );
}
```

### Conversation View

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

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

  return (
    <View style={{ flex: 1 }}>
      <FlatList
        data={messages}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => (
          <View style={{ padding: 8 }}>
            <Text style={{ fontWeight: 'bold' }}>{item.role}</Text>
            <Text>{item.content[0]?.text}</Text>
          </View>
        )}
      />
      <ChatInput onSend={sendMessage} />
    </View>
  );
}
```

### Agent Management

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

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

  if (isLoading) return <ActivityIndicator />;

  return (
    <FlatList
      data={agents}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <Text>{item.name} - {item.status}</Text>}
    />
  );
}
```

## Offline Support

The SDK automatically queues messages when the device is offline and sends them when connectivity is restored.

### Connection Status Hook

```tsx
import { useConnectionStatus } from '@journeyrewards/hive-react-native';

function ConnectionBanner() {
  const { isConnected } = useConnectionStatus();

  if (isConnected) return null;

  return (
    <View style={{ backgroundColor: '#f59e0b', padding: 8 }}>
      <Text style={{ textAlign: 'center', color: 'white' }}>
        You are offline. Messages will be sent when connected.
      </Text>
    </View>
  );
}
```

### Manual Connection Management

If you use `@react-native-community/netinfo`, connect it to the client:

```tsx
import NetInfo from '@react-native-community/netinfo';
import { useJourneyHive } from '@journeyrewards/hive-react-native';
import { useEffect } from 'react';

function NetworkSync() {
  const client = useJourneyHive();

  useEffect(() => {
    const unsubscribe = NetInfo.addEventListener((state) => {
      client.setConnectionStatus(!!state.isConnected);
    });
    return unsubscribe;
  }, [client]);

  return null;
}
```

### App Lifecycle

Connect app state changes to pause/resume operations:

```tsx
import { AppState } from 'react-native';
import { useJourneyHive } from '@journeyrewards/hive-react-native';
import { useEffect } from 'react';

function AppLifecycle() {
  const client = useJourneyHive();

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (state) => {
      client.setAppState(state);
    });
    return () => subscription.remove();
  }, [client]);

  return null;
}
```

## Direct Client Usage

For non-hook scenarios (background tasks, services):

```tsx
import { JourneyHiveRNClient } from '@journeyrewards/hive-react-native';

const client = new JourneyHiveRNClient({
  apiKey: 'jh_live_...',
  baseUrl: 'https://your-api.com',
});

const agents = await client.listAgents();
const response = await client.createResponse({
  agent_id: 'agent-id',
  input: 'Hello!',
});
```

## Expo Compatibility

This SDK is fully compatible with Expo (SDK 49+). No native modules or custom dev clients are required. It uses:

- Standard `fetch` API (available in all React Native environments)
- `ReadableStream` for SSE parsing (supported in Hermes engine)
- No native dependencies

For Expo Go, the SDK works out of the box with no additional configuration.

## API Reference

### Hooks

| Hook | Returns | Description |
|------|---------|-------------|
| `useJourneyHive()` | `JourneyHiveRNClient` | Access the client instance |
| `useResponse(params?)` | `{ data, isLoading, isStreaming, streamedText, error, send }` | Streaming responses |
| `useConversation(id)` | `{ conversation, messages, isLoading, error, sendMessage }` | Manage conversations |
| `useAgent(id)` | `{ agent, isLoading, error, update }` | Fetch/update an agent |
| `useAgents()` | `{ agents, isLoading, error }` | List agents |
| `useConnectionStatus()` | `{ isConnected }` | Track connectivity |

### Client Methods

| Method | Description |
|--------|-------------|
| `createResponse(params)` | Send a message to an agent |
| `createStreamingResponse(params)` | Stream a response (async generator) |
| `getAgent(id)` | Get agent details |
| `listAgents()` | List available agents |
| `updateAgent(id, params)` | Update agent configuration |
| `createConversation(params)` | Start a new conversation |
| `getConversation(id)` | Get conversation details |
| `getMessages(id)` | Get conversation messages |
| `setConnectionStatus(bool)` | Update connectivity state |
| `setAppState(state)` | Update app lifecycle state |

## License

MIT