@hyperyai/sdk 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Hypery Auth Types
+ */
+/**
+ * How interactive auth / card-entry steps are presented.
+ *   - `popup`    — a centered popup (seamless; stays on your page). PayPal/Firebase-style.
+ *   - `redirect` — a full-page redirect that resumes the flow on return. Robust everywhere.
+ *   - `auto`     — popup on desktop, redirect on mobile / when a popup is blocked.
+ */
+export type InteractionMode = 'auto' | 'popup' | 'redirect';
+/** The concrete mode after resolving `auto` for the current environment. */
+export type ResolvedMode = 'popup' | 'redirect';
+/** Result of a popup-based login attempt. */
+export interface PopupAuthResult {
+    /** Authentication succeeded and the user is now signed in. */
+    ok: boolean;
+    /** The browser blocked the popup — caller should fall back to redirect. */
+    blocked: boolean;
+    /** The user closed the popup without completing auth. */
+    cancelled: boolean;
+}
+/**
+ * Custom branding shared by AuthButton / AuthModal / ModernAuthForm.
+ */
+export interface BrandingConfig {
+    /** URL to logo image */
+    logo?: string;
+    /** Your app name */
+    appName?: string;
+    /** Hex color (e.g., '#8b5cf6') */
+    primaryColor?: string;
+}
+export interface HyperyAuthConfig {
+    /** OAuth Client ID */
+    clientId: string;
+    /** Redirect URI after auth */
+    redirectUri: string;
+    /** Hypery base URL */
+    gatewayUrl: string;
+    /** OAuth scopes to request */
+    scopes?: string[];
+    /** Storage type for tokens */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+    /**
+     * How interactive auth / card-entry steps in the auth+charge flow are shown.
+     * Defaults to `auto` (popup on desktop, redirect on mobile / blocked popups).
+     * For popup mode, `redirectUri` must be same-origin as your app.
+     */
+    interactionMode?: InteractionMode;
+    /**
+     * Called when an {@link AuthContextValue.authenticatedFetch} request stays 401
+     * after a single silent-refresh retry (server-revoked token / suspended app).
+     * Use for custom re-auth handling; if omitted, `authRequired` is set so
+     * `<HyperyModals>` can auto-open the auth modal.
+     */
+    onUnauthorized?: () => void;
+    /**
+     * Called when an {@link AuthContextValue.authenticatedFetch} request returns a
+     * billing restriction (402/429). Receives the classified error; if omitted,
+     * `restriction` is set so `<HyperyModals>` can auto-open the funds modal.
+     */
+    onRestricted?: (error: ParsedError) => void;
+}
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    image?: string;
+}
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: string;
+}
+export interface AuthState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+    isLoggingOut?: boolean;
+}
+export interface AuthContextValue extends AuthState {
+    login: () => Promise<void>;
+    /**
+     * Log in via a centered popup (no full-page redirect). Resolves once the popup
+     * completes: `ok` on success, `blocked` if the browser blocked the popup (fall
+     * back to `login()`), `cancelled` if the user closed it. Used by the seamless
+     * auth+charge flow (see `useCheckout`).
+     */
+    loginPopup: () => Promise<PopupAuthResult>;
+    /** The interaction mode resolved for this environment (popup vs redirect). */
+    interactionMode: ResolvedMode;
+    /** The redirectUri this provider was configured with. */
+    redirectUri: string;
+    signUp?: () => Promise<void>;
+    logout: () => Promise<void>;
+    refreshAuth: () => Promise<void>;
+    /**
+     * Get a valid access token, refreshing if the local expiry clock says so.
+     * Pass `forceRefresh` to refresh even when the clock says valid (used by the
+     * 401 retry path). Concurrent calls share ONE in-flight refresh (single-flight).
+     */
+    getAccessToken: (forceRefresh?: boolean) => Promise<string | null>;
+    /** OAuth clientId this provider was configured with. */
+    clientId: string;
+    /** Gateway base URL this provider was configured with. */
+    gatewayUrl: string;
+    /**
+     * fetch() that injects the bearer token and drives the turnkey modal UX:
+     * 401 → one silent-refresh retry, then `authRequired` (+ `onUnauthorized`);
+     * 402/429 → `restriction` is set (+ `onRestricted`). Always returns the
+     * Response so the caller can still read the body.
+     */
+    authenticatedFetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    /** Current billing restriction from the last authenticatedFetch, if any. */
+    restriction: ParsedError | null;
+    /** Clear the current restriction (e.g. after the funds modal closes). */
+    clearRestriction: () => void;
+    /** True when re-auth is required (401 survived a refresh retry). */
+    authRequired: boolean;
+    /** Clear the re-auth requirement (e.g. after the auth modal closes). */
+    clearAuthRequired: () => void;
+}
+/**
+ * Error response types from Hypery API
+ */
+export interface SpendingLimitErrorData {
+    code: 'SPENDING_LIMIT_EXCEEDED';
+    message: string;
+    type: 'spending_limit_error';
+    limitType: 'daily' | 'monthly' | 'total';
+    limit: number;
+    current: number;
+    requested: number;
+    resetsAt?: string;
+}
+export interface InsufficientCreditsErrorData {
+    code: 'INSUFFICIENT_CREDITS';
+    message: string;
+    type: 'insufficient_credits_error';
+    available: number;
+    required: number;
+}
+export interface PaymentMethodRequiredErrorData {
+    code: 'PAYMENT_METHOD_REQUIRED';
+    message: string;
+    type: 'payment_method_required_error';
+}
+export interface PaymentDeclinedErrorData {
+    code: 'PAYMENT_DECLINED';
+    message: string;
+    type: 'payment_declined_error';
+    reason?: string;
+}
+export interface AuthenticationErrorData {
+    code: 'UNAUTHENTICATED';
+    message: string;
+    type: 'authentication_error';
+}
+export interface GenericErrorData {
+    code: string;
+    message: string;
+    type?: string;
+    [key: string]: any;
+}
+export type ErrorData = SpendingLimitErrorData | InsufficientCreditsErrorData | PaymentMethodRequiredErrorData | PaymentDeclinedErrorData | AuthenticationErrorData | GenericErrorData;
+export interface ErrorResponse {
+    error: ErrorData;
+}
+/**
+ * Parsed error information
+ */
+export interface ParsedError {
+    code: string;
+    message: string;
+    type?: string;
+    /** HTTP status, when the caller attaches it (used as a classification fallback). */
+    status?: number;
+    isSpendingLimit: boolean;
+    isInsufficientCredits: boolean;
+    isPaymentMethodRequired: boolean;
+    isPaymentDeclined: boolean;
+    /** True for an authentication failure (401 / UNAUTHENTICATED) — drive re-auth. */
+    isAuth: boolean;
+    /** True for a scope/permission denial (403 / PERMISSION_DENIED / INSUFFICIENT_SCOPE). */
+    isPermissionDenied: boolean;
+    /** True for a rate-limit denial (429 / RATE_LIMITED). */
+    isRateLimit: boolean;
+    data: ErrorData;
+}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Hypery Auth Types
+ */
+export {};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@hyperyai/sdk",
+  "version": "1.0.0",
+  "description": "Drop-in authentication, checkout, and error handling for apps built on Hypery",
+  "license": "PIF",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hyperyai/hypery-sdk.git"
+  },
+  "homepage": "https://github.com/hyperyai/hypery-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/hyperyai/hypery-sdk/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "!src/**/__tests__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test src",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "^1.0.5",
+    "clsx": "^2.1.0",
+    "lucide-react": "^0.541.0",
+    "tailwind-merge": "^3.6.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "hypery",
+    "auth",
+    "authentication",
+    "oauth",
+    "pkce",
+    "react",
+    "checkout",
+    "error-handling",
+    "spending-limits",
+    "credits"
+  ]
+}

package/src/components/AuthButton.tsx

@@ -0,0 +1,123 @@
+/**
+ * AuthButton Component
+ * Simple button that triggers authentication modal
+ * Drop this anywhere in your app for instant auth
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { AuthModal } from './AuthModal';
+
+export interface AuthButtonProps {
+  /** Button text */
+  children?: React.ReactNode;
+  /** Button variant */
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+  /** Button size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Custom className */
+  className?: string;
+  /** Initial auth mode */
+  mode?: 'signin' | 'signup';
+  /** Callback after successful auth */
+  onSuccess?: () => void;
+  /** Show social login options */
+  showSocial?: boolean;
+  /** Show email/password form */
+  showEmailPassword?: boolean;
+  /** Custom branding for modal */
+  branding?: {
+    logo?: string;
+    appName?: string;
+    primaryColor?: string;
+  };
+}
+
+/**
+ * Button that opens authentication modal
+ * Perfect for navbar, landing pages, or anywhere you need auth
+ * 
+ * @example
+ * ```tsx
+ * // Simple usage
+ * <AuthButton>Sign In</AuthButton>
+ * 
+ * // With customization
+ * <AuthButton 
+ *   variant="primary"
+ *   mode="signup"
+ *   onSuccess={() => router.push('/dashboard')}
+ *   branding={{ appName: 'My App', primaryColor: '#8b5cf6' }}
+ * >
+ *   Get Started
+ * </AuthButton>
+ * ```
+ */
+export function AuthButton({
+  children = 'Sign In',
+  variant = 'primary',
+  size = 'md',
+  className = '',
+  mode = 'signin',
+  onSuccess,
+  showSocial = true,
+  showEmailPassword = true,
+  branding,
+}: AuthButtonProps) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const sizeClasses = {
+    sm: 'px-4 py-2 text-sm',
+    md: 'px-6 py-2.5 text-base',
+    lg: 'px-8 py-3 text-lg',
+  };
+
+  const variantClasses = {
+    primary: 'bg-purple-600 hover:bg-purple-700 text-white shadow-md hover:shadow-lg',
+    secondary: 'bg-gray-600 hover:bg-gray-700 text-white shadow-md hover:shadow-lg',
+    outline: 'border-2 border-purple-600 text-purple-600 hover:bg-purple-50 dark:hover:bg-purple-950/30',
+    ghost: 'hover:bg-gray-100 dark:hover:bg-gray-800 text-gray-700 dark:text-gray-300',
+  };
+
+  const handleClick = () => {
+    console.log('AuthButton clicked! Opening modal...', { isOpen, mode });
+    setIsOpen(true);
+  };
+
+  console.log('AuthButton render:', { isOpen, mode, variant, size });
+
+  return (
+    <>
+      <button
+        onClick={handleClick}
+        type="button"
+        className={`
+          ${sizeClasses[size]}
+          ${variantClasses[variant]}
+          rounded-lg font-medium transition-all
+          ${className}
+        `}
+      >
+        {children}
+      </button>
+
+      <AuthModal
+        isOpen={isOpen}
+        onClose={() => {
+          console.log('AuthModal closing...');
+          setIsOpen(false);
+        }}
+        initialMode={mode}
+        onSuccess={() => {
+          setIsOpen(false);
+          onSuccess?.();
+        }}
+        showSocial={showSocial}
+        showEmailPassword={showEmailPassword}
+        branding={branding}
+      />
+    </>
+  );
+}
+

package/src/components/AuthModal.tsx

@@ -0,0 +1,240 @@
+/**
+ * AuthModal Component  
+ * Modal dialog for authentication using shadcn Dialog
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from './ui/dialog';
+import { useHyperyAuth } from '../lib/context';
+
+export interface AuthModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  initialMode?: 'signin' | 'signup';
+  onSuccess?: () => void;
+  onError?: (error: string) => void;
+  showSocial?: boolean;
+  showEmailPassword?: boolean;
+  branding?: {
+    logo?: string;
+    appName?: string;
+    primaryColor?: string;
+  };
+}
+
+export function AuthModal({
+  isOpen,
+  onClose,
+  initialMode = 'signin',
+  onSuccess,
+  onError,
+  showSocial = true,
+  showEmailPassword = false,
+  branding,
+}: AuthModalProps) {
+
+  const { login } = useHyperyAuth();
+  const [mode, setMode] = useState<'signin' | 'signup'>(initialMode);
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadingProvider, setLoadingProvider] = useState<string | null>(null);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [name, setName] = useState('');
+  const [error, setError] = useState('');
+
+  const handleSocialSignIn = async (provider: 'google' | 'github') => {
+    console.log('[AuthModal] Social button clicked:', provider);
+    setLoadingProvider(provider);
+    setError('');
+    try {
+      console.log('[AuthModal] Calling login()...');
+      await login();
+      console.log('[AuthModal] Login completed');
+      if (onSuccess) {
+        onSuccess();
+      }
+    } catch (err) {
+      console.error('[AuthModal] Login failed:', err);
+      const errorMessage = err instanceof Error ? err.message : `${provider} sign in failed`;
+      setError(errorMessage);
+      if (onError) {
+        onError(errorMessage);
+      }
+      setLoadingProvider(null);
+    }
+  };
+
+  const handleEmailSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    setError('');
+    setIsLoading(true);
+
+    if (!email || !password) {
+      setError('Please fill in all fields');
+      setIsLoading(false);
+      return;
+    }
+
+    if (mode === 'signup' && !name) {
+      setError('Please enter your name');
+      setIsLoading(false);
+      return;
+    }
+
+    setError('Direct email authentication coming soon. Please use social sign-in.');
+    setIsLoading(false);
+  };
+
+  const primaryColor = branding?.primaryColor || '#8b5cf6';
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <DialogContent className="sm:max-w-md bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+        <DialogHeader>
+          {branding?.logo && (
+            <img src={branding.logo} alt="Logo" className="h-12 mx-auto mb-4" />
+          )}
+          <DialogTitle className="text-center text-2xl text-gray-900 dark:text-white">
+            {mode === 'signin' ? 'Welcome back' : 'Create your account'}
+          </DialogTitle>
+          <DialogDescription className="text-center text-sm text-gray-600 dark:text-gray-400">
+            {mode === 'signin' 
+              ? `Sign in to ${branding?.appName || 'continue'}`
+              : `Get started with ${branding?.appName || 'your account'}`
+            }
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-6 py-4">
+          {/* Error message */}
+          {error && (
+            <div className="p-3 rounded-lg bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 text-red-800 dark:text-red-200 text-sm">
+              {error}
+            </div>
+          )}
+
+          {/* Social buttons */}
+          {showSocial && (
+            <div className="space-y-2">
+              <button
+                onClick={() => handleSocialSignIn('google')}
+                disabled={!!loadingProvider}
+                className="w-full bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-750 border border-gray-300 dark:border-gray-700 text-gray-900 dark:text-white py-2 px-3 rounded flex items-center justify-center gap-2 text-sm font-medium transition-all disabled:opacity-50"
+              >
+                {loadingProvider === 'google' ? (
+                  <div className="w-4 h-4 border-2 border-gray-300 border-t-transparent rounded-full animate-spin" />
+                ) : (
+                  <svg className="w-4 h-4" viewBox="0 0 24 24">
+                    <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" />
+                    <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" />
+                    <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" />
+                    <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" />
+                  </svg>
+                )}
+                <span>Continue with Google</span>
+              </button>
+
+              <button
+                onClick={() => handleSocialSignIn('github')}
+                disabled={!!loadingProvider}
+                className="w-full bg-gray-900 dark:bg-gray-800 hover:bg-gray-800 dark:hover:bg-gray-750 text-white py-2 px-3 rounded flex items-center justify-center gap-2 text-sm font-medium transition-all disabled:opacity-50"
+              >
+                {loadingProvider === 'github' ? (
+                  <div className="w-4 h-4 border-2 border-white/30 border-t-white rounded-full animate-spin" />
+                ) : (
+                  <svg className="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
+                    <path fillRule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clipRule="evenodd" />
+                  </svg>
+                )}
+                <span>Continue with GitHub</span>
+              </button>
+            </div>
+          )}
+
+          {/* Divider */}
+          {showSocial && showEmailPassword && (
+            <div className="relative">
+              <div className="absolute inset-0 flex items-center">
+                <div className="w-full border-t border-gray-300 dark:border-gray-700" />
+              </div>
+              <div className="relative flex justify-center text-xs uppercase">
+                <span className="bg-white dark:bg-gray-900 px-2 text-gray-500 dark:text-gray-400">
+                  Or continue with email
+                </span>
+              </div>
+            </div>
+          )}
+
+          {/* Email/Password form */}
+          {showEmailPassword && (
+            <form onSubmit={handleEmailSubmit} className="space-y-4">
+              {mode === 'signup' && (
+              <div className="space-y-2">
+                <label className="text-sm font-medium text-gray-700 dark:text-gray-300">Full name</label>
+                <input
+                  type="text"
+                  value={name}
+                  onChange={(e) => setName(e.target.value)}
+                  className="w-full px-3 py-2 rounded-md border border-gray-300 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-900 dark:text-white"
+                  placeholder="John Doe"
+                  disabled={isLoading}
+                />
+              </div>
+              )}
+
+              <div className="space-y-2">
+                <label className="text-sm font-medium text-gray-700 dark:text-gray-300">Email</label>
+                <input
+                  type="email"
+                  value={email}
+                  onChange={(e) => setEmail(e.target.value)}
+                  className="w-full px-3 py-2 rounded-md border border-gray-300 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-900 dark:text-white"
+                  placeholder="you@example.com"
+                  disabled={isLoading}
+                />
+              </div>
+
+              <div className="space-y-2">
+                <label className="text-sm font-medium text-gray-700 dark:text-gray-300">Password</label>
+                <input
+                  type="password"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  className="w-full px-3 py-2 rounded-md border border-gray-300 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-900 dark:text-white"
+                  placeholder="••••••••"
+                  disabled={isLoading}
+                />
+              </div>
+
+              <button
+                type="submit"
+                disabled={isLoading}
+                className="w-full py-2 px-4 rounded-md font-medium text-white transition-all"
+                style={{ backgroundColor: primaryColor }}
+              >
+                {isLoading ? 'Processing...' : mode === 'signin' ? 'Sign in' : 'Create account'}
+              </button>
+            </form>
+          )}
+
+          {/* Toggle mode */}
+          <div className="text-center text-sm">
+            <span className="text-gray-600 dark:text-gray-400">
+              {mode === 'signin' ? "Don't have an account?" : 'Already have an account?'}
+            </span>
+            {' '}
+            <button
+              onClick={() => setMode(mode === 'signin' ? 'signup' : 'signin')}
+              className="font-medium hover:underline"
+              style={{ color: primaryColor }}
+            >
+              {mode === 'signin' ? 'Sign up' : 'Sign in'}
+            </button>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}