@hyperyai/sdk 1.0.0

package/src/components/BuyButton.tsx

@@ -0,0 +1,150 @@
+/**
+ * BuyButton — "buy with Hypery" marketplace checkout button.
+ *
+ * On click it runs the full auth+charge flow via {@link useCheckout}: it logs
+ * the buyer in if needed, charges, and adds a card if none is on file — each
+ * step as a popup or a redirect per `config.interactionMode` (`auto` by default).
+ * So an unauthenticated visitor can click Buy and be walked through login → card
+ * → charge without leaving the page (popup mode). Never throws.
+ */
+
+"use client";
+
+import type React from "react";
+import { useState } from "react";
+import { type BuySuccess } from "../hooks/useMarketplace";
+import { useCheckout } from "../hooks/useCheckout";
+import type { BrandingConfig, ParsedError } from "../types";
+
+export interface BuyButtonProps {
+  /** 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;
+  /** Button label. Defaults to a price-formatted "Buy · $X.XX". */
+  label?: React.ReactNode;
+  /**
+   * Require an explicit per-transaction confirmation before charging (the card
+   * is charged off-session, so this gives the buyer a clear "yes"). Defaults to
+   * true: the first click arms the button ("Confirm · $X.XX" + Cancel), the
+   * second click charges. Set false to charge on a single click.
+   */
+  requireConfirmation?: boolean;
+  /** Called with the successful checkout result. */
+  onSuccess?: (result: BuySuccess) => void;
+  /** Called with a classified error for failures other than needs-a-card. */
+  onError?: (error: ParsedError) => void;
+  /** Custom className appended to the button. */
+  className?: string;
+  /** Optional branding (primaryColor is used as the button color). */
+  branding?: BrandingConfig;
+}
+
+function formatUsd(amountCents: number): string {
+  return `$${(amountCents / 100).toFixed(2)}`;
+}
+
+/**
+ * Drop-in checkout button for the Hypery marketplace.
+ *
+ * @example
+ * ```tsx
+ * <BuyButton appId="app_123" amountCents={499} description="Pro upgrade"
+ *   onSuccess={(r) => console.log('paid', r.paymentIntentId)} />
+ * ```
+ */
+export function BuyButton({
+  appId,
+  amountCents,
+  description,
+  label,
+  onSuccess,
+  onError,
+  className = "",
+  branding,
+  requireConfirmation = true,
+}: BuyButtonProps) {
+  const { checkout, isRunning } = useCheckout();
+  const [armed, setArmed] = useState(false);
+
+  const busy = isRunning;
+
+  const charge = async () => {
+    setArmed(false);
+    // Runs login → charge → add-card → retry as needed (popup or redirect).
+    const result = await checkout({ kind: "purchase", appId, amountCents, description });
+
+    if (result.status === "success") {
+      const b = result.data || {};
+      onSuccess?.({
+        ok: true,
+        paymentIntentId: b.paymentIntentId,
+        status: b.status,
+        amountCents: b.amountCents ?? amountCents,
+        applicationFeeCents: b.applicationFeeCents ?? 0,
+      } as BuySuccess);
+      return;
+    }
+    // 'redirecting' (navigating away, resumes on return) and 'cancelled' (user
+    // closed a popup) are not errors — stay quiet.
+    if (result.status === "error" && result.error) {
+      onError?.(result.error);
+    }
+  };
+
+  const handleClick = () => {
+    if (requireConfirmation && !armed) {
+      setArmed(true);
+      return;
+    }
+    void charge();
+  };
+
+  const primaryColor = branding?.primaryColor;
+  const style = primaryColor ? { backgroundColor: primaryColor } : undefined;
+
+  const idleLabel = label ?? `Buy · ${formatUsd(amountCents)}`;
+  const buttonLabel = busy
+    ? "Processing…"
+    : armed
+      ? `Confirm · ${formatUsd(amountCents)}`
+      : idleLabel;
+
+  return (
+    <span className="inline-flex items-center gap-2">
+      <button
+        type="button"
+        onClick={handleClick}
+        disabled={busy}
+        style={style}
+        className={`
+        inline-flex items-center justify-center gap-2
+        px-6 py-2.5 text-base rounded-lg font-medium transition-all
+        text-white shadow-md hover:shadow-lg
+        ${primaryColor ? "" : "bg-purple-600 hover:bg-purple-700"}
+        disabled:opacity-60 disabled:cursor-not-allowed
+        ${className}
+      `}
+      >
+        {busy && (
+          <span
+            className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-white/40 border-t-white"
+            aria-hidden="true"
+          />
+        )}
+        {buttonLabel}
+      </button>
+      {armed && !busy && (
+        <button
+          type="button"
+          onClick={() => setArmed(false)}
+          className="px-3 py-2.5 text-sm rounded-lg font-medium text-gray-600 hover:text-gray-900 hover:bg-gray-100 transition-colors"
+        >
+          Cancel
+        </button>
+      )}
+    </span>
+  );
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import { parseError } from '../lib/parse-error';
+import { SpendingLimitAlert } from './SpendingLimitAlert';
+import { InsufficientCreditsAlert } from './InsufficientCreditsAlert';
+
+export interface ErrorBoundaryProps {
+  error: any;
+  onRetry?: () => void;
+  onUpgradeLimits?: () => void;
+  onAddCredits?: () => void;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * Universal error boundary component
+ * Automatically renders the appropriate error UI based on error type
+ */
+export function ErrorBoundary({
+  error,
+  onRetry,
+  onUpgradeLimits,
+  onAddCredits,
+  className = '',
+  children,
+}: ErrorBoundaryProps) {
+  if (!error) return <>{children}</>;
+
+  const parsed = parseError(error);
+
+  // Render spending limit alert
+  if (parsed.isSpendingLimit) {
+    return (
+      <SpendingLimitAlert
+        error={parsed}
+        onRetry={onRetry}
+        onUpgradeLimits={onUpgradeLimits}
+        className={className}
+      />
+    );
+  }
+
+  // Render insufficient credits alert
+  if (parsed.isInsufficientCredits) {
+    return (
+      <InsufficientCreditsAlert
+        error={parsed}
+        onAddCredits={onAddCredits}
+        className={className}
+      />
+    );
+  }
+
+  // Render generic error
+  return (
+    <div
+      className={`rounded-lg border border-gray-200 bg-gray-50 p-4 ${className}`}
+      role="alert"
+    >
+      <div className="flex items-start gap-3">
+        <div className="flex-shrink-0">
+          <svg
+            className="h-5 w-5 text-gray-400"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fillRule="evenodd"
+              d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z"
+              clipRule="evenodd"
+            />
+          </svg>
+        </div>
+        <div className="flex-1">
+          <h3 className="text-sm font-medium text-gray-800">Error</h3>
+          <div className="mt-2 text-sm text-gray-700">
+            <p>{parsed.message}</p>
+          </div>
+          {onRetry && (
+            <div className="mt-4">
+              <button
+                type="button"
+                onClick={onRetry}
+                className="text-sm font-medium text-gray-800 hover:text-gray-900"
+              >
+                Try again
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+

package/src/components/HyperyModals.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import React from "react";
+import { useHyperyAuth } from "../lib/context";
+import { AuthModal } from "./AuthModal";
+import { type RestrictionError, RestrictionModal } from "./RestrictionModal";
+
+export interface HyperyModalsProps {
+  /**
+   * Branding + auth-form options forwarded to the auto-opened `AuthModal`.
+   */
+  branding?: {
+    logo?: string;
+    appName?: string;
+    primaryColor?: string;
+  };
+  showSocial?: boolean;
+  showEmailPassword?: boolean;
+  /**
+   * Called when the funds modal's retry button is pressed (e.g. re-run the
+   * request that was blocked). The restriction is cleared automatically.
+   */
+  onRetry?: () => void;
+}
+
+/**
+ * Turnkey modal host. Mount this ONCE anywhere inside `<HyperyProvider>` and the
+ * billing/auth modals open automatically off the context state that
+ * `authenticatedFetch` sets — no manual `setError`/`isOpen` wiring:
+ *
+ *   - a 402/429 billing restriction → `<RestrictionModal>` (add funds / add card)
+ *   - a 401 that survives a silent-refresh retry → `<AuthModal>` (re-auth)
+ *
+ * All wiring (clientId, gatewayUrl, getAccessToken, open/close) is read from
+ * context, so this component takes no required props.
+ */
+export function HyperyModals({
+  branding,
+  showSocial,
+  showEmailPassword,
+  onRetry,
+}: HyperyModalsProps = {}) {
+  const {
+    clientId,
+    gatewayUrl,
+    getAccessToken,
+    restriction,
+    clearRestriction,
+    authRequired,
+    clearAuthRequired,
+  } = useHyperyAuth();
+
+  // ParsedError → RestrictionModal's RestrictionError (data carries the billing
+  // fields: limit/current/available/resetsAt/...).
+  const restrictionError: RestrictionError | null = restriction
+    ? {
+        code: restriction.code,
+        message: restriction.message,
+        type: restriction.type,
+        ...(restriction.data as Record<string, unknown>),
+      }
+    : null;
+
+  return (
+    <>
+      <RestrictionModal
+        error={restrictionError}
+        clientId={clientId}
+        gatewayUrl={gatewayUrl}
+        getAccessToken={getAccessToken}
+        onClose={clearRestriction}
+        onRetry={onRetry}
+      />
+      <AuthModal
+        isOpen={authRequired}
+        onClose={clearAuthRequired}
+        branding={branding}
+        showSocial={showSocial}
+        showEmailPassword={showEmailPassword}
+      />
+    </>
+  );
+}

package/src/components/InsufficientCreditsAlert.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { ParsedError } from '../types';
+
+export interface InsufficientCreditsAlertProps {
+  error: ParsedError;
+  onAddCredits?: () => void;
+  className?: string;
+}
+
+/**
+ * Alert component for insufficient credits errors
+ * Displays a user-friendly message with option to add credits
+ */
+export function InsufficientCreditsAlert({
+  error,
+  onAddCredits,
+  className = '',
+}: InsufficientCreditsAlertProps) {
+  if (!error.isInsufficientCredits) return null;
+
+  const data = error.data as any;
+
+  return (
+    <div
+      className={`rounded-lg border border-red-200 bg-red-50 p-4 ${className}`}
+      role="alert"
+    >
+      <div className="flex items-start gap-3">
+        <div className="flex-shrink-0">
+          <svg
+            className="h-5 w-5 text-red-400"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fillRule="evenodd"
+              d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.28 7.22a.75.75 0 00-1.06 1.06L8.94 10l-1.72 1.72a.75.75 0 101.06 1.06L10 11.06l1.72 1.72a.75.75 0 101.06-1.06L11.06 10l1.72-1.72a.75.75 0 00-1.06-1.06L10 8.94 8.28 7.22z"
+              clipRule="evenodd"
+            />
+          </svg>
+        </div>
+        <div className="flex-1">
+          <h3 className="text-sm font-medium text-red-800">
+            Insufficient Credits
+          </h3>
+          <div className="mt-2 text-sm text-red-700">
+            <p>{error.message}</p>
+            {data.available !== undefined && data.required !== undefined && (
+              <p className="mt-1">
+                You have <strong>{data.available}</strong> credits, but need{' '}
+                <strong>{data.required}</strong> credits.
+              </p>
+            )}
+          </div>
+          {onAddCredits && (
+            <div className="mt-4">
+              <button
+                type="button"
+                onClick={onAddCredits}
+                className="text-sm font-medium text-red-800 hover:text-red-900 underline"
+              >
+                Add credits →
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+