godgpt-web-auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+interface AuthConfig {
+    /** Backend API URL for token exchange */
+    backendUrl: string;
+    /** Google OAuth configuration */
+    google?: {
+        clientId: string;
+        scopes?: string[];
+    };
+    /** Apple Sign-In configuration */
+    apple?: {
+        clientId: string;
+        redirectUri?: string;
+    };
+    /** Email auth configuration */
+    email?: {
+        enabled: boolean;
+    };
+    /** App identification for backend */
+    appId?: string;
+}
+type AuthProviderType = "google" | "apple" | "password";
+interface JWTData {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type: string;
+}
+interface AuthResult {
+    success: boolean;
+    state: "success" | "cancelled" | "error";
+    tokens: JWTData | null;
+    message?: string;
+    provider?: AuthProviderType;
+}
+interface AuthError {
+    provider: AuthProviderType;
+    code: string;
+    message: string;
+}
+interface AuthCallbacks {
+    /**
+     * Called when user logs out or tokens are invalid on mount.
+     * Use this to redirect to login, clear app state, etc.
+     */
+    onLogout?: () => void;
+}
+/**
+ * Public API exposed by useAuth() hook.
+ * Intentionally minimal - only what consumers need.
+ */
+interface AuthContextValue {
+    /** Current JWT tokens, null if not authenticated */
+    tokens: JWTData | null;
+    /** Logout and clear tokens. Triggers onLogout callback. */
+    logout: () => Promise<void>;
+    /** True while a login operation is in progress */
+    isLoading: boolean;
+    /** True once initial token load from storage is complete */
+    isAuthLoaded: boolean;
+}
+interface TokenRequestParams {
+    id_token?: string;
+    code?: string;
+    username?: string;
+    password?: string;
+}
+
+interface AuthProviderProps {
+    children: React.ReactNode;
+    /** Auth configuration with backend URL and provider settings */
+    config: AuthConfig;
+    /**
+     * Called when user logs out or tokens are invalid on mount.
+     * Use this to redirect, clear app state, etc.
+     */
+    onLogout?: () => void;
+}
+/**
+ * AuthProvider - Wraps your app to provide authentication state.
+ *
+ * @example
+ * ```tsx
+ * <AuthProvider
+ *   config={{
+ *     backendUrl: import.meta.env.VITE_AUTH_BACKEND_URL,
+ *     google: { clientId: import.meta.env.VITE_GOOGLE_CLIENT_ID },
+ *     apple: { clientId: import.meta.env.VITE_APPLE_CLIENT_ID },
+ *   }}
+ *   onLogout={() => router.push('/')}
+ * >
+ *   <App />
+ * </AuthProvider>
+ * ```
+ */
+declare function AuthProvider({ children, config, onLogout, }: AuthProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * LoginPage - Complete login UI component.
+ * Gets config from AuthProvider context.
+ * Handles Google, Apple, and Email sign-in.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { tokens, isAuthLoaded } = useAuth();
+ *
+ *   if (!isAuthLoaded) return <SplashScreen />;
+ *   if (!tokens) return <LoginPage />;
+ *   return <MainApp />;
+ * }
+ * ```
+ */
+declare function LoginPage(): react_jsx_runtime.JSX.Element;
+
+/**
+ * useAuth - Public hook for consumers.
+ * Returns only the public API (tokens, logout, isLoading, isAuthLoaded).
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { tokens, logout, isLoading, isAuthLoaded } = useAuth();
+ *
+ *   if (!isAuthLoaded) return <SplashScreen />;
+ *   if (!tokens) return <LoginPage />;
+ *   return <MainApp onLogout={logout} />;
+ * }
+ * ```
+ */
+declare function useAuth(): AuthContextValue;
+
+/**
+ * Sign in with email and password.
+ * Sends credentials to backend for authentication.
+ *
+ * @param email - User's email address
+ * @param password - User's password
+ * @param config - Auth configuration with backendUrl
+ * @returns AuthResult with tokens on success
+ */
+declare function signInWithEmail(email: string, password: string, config: AuthConfig): Promise<AuthResult>;
+
+declare global {
+    interface Window {
+        google?: {
+            accounts: {
+                id: {
+                    initialize: (config: GoogleInitConfig) => void;
+                    prompt: (callback?: (notification: PromptNotification) => void) => void;
+                    renderButton: (element: HTMLElement, config: ButtonConfig) => void;
+                    revoke: (hint: string, callback: () => void) => void;
+                    cancel: () => void;
+                };
+            };
+        };
+    }
+}
+interface GoogleInitConfig {
+    client_id: string;
+    callback: (response: GoogleCredentialResponse) => void;
+    auto_select?: boolean;
+    cancel_on_tap_outside?: boolean;
+    context?: "signin" | "signup" | "use";
+    ux_mode?: "popup" | "redirect";
+    login_uri?: string;
+    nonce?: string;
+    use_fedcm_for_prompt?: boolean;
+}
+interface GoogleCredentialResponse {
+    credential: string;
+    select_by?: string;
+    clientId?: string;
+}
+interface PromptNotification {
+    isNotDisplayed: () => boolean;
+    isSkippedMoment: () => boolean;
+    isDismissedMoment: () => boolean;
+    getNotDisplayedReason: () => string;
+    getSkippedReason: () => string;
+    getDismissedReason: () => string;
+}
+interface ButtonConfig {
+    type?: "standard" | "icon";
+    theme?: "outline" | "filled_blue" | "filled_black";
+    size?: "large" | "medium" | "small";
+    text?: "signin_with" | "signup_with" | "continue_with" | "signin";
+    shape?: "rectangular" | "pill" | "circle" | "square";
+    logo_alignment?: "left" | "center";
+    width?: number;
+    locale?: string;
+}
+/**
+ * Load Google Identity Services SDK
+ */
+declare function loadGoogleSDK(): Promise<void>;
+/**
+ * Sign in with Google using Google Identity Services.
+ * Uses One Tap flow with popup fallback.
+ *
+ * @param config - Auth configuration with Google client ID
+ * @returns AuthResult with tokens on success
+ */
+declare function signInWithGoogle(config: AuthConfig): Promise<AuthResult>;
+
+declare global {
+    interface Window {
+        AppleID?: {
+            auth: {
+                init: (config: AppleInitConfig) => void;
+                signIn: (config?: AppleSignInConfig) => Promise<AppleSignInResponse>;
+            };
+        };
+    }
+}
+interface AppleInitConfig {
+    clientId: string;
+    scope?: string;
+    redirectURI: string;
+    state?: string;
+    nonce?: string;
+    usePopup?: boolean;
+}
+interface AppleSignInConfig {
+    scope?: string;
+    state?: string;
+    nonce?: string;
+}
+interface AppleSignInResponse {
+    authorization: {
+        code: string;
+        id_token?: string;
+        state?: string;
+    };
+    user?: {
+        email?: string;
+        name?: {
+            firstName?: string;
+            lastName?: string;
+        };
+    };
+}
+/**
+ * Load Apple Sign In JS SDK
+ */
+declare function loadAppleSDK(): Promise<void>;
+/**
+ * Sign in with Apple using Apple Sign In JS.
+ *
+ * @param config - Auth configuration with Apple client ID
+ * @returns AuthResult with tokens on success
+ */
+declare function signInWithApple(config: AuthConfig): Promise<AuthResult>;
+
+/**
+ * Validate auth configuration.
+ * Called by AuthProvider on mount.
+ */
+declare function validateConfig(config: AuthConfig): void;
+
+/**
+ * Interface for custom storage adapters.
+ * Implement this to use your own storage (Redux, Zustand, AsyncStorage, etc.)
+ */
+interface StorageAdapter {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+}
+/**
+ * Default localStorage adapter for web
+ */
+declare const localStorageAdapter: StorageAdapter;
+/**
+ * Memory adapter for SSR or testing
+ */
+declare const memoryStorageAdapter: () => StorageAdapter;
+/**
+ * Creates a storage service with the provided adapter.
+ * Reusable token logic with pluggable storage backend.
+ */
+declare function createStorageService(adapter: StorageAdapter): {
+    /**
+     * Save tokens to storage
+     */
+    saveTokens(tokens: JWTData): Promise<void>;
+    /**
+     * Get tokens from storage
+     * Returns null if no tokens exist or if they're invalid
+     */
+    getTokens(): Promise<JWTData | null>;
+    /**
+     * Get raw stored data (including metadata like stored_at)
+     */
+    getRawData(): Promise<{
+        tokens: JWTData;
+        stored_at: number;
+    } | null>;
+    /**
+     * Clear tokens from storage
+     */
+    clearTokens(): Promise<void>;
+    /**
+     * Check if tokens exist in storage
+     */
+    hasTokens(): Promise<boolean>;
+    /**
+     * Check if stored tokens are expired
+     * Uses expires_in from the token data
+     */
+    isTokenExpired(): Promise<boolean>;
+    /**
+     * Get the time until token expires (in milliseconds)
+     * Returns 0 if token is expired or doesn't exist
+     */
+    getTimeUntilExpiry(): Promise<number>;
+};
+type StorageService = ReturnType<typeof createStorageService>;
+/**
+ * Default storage service using localStorage.
+ * For custom storage, use createStorageService(yourAdapter) instead.
+ */
+declare const storageService: {
+    /**
+     * Save tokens to storage
+     */
+    saveTokens(tokens: JWTData): Promise<void>;
+    /**
+     * Get tokens from storage
+     * Returns null if no tokens exist or if they're invalid
+     */
+    getTokens(): Promise<JWTData | null>;
+    /**
+     * Get raw stored data (including metadata like stored_at)
+     */
+    getRawData(): Promise<{
+        tokens: JWTData;
+        stored_at: number;
+    } | null>;
+    /**
+     * Clear tokens from storage
+     */
+    clearTokens(): Promise<void>;
+    /**
+     * Check if tokens exist in storage
+     */
+    hasTokens(): Promise<boolean>;
+    /**
+     * Check if stored tokens are expired
+     * Uses expires_in from the token data
+     */
+    isTokenExpired(): Promise<boolean>;
+    /**
+     * Get the time until token expires (in milliseconds)
+     * Returns 0 if token is expired or doesn't exist
+     */
+    getTimeUntilExpiry(): Promise<number>;
+};
+
+/**
+ * Exchange provider credentials for JWT tokens from the backend.
+ * @param params - Auth parameters (id_token, code, username/password)
+ * @param provider - The auth provider type
+ * @param config - Auth configuration with backendUrl
+ */
+declare function exchangeToken(params: TokenRequestParams, provider: AuthProviderType, config: AuthConfig): Promise<AuthResult>;
+/**
+ * Refresh an expired access token using the refresh token.
+ * @param refresh_token - The refresh token
+ * @param backendUrl - The backend API URL
+ */
+declare function refreshToken(refresh_token: string, backendUrl: string): Promise<JWTData | null>;
+
+export { type AuthCallbacks, type AuthConfig, type AuthContextValue, type AuthError, AuthProvider, type AuthProviderType, type AuthResult, type JWTData, LoginPage, type StorageAdapter, type StorageService, createStorageService, exchangeToken, loadAppleSDK, loadGoogleSDK, localStorageAdapter, memoryStorageAdapter, refreshToken, signInWithApple, signInWithEmail, signInWithGoogle, storageService, useAuth, validateConfig };