Authentication Sessions

/**
 * Opens secure authentication session with redirect handling
 * @param url - The login page URL to open
 * @param redirectUrl - Optional URL to deep link back into your app
 * @param options - Optional configuration extending WebBrowserOpenOptions
 * @returns Promise resolving to:
 * - { type: 'success', url: string } if authentication succeeds with redirect URL
 * - { type: 'cancel' } if user cancels or closes browser
 * - { type: 'dismiss' } if dismissed programmatically
 */
function openAuthSessionAsync(
  url: string,
  redirectUrl?: string | null,
  options?: AuthSessionOpenOptions
): Promise<WebBrowserAuthSessionResult>;

import * as WebBrowser from 'expo-web-browser';

// Basic OAuth flow
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://accounts.google.com/oauth/authorize?client_id=...',
  'myapp://redirect'
);

if (authResult.type === 'success') {
  const redirectUrl = authResult.url;
  // Parse redirect URL for auth tokens
  const url = new URL(redirectUrl);
  const code = url.searchParams.get('code');
  console.log('Authorization code:', code);
}

// With ephemeral session (iOS only)
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://example.com/login',
  'myapp://auth',
  {
    preferEphemeralSession: true, // Doesn't share cookies with browser
    presentationStyle: WebBrowser.WebBrowserPresentationStyle.PAGE_SHEET
  }
);

// Web-specific authentication
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://oauth.provider.com/auth?redirect_uri=https://mysite.com/callback',
  null, // Auto-generated from Linking.createURL("")
  {
    windowName: 'OAuth',
    windowFeatures: { width: 500, height: 600 }
  }
);

/**
 * Dismisses the current authentication session
 * @platform ios
 * @platform web
 */
function dismissAuthSession(): void;

import * as WebBrowser from 'expo-web-browser';

// Start auth session
const authPromise = WebBrowser.openAuthSessionAsync(
  'https://accounts.google.com/oauth/authorize?...',
  'myapp://redirect'
);

// Cancel after timeout
setTimeout(() => {
  try {
    WebBrowser.dismissAuthSession();
    console.log('Auth session dismissed');
  } catch (error) {
    console.log('Dismiss not available on this platform');
  }
}, 30000);

const result = await authPromise;
console.log('Auth result:', result);

/**
 * Completes authentication session on web platform
 * @param options - Optional configuration for completion
 * @returns Result object indicating success or failure with descriptive message
 * @platform web
 */
function maybeCompleteAuthSession(
  options?: WebBrowserCompleteAuthSessionOptions
): WebBrowserCompleteAuthSessionResult;

import * as WebBrowser from 'expo-web-browser';

// On the redirect page (e.g., https://mysite.com/auth-callback)
const result = WebBrowser.maybeCompleteAuthSession();

if (result.type === 'success') {
  console.log('Auth completed successfully:', result.message);
  // Parent window will close this popup automatically
} else {
  console.log('Auth completion failed:', result.message);
  // Handle various error cases:
  // - "Not supported on this platform"
  // - "Cannot use expo-web-browser in a non-browser environment"  
  // - "No auth session is currently in progress"
  // - "Current URL and original redirect URL do not match"
}

// Skip redirect URL validation in development
const result = WebBrowser.maybeCompleteAuthSession({
  skipRedirectCheck: true
});

interface AuthSessionOpenOptions extends WebBrowserOpenOptions {
  /**
   * Request private authentication session that doesn't share cookies
   * with the user's normal browser session
   * @default false
   * @platform ios
   */
  preferEphemeralSession?: boolean;
}

interface WebBrowserCompleteAuthSessionOptions {
  /**
   * Skip checking if redirect URL matches cached redirect URL
   * Useful for development environments
   */
  skipRedirectCheck?: boolean;
}

interface WebBrowserCompleteAuthSessionResult {
  /** Type of the result: 'success' or 'failed' */
  type: 'success' | 'failed';
  /** Additional description or reasoning of the result */
  message: string;
}