rehive

Rehive SDK

A modern, fully typed TypeScript SDK for the Rehive platform and extension APIs. Tree-shakeable modular imports, shared authentication, and full autocomplete on every method.

Note: This is version 4 of the Rehive JavaScript SDK -- a major rewrite with a modular architecture. For v3, see the v3 branch. For v2, see the v2 branch.

Installation

npm install rehive

Quick Start

Modular API

Import only what you need. Each module is tree-shakeable and fully typed.

import { createAuth } from "rehive/auth";
import { createUserApi } from "rehive/user";
import { createAdminApi } from "rehive/admin";
import { createConversionApi } from "rehive/extensions/conversion";

// Create a shared auth instance
const auth = createAuth({
  baseUrl: "https://api.rehive.com",
  storage: "local",           // "local" | "memory" | custom StorageAdapter
});

// Create API instances -- each uses auth.getToken() automatically
const user = createUserApi({ auth });
const admin = createAdminApi({ auth });
const conversion = createConversionApi({ auth });

// Authenticate
await auth.login({ user: "[e-mail]", password: "pass", company: "myco" });

// All APIs are now authenticated -- full autocomplete on every method
await user.userRetrieve();
await admin.adminUsersList({});
await conversion.userConversionPairsList({});

// Logout
await auth.logout();

Server-side with permanent token

import { createAuth } from "rehive/auth";
import { createAdminApi } from "rehive/admin";

const auth = createAuth({ token: "your-permanent-admin-token" });
const admin = createAdminApi({ auth });

await admin.adminUsersCreate({ body: { email: "[e-mail]" } });

Authenticated Fetch (for custom endpoints)

For API endpoints not covered by the generated SDK, use createAuthenticatedFetch to get a fetch function that automatically injects the auth token:

import { createAuth } from "rehive/auth";
import { createAuthenticatedFetch } from "rehive";

const auth = createAuth({ storage: "local" });
await auth.login({ user: "[e-mail]", password: "pass", company: "myco" });

// Create an authenticated fetch -- handles token refresh automatically
const authFetch = createAuthenticatedFetch(auth);

// Use it like regular fetch, but with auth headers injected
const response = await authFetch("https://example.services.rehive.com/api/custom-endpoint/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: { /* ... */ } }),
});
const data = await response.json();

React Integration

For a complete working example, see the interactive demo.

import { AuthProvider, useAuth } from "rehive/react";

function App() {
  return (
    <AuthProvider config={{ baseUrl: "https://api.rehive.com", storage: "local" }}>
      <Dashboard />
    </AuthProvider>
  );
}

function Dashboard() {
  const { authUser, authLoading, login, logout, auth } = useAuth();

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

  if (!authUser) {
    return (
      <button onClick={() => login({ user: "[e-mail]", password: "pass", company: "myco" })}>
        Login
      </button>
    );
  }

  return (
    <div>
      <p>Logged in as {authUser.user.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

The useAuth hook provides: authUser, authLoading, authError, login, register, registerCompany, logout, logoutAll, refresh, getSessions, switchToSession, clearAllSessions, deleteChallenge, and auth (the Auth instance for creating modular API clients).

Extension APIs

All 15 extension APIs follow the same pattern -- import the factory, pass auth, call methods:

import { createConversionApi } from "rehive/extensions/conversion";
import { createRewardsApi } from "rehive/extensions/rewards";
import { createStellarApi } from "rehive/extensions/stellar";
import { createProductsApi } from "rehive/extensions/products";
import { createNotificationsApi } from "rehive/extensions/notifications";
import { createMassSendApi } from "rehive/extensions/mass-send";
import { createStellarTestnetApi } from "rehive/extensions/stellar-testnet";
import { createBusinessApi } from "rehive/extensions/business";
import { createPaymentRequestsApi } from "rehive/extensions/payment-requests";
import { createBridgeApi } from "rehive/extensions/bridge";
import { createAppApi } from "rehive/extensions/app";
import { createBillingApi } from "rehive/extensions/billing";
import { createBuilderApi } from "rehive/extensions/builder";
import { createRainApi } from "rehive/extensions/rain";
import { createAlchemyApi } from "rehive/extensions/alchemy";

const conversion = createConversionApi({ auth });
const rewards = createRewardsApi({ auth });
const stellar = createStellarApi({ auth });

// Each uses its default production base URL, or pass a custom one:
const conversionStaging = createConversionApi({
  auth,
  baseUrl: "https://staging-conversion.services.rehive.com/api/",
});

Extension	Default Base URL
Conversion	https://conversion.services.rehive.com/api/
Mass Send	https://mass-send.services.rehive.com/api/
Notifications	https://notification.services.rehive.com/api/
Products	https://product.services.rehive.com/api/
Rewards	https://reward.services.rehive.com/api/
Stellar	https://stellar.services.rehive.com/api/
Stellar Testnet	https://stellar-testnet.services.rehive.com/api/
Business	https://business.services.rehive.com/api/
Payment Requests	https://payment-requests.services.rehive.com/api/
Bridge	https://bridge.services.rehive.com/api/
App	https://app.services.rehive.com/api/
Billing	https://billing.services.rehive.com/api/
Builder	https://builder.services.rehive.com/api/
Rain	https://rain.services.rehive.com/api/
Alchemy	https://alchemy.services.rehive.com/api/

Error Handling

The SDK throws ApiError on non-200 responses:

import { ApiError } from "rehive";

try {
  await user.userRetrieve();
} catch (error) {
  if (error instanceof ApiError) {
    console.log("Status:", error.status);    // 401, 400, 500, etc.
    console.log("Message:", error.message);  // Human-readable message
    console.log("Details:", error.error);    // Full API error response
  }
}

Subscribe to auth errors for global handling:

const unsubscribe = auth.subscribeToErrors((error) => {
  if (error) {
    console.error("Auth error:", error.message);
  }
});

Multi-Session Support

The auth module supports multiple concurrent sessions across different companies:

// Login to multiple companies
await auth.login({ user: "[e-mail]", password: "pass", company: "company-one" });
await auth.login({ user: "[e-mail]", password: "pass", company: "company-two" });

// List and switch sessions
const sessions = auth.getSessions();                        // All sessions
const filtered = auth.getSessionsByCompany("company-one");  // By company
await auth.switchToSession("user-id", "company-two");       // Switch active

// Cleanup
await auth.clearAllSessions();  // Local only
await auth.logoutAll();         // Invalidates tokens on server

Storage Options

import { createAuth } from "rehive/auth";
import { WebStorageAdapter, MemoryStorageAdapter, AsyncStorageAdapter } from "rehive";

// localStorage (default in browser, auto-detected)
const auth = createAuth({ storage: "local" });

// In-memory (not persisted -- good for tests)
const auth = createAuth({ storage: "memory" });

// Custom adapter (e.g. React Native AsyncStorage)
import AsyncStorage from "@react-native-async-storage/async-storage";
const auth = createAuth({ storage: new AsyncStorageAdapter(AsyncStorage) });

// Or implement your own StorageAdapter
const auth = createAuth({
  storage: {
    getItem: async (key) => { /* ... */ },
    setItem: async (key, value) => { /* ... */ },
    removeItem: async (key) => { /* ... */ },
  },
});

Auth Configuration

import { createAuth, type AuthConfig } from "rehive/auth";

const auth = createAuth({
  baseUrl: "https://api.rehive.com",    // API base URL (default: https://api.rehive.com)
  storage: "local",                     // Storage adapter or shorthand
  token: "permanent-token",             // Server-side permanent token
  enableCrossTabSync: true,             // Sync auth across browser tabs (default: true)
});

Architecture

rehive/
├── rehive/auth           → createAuth()
├── rehive/user           → createUserApi()
├── rehive/admin          → createAdminApi()
├── rehive/extensions/*   → create*Api() for each extension
├── rehive/react          → AuthProvider, useAuth
└── rehive                → re-exports + utilities

Each module is a separate entry point with its own bundle. Import only the factories you need for optimal tree-shaking.

How it works

• createAuth() manages sessions, tokens, and refresh internally using its own openapi-ts client
• Each API factory (createUserApi, createAdminApi, etc.) creates an openapi-ts client configured with auth: () => auth.getToken()
• bindSdk() injects the client into every generated SDK function, preserving full type safety
• All methods use v4 structured parameters: { query, body, path }

Available APIs

API	Import	Methods
Platform User	rehive/user	203
Platform Admin	rehive/admin	360
Conversion	rehive/extensions/conversion	60
Mass Send	rehive/extensions/mass-send	18
Notifications	rehive/extensions/notifications	37
Products	rehive/extensions/products	241
Rewards	rehive/extensions/rewards	30
Stellar	rehive/extensions/stellar	101
Stellar Testnet	rehive/extensions/stellar-testnet	101
Business	rehive/extensions/business	84
Payment Requests	rehive/extensions/payment-requests	77
Bridge	rehive/extensions/bridge	27
App	rehive/extensions/app	46
Billing	rehive/extensions/billing	13
Builder	rehive/extensions/builder	5
Rain	rehive/extensions/rain	26
Alchemy	rehive/extensions/alchemy	20

Total: 1,449 typed API methods across platform and extensions

Development

# Build
npm run build

# Type check
npm run typecheck

# Run tests
npm test

# Regenerate API clients from OpenAPI specs
npm run codegen:openapi-ts

See CODEGEN.md for the full code generation workflow.

License

MIT License