rehive

Rehive SDK

A modern TypeScript SDK for the Rehive platform and extension APIs, providing a unified interface for both server-side and client-side usage.

Note: This is version 3 of the Rehive JavaScript SDK. For the previous version (v2) documentation, please refer to the v2 branch.

Installation

npm install rehive

Quick Start

Server-side Usage (Permanent Token)

Perfect for backend services, webhooks, and admin operations:

import { RehiveClient } from 'rehive';

// Initialize with permanent token (baseUrl defaults to https://api.rehive.com)
const rehive = new RehiveClient({
  token: 'your-permanent-admin-token'
});

// Or explicitly specify the baseUrl
const rehive = new RehiveClient({
  baseUrl: 'https://api.rehive.com',
  token: 'your-permanent-admin-token'
});

// Direct API access - no initialization needed
await rehive.admin.adminUsersCreate({
  email: '[e-mail]',
  first_name: 'John',
  last_name: 'Doe'
});

// User API with admin token (for impersonation)
const userProfile = await rehive.user.userRetrieve();

Client-side Usage (Authentication Flows)

Perfect for web and mobile applications:

import { RehiveClient } from 'rehive';

// Initialize without token (baseUrl defaults to https://api.rehive.com)
const rehive = new RehiveClient();

// Or explicitly specify the baseUrl
const rehive = new RehiveClient({
  baseUrl: 'https://api.rehive.com'
});

// Authentication flows
await rehive.auth.login({
  user: '[e-mail]',
  password: 'secure-password',
  company: 'your-company'
});

// Now all APIs are automatically authenticated
const profile = await rehive.user.userRetrieve();
const accounts = await rehive.user.userAccountsList({});

// Logout when done
await rehive.auth.logout();

React Integration

For a complete working example, see the interactive demo.

import { useState } from 'react';
import { AuthProvider, useAuth } from 'rehive/react';

function App() {
  return (
    <AuthProvider config={{ baseUrl: 'https://api.rehive.com' }}>
      <UserDashboard />
    </AuthProvider>
  );
}

function UserDashboard() {
  const { login, logout, session, loading, rehive } = useAuth();
  const [userDetails, setUserDetails] = useState(null);
  const [isLoadingDetails, setIsLoadingDetails] = useState(false);

  const handleLogin = async () => {
    await login({
      user: '[e-mail]',
      password: 'password',
      company: 'my-company'
    });
  };

  const fetchUserDetails = async () => {
    setIsLoadingDetails(true);
    try {
      const response = await rehive.user.userRetrieve();
      setUserDetails(response.data);
    } catch (error) {
      console.error('Failed to fetch user details:', error);
    } finally {
      setIsLoadingDetails(false);
    }
  };

  if (loading) return <div>Loading...</div>;

  if (!session) {
    return <button onClick={handleLogin}>Login</button>;
  }

  return (
    <div>
      <h2>Welcome, {session.user.email}</h2>
      <button onClick={logout}>Logout</button>
      
      <div>
        <button onClick={fetchUserDetails} disabled={isLoadingDetails}>
          {isLoadingDetails ? 'Loading...' : 'Fetch User Details'}
        </button>
        
        {userDetails && (
          <div>
            <h3>User Details</h3>
            <p>ID: {userDetails.id}</p>
            <p>Name: {userDetails.first_name} {userDetails.last_name}</p>
            <p>Status: {userDetails.status}</p>
            <p>Verified: {userDetails.verified ? 'Yes' : 'No'}</p>
          </div>
        )}
      </div>
    </div>
  );
}

Extension APIs

All extension APIs work the same way with automatic token synchronization:

// All extensions work the same way - no imports needed
const conversion = rehive.extensions.conversion();
await conversion.user.userConversionPairsList({});
await conversion.admin.adminConversionRatesList({});

const rewards = rehive.extensions.rewards();
await rewards.user.userRewardsList({});

const products = rehive.extensions.products();
await products.user.userProductsList({});

const notifications = rehive.extensions.notifications();
await notifications.user.userNotificationsList({});

const app = rehive.extensions.app();
await app.user.userAppsRetrieve({});

// Custom environment URLs (same pattern for all extensions)
const stagingConversion = rehive.extensions.conversion({
  baseUrl: 'https://onversion.services.rehive.com/api/'
});

const stagingRewards = rehive.extensions.rewards({
  baseUrl: 'https://rewards.services.rehive.com/api/'
});

Custom Extensions and Ad-hoc API Calls

For custom extensions or one-off API calls, use the authenticated fetch method:

// GET request to custom extension
const response = await rehive.extensions.fetch('https://my-custom.services.rehive.com/api/users');
const users = await response.json();

// POST request with data
const response = await rehive.extensions.fetch('https://my-custom.services.rehive.com/api/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ product_id: 123, quantity: 2 })
});

// Works with any HTTP endpoint - automatically handles authentication
const response = await rehive.extensions.fetch('https://api.external-service.com/data', {
  method: 'GET',
  headers: { 'X-Custom-Header': 'value' }
});

Key Benefits:

• Automatic authentication: Attaches current user token to requests
• Token refresh: Automatically refreshes expired tokens
• Works anywhere: Use with any HTTP endpoint, not just Rehive services
• Standard fetch API: Same interface as native fetch() with auth handling

API Responses and Error Handling

Response Structure

All API methods return responses in a consistent format that matches the Rehive API structure:

// API responses have a standard structure
const user = await rehive.user.authRetrieve();
console.log(user.data.email); // Access user data

const accounts = await rehive.user.userAccountsList({});
console.log(accounts.data.results); // Access account list

Response Format:

{
  status: "success",
  data: {
    // Your actual data here
    id: "user-id",
    email: "[e-mail]",
    // ... other properties
  }
}

Error Handling

The SDK provides error handling through the ApiError class:

import { RehiveClient, ApiError } from 'rehive';

try {
  const user = await rehive.user.authRetrieve();
  console.log('User:', user.data.email);
} catch (error) {
  if (error instanceof ApiError) {
    // Structured API errors from Rehive
    console.log('Status Code:', error.status);        // 401, 400, 500, etc.
    console.log('Error Message:', error.message);     // Human-readable message
    console.log('Error Details:', error.error);       // Full API error response
    
    // Handle specific error types
    switch (error.status) {
      case 401:
        console.log('Authentication required');
        // Redirect to login
        break;
      case 400:
        console.log('Bad request:', error.error.data);
        // Show validation errors
        break;
      case 429:
        console.log('Rate limited - retry later');
        break;
      default:
        console.log('API error:', error.message);
    }
  } else {
    // Network errors, timeouts, etc.
    console.error('Network error:', error.message);
  }
}

Common Error Scenarios:

Status Code	Description	Common Causes
400	Bad Request	Missing required fields, invalid data format
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions for the operation
404	Not Found	Resource doesn't exist or user lacks access
429	Rate Limited	Too many requests - implement retry logic
500	Server Error	Internal server error - retry or contact support

Error Response Structure:

// ApiError properties
{
  status: 400,                    // HTTP status code
  message: "Validation failed",   // Human-readable message
  error: {                        // Full API response
    status: "error",
    message: "Validation failed",
    data: {
      email: ["This field is required"],
      password: ["Password too short"]
    }
  }
}

Authentication Error Handling

The SDK provides specialized handlers for authentication flows:

// Subscribe to authentication errors
const unsubscribe = rehive.auth.subscribeToErrors((error) => {
  if (error) {
    console.error('Auth error:', error.message);
    
    // Handle different auth error types
    if (error.status === 401) {
      // Token expired or invalid
      window.location.href = '/login';
    } else if (error.status === 400) {
      // Invalid credentials
      showErrorMessage('Invalid email or password');
    }
  }
});

// Subscribe to session changes
const unsubscribeSession = rehive.auth.subscribeToSession((session) => {
  if (session) {
    console.log('User logged in:', session.user.email);
    // Update UI for authenticated state
  } else {
    console.log('User logged out');
    // Update UI for unauthenticated state
  }
});

// Clean up subscriptions
unsubscribe();
unsubscribeSession();

Key Features

✅ Smart Token Management

• Automatic refresh: Tokens refresh 30 seconds before expiration
• Cross-API sync: All API instances share the same authentication state
• Persistent sessions: Authentication survives page reloads
• Cross-tab sync: Authentication state syncs across browser tabs

✅ Extension Integration

• Factory methods: Built-in methods for all Rehive extensions
• Default URLs: Production URLs configured by default
• Environment flexibility: Easy to override for staging/development
• Same DX: Extensions get the same token management and response unwrapping

Architecture

The SDK includes multiple API clients generated from swagger specifications:

src/
├── platform/
│   ├── user/           # Platform User API (203 methods)
│   └── admin/          # Platform Admin API (360 methods)
├── extensions/         # Service Extensions
│   ├── conversion/     # 60 methods
│   ├── mass-send/      # 18 methods
│   ├── notifications/  # 37 methods
│   ├── products/       # 241 methods
│   ├── rewards/        # 30 methods
│   ├── stellar/        # 101 methods
│   ├── stellar-testnet/# 101 methods
│   ├── business/       # 84 methods
│   ├── payment-requests/# 77 methods
│   ├── bridge/         # 27 methods
│   └── app/            # 46 methods
├── shared/
│   └── http-client.ts  # Shared/customized HTTP client
└── auth/              # Auth functionality using Platform User API

Available APIs

API	Client Name	Methods	Documentation
Platform User API	platform-user-api	203	Methods
Platform Admin API	platform-admin-api	360	Methods
Conversion Extension	conversion-api	60	Methods
Mass Send Extension	mass-send-api	18	Methods
Notifications Extension	notifications-api	37	Methods
Products Extension	products-api	241	Methods
Rewards Extension	rewards-api	30	Methods
Stellar Extension	stellar-api	101	Methods
Stellar Testnet Extension	stellar-testnet-api	101	Methods
Business Extension	business-api	84	Methods
Payment Requests Extension	payment-requests-api	77	Methods
Bridge Extension	bridge-api	27	Methods
App Extension	app-api	46	Methods

Total: 1,385 API methods across platform and extensions

📋 View complete API overview

Advanced Usage

Error Handling

// Subscribe to auth errors
const unsubscribe = rehive.auth.subscribeToErrors((error) => {
  if (error) {
    console.error('Auth error:', error.message);
    // Handle login redirect, show error message, etc.
  }
});

// Subscribe to session changes
const unsubscribeSession = rehive.auth.subscribeToSession((session) => {
  if (session) {
    console.log('User logged in:', session.user.email);
  } else {
    console.log('User logged out');
  }
});

Custom Storage

import { RehiveClient, MemoryStorageAdapter } from 'rehive';

const rehive = new RehiveClient({
  baseUrl: 'https://api.rehive.com',
  storage: new MemoryStorageAdapter(), // Won't persist across page reloads
  enableCrossTabSync: false // Disable cross-tab synchronization
});

TypeScript Support

The SDK is fully typed with TypeScript support:

import { RehiveClient, type RehiveConfig, type UserSession } from 'rehive';

const config: RehiveConfig = {
  baseUrl: 'https://api.rehive.com',
  token: 'optional-permanent-token'
};

const rehive = new RehiveClient(config);

// Full type safety on all API methods
const session: UserSession = await rehive.auth.login({
  user: '[e-mail]',
  password: 'password',
  company: 'company-name'
});

Development

Building the SDK

npm run build

Updating API Clients

The SDK uses generated API clients from swagger specifications. To update them:

# Extract current API methods for reference
node scripts/extract-api-methods.js

# Follow the code generation workflow

📖 Complete code generation guide

Testing

npm run dev

Documentation

• API Methods Overview - Complete list of all available API methods
• Code Generation Workflow - How to update generated API clients
• Individual API Documentation - Detailed method lists for each API in docs/api-methods/

License

MIT License

---

This modern SDK design follows current best practices and provides a clean, intuitive developer experience for both server-side and client-side usage.