@hyperyai/sdk

Drop-in authentication, checkout and error handling for React apps built on Hypery. Sign users in with OAuth 2.0 + PKCE, call AI models on their behalf, charge them (one-off purchases, credit top-ups, subscriptions) and resolve billing/auth errors with ready-made UI.

Installation

npm install @hyperyai/sdk

Peer dependencies: react and react-dom 18 or 19. The package ships compiled JavaScript with type declarations (plus the TypeScript source under src/ for reference), so no transpilePackages or build configuration is needed. Components use Tailwind utility classes for their default styling.

Quick start

1. Wrap your app with HyperyProvider

import { HyperyProvider, HyperyModals } from '@hyperyai/sdk';

const config = {
  clientId: process.env.NEXT_PUBLIC_OAUTH_CLIENT_ID!,
  redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI!, // e.g. http://localhost:3000/callback
  gatewayUrl: 'https://hypery.ai',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <HyperyProvider config={config}>
      {children}
      <HyperyModals /> {/* auto-opens funds / re-auth modals */}
    </HyperyProvider>
  );
}

2. Gate UI on auth

import { SignedIn, SignedOut, SignIn, UserButton } from '@hyperyai/sdk';

export function Header() {
  return (
    <header>
      <SignedIn><UserButton showUserInfo /></SignedIn>
      <SignedOut><SignIn /></SignedOut>
    </header>
  );
}

3. Make authenticated requests

import { useAuth, useUser } from '@hyperyai/sdk';

function Dashboard() {
  const { user } = useUser();
  const { authenticatedFetch, gatewayUrl, logout } = useAuth();

  const ask = async () => {
    // Bearer token injected; 401 refreshes once; 402/429 opens <HyperyModals>
    const res = await authenticatedFetch(`${gatewayUrl}/api/v1/chat/completions`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ model: 'openai/gpt-4o-mini', messages: [{ role: 'user', content: 'Hi' }] }),
    });
    return res.json();
  };

  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={ask}>Ask</button>
      <button onClick={logout}>Sign out</button>
    </div>
  );
}

4. Charge users

import { BuyButton, SubscribeButton } from '@hyperyai/sdk';

<BuyButton appId="app_123" amountCents={499} description="Pro upgrade" />
<SubscribeButton planId="plan_123" priceCents={999} interval="month" />

Add billing:charge to config.scopes for checkout.

Documentation

| Guide | Covers | | --- | --- | | Provider and configuration | HyperyProvider, every HyperyAuthConfig option (scopes, storage, interactionMode, onUnauthorized, onRestricted), BrandingConfig, the context value | | Components | SignIn, SignUp, SignInForm, AuthButton, AuthModal, ModernAuthForm, UserButton, UserProfile, WorkspaceSwitcher, SignedIn, SignedOut, RedirectToSignIn, Protect (with screenshots) | | Hooks | useAuth, useHyperyAuth, useUser, useMemberships, useActiveWorkspace, setActiveWorkspace, useWallet, useBuyerWallet, useError | | Checkout | BuyButton, SubscribeButton, useCheckout, useMarketplace, useAppSubscription, planPriceCents, popup vs redirect, annual billing | | Errors | Error codes, parseError and the is*Error guards, formatTimeUntilReset, HyperyModals, RestrictionModal, SpendingLimitAlert, InsufficientCreditsAlert, ErrorBoundary | | Streaming | consumeSSEStream, parseSSEFrame, parseSSEError | | Advanced | TokenStorage, getAuthorizationUrl, exchangeCodeForToken, refreshAccessToken, getUserInfo | | Type reference | Every exported type, grouped |

Feature map

• Auth: OAuth 2.0 + PKCE, redirect or popup login, single-flight token refresh, configurable token storage.
• Workspaces: list teams/workspaces and switch the active one (WorkspaceSwitcher).
• AI credits: mode-aware wallet (useWallet) with 1-click top-ups and card setup.
• Checkout: log in, charge, add a card and retry in one call, as popups or redirects (useCheckout).
• Subscriptions: sell your app's plans with monthly or annual billing and expiring app-scoped credit grants (useAppSubscription).
• Errors: one classified ParsedError for HTTP and streaming failures, plus turnkey modals.

Local development against this repo

To develop @hyperyai/sdk alongside a consuming app, use yalc (npm link duplicates React and breaks hooks):

# in hypery-sdk
npm i -g yalc
yalc publish            # builds via prepack and stores the real pack output
# in your app
yalc add @hyperyai/sdk && npm install

# iterate: rebuild + push updates into consumers
yalc push               # in hypery-sdk, after changes

# before committing your app
yalc remove --all && npm install

Checks: npx tsc --noEmit, npm run build, bun test src. The test suite includes a guard that fails when a public export is not documented in docs/*.md.

Examples

Working apps live in hypery-examples.

License

MIT