SDK REFERENCE

React Components & Hooks

Official React context provider, authentication hooks, and declarative RBAC permission gates for seamless integration with React, Next.js, and Remix applications.

Installation

Install the zero-dependency SDK package via npm or pnpm:

bash
npm install @hvt/sdk

1. Provider Setup

Wrap your application root with <HVTProvider> and pass a configured HVTClient instance:

tsx
import React from 'react';
import { HVTClient } from '@hvt/sdk';
import { HVTProvider } from '@hvt/sdk/react';

const hvt = new HVTClient({
  baseUrl: 'https://api.hvts.app',
  apiKey: 'hvt_live_...', // Your project runtime API key
});

export function App({ children }) {
  return (
    <HVTProvider client={hvt}>
      {children}
    </HVTProvider>
  );
}

2. The useHVTAuth Hook

Access authentication state, logged-in user profile, effective permissions, and auth methods anywhere in the component tree:

tsx
import { useHVTAuth } from '@hvt/sdk/react';

export function UserProfile() {
  const { user, session, isLoading, login, logout, hasPermission } = useHVTAuth();

  if (isLoading) return <p>Loading session...</p>;
  if (!user) return <button onClick={() => login({ email: '[email protected]', password: '...' })}>Sign In</button>;

  return (
    <div>
      <h3>Logged in as: {user.email}</h3>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

3. Declarative Permission Gating

Use <PermissionGate> to conditionally render UI controls based on project-scoped permission slugs:

tsx
import { PermissionGate } from '@hvt/sdk/react';

export function OrderPanel() {
  return (
    <div>
      <h2>Order Management</h2>

      {/* Renders only if user has orders.create */}
      <PermissionGate
        permission="orders.create"
        fallback={<p className="text-muted">You do not have permission to place orders.</p>}
      >
        <button onClick={handleCreateOrder}>Place New Order</button>
      </PermissionGate>

      {/* Renders if user has either of these permissions */}
      <PermissionGate anyOf={['orders.export', 'admin.manage']}>
        <button onClick={handleExportCSV}>Export Orders CSV</button>
      </PermissionGate>
    </div>
  );
}

4. Declarative Role Gating

Use <RoleGate> to gate sections based on project role assignments:

tsx
import { RoleGate } from '@hvt/sdk/react';

export function MerchantPortal() {
  return (
    <RoleGate role="seller" fallback={<p>Become a seller to view store analytics.</p>}>
      <StoreAnalyticsDashboard />
    </RoleGate>
  );
}