@hyperyai/sdk 1.0.0

package/dist/components/ui/dialog.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { X } from "lucide-react";
+import { cn } from "../../lib/utils";
+const Dialog = DialogPrimitive.Root;
+const DialogTrigger = DialogPrimitive.Trigger;
+const DialogPortal = DialogPrimitive.Portal;
+const DialogClose = DialogPrimitive.Close;
+const DialogOverlay = React.forwardRef(({ className, style, ...props }, ref) => (_jsx(DialogPrimitive.Overlay, { ref: ref, style: {
+        position: 'fixed',
+        inset: 0,
+        zIndex: 50,
+        backgroundColor: 'rgba(0, 0, 0, 0.8)',
+        ...style,
+    }, className: className, ...props })));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+const DialogContent = React.forwardRef(({ className, children, style, ...props }, ref) => (_jsxs(DialogPortal, { children: [_jsx(DialogOverlay, {}), _jsxs(DialogPrimitive.Content, { ref: ref, style: {
+                position: 'fixed',
+                left: '50%',
+                top: '50%',
+                zIndex: 50,
+                display: 'grid',
+                width: '100%',
+                maxWidth: '32rem',
+                transform: 'translate(-50%, -50%)',
+                gap: '1rem',
+                border: '1px solid #e5e7eb',
+                backgroundColor: '#ffffff',
+                padding: '1.5rem',
+                boxShadow: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
+                borderRadius: '0.5rem',
+                ...style,
+            }, className: className, ...props, children: [children, _jsxs(DialogPrimitive.Close, { style: {
+                        position: 'absolute',
+                        right: '1rem',
+                        top: '1rem',
+                        opacity: 0.7,
+                        cursor: 'pointer',
+                        border: 'none',
+                        background: 'transparent',
+                    }, children: [_jsx(X, { style: { width: '1rem', height: '1rem' } }), _jsx("span", { style: { position: 'absolute', width: '1px', height: '1px', padding: 0, margin: '-1px', overflow: 'hidden', clip: 'rect(0, 0, 0, 0)', whiteSpace: 'nowrap', borderWidth: 0 }, children: "Close" })] })] })] })));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+const DialogHeader = ({ className, ...props }) => (_jsx("div", { className: cn("flex flex-col space-y-1.5 text-center sm:text-left", className), ...props }));
+DialogHeader.displayName = "DialogHeader";
+const DialogFooter = ({ className, ...props }) => (_jsx("div", { className: cn("flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2", className), ...props }));
+DialogFooter.displayName = "DialogFooter";
+const DialogTitle = React.forwardRef(({ className, ...props }, ref) => (_jsx(DialogPrimitive.Title, { ref: ref, className: cn("text-lg font-semibold leading-none tracking-tight", className), ...props })));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+const DialogDescription = React.forwardRef(({ className, ...props }, ref) => (_jsx(DialogPrimitive.Description, { ref: ref, className: cn("text-sm text-muted-foreground", className), ...props })));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+export { Dialog, DialogPortal, DialogOverlay, DialogTrigger, DialogClose, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };

package/dist/hooks/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Re-export hooks for convenience
+ */
+export { useHyperyAuth, useUser } from '../lib/context';
+/**
+ * Alias for useHyperyAuth to match Clerk's API
+ * @example
+ * ```tsx
+ * const { isLoaded, isAuthenticated, user } = useAuth();
+ * ```
+ */
+export { useHyperyAuth as useAuth } from '../lib/context';
+export { useMemberships, useActiveWorkspace, setActiveWorkspace, } from './useMemberships';
+export type { MembershipEntry, MembershipTeam, MembershipWorkspace, MembershipsResponse, ActiveWorkspace, } from './useMemberships';
+export { useWallet } from './useWallet';
+export type { BillingMode, WalletState, WalletTier, UseWalletReturn, } from './useWallet';
+export { useBuyerWallet } from './useBuyerWallet';
+export type { BuyerPaymentMethod, AddCardOptions, UseBuyerWalletReturn, } from './useBuyerWallet';
+export { useMarketplace } from './useMarketplace';
+export type { BuyInput, BuySuccess, BuyFailure, BuyResult, UseMarketplaceReturn, } from './useMarketplace';
+export { useCheckout } from './useCheckout';
+export type { CheckoutInput, CheckoutStatus, CheckoutResult, UseCheckoutReturn, } from './useCheckout';

package/dist/hooks/index.js

@@ -0,0 +1,23 @@
+/**
+ * Re-export hooks for convenience
+ */
+export { useHyperyAuth, useUser } from '../lib/context';
+/**
+ * Alias for useHyperyAuth to match Clerk's API
+ * @example
+ * ```tsx
+ * const { isLoaded, isAuthenticated, user } = useAuth();
+ * ```
+ */
+export { useHyperyAuth as useAuth } from '../lib/context';
+// Workspace + membership hooks for the WorkspaceSwitcher and consumer apps.
+export { useMemberships, useActiveWorkspace, setActiveWorkspace, } from './useMemberships';
+// Mode-aware wallet hook (balance, 1-click add funds, add payment method).
+export { useWallet } from './useWallet';
+// "Buy with Hypery" marketplace layer (Stripe Connect, consumer side).
+export { useBuyerWallet } from './useBuyerWallet';
+export { useMarketplace } from './useMarketplace';
+// Seamless auth + charge orchestrator (login → charge → add-card → retry) in
+// popup or redirect mode. Powers <BuyButton>; use directly for custom buttons
+// and for AI-credit top-ups (kind: 'topup').
+export { useCheckout } from './useCheckout';

package/dist/hooks/useBuyerWallet.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Buyer wallet hook for the "buy with Hypery" marketplace layer.
+ *
+ * Reads the buyer's saved payment methods from the gateway
+ * (GET /api/buyer/wallet) and exposes an `addCard` action that starts the
+ * Stripe-hosted card-entry flow (POST /api/buyer/wallet/checkout-setup) and
+ * redirects the browser to it.
+ */
+import type { ParsedError } from "../types";
+export interface BuyerPaymentMethod {
+    id: string;
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+    isDefault: boolean;
+}
+export interface AddCardOptions {
+    /** Where Stripe returns after a successful card add. Defaults to current URL. */
+    successUrl?: string;
+    /** Where Stripe returns if the buyer cancels. Defaults to current URL. */
+    cancelUrl?: string;
+}
+export interface UseBuyerWalletReturn {
+    paymentMethods: BuyerPaymentMethod[];
+    hasDefault: boolean;
+    isLoading: boolean;
+    error: ParsedError | null;
+    /** Re-fetch the buyer wallet snapshot. */
+    refresh: () => Promise<void>;
+    /**
+     * Start Stripe-hosted card entry and redirect the browser to it.
+     * `successUrl`/`cancelUrl` default to the current location.
+     */
+    addCard: (opts?: AddCardOptions) => Promise<void>;
+}
+export declare function useBuyerWallet(): UseBuyerWalletReturn;

package/dist/hooks/useBuyerWallet.js

@@ -0,0 +1,66 @@
+/**
+ * Buyer wallet hook for the "buy with Hypery" marketplace layer.
+ *
+ * Reads the buyer's saved payment methods from the gateway
+ * (GET /api/buyer/wallet) and exposes an `addCard` action that starts the
+ * Stripe-hosted card-entry flow (POST /api/buyer/wallet/checkout-setup) and
+ * redirects the browser to it.
+ */
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { useHyperyAuth } from "../lib/context";
+import { parseError } from "../lib/parse-error";
+function currentLocation() {
+    return typeof window !== "undefined" ? window.location.href : "";
+}
+export function useBuyerWallet() {
+    const { authenticatedFetch, gatewayUrl } = useHyperyAuth();
+    const [paymentMethods, setPaymentMethods] = useState([]);
+    const [hasDefault, setHasDefault] = useState(false);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const res = await authenticatedFetch(`${gatewayUrl}/api/buyer/wallet`);
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                setError(parseError({ ...body, status: res.status }));
+                setPaymentMethods([]);
+                setHasDefault(false);
+                return;
+            }
+            setPaymentMethods(Array.isArray(body?.paymentMethods) ? body.paymentMethods : []);
+            setHasDefault(Boolean(body?.hasDefault));
+        }
+        catch (err) {
+            setError(parseError(err));
+            setPaymentMethods([]);
+            setHasDefault(false);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [authenticatedFetch, gatewayUrl]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const addCard = useCallback(async (opts = {}) => {
+        const successUrl = opts.successUrl ?? currentLocation();
+        const cancelUrl = opts.cancelUrl ?? currentLocation();
+        const res = await authenticatedFetch(`${gatewayUrl}/api/buyer/wallet/checkout-setup`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ successUrl, cancelUrl }),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body?.url) {
+            throw new Error(body?.error?.message || `Could not start card entry: ${res.status}`);
+        }
+        if (typeof window !== "undefined") {
+            window.location.href = body.url;
+        }
+    }, [authenticatedFetch, gatewayUrl]);
+    return { paymentMethods, hasDefault, isLoading, error, refresh, addCard };
+}

package/dist/hooks/useCheckout.d.ts

@@ -0,0 +1,27 @@
+import type { ParsedError } from '../types';
+export type CheckoutInput = {
+    kind: 'purchase';
+    appId: string;
+    amountCents: number;
+    description?: string;
+    /** Stable key so a resumed/retried charge is not double-billed. Auto-generated if omitted. */
+    idempotencyKey?: string;
+} | {
+    kind: 'topup';
+    /** USD amount of credits to buy. */
+    usdAmount: number;
+};
+export type CheckoutStatus = 'idle' | 'authenticating' | 'charging' | 'adding-card' | 'redirecting' | 'success' | 'error' | 'cancelled';
+export interface CheckoutResult {
+    status: 'success' | 'error' | 'cancelled' | 'redirecting';
+    data?: any;
+    error?: ParsedError;
+}
+export interface UseCheckoutReturn {
+    /** Run the auth+charge flow. Resolves when the chain finishes (or is redirecting away). */
+    checkout: (input: CheckoutInput) => Promise<CheckoutResult>;
+    status: CheckoutStatus;
+    isRunning: boolean;
+    error: ParsedError | null;
+}
+export declare function useCheckout(): UseCheckoutReturn;

package/dist/hooks/useCheckout.js

@@ -0,0 +1,246 @@
+'use client';
+/**
+ * useCheckout — the seamless auth + charge flow.
+ *
+ * One action drives the whole chain: press-buy → (log in if needed) → charge →
+ * (add a card if needed) → retry → done. Works two ways, chosen by
+ * `config.interactionMode` (`auto` by default):
+ *
+ *   - popup:    each interactive step is a centered popup; the chain completes
+ *               in-page without navigation (PayPal / Firebase signInWithPopup).
+ *   - redirect: each step is a full-page redirect; the flow is persisted and
+ *               auto-resumed when the user returns (robust on mobile / blocked
+ *               popups). `auto` falls back to redirect there automatically.
+ *
+ * Covers two charge kinds:
+ *   - `purchase` — a marketplace Connect charge (POST /api/marketplace/checkout).
+ *   - `topup`    — buy AI credits (POST /api/wallet/topup).
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useHyperyAuth } from '../lib/context';
+import { openPopup } from '../lib/popup';
+import { parseError } from '../lib/parse-error';
+const PENDING_KEY = 'hypery_pending_checkout';
+const MAX_ATTEMPTS = 3; // auth redirect + card redirect + margin; guards against loops
+const CARD_POPUP_NAME = 'hypery-add-card';
+const ENDPOINTS = {
+    purchase: { charge: '/api/marketplace/checkout', cardSetup: '/api/buyer/wallet/checkout-setup' },
+    topup: { charge: '/api/wallet/topup', cardSetup: '/api/payments/stripe/checkout-setup' },
+};
+// Module-level guard so a redirect-resume runs exactly once per page load, even
+// if several components mount useCheckout.
+let resumeConsumed = false;
+function readPending() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const raw = window.localStorage.getItem(PENDING_KEY);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePending(input, attempts) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(PENDING_KEY, JSON.stringify({ input, attempts }));
+    }
+    catch {
+        /* storage may be unavailable; redirect resume just won't fire */
+    }
+}
+function clearPending() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.removeItem(PENDING_KEY);
+    }
+    catch {
+        /* ignore */
+    }
+}
+function currentUrl() {
+    return typeof window !== 'undefined' ? window.location.href : '';
+}
+function withIdempotency(input) {
+    if (input.kind === 'purchase' && !input.idempotencyKey) {
+        const key = typeof crypto !== 'undefined' && 'randomUUID' in crypto
+            ? crypto.randomUUID()
+            : `idem_${Date.now()}_${Math.floor(Math.random() * 1e9)}`;
+        return { ...input, idempotencyKey: key };
+    }
+    return input;
+}
+export function useCheckout() {
+    const { isAuthenticated, isLoading, loginPopup, login, interactionMode, gatewayUrl, getAccessToken } = useHyperyAuth();
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const runningRef = useRef(false);
+    const gatewayOrigin = (() => {
+        try {
+            return new URL(gatewayUrl).origin;
+        }
+        catch {
+            return typeof window !== 'undefined' ? window.location.origin : '';
+        }
+    })();
+    const authedFetch = useCallback(async (path, body) => {
+        const token = await getAccessToken();
+        const res = await fetch(`${gatewayUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+        const parsed = await res.json().catch(() => ({}));
+        return { res, body: parsed };
+    }, [gatewayUrl, getAccessToken]);
+    const chargeBody = (input) => input.kind === 'purchase'
+        ? {
+            appId: input.appId,
+            amountCents: input.amountCents,
+            description: input.description,
+            idempotencyKey: input.idempotencyKey,
+        }
+        : { amount: input.usdAmount };
+    /** Open the Stripe-hosted card-entry popup and wait for it to finish (or close). */
+    const addCardPopup = useCallback(async (input) => {
+        const { body } = await authedFetch(ENDPOINTS[input.kind].cardSetup, {
+            successUrl: currentUrl(),
+            cancelUrl: currentUrl(),
+        });
+        if (!body?.url)
+            return false;
+        const result = await openPopup({
+            url: body.url,
+            name: CARD_POPUP_NAME,
+            expectedOrigin: gatewayOrigin,
+            messageType: 'hypery:payment-method',
+        });
+        if (result.blocked)
+            return false; // caller falls back to redirect
+        // Whether we got an explicit "added" message or the popup just closed, the
+        // retry charge below is the source of truth (a 402 again ⇒ still no card).
+        return !result.cancelled;
+    }, [authedFetch, gatewayOrigin]);
+    /** Redirect to Stripe-hosted card entry, persisting the flow to resume on return. */
+    const addCardRedirect = useCallback(async (input, attempts) => {
+        const { body } = await authedFetch(ENDPOINTS[input.kind].cardSetup, {
+            successUrl: currentUrl(),
+            cancelUrl: currentUrl(),
+        });
+        if (body?.url && typeof window !== 'undefined') {
+            writePending(input, attempts + 1);
+            window.location.href = body.url;
+        }
+    }, [authedFetch]);
+    const runCheckout = useCallback(async (rawInput, attempts) => {
+        if (runningRef.current)
+            return { status: 'error', error: undefined };
+        runningRef.current = true;
+        setError(null);
+        const input = withIdempotency(rawInput);
+        try {
+            // 1) Ensure authentication.
+            if (!isAuthenticated) {
+                setStatus('authenticating');
+                if (interactionMode === 'popup') {
+                    const r = await loginPopup();
+                    if (r.cancelled) {
+                        setStatus('cancelled');
+                        return { status: 'cancelled' };
+                    }
+                    if (r.blocked) {
+                        // Popup blocked → fall back to a full-page redirect + resume.
+                        setStatus('redirecting');
+                        writePending(input, attempts + 1);
+                        await login();
+                        return { status: 'redirecting' };
+                    }
+                    // r.ok → fall through to charge (isAuthenticated updates async, but the
+                    // token is now in storage so getAccessToken() will return it).
+                }
+                else {
+                    setStatus('redirecting');
+                    writePending(input, attempts + 1);
+                    await login();
+                    return { status: 'redirecting' };
+                }
+            }
+            // 2) Attempt the charge. Retry once after adding a card.
+            for (let charge = 0; charge < 2; charge++) {
+                setStatus('charging');
+                const { res, body } = await authedFetch(ENDPOINTS[input.kind].charge, chargeBody(input));
+                if (res.ok && body?.success !== false) {
+                    clearPending();
+                    setStatus('success');
+                    return { status: 'success', data: body };
+                }
+                const parsed = parseError({ ...body, status: res.status });
+                // Needs a card → add one, then retry the charge once.
+                if ((parsed.isPaymentMethodRequired || res.status === 402) && charge === 0) {
+                    setStatus('adding-card');
+                    if (interactionMode === 'popup') {
+                        const ok = await addCardPopup(input);
+                        if (!ok) {
+                            // Popup blocked/cancelled → redirect fallback (resumes on return).
+                            setStatus('redirecting');
+                            await addCardRedirect(input, attempts);
+                            return { status: 'redirecting' };
+                        }
+                        continue; // retry charge
+                    }
+                    else {
+                        setStatus('redirecting');
+                        await addCardRedirect(input, attempts);
+                        return { status: 'redirecting' };
+                    }
+                }
+                // Any other error is terminal for this flow.
+                clearPending();
+                setError(parsed);
+                setStatus('error');
+                return { status: 'error', error: parsed };
+            }
+            // Retried once after adding a card and still not ok.
+            const fail = parseError({ code: 'PAYMENT_METHOD_REQUIRED', status: 402 });
+            clearPending();
+            setError(fail);
+            setStatus('error');
+            return { status: 'error', error: fail };
+        }
+        catch (err) {
+            const parsed = parseError(err);
+            clearPending();
+            setError(parsed);
+            setStatus('error');
+            return { status: 'error', error: parsed };
+        }
+        finally {
+            runningRef.current = false;
+        }
+    }, [isAuthenticated, interactionMode, loginPopup, login, authedFetch, addCardPopup, addCardRedirect]);
+    const checkout = useCallback((input) => runCheckout(input, 0), [runCheckout]);
+    // Redirect-mode resume: after the user returns from an auth or card redirect,
+    // continue the persisted flow exactly once.
+    useEffect(() => {
+        if (resumeConsumed || isLoading)
+            return;
+        const pending = readPending();
+        if (!pending)
+            return;
+        if (!isAuthenticated)
+            return; // wait until the auth callback has set the user
+        if (pending.attempts >= MAX_ATTEMPTS) {
+            clearPending();
+            return;
+        }
+        resumeConsumed = true;
+        void runCheckout(pending.input, pending.attempts);
+    }, [isAuthenticated, isLoading, runCheckout]);
+    return { checkout, status, isRunning: status !== 'idle' && status !== 'success' && status !== 'error' && status !== 'cancelled', error };
+}

package/dist/hooks/useError.d.ts

@@ -0,0 +1,19 @@
+import type { ParsedError } from '../types';
+export interface UseErrorReturn {
+    error: ParsedError | null;
+    setError: (error: any) => void;
+    clearError: () => void;
+    hasError: boolean;
+    isSpendingLimit: boolean;
+    isInsufficientCredits: boolean;
+    isPaymentMethodRequired: boolean;
+    isPaymentDeclined: boolean;
+    /** True when the error is an authentication failure (401) — open the auth modal / re-auth. */
+    isAuth: boolean;
+    /** True for any billing restriction the funds widget can resolve. */
+    isBillingRestriction: boolean;
+}
+/**
+ * Hook for managing error state with automatic parsing
+ */
+export declare function useError(): UseErrorReturn;

package/dist/hooks/useError.js

@@ -0,0 +1,36 @@
+'use client';
+import { useState, useCallback } from 'react';
+import { parseError } from '../lib/parse-error';
+/**
+ * Hook for managing error state with automatic parsing
+ */
+export function useError() {
+    const [error, setErrorState] = useState(null);
+    const setError = useCallback((err) => {
+        if (!err) {
+            setErrorState(null);
+            return;
+        }
+        setErrorState(parseError(err));
+    }, []);
+    const clearError = useCallback(() => {
+        setErrorState(null);
+    }, []);
+    const isSpendingLimit = error?.isSpendingLimit || false;
+    const isInsufficientCredits = error?.isInsufficientCredits || false;
+    const isPaymentMethodRequired = error?.isPaymentMethodRequired || false;
+    const isPaymentDeclined = error?.isPaymentDeclined || false;
+    const isAuth = error?.isAuth || false;
+    return {
+        error,
+        setError,
+        clearError,
+        hasError: error !== null,
+        isSpendingLimit,
+        isInsufficientCredits,
+        isPaymentMethodRequired,
+        isPaymentDeclined,
+        isAuth,
+        isBillingRestriction: isSpendingLimit || isInsufficientCredits || isPaymentMethodRequired || isPaymentDeclined,
+    };
+}

package/dist/hooks/useMarketplace.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Marketplace hook for the "buy with Hypery" layer (Stripe Connect).
+ *
+ * Runs a marketplace checkout against the gateway
+ * (POST /api/marketplace/checkout). Expected billing errors (no card on file,
+ * card declined, seller not onboarded, ...) are returned as a discriminated
+ * result — this hook never throws for them.
+ */
+import type { ParsedError } from "../types";
+export interface BuyInput {
+    /** Seller app the purchase is credited to. */
+    appId: string;
+    /** Amount to charge the buyer, in cents. */
+    amountCents: number;
+    /** Optional human-readable description of the purchase. */
+    description?: string;
+    /** Optional specific saved card (pm_...). Defaults to the buyer's default. */
+    paymentMethodId?: string;
+    /**
+     * Optional idempotency key to make retries safe. Pass a STABLE value per
+     * logical purchase (e.g. an order id) so a user-initiated retry of the same
+     * purchase does not charge twice. If omitted, a fresh key is generated per
+     * call — which still protects against the SDK's internal auth-refresh retry,
+     * but not against a fresh second call for the same order.
+     */
+    idempotencyKey?: string;
+}
+export interface BuySuccess {
+    ok: true;
+    paymentIntentId: string;
+    status: string;
+    amountCents: number;
+    applicationFeeCents: number;
+}
+export interface BuyFailure {
+    ok: false;
+    error: ParsedError;
+    /** True when the buyer has no card and must add one before retrying. */
+    needsPaymentMethod: boolean;
+    /** True when the caller is not authenticated and must log in before retrying. */
+    needsAuth: boolean;
+}
+export type BuyResult = BuySuccess | BuyFailure;
+export interface UseMarketplaceReturn {
+    /** Run a marketplace checkout. Never throws for expected billing errors. */
+    buy: (input: BuyInput) => Promise<BuyResult>;
+    isBuying: boolean;
+    lastError: ParsedError | null;
+}
+export declare function useMarketplace(): UseMarketplaceReturn;

package/dist/hooks/useMarketplace.js

@@ -0,0 +1,69 @@
+/**
+ * Marketplace hook for the "buy with Hypery" layer (Stripe Connect).
+ *
+ * Runs a marketplace checkout against the gateway
+ * (POST /api/marketplace/checkout). Expected billing errors (no card on file,
+ * card declined, seller not onboarded, ...) are returned as a discriminated
+ * result — this hook never throws for them.
+ */
+"use client";
+import { useCallback, useState } from "react";
+import { useHyperyAuth } from "../lib/context";
+import { isPaymentMethodRequiredError, parseError } from "../lib/parse-error";
+/** Best-effort unique idempotency token (browser crypto with a fallback). */
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return `mkt_${c.randomUUID()}`;
+    return `mkt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+export function useMarketplace() {
+    const { authenticatedFetch, gatewayUrl } = useHyperyAuth();
+    const [isBuying, setIsBuying] = useState(false);
+    const [lastError, setLastError] = useState(null);
+    const buy = useCallback(async (input) => {
+        setIsBuying(true);
+        setLastError(null);
+        const fail = (raw) => {
+            const error = parseError(raw);
+            setLastError(error);
+            return {
+                ok: false,
+                error,
+                needsPaymentMethod: isPaymentMethodRequiredError(raw),
+                needsAuth: error.isAuth,
+            };
+        };
+        try {
+            const res = await authenticatedFetch(`${gatewayUrl}/api/marketplace/checkout`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    appId: input.appId,
+                    amountCents: input.amountCents,
+                    description: input.description,
+                    paymentMethodId: input.paymentMethodId,
+                    idempotencyKey: input.idempotencyKey ?? newIdempotencyKey(),
+                }),
+            });
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok || !body?.success) {
+                return fail({ ...body, status: res.status });
+            }
+            return {
+                ok: true,
+                paymentIntentId: body.paymentIntentId,
+                status: body.status,
+                amountCents: body.amountCents,
+                applicationFeeCents: body.applicationFeeCents,
+            };
+        }
+        catch (err) {
+            return fail(err);
+        }
+        finally {
+            setIsBuying(false);
+        }
+    }, [authenticatedFetch, gatewayUrl]);
+    return { buy, isBuying, lastError };
+}