@hyperyai/sdk 1.0.0

package/dist/hooks/useMemberships.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Memberships + active-workspace hooks for consumer apps.
+ *
+ * These power the <WorkspaceSwitcher /> component. They fetch the user's
+ * full team → workspace tree from the gateway and let the caller switch
+ * the active workspace. The active workspace is stored on the OAuth
+ * session server-side so it's persistent across page reloads + devices.
+ */
+export interface MembershipWorkspace {
+    id: string;
+    name: string;
+    slug: string;
+    isDefault: boolean;
+    icon: string | null;
+    role: 'owner' | 'admin' | 'developer' | 'viewer';
+    isActive: boolean;
+}
+export interface MembershipTeam {
+    id: string;
+    name: string;
+    slug: string;
+    isPersonal: boolean;
+    role: 'owner' | 'admin' | 'developer' | 'viewer';
+}
+export interface MembershipEntry {
+    team: MembershipTeam;
+    workspaces: MembershipWorkspace[];
+}
+export interface MembershipsResponse {
+    activeOrganizationId: string | null;
+    activeWorkspaceId: string | null;
+    memberships: MembershipEntry[];
+}
+interface MembershipsState {
+    data: MembershipsResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+}
+/**
+ * Hook: list every team + workspace the current user belongs to. Returns a
+ * flat memberships array that's easy to render in a switcher dropdown.
+ */
+export declare function useMemberships(): MembershipsState;
+export interface ActiveWorkspace {
+    teamId: string;
+    teamName: string;
+    workspaceId: string;
+    workspaceName: string;
+    role: 'owner' | 'admin' | 'developer' | 'viewer';
+}
+/**
+ * Hook: resolves the user's currently-active team + workspace from the
+ * server-side OAuth session. Returns null until memberships have loaded.
+ */
+export declare function useActiveWorkspace(): {
+    active: ActiveWorkspace | null;
+    isLoading: boolean;
+};
+/**
+ * Mutation: persist a new active team+workspace on the OAuth session. The
+ * gateway updates the session record, future requests' Bearer tokens carry
+ * the new claims, and consumer apps see the change on their next render.
+ */
+export declare function setActiveWorkspace(opts: {
+    teamId: string;
+    workspaceId: string;
+    getAccessToken: () => Promise<string | null>;
+    gatewayUrl?: string;
+}): Promise<void>;
+export {};

package/dist/hooks/useMemberships.js

@@ -0,0 +1,138 @@
+/**
+ * Memberships + active-workspace hooks for consumer apps.
+ *
+ * These power the <WorkspaceSwitcher /> component. They fetch the user's
+ * full team → workspace tree from the gateway and let the caller switch
+ * the active workspace. The active workspace is stored on the OAuth
+ * session server-side so it's persistent across page reloads + devices.
+ */
+'use client';
+import { useCallback, useEffect, useState } from 'react';
+import { useHyperyAuth } from '../lib/context';
+/**
+ * Hook: list every team + workspace the current user belongs to. Returns a
+ * flat memberships array that's easy to render in a switcher dropdown.
+ */
+export function useMemberships() {
+    const { isAuthenticated, getAccessToken } = useHyperyAuth();
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // We can't pull the gatewayUrl off the public context value (intentionally),
+    // so we rely on the `Origin` header path: in practice every consumer is
+    // configured to point its access-token Bearer at the same gateway, so a
+    // simple relative fetch on the gateway's domain works. Consumer apps that
+    // run on a different origin override this by setting NEXT_PUBLIC_GATEWAY_URL.
+    const gatewayUrl = (typeof process !== 'undefined' &&
+        process.env?.NEXT_PUBLIC_GATEWAY_URL) ||
+        '';
+    const load = useCallback(async () => {
+        if (!isAuthenticated) {
+            setData(null);
+            setIsLoading(false);
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const token = await getAccessToken();
+            if (!token) {
+                setData(null);
+                return;
+            }
+            const url = `${gatewayUrl}/api/auth/list_memberships`;
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+                credentials: 'include',
+            });
+            if (!res.ok) {
+                throw new Error(`Memberships request failed: ${res.status}`);
+            }
+            const body = (await res.json());
+            // Decorate isActive on each workspace from the response's pointers.
+            const decorated = {
+                ...body,
+                memberships: body.memberships.map((m) => ({
+                    ...m,
+                    workspaces: m.workspaces.map((w) => ({
+                        ...w,
+                        isActive: w.id === body.activeWorkspaceId,
+                    })),
+                })),
+            };
+            setData(decorated);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Unknown error');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [isAuthenticated, getAccessToken, gatewayUrl]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    return { data, isLoading, error, reload: load };
+}
+/**
+ * Hook: resolves the user's currently-active team + workspace from the
+ * server-side OAuth session. Returns null until memberships have loaded.
+ */
+export function useActiveWorkspace() {
+    const { data, isLoading } = useMemberships();
+    if (!data)
+        return { active: null, isLoading };
+    // Prefer the explicit activeWorkspaceId pointer. Fall back to the personal
+    // team's default workspace so first-time users see something sensible.
+    const flat = data.memberships.flatMap((m) => m.workspaces.map((w) => ({ membership: m, workspace: w })));
+    let entry = flat.find((e) => e.workspace.id === data.activeWorkspaceId) ?? null;
+    if (!entry) {
+        const personal = data.memberships.find((m) => m.team.isPersonal);
+        const personalDefault = personal?.workspaces.find((w) => w.isDefault);
+        if (personal && personalDefault) {
+            entry = { membership: personal, workspace: personalDefault };
+        }
+    }
+    if (!entry)
+        return { active: null, isLoading: false };
+    return {
+        isLoading: false,
+        active: {
+            teamId: entry.membership.team.id,
+            teamName: entry.membership.team.name,
+            workspaceId: entry.workspace.id,
+            workspaceName: entry.workspace.name,
+            role: entry.workspace.role,
+        },
+    };
+}
+/**
+ * Mutation: persist a new active team+workspace on the OAuth session. The
+ * gateway updates the session record, future requests' Bearer tokens carry
+ * the new claims, and consumer apps see the change on their next render.
+ */
+export async function setActiveWorkspace(opts) {
+    const token = await opts.getAccessToken();
+    if (!token)
+        throw new Error('No access token; user is not signed in');
+    const base = opts.gatewayUrl ??
+        (typeof process !== 'undefined'
+            ? process.env?.NEXT_PUBLIC_GATEWAY_URL ?? ''
+            : '');
+    const res = await fetch(`${base}/api/oauth/session`, {
+        method: 'PATCH',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        credentials: 'include',
+        body: JSON.stringify({
+            activeOrganizationId: opts.teamId,
+            activeWorkspaceId: opts.workspaceId,
+        }),
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => res.statusText);
+        throw new Error(`Failed to switch workspace: ${detail}`);
+    }
+}

package/dist/hooks/useWallet.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Wallet hook for consumer apps.
+ *
+ * Reads the mode-aware wallet snapshot from the gateway (GET /api/wallet/state)
+ * and exposes the two funding actions the embeddable widget needs:
+ *   - addFunds(usd)        → 1-click off-session charge of the card on file
+ *   - addPaymentMethod()   → Stripe-hosted Checkout (setup) in a popup
+ *
+ * Works in both billing modes; the widget chooses which action to show from
+ * `wallet.mode` and `wallet.paymentMethod.exists`.
+ */
+export type BillingMode = 'metered' | 'prepaid';
+export interface WalletTier {
+    name: string;
+    usdAmount: number;
+    credits: number;
+    bonus: number;
+    popular?: boolean;
+}
+export interface WalletState {
+    mode: BillingMode;
+    balance: {
+        current: number;
+        reserved: number;
+        monthlySpent: number;
+        monthlyLimit: number;
+    };
+    paymentMethod: {
+        exists: boolean;
+        last4?: string;
+        brand?: string;
+    };
+    autoTopUp: {
+        enabled: boolean;
+        threshold?: number;
+        amount?: number;
+    };
+    lowBalance: {
+        isLow: boolean;
+        threshold: number;
+        current: number;
+    };
+    topupTiers: WalletTier[];
+    settingsUrls: {
+        billing: string;
+        topup: string;
+        addPaymentMethod: string;
+    };
+}
+export interface UseWalletReturn {
+    wallet: WalletState | null;
+    isLoading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+    /** 1-click: charge the card on file for `usd` dollars and credit the team. */
+    addFunds: (usd: number) => Promise<void>;
+    /** Open Stripe-hosted Checkout to add a card; resolves true once added. */
+    addPaymentMethod: () => Promise<boolean>;
+}
+export declare function useWallet(opts?: {
+    gatewayUrl?: string;
+}): UseWalletReturn;

package/dist/hooks/useWallet.js

@@ -0,0 +1,123 @@
+/**
+ * Wallet hook for consumer apps.
+ *
+ * Reads the mode-aware wallet snapshot from the gateway (GET /api/wallet/state)
+ * and exposes the two funding actions the embeddable widget needs:
+ *   - addFunds(usd)        → 1-click off-session charge of the card on file
+ *   - addPaymentMethod()   → Stripe-hosted Checkout (setup) in a popup
+ *
+ * Works in both billing modes; the widget chooses which action to show from
+ * `wallet.mode` and `wallet.paymentMethod.exists`.
+ */
+'use client';
+import { useCallback, useEffect, useState } from 'react';
+import { useHyperyAuth } from '../lib/context';
+function resolveGatewayUrl(explicit) {
+    return (explicit ||
+        (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_GATEWAY_URL) ||
+        '');
+}
+export function useWallet(opts = {}) {
+    const { isAuthenticated, getAccessToken } = useHyperyAuth();
+    const gatewayUrl = resolveGatewayUrl(opts.gatewayUrl);
+    const [wallet, setWallet] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const reload = useCallback(async () => {
+        if (!isAuthenticated) {
+            setWallet(null);
+            setIsLoading(false);
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const token = await getAccessToken();
+            if (!token) {
+                setWallet(null);
+                return;
+            }
+            const res = await fetch(`${gatewayUrl}/api/wallet/state`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok)
+                throw new Error(`Wallet state request failed: ${res.status}`);
+            const body = (await res.json());
+            setWallet(body);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Unknown error');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [isAuthenticated, getAccessToken, gatewayUrl]);
+    useEffect(() => {
+        void reload();
+    }, [reload]);
+    const addFunds = useCallback(async (usd) => {
+        const token = await getAccessToken();
+        if (!token)
+            throw new Error('Not authenticated');
+        const res = await fetch(`${gatewayUrl}/api/wallet/topup`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ amount: usd }),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body?.success) {
+            throw new Error(body?.error || `Top-up failed: ${res.status}`);
+        }
+        await reload();
+    }, [getAccessToken, gatewayUrl, reload]);
+    const addPaymentMethod = useCallback(async () => {
+        const token = await getAccessToken();
+        if (!token)
+            throw new Error('Not authenticated');
+        const res = await fetch(`${gatewayUrl}/api/payments/stripe/checkout-setup`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({}),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body?.url) {
+            throw new Error(body?.error || `Could not start checkout: ${res.status}`);
+        }
+        const popup = typeof window !== 'undefined'
+            ? window.open(body.url, 'hypery-add-card', 'width=480,height=720')
+            : null;
+        // Resolve when the hosted-Checkout return page messages us, or when the
+        // popup closes (fall back to a state reload to detect the new card).
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = async (added) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(poll);
+                await reload();
+                resolve(added);
+            };
+            // Only trust the completion message from the gateway's own origin.
+            const expectedOrigin = gatewayUrl
+                ? new URL(gatewayUrl).origin
+                : typeof window !== 'undefined'
+                    ? window.location.origin
+                    : '';
+            const onMessage = (event) => {
+                if (event.origin !== expectedOrigin)
+                    return;
+                if (event?.data?.type === 'hypery:payment-method') {
+                    void finish(event.data.status === 'added');
+                }
+            };
+            window.addEventListener('message', onMessage);
+            const poll = setInterval(() => {
+                if (popup && popup.closed)
+                    void finish(false);
+            }, 700);
+        });
+    }, [getAccessToken, gatewayUrl, reload]);
+    return { wallet, isLoading, error, reload, addFunds, addPaymentMethod };
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @hyperyai/sdk
+ * Drop-in authentication and error handling library for Hypery apps
+ *
+ * @example
+ * ```tsx
+ * import { HyperyProvider, useUser, SignedIn, SignedOut } from '@hyperyai/sdk';
+ *
+ * <HyperyProvider config={{ ... }}>
+ *   <SignedIn>
+ *     <App />
+ *   </SignedIn>
+ *   <SignedOut>
+ *     <SignIn />
+ *   </SignedOut>
+ * </HyperyProvider>
+ * ```
+ */
+export { HyperyProvider, useHyperyAuth, useUser } from './lib/context';
+export { useAuth, useMemberships, useActiveWorkspace, setActiveWorkspace, useWallet, useBuyerWallet, useMarketplace, useCheckout, } from './hooks';
+export type { MembershipEntry, MembershipTeam, MembershipWorkspace, MembershipsResponse, ActiveWorkspace, BillingMode, WalletState, WalletTier, UseWalletReturn, BuyerPaymentMethod, AddCardOptions, UseBuyerWalletReturn, BuyInput, BuySuccess, BuyFailure, BuyResult, UseMarketplaceReturn, CheckoutInput, CheckoutStatus, CheckoutResult, UseCheckoutReturn, } from './hooks';
+export { SignIn } from './components/SignIn';
+export { SignUp } from './components/SignUp';
+export { SignInForm } from './components/SignInForm';
+export { UserButton } from './components/UserButton';
+export { UserProfile } from './components/UserProfile';
+export { SignedIn, SignedOut, RedirectToSignIn, Protect } from './components/control';
+export { AuthModal } from './components/AuthModal';
+export type { AuthModalProps } from './components/AuthModal';
+export { AuthButton } from './components/AuthButton';
+export type { AuthButtonProps } from './components/AuthButton';
+export { ModernAuthForm } from './components/ModernAuthForm';
+export type { ModernAuthFormProps } from './components/ModernAuthForm';
+export { WorkspaceSwitcher } from './components/WorkspaceSwitcher';
+export type { WorkspaceSwitcherProps } from './components/WorkspaceSwitcher';
+export { BuyButton } from './components/BuyButton';
+export type { BuyButtonProps } from './components/BuyButton';
+export { RestrictionModal } from './components/RestrictionModal';
+export type { RestrictionError } from './components/RestrictionModal';
+export { HyperyModals } from './components/HyperyModals';
+export type { HyperyModalsProps } from './components/HyperyModals';
+export { SpendingLimitAlert } from './components/SpendingLimitAlert';
+export type { SpendingLimitAlertProps } from './components/SpendingLimitAlert';
+export { InsufficientCreditsAlert } from './components/InsufficientCreditsAlert';
+export type { InsufficientCreditsAlertProps } from './components/InsufficientCreditsAlert';
+export { ErrorBoundary } from './components/ErrorBoundary';
+export type { ErrorBoundaryProps } from './components/ErrorBoundary';
+export { useError } from './hooks/useError';
+export type { UseErrorReturn } from './hooks/useError';
+export type { BrandingConfig, HyperyAuthConfig, InteractionMode, ResolvedMode, PopupAuthResult, User, AuthTokens, AuthState, AuthContextValue, SpendingLimitErrorData, InsufficientCreditsErrorData, PaymentMethodRequiredErrorData, PaymentDeclinedErrorData, AuthenticationErrorData, GenericErrorData, ErrorData, ErrorResponse, ParsedError, } from './types';
+export { TokenStorage } from './lib/storage';
+export { getAuthorizationUrl, exchangeCodeForToken, refreshAccessToken, getUserInfo, } from './lib/oauth';
+export { parseError, isSpendingLimitError, isInsufficientCreditsError, isPaymentMethodRequiredError, isPaymentDeclinedError, isAuthError, isPermissionDeniedError, isRateLimitError, isBillingRestriction, formatTimeUntilReset, } from './lib/parse-error';
+export { parseSSEError, parseSSEFrame, consumeSSEStream } from './lib/parse-stream';
+export type { SSEEvent, SSEStreamHandlers } from './lib/parse-stream';

package/dist/index.js

@@ -0,0 +1,52 @@
+/**
+ * @hyperyai/sdk
+ * Drop-in authentication and error handling library for Hypery apps
+ *
+ * @example
+ * ```tsx
+ * import { HyperyProvider, useUser, SignedIn, SignedOut } from '@hyperyai/sdk';
+ *
+ * <HyperyProvider config={{ ... }}>
+ *   <SignedIn>
+ *     <App />
+ *   </SignedIn>
+ *   <SignedOut>
+ *     <SignIn />
+ *   </SignedOut>
+ * </HyperyProvider>
+ * ```
+ */
+// Provider & Hooks
+export { HyperyProvider, useHyperyAuth, useUser } from './lib/context';
+export { useAuth, useMemberships, useActiveWorkspace, setActiveWorkspace, useWallet, useBuyerWallet, useMarketplace, useCheckout, } from './hooks';
+// Auth Components
+export { SignIn } from './components/SignIn';
+export { SignUp } from './components/SignUp';
+export { SignInForm } from './components/SignInForm';
+export { UserButton } from './components/UserButton';
+export { UserProfile } from './components/UserProfile';
+export { SignedIn, SignedOut, RedirectToSignIn, Protect } from './components/control';
+export { AuthModal } from './components/AuthModal';
+export { AuthButton } from './components/AuthButton';
+export { ModernAuthForm } from './components/ModernAuthForm';
+export { WorkspaceSwitcher } from './components/WorkspaceSwitcher';
+// "Buy with Hypery" marketplace checkout button.
+export { BuyButton } from './components/BuyButton';
+// Error Components
+export { RestrictionModal } from './components/RestrictionModal';
+// Turnkey modal host — mount once for automatic billing/auth modals driven by
+// authenticatedFetch (issue #42).
+export { HyperyModals } from './components/HyperyModals';
+export { SpendingLimitAlert } from './components/SpendingLimitAlert';
+export { InsufficientCreditsAlert } from './components/InsufficientCreditsAlert';
+export { ErrorBoundary } from './components/ErrorBoundary';
+// Error Hook
+export { useError } from './hooks/useError';
+// Utilities (for advanced usage)
+export { TokenStorage } from './lib/storage';
+export { getAuthorizationUrl, exchangeCodeForToken, refreshAccessToken, getUserInfo, } from './lib/oauth';
+// Error Utilities
+export { parseError, isSpendingLimitError, isInsufficientCreditsError, isPaymentMethodRequiredError, isPaymentDeclinedError, isAuthError, isPermissionDeniedError, isRateLimitError, isBillingRestriction, formatTimeUntilReset, } from './lib/parse-error';
+// Streaming (SSE) error classification — surface a terminal mid-stream error in
+// the same classified shape as a non-streaming failure (issue #44).
+export { parseSSEError, parseSSEFrame, consumeSSEStream } from './lib/parse-stream';

package/dist/lib/context.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hypery Auth Context
+ * Similar to Clerk's <ClerkProvider>
+ */
+import React, { type ReactNode } from 'react';
+import type { HyperyAuthConfig, AuthContextValue, User } from '../types';
+export interface HyperyProviderProps {
+    config: HyperyAuthConfig;
+    children: ReactNode;
+}
+/**
+ * Hypery Auth Provider
+ * Wrap your app with this component to enable authentication
+ *
+ * @example
+ * ```tsx
+ * <HyperyProvider config={{
+ *   clientId: 'your-client-id',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   gatewayUrl: 'https://api.hypery.ai',
+ *   scopes: ['read', 'write', 'ai:chat']
+ * }}>
+ *   <App />
+ * </HyperyProvider>
+ * ```
+ */
+export declare function HyperyProvider({ config, children, }: HyperyProviderProps): React.JSX.Element;
+/**
+ * Hook to access auth state and methods
+ * Similar to Clerk's useAuth()
+ *
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated, login, logout } = useHyperyAuth();
+ * ```
+ */
+export declare function useHyperyAuth(): AuthContextValue;
+/**
+ * Hook to access user data
+ * Similar to Clerk's useUser()
+ *
+ * @example
+ * ```tsx
+ * const { user, isLoading } = useUser();
+ * ```
+ */
+export declare function useUser(): {
+    user: User | null;
+    isLoading: boolean;
+};