@fastshot/auth 1.0.1 → 1.0.3

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@fastshot/auth",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "OAuth authentication SDK for Expo React Native applications with Supabase",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
   "repository": {
     "type": "git",
     "directory": "packages/fastshot-auth"
@@ -34,6 +33,6 @@
     "typescript": "~5.9.2"
   },
   "files": [
-    "dist"
+    "src"
   ]
 }

package/src/auth.ts

@@ -0,0 +1,216 @@
+/**
+ * Core authentication functions for OAuth with auth-broker
+ */
+
+import * as WebBrowser from 'expo-web-browser';
+import type { SupabaseClient, Session } from '@supabase/supabase-js';
+import { AUTH_CONFIG } from './constants';
+import type {
+  OAuthProvider,
+  AuthMode,
+  AuthCallbackResult,
+  AuthError,
+} from './types';
+import {
+  getDefaultCallbackUrl,
+  parseCallbackUrl,
+  isAuthCallbackUrl,
+  buildOAuthStartUrl,
+  exchangeTicket,
+  restoreSession,
+  createAuthError,
+} from './utils';
+
+/**
+ * Get the project ID from environment variables
+ */
+function getProjectId(): string {
+  const projectId = AUTH_CONFIG.PROJECT_ID;
+
+  if (!projectId) {
+    throw createAuthError(
+      'UNKNOWN_ERROR',
+      'Project ID not found. Ensure EXPO_PUBLIC_PROJECT_ID is set in your .env file.'
+    );
+  }
+
+  return projectId;
+}
+
+/**
+ * Configuration for sign-in function
+ */
+export interface SignInOptions {
+  /** Supabase client for session restoration */
+  supabaseClient: SupabaseClient;
+  /** Custom return URL (defaults to fastshot://auth/callback) */
+  returnTo?: string;
+  /** Auth mode: 'browser' (default) or 'webview' */
+  mode?: AuthMode;
+  /** Email hint for Google sign-in */
+  loginHint?: string;
+}
+
+/**
+ * Sign in with Google OAuth
+ *
+ * Opens the system browser to initiate Google OAuth flow via auth-broker.
+ * After successful authentication, the browser redirects back to the app.
+ *
+ * @example
+ * ```typescript
+ * import { signInWithGoogle } from '@fastshot/auth';
+ * import { supabase } from './lib/supabase';
+ *
+ * await signInWithGoogle({ supabaseClient: supabase });
+ * ```
+ */
+export async function signInWithGoogle(options: SignInOptions): Promise<void> {
+  return signInWithProvider('google', options);
+}
+
+/**
+ * Sign in with Apple OAuth
+ *
+ * Opens the system browser to initiate Apple OAuth flow via auth-broker.
+ * After successful authentication, the browser redirects back to the app.
+ *
+ * @example
+ * ```typescript
+ * import { signInWithApple } from '@fastshot/auth';
+ * import { supabase } from './lib/supabase';
+ *
+ * await signInWithApple({ supabaseClient: supabase });
+ * ```
+ */
+export async function signInWithApple(options: SignInOptions): Promise<void> {
+  return signInWithProvider('apple', options);
+}
+
+/**
+ * Generic sign-in with OAuth provider
+ */
+async function signInWithProvider(
+  provider: OAuthProvider,
+  options: SignInOptions
+): Promise<void> {
+  const {
+    supabaseClient,
+    returnTo = getDefaultCallbackUrl(),
+    mode = 'browser',
+    loginHint,
+  } = options;
+
+  const projectId = getProjectId();
+
+  const authUrl = buildOAuthStartUrl(provider, {
+    tenant: projectId,
+    returnTo,
+    mode,
+    loginHint,
+  });
+
+  // Open browser for OAuth flow
+  const result = await WebBrowser.openAuthSessionAsync(authUrl, returnTo);
+
+  if (result.type === 'cancel' || result.type === 'dismiss') {
+    throw createAuthError('BROWSER_DISMISSED', 'Authentication was cancelled');
+  }
+
+  // Handle successful auth callback and restore session
+  if (result.type === 'success' && result.url) {
+    const callbackResult = await handleAuthCallback(result.url, supabaseClient);
+    if (!callbackResult.success) {
+      throw createAuthError('UNKNOWN_ERROR', callbackResult.error || 'Failed to complete authentication');
+    }
+  }
+}
+
+/**
+ * Handle OAuth callback URL and restore session
+ *
+ * Call this when your app receives a deep link callback from OAuth.
+ * This function exchanges the ticket for tokens and restores the Supabase session.
+ *
+ * @example
+ * ```typescript
+ * import { handleAuthCallback } from '@fastshot/auth';
+ * import { supabase } from './lib/supabase';
+ * import * as Linking from 'expo-linking';
+ *
+ * Linking.addEventListener('url', async ({ url }) => {
+ *   const result = await handleAuthCallback(url, supabase);
+ *   if (result.success) {
+ *     console.log('Logged in as:', result.user?.email);
+ *   }
+ * });
+ * ```
+ */
+export async function handleAuthCallback(
+  url: string,
+  supabaseClient: SupabaseClient
+): Promise<AuthCallbackResult> {
+  // Check if this is an auth callback URL
+  if (!isAuthCallbackUrl(url)) {
+    return {
+      success: false,
+      error: 'Not an auth callback URL',
+    };
+  }
+
+  const { ticket, error, errorDescription } = parseCallbackUrl(url);
+
+  // Handle OAuth error from auth-broker
+  if (error) {
+    return {
+      success: false,
+      error: errorDescription || error,
+    };
+  }
+
+  // No ticket means something went wrong
+  if (!ticket) {
+    return {
+      success: false,
+      error: 'No ticket in callback URL',
+    };
+  }
+
+  try {
+    // Exchange ticket for session tokens
+    const exchangeResponse = await exchangeTicket(ticket);
+
+    // Restore session to Supabase client
+    const session = await restoreSession(supabaseClient, exchangeResponse);
+
+    return {
+      success: true,
+      session,
+      user: session.user,
+    };
+  } catch (err) {
+    const authError = err as AuthError;
+    return {
+      success: false,
+      error: authError.message || 'Failed to complete authentication',
+    };
+  }
+}
+
+/**
+ * Sign out from Supabase
+ *
+ * @example
+ * ```typescript
+ * import { signOut } from '@fastshot/auth';
+ * import { supabase } from './lib/supabase';
+ *
+ * await signOut(supabase);
+ * ```
+ */
+export async function signOut(supabaseClient: SupabaseClient): Promise<void> {
+  const { error } = await supabaseClient.auth.signOut();
+  if (error) {
+    throw createAuthError('UNKNOWN_ERROR', `Sign out failed: ${error.message}`, error);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,56 @@
+/**
+ * Get environment variable with fallback
+ * Works in both React Native (process.env.EXPO_PUBLIC_*) and Node.js environments
+ */
+function getEnvVar(key: string, fallback: string): string {
+  // React Native / Expo environment
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[key] || fallback;
+  }
+  return fallback;
+}
+
+/**
+ * Auth Broker configuration
+ * URLs are read from environment variables at runtime
+ *
+ * Required env vars:
+ * - EXPO_PUBLIC_AUTH_BROKER_URL: Auth broker service URL
+ * - EXPO_PUBLIC_PROJECT_ID: Fastshot project ID
+ */
+export const AUTH_CONFIG = {
+  /** Auth broker URL - must be set via EXPO_PUBLIC_AUTH_BROKER_URL */
+  get AUTH_BROKER_URL(): string {
+    return getEnvVar('EXPO_PUBLIC_AUTH_BROKER_URL', '');
+  },
+  /** Project ID for authentication */
+  get PROJECT_ID(): string | undefined {
+    return getEnvVar('EXPO_PUBLIC_PROJECT_ID', '');
+  },
+  /** Deep link scheme for OAuth callback */
+  DEEP_LINK_SCHEME: 'fastshot',
+  /** Callback path for OAuth */
+  CALLBACK_PATH: 'auth/callback',
+} as const;
+
+/**
+ * OAuth endpoints on the auth broker
+ */
+export const AUTH_ENDPOINTS = {
+  GOOGLE_START: '/v1/auth/google/start',
+  APPLE_START: '/v1/auth/apple/start',
+  EXCHANGE_TICKET: '/v1/auth/exchange',
+} as const;
+
+/**
+ * Supported OAuth providers
+ */
+export type OAuthProvider = 'google' | 'apple';
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_AUTH_CONFIG = {
+  TIMEOUT: 30000, // 30 seconds
+  MODE: 'browser' as const,
+} as const;

package/{dist/hooks/index.d.ts → src/hooks/index.ts}

@@ -1,7 +1,8 @@
 export { useGoogleSignIn } from './useGoogleSignIn';
 export type { UseGoogleSignInConfig, UseGoogleSignInResult } from './useGoogleSignIn';
+
 export { useAppleSignIn } from './useAppleSignIn';
 export type { UseAppleSignInConfig, UseAppleSignInResult } from './useAppleSignIn';
+
 export { useAuthCallback } from './useAuthCallback';
 export type { UseAuthCallbackConfig, UseAuthCallbackResult } from './useAuthCallback';
-//# sourceMappingURL=index.d.ts.map

package/src/hooks/useAppleSignIn.ts

@@ -0,0 +1,92 @@
+import { useState, useCallback } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { signInWithApple } from '../auth';
+import type { AuthError, AuthMode } from '../types';
+import { isAuthError, createAuthError } from '../utils';
+
+export interface UseAppleSignInConfig {
+  /** Supabase client instance */
+  supabaseClient: SupabaseClient;
+  /** Custom return URL */
+  returnTo?: string;
+  /** Auth mode */
+  mode?: AuthMode;
+  /** Callback on error */
+  onError?: (error: AuthError) => void;
+}
+
+export interface UseAppleSignInResult {
+  /** Trigger Apple sign-in */
+  signIn: () => Promise<void>;
+  /** Whether sign-in is in progress */
+  isLoading: boolean;
+  /** Error from last sign-in attempt */
+  error: AuthError | null;
+  /** Reset error state */
+  reset: () => void;
+}
+
+/**
+ * React hook for Apple sign-in with auth-broker
+ *
+ * @example
+ * ```tsx
+ * import { useAppleSignIn } from '@fastshot/auth';
+ * import { supabase } from '../lib/supabase';
+ *
+ * function LoginScreen() {
+ *   const { signIn, isLoading, error } = useAppleSignIn({
+ *     supabaseClient: supabase,
+ *   });
+ *
+ *   return (
+ *     <Button
+ *       title={isLoading ? 'Signing in...' : 'Sign in with Apple'}
+ *       onPress={signIn}
+ *       disabled={isLoading}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useAppleSignIn(config: UseAppleSignInConfig): UseAppleSignInResult {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<AuthError | null>(null);
+
+  const signIn = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await signInWithApple({
+        supabaseClient: config.supabaseClient,
+        returnTo: config.returnTo,
+        mode: config.mode,
+      });
+    } catch (err) {
+      const authError = isAuthError(err)
+        ? err
+        : createAuthError(
+            'UNKNOWN_ERROR',
+            err instanceof Error ? err.message : 'Unknown error',
+            err
+          );
+
+      setError(authError);
+      config.onError?.(authError);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [config]);
+
+  const reset = useCallback(() => {
+    setError(null);
+  }, []);
+
+  return {
+    signIn,
+    isLoading,
+    error,
+    reset,
+  };
+}

package/src/hooks/useAuthCallback.ts

@@ -0,0 +1,135 @@
+import { useState, useEffect, useCallback } from 'react';
+import * as Linking from 'expo-linking';
+import type { SupabaseClient, Session, User } from '@supabase/supabase-js';
+import { handleAuthCallback } from '../auth';
+import { isAuthCallbackUrl } from '../utils';
+import type { AuthError, AuthCallbackResult } from '../types';
+import { createAuthError } from '../utils';
+
+export interface UseAuthCallbackConfig {
+  /** Supabase client instance */
+  supabaseClient: SupabaseClient;
+  /** Callback when authentication succeeds */
+  onSuccess?: (result: { session: Session; user: User }) => void;
+  /** Callback when authentication fails */
+  onError?: (error: AuthError) => void;
+  /** Whether to automatically listen for deep links (default: true) */
+  autoListen?: boolean;
+}
+
+export interface UseAuthCallbackResult {
+  /** Whether callback is being processed */
+  isProcessing: boolean;
+  /** Error if callback processing failed */
+  error: AuthError | null;
+  /** Manually handle a callback URL */
+  handleUrl: (url: string) => Promise<AuthCallbackResult>;
+}
+
+/**
+ * React hook to handle OAuth callback deep links
+ *
+ * This hook automatically listens for deep link callbacks and restores
+ * the Supabase session when authentication completes.
+ *
+ * @example
+ * ```tsx
+ * import { useAuthCallback } from '@fastshot/auth';
+ * import { supabase } from '../lib/supabase';
+ *
+ * function App() {
+ *   const { isProcessing, error } = useAuthCallback({
+ *     supabaseClient: supabase,
+ *     onSuccess: ({ user }) => {
+ *       console.log('Logged in:', user.email);
+ *       navigation.navigate('Home');
+ *     },
+ *     onError: (error) => {
+ *       Alert.alert('Login Failed', error.message);
+ *     },
+ *   });
+ *
+ *   if (isProcessing) {
+ *     return <LoadingScreen message="Completing sign-in..." />;
+ *   }
+ *
+ *   return <MainApp />;
+ * }
+ * ```
+ */
+export function useAuthCallback(config: UseAuthCallbackConfig): UseAuthCallbackResult {
+  const { supabaseClient, onSuccess, onError, autoListen = true } = config;
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [error, setError] = useState<AuthError | null>(null);
+
+  const handleUrl = useCallback(
+    async (url: string): Promise<AuthCallbackResult> => {
+      // Skip if not an auth callback URL
+      if (!isAuthCallbackUrl(url)) {
+        return { success: false, error: 'Not an auth callback URL' };
+      }
+
+      setIsProcessing(true);
+      setError(null);
+
+      try {
+        const result = await handleAuthCallback(url, supabaseClient);
+
+        if (result.success && result.session && result.user) {
+          onSuccess?.({ session: result.session, user: result.user });
+        } else if (!result.success && result.error) {
+          const authError = createAuthError('CALLBACK_ERROR', result.error);
+          setError(authError);
+          onError?.(authError);
+        }
+
+        return result;
+      } catch (err) {
+        const authError = createAuthError(
+          'CALLBACK_ERROR',
+          err instanceof Error ? err.message : 'Failed to process callback',
+          err
+        );
+        setError(authError);
+        onError?.(authError);
+
+        return { success: false, error: authError.message };
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [supabaseClient, onSuccess, onError]
+  );
+
+  // Auto-listen for deep links
+  useEffect(() => {
+    if (!autoListen) return;
+
+    // Handle URL that opened the app
+    const checkInitialUrl = async () => {
+      const initialUrl = await Linking.getInitialURL();
+      if (initialUrl && isAuthCallbackUrl(initialUrl)) {
+        handleUrl(initialUrl);
+      }
+    };
+
+    checkInitialUrl();
+
+    // Listen for incoming URLs while app is running
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      if (isAuthCallbackUrl(url)) {
+        handleUrl(url);
+      }
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, [autoListen, handleUrl]);
+
+  return {
+    isProcessing,
+    error,
+    handleUrl,
+  };
+}

package/src/hooks/useGoogleSignIn.ts

@@ -0,0 +1,95 @@
+import { useState, useCallback } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { signInWithGoogle } from '../auth';
+import type { AuthError, AuthMode } from '../types';
+import { isAuthError, createAuthError } from '../utils';
+
+export interface UseGoogleSignInConfig {
+  /** Supabase client instance */
+  supabaseClient: SupabaseClient;
+  /** Custom return URL */
+  returnTo?: string;
+  /** Auth mode */
+  mode?: AuthMode;
+  /** Email hint */
+  loginHint?: string;
+  /** Callback on error */
+  onError?: (error: AuthError) => void;
+}
+
+export interface UseGoogleSignInResult {
+  /** Trigger Google sign-in */
+  signIn: () => Promise<void>;
+  /** Whether sign-in is in progress */
+  isLoading: boolean;
+  /** Error from last sign-in attempt */
+  error: AuthError | null;
+  /** Reset error state */
+  reset: () => void;
+}
+
+/**
+ * React hook for Google sign-in with auth-broker
+ *
+ * @example
+ * ```tsx
+ * import { useGoogleSignIn } from '@fastshot/auth';
+ * import { supabase } from '../lib/supabase';
+ *
+ * function LoginScreen() {
+ *   const { signIn, isLoading, error } = useGoogleSignIn({
+ *     supabaseClient: supabase,
+ *   });
+ *
+ *   return (
+ *     <Button
+ *       title={isLoading ? 'Signing in...' : 'Sign in with Google'}
+ *       onPress={signIn}
+ *       disabled={isLoading}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useGoogleSignIn(config: UseGoogleSignInConfig): UseGoogleSignInResult {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<AuthError | null>(null);
+
+  const signIn = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await signInWithGoogle({
+        supabaseClient: config.supabaseClient,
+        returnTo: config.returnTo,
+        mode: config.mode,
+        loginHint: config.loginHint,
+      });
+    } catch (err) {
+      const authError = isAuthError(err)
+        ? err
+        : createAuthError(
+            'UNKNOWN_ERROR',
+            err instanceof Error ? err.message : 'Unknown error',
+            err
+          );
+
+      setError(authError);
+      config.onError?.(authError);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [config]);
+
+  const reset = useCallback(() => {
+    setError(null);
+  }, []);
+
+  return {
+    signIn,
+    isLoading,
+    error,
+    reset,
+  };
+}

package/{dist/index.js → src/index.ts}

@@ -51,11 +51,50 @@
  * const result = await handleAuthCallback(url, supabase);
  * ```
  */
+
 // Core auth functions
-export { signInWithGoogle, signInWithApple, handleAuthCallback, signOut, } from './auth';
+export {
+  signInWithGoogle,
+  signInWithApple,
+  handleAuthCallback,
+  signOut,
+} from './auth';
+export type { SignInOptions } from './auth';
+
 // React hooks
-export { useGoogleSignIn, useAppleSignIn, useAuthCallback, } from './hooks';
+export {
+  useGoogleSignIn,
+  useAppleSignIn,
+  useAuthCallback,
+} from './hooks';
+export type {
+  UseGoogleSignInConfig,
+  UseGoogleSignInResult,
+  UseAppleSignInConfig,
+  UseAppleSignInResult,
+  UseAuthCallbackConfig,
+  UseAuthCallbackResult,
+} from './hooks';
+
 // Utilities (for advanced usage)
-export { exchangeTicket, isAuthCallbackUrl, parseCallbackUrl, getDefaultCallbackUrl, createAuthError, isAuthError, } from './utils';
+export {
+  exchangeTicket,
+  isAuthCallbackUrl,
+  parseCallbackUrl,
+  getDefaultCallbackUrl,
+  createAuthError,
+  isAuthError,
+} from './utils';
+
+// Types
+export type {
+  OAuthProvider,
+  AuthMode,
+  AuthError,
+  AuthErrorType,
+  AuthCallbackResult,
+  ExchangeTicketResponse,
+} from './types';
+
 // Constants (for debugging/customization)
 export { AUTH_CONFIG, AUTH_ENDPOINTS } from './constants';