@hyperyai/sdk 1.0.0

package/src/hooks/useMemberships.ts

@@ -0,0 +1,203 @@
+/**
+ * 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';
+
+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 function useMemberships(): MembershipsState {
+  const { isAuthenticated, getAccessToken } = useHyperyAuth();
+  const [data, setData] = useState<MembershipsResponse | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [error, setError] = useState<string | null>(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()) as MembershipsResponse;
+      // Decorate isActive on each workspace from the response's pointers.
+      const decorated: MembershipsResponse = {
+        ...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 };
+}
+
+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 function useActiveWorkspace(): {
+  active: ActiveWorkspace | null;
+  isLoading: boolean;
+} {
+  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: {
+    teamId: string;
+    workspaceId: string;
+    getAccessToken: () => Promise<string | null>;
+    gatewayUrl?: string;
+  },
+): Promise<void> {
+  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/src/hooks/useWallet.ts

@@ -0,0 +1,170 @@
+/**
+ * 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';
+
+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>;
+}
+
+function resolveGatewayUrl(explicit?: string): string {
+  return (
+    explicit ||
+    (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_GATEWAY_URL) ||
+    ''
+  );
+}
+
+export function useWallet(opts: { gatewayUrl?: string } = {}): UseWalletReturn {
+  const { isAuthenticated, getAccessToken } = useHyperyAuth();
+  const gatewayUrl = resolveGatewayUrl(opts.gatewayUrl);
+
+  const [wallet, setWallet] = useState<WalletState | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(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()) as WalletState & { success: boolean };
+      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: number) => {
+      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 (): Promise<boolean> => {
+    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<boolean>((resolve) => {
+      let settled = false;
+      const finish = async (added: boolean) => {
+        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: MessageEvent) => {
+        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/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * @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';
+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';
+
+// 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 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';
+
+// "Buy with Hypery" marketplace checkout button.
+export { BuyButton } from './components/BuyButton';
+export type { BuyButtonProps } from './components/BuyButton';
+
+// Error Components
+export { RestrictionModal } from './components/RestrictionModal';
+export type { RestrictionError } from './components/RestrictionModal';
+
+// Turnkey modal host — mount once for automatic billing/auth modals driven by
+// authenticatedFetch (issue #42).
+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';
+
+// Error Hook
+export { useError } from './hooks/useError';
+export type { UseErrorReturn } from './hooks/useError';
+
+// Types
+export type {
+  BrandingConfig,
+  HyperyAuthConfig,
+  InteractionMode,
+  ResolvedMode,
+  PopupAuthResult,
+  User,
+  AuthTokens,
+  AuthState,
+  AuthContextValue,
+  SpendingLimitErrorData,
+  InsufficientCreditsErrorData,
+  PaymentMethodRequiredErrorData,
+  PaymentDeclinedErrorData,
+  AuthenticationErrorData,
+  GenericErrorData,
+  ErrorData,
+  ErrorResponse,
+  ParsedError,
+} from './types';
+
+// 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';
+export type { SSEEvent, SSEStreamHandlers } from './lib/parse-stream';
+