@blinkdotnew/sdk 0.19.4 → 0.19.5

package/README.md

@@ -195,48 +195,167 @@ const blink = createClient({
 
 The SDK has **first-class React Native support** with platform-aware features that automatically adapt to mobile environments.
 
+#### Step 1: Install Dependencies
+
 ```bash
-npm install @blinkdotnew/sdk @react-native-async-storage/async-storage
+npm install @blinkdotnew/sdk @react-native-async-storage/async-storage expo-web-browser
 ```
 
+**Required packages:**
+- `@blinkdotnew/sdk` - The Blink SDK
+- `@react-native-async-storage/async-storage` - For token persistence
+- `expo-web-browser` - For OAuth authentication (Google, GitHub, Apple, etc.)
+
+#### Step 2: Create Client (`lib/blink.ts`)
+
+**⚠️ IMPORTANT: You MUST pass `webBrowser: WebBrowser` to enable OAuth on mobile!**
+
 ```typescript
+// lib/blink.ts
 import { createClient, AsyncStorageAdapter } from '@blinkdotnew/sdk'
 import AsyncStorage from '@react-native-async-storage/async-storage'
+import * as WebBrowser from 'expo-web-browser'  // ← Import this
 
-const blink = createClient({
+export const blink = createClient({
   projectId: 'your-project-id',
   authRequired: false,
-  // Use AsyncStorage for secure token persistence on mobile
+  auth: {
+    mode: 'headless',
+    webBrowser: WebBrowser  // ← Pass it here! Required for OAuth
+  },
   storage: new AsyncStorageAdapter(AsyncStorage)
 })
+```
 
-// All features work seamlessly in React Native!
-const { data } = await blink.ai.generateImage({
-  prompt: 'A beautiful sunset over mountains',
-  n: 1
+#### Step 3: Use Authentication
+
+**Email/Password (works immediately):**
+```typescript
+// Sign up
+const user = await blink.auth.signUp({ 
+  email: 'user@example.com', 
+  password: 'SecurePass123' 
 })
+
+// Sign in
+const user = await blink.auth.signInWithEmail('user@example.com', 'SecurePass123')
+```
+
+**OAuth (Google, GitHub, Apple, Microsoft):**
+```typescript
+// ✅ Same code works on web, iOS, AND Android!
+const user = await blink.auth.signInWithGoogle()
+const user = await blink.auth.signInWithGitHub()
+const user = await blink.auth.signInWithApple()
+const user = await blink.auth.signInWithMicrosoft()
+```
+
+#### Step 4: Create Auth Hook (`hooks/useAuth.ts`)
+
+```typescript
+// hooks/useAuth.ts
+import { useEffect, useState } from 'react'
+import { blink } from '@/lib/blink'
+import type { BlinkUser } from '@blinkdotnew/sdk'
+
+export function useAuth() {
+  const [user, setUser] = useState<BlinkUser | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+
+  useEffect(() => {
+    const unsubscribe = blink.auth.onAuthStateChanged((state) => {
+      setUser(state.user)
+      setIsLoading(state.isLoading)
+    })
+    return unsubscribe
+  }, [])
+
+  return {
+    user,
+    isLoading,
+    isAuthenticated: !!user,
+    signInWithGoogle: () => blink.auth.signInWithGoogle(),
+    signInWithGitHub: () => blink.auth.signInWithGitHub(),
+    signInWithApple: () => blink.auth.signInWithApple(),
+    signOut: () => blink.auth.signOut(),
+  }
+}
+```
+
+#### Step 5: Use in Components
+
+```typescript
+import { useAuth } from '@/hooks/useAuth'
+import { View, Text, Button } from 'react-native'
+
+function App() {
+  const { user, isLoading, signInWithGoogle, signOut } = useAuth()
+
+  if (isLoading) return <Text>Loading...</Text>
+
+  if (!user) {
+    return <Button onPress={signInWithGoogle} title="Sign in with Google" />
+  }
+
+  return (
+    <View>
+      <Text>Welcome, {user.email}!</Text>
+      <Button onPress={signOut} title="Sign Out" />
+    </View>
+  )
+}
 ```
 
-**Platform-Aware Features:**
-- ✅ **AsyncStorage integration** for secure token persistence
-- ✅ **Automatic platform detection** - skips browser-only features (analytics tracking, cross-tab sync)
-- ✅ **No polyfills needed** - works out of the box
-- ✅ **Optimized for mobile** - reduced memory footprint
+#### Common Mistakes
 
-**Configuration Options:**
 ```typescript
-// With AsyncStorage (recommended for token persistence)
+// ❌ WRONG: Missing webBrowser - OAuth won't work on mobile!
 const blink = createClient({
   projectId: 'your-project-id',
+  auth: { mode: 'headless' },  // Missing webBrowser!
   storage: new AsyncStorageAdapter(AsyncStorage)
 })
 
-// Without persistence (tokens in memory only)
+// ✅ CORRECT: Include webBrowser for OAuth support
+import * as WebBrowser from 'expo-web-browser'
+
 const blink = createClient({
-  projectId: 'your-project-id'
+  projectId: 'your-project-id',
+  auth: { 
+    mode: 'headless',
+    webBrowser: WebBrowser  // ← Required for OAuth!
+  },
+  storage: new AsyncStorageAdapter(AsyncStorage)
+})
+```
+
+#### Low-Level OAuth (For Custom Control)
+
+If you need custom polling timeouts or manual browser handling:
+
+```typescript
+// Get auth URL and authenticate function separately
+const { authUrl, authenticate } = await blink.auth.signInWithProviderMobile('google')
+
+// Open browser manually
+await WebBrowser.openAuthSessionAsync(authUrl)
+
+// Poll with custom options
+const user = await authenticate({
+  maxAttempts: 120,  // 60 seconds (default: 60 = 30 seconds)
+  intervalMs: 500    // Check every 500ms
 })
 ```
 
+#### Platform Features
+
+- ✅ **AsyncStorage** - Secure token persistence
+- ✅ **Universal OAuth** - Same code works on web + mobile
+- ✅ **expo-web-browser** - Native browser UI
+- ✅ **No deep linking** - Session-based polling
+- ✅ **Works in Expo Go** - No custom dev client needed
+- ✅ **Auto token refresh** - Seamless sessions
+
 ## 📖 API Reference
 
 ### Authentication

package/dist/index.d.mts

@@ -82,6 +82,49 @@ interface BlinkClientConfig {
 }
 interface BlinkAuthConfig {
     mode?: 'managed' | 'headless';
+    /**
+     * Automatically detect and extract auth tokens from URL parameters
+     *
+     * - Web: Set to `true` (default) to handle OAuth redirects
+     * - React Native: Set to `false` to use deep links instead
+     *
+     * @default true
+     *
+     * @example
+     * // React Native - disable URL detection, use deep links
+     * {
+     *   auth: {
+     *     detectSessionInUrl: false,
+     *     storage: AsyncStorageAdapter(AsyncStorage)
+     *   }
+     * }
+     */
+    detectSessionInUrl?: boolean;
+    /**
+     * WebBrowser module for React Native OAuth (expo-web-browser)
+     *
+     * When provided, `signInWithGoogle()` and other OAuth methods will
+     * automatically use the mobile session-based flow on React Native,
+     * so you don't need platform-specific code.
+     *
+     * @example
+     * // React Native setup (configure once)
+     * import * as WebBrowser from 'expo-web-browser'
+     * import AsyncStorage from '@react-native-async-storage/async-storage'
+     *
+     * const blink = createClient({
+     *   projectId: 'your-project',
+     *   auth: {
+     *     mode: 'headless',
+     *     webBrowser: WebBrowser  // Pass the module here
+     *   },
+     *   storage: new AsyncStorageAdapter(AsyncStorage)
+     * })
+     *
+     * // Now this works on both web and mobile!
+     * const user = await blink.auth.signInWithGoogle()
+     */
+    webBrowser?: WebBrowserModule;
     email?: {
         requireVerification?: boolean;
         allowSignUp?: boolean;
@@ -118,11 +161,7 @@ type AuthProvider = 'email' | 'google' | 'github' | 'apple' | 'microsoft' | 'twi
 interface AuthOptions {
     redirectUrl?: string;
     metadata?: Record<string, any>;
-    /**
-     * Force redirect flow instead of popup (useful for Safari or when popups are blocked)
-     * When true, always uses redirect flow regardless of browser detection
-     */
-    forceRedirect?: boolean;
+    useMobileSession?: boolean;
 }
 interface SignUpData {
     email: string;
@@ -136,6 +175,22 @@ interface SignUpData {
 interface MagicLinkOptions {
     redirectUrl?: string;
 }
+/**
+ * WebBrowser interface for React Native OAuth
+ * Compatible with expo-web-browser module
+ *
+ * Simply pass the expo-web-browser module directly:
+ * ```typescript
+ * import * as WebBrowser from 'expo-web-browser'
+ * const blink = createClient({ auth: { webBrowser: WebBrowser } })
+ * ```
+ */
+interface WebBrowserModule {
+    openAuthSessionAsync(url: string, redirectUrl?: string, options?: unknown): Promise<{
+        type: string;
+        url?: string;
+    }>;
+}
 interface BlinkUser {
     id: string;
     email: string;
@@ -999,28 +1054,156 @@ declare class BlinkAuth {
     signInWithEmail(email: string, password: string): Promise<BlinkUser>;
     /**
      * Sign in with Google (headless mode)
+     *
+     * **Universal OAuth** - Works on both Web and React Native!
+     *
+     * On React Native, requires `webBrowser` to be configured in client:
+     * ```typescript
+     * const blink = createClient({
+     *   auth: { mode: 'headless', webBrowser: WebBrowser }
+     * })
+     * await blink.auth.signInWithGoogle() // Works on both platforms!
+     * ```
      */
     signInWithGoogle(options?: AuthOptions): Promise<BlinkUser>;
     /**
      * Sign in with GitHub (headless mode)
+     *
+     * **Universal OAuth** - Works on both Web and React Native!
+     * See signInWithGoogle() for setup instructions.
      */
     signInWithGitHub(options?: AuthOptions): Promise<BlinkUser>;
     /**
      * Sign in with Apple (headless mode)
+     *
+     * **Universal OAuth** - Works on both Web and React Native!
+     * See signInWithGoogle() for setup instructions.
      */
     signInWithApple(options?: AuthOptions): Promise<BlinkUser>;
     /**
      * Sign in with Microsoft (headless mode)
+     *
+     * **Universal OAuth** - Works on both Web and React Native!
+     * See signInWithGoogle() for setup instructions.
      */
     signInWithMicrosoft(options?: AuthOptions): Promise<BlinkUser>;
     /**
-     * Check if current browser is Safari (desktop, iPhone, iPad)
-     * Safari has strict popup blocking, so we must use redirect flow
+     * Initiate OAuth for mobile without deep linking (expo-web-browser pattern)
+     *
+     * This method:
+     * 1. Generates a unique session ID
+     * 2. Returns OAuth URL with session parameter
+     * 3. App opens URL in expo-web-browser
+     * 4. App polls checkMobileOAuthSession() until complete
+     *
+     * @param provider - OAuth provider (google, github, apple, etc.)
+     * @param options - Optional metadata
+     * @returns Session ID and OAuth URL
+     *
+     * @example
+     * // React Native with expo-web-browser
+     * import * as WebBrowser from 'expo-web-browser';
+     *
+     * const { sessionId, authUrl } = await blink.auth.initiateMobileOAuth('google');
+     *
+     * // Open browser
+     * await WebBrowser.openAuthSessionAsync(authUrl);
+     *
+     * // Poll for completion
+     * const user = await blink.auth.pollMobileOAuthSession(sessionId);
+     * console.log('Authenticated:', user.email);
      */
-    private isSafari;
+    initiateMobileOAuth(provider: AuthProvider, options?: Omit<AuthOptions, 'redirectUrl'>): Promise<{
+        sessionId: string;
+        authUrl: string;
+    }>;
+    /**
+     * Check mobile OAuth session status (single check)
+     *
+     * @param sessionId - Session ID from initiateMobileOAuth
+     * @returns Tokens if session is complete, null if still pending
+     */
+    checkMobileOAuthSession(sessionId: string): Promise<AuthTokens | null>;
+    /**
+     * Poll mobile OAuth session until complete (convenience method)
+     *
+     * @param sessionId - Session ID from initiateMobileOAuth
+     * @param options - Polling options
+     * @returns Authenticated user
+     *
+     * @example
+     * const { sessionId, authUrl } = await blink.auth.initiateMobileOAuth('google');
+     * await WebBrowser.openAuthSessionAsync(authUrl);
+     * const user = await blink.auth.pollMobileOAuthSession(sessionId, {
+     *   maxAttempts: 60,
+     *   intervalMs: 1000
+     * });
+     */
+    pollMobileOAuthSession(sessionId: string, options?: {
+        maxAttempts?: number;
+        intervalMs?: number;
+    }): Promise<BlinkUser>;
+    /**
+     * Sign in with OAuth provider using expo-web-browser (React Native)
+     *
+     * This is a convenience method that handles the entire flow:
+     * 1. Initiates mobile OAuth session
+     * 2. Returns auth URL to open in WebBrowser
+     * 3. Provides polling function to call after browser opens
+     *
+     * @param provider - OAuth provider
+     * @returns Object with authUrl and authenticate function
+     *
+     * @example
+     * import * as WebBrowser from 'expo-web-browser';
+     *
+     * const { authUrl, authenticate } = await blink.auth.signInWithProviderMobile('google');
+     *
+     * // Open browser
+     * await WebBrowser.openAuthSessionAsync(authUrl);
+     *
+     * // Wait for authentication
+     * const user = await authenticate();
+     */
+    signInWithProviderMobile(provider: AuthProvider, options?: Omit<AuthOptions, 'redirectUrl'>): Promise<{
+        authUrl: string;
+        authenticate: () => Promise<BlinkUser>;
+    }>;
+    /**
+     * Universal OAuth flow using session-based authentication (internal)
+     * Works on ALL platforms: Web, iOS, Android
+     * Uses expo-web-browser to open auth URL and polls for completion
+     */
+    private signInWithProviderUniversal;
     /**
      * Generic provider sign-in method (headless mode)
-     * Uses redirect flow for Safari, popup flow for other browsers
+     *
+     * **Universal OAuth** - Works seamlessly on both Web and React Native!
+     *
+     * When `webBrowser` is configured in the client, this method automatically
+     * uses the session-based OAuth flow that works on ALL platforms.
+     *
+     * **Universal Setup (configure once, works everywhere):**
+     * ```typescript
+     * import * as WebBrowser from 'expo-web-browser'
+     * import AsyncStorage from '@react-native-async-storage/async-storage'
+     *
+     * const blink = createClient({
+     *   projectId: 'your-project',
+     *   auth: {
+     *     mode: 'headless',
+     *     webBrowser: WebBrowser  // Pass the module here
+     *   },
+     *   storage: new AsyncStorageAdapter(AsyncStorage)
+     * })
+     *
+     * // Now this works on ALL platforms - no platform checks needed!
+     * const user = await blink.auth.signInWithGoogle()
+     * ```
+     *
+     * @param provider - OAuth provider (google, github, apple, etc.)
+     * @param options - Optional redirect URL and metadata
+     * @returns Promise that resolves with authenticated user
      */
     signInWithProvider(provider: AuthProvider, options?: AuthOptions): Promise<BlinkUser>;
     /**
@@ -1110,6 +1293,40 @@ declare class BlinkAuth {
      * Manually set tokens (for server-side usage)
      */
     setToken(jwt: string, persist?: boolean): Promise<void>;
+    /**
+     * Manually set auth session from tokens (React Native deep link OAuth)
+     *
+     * Use this method to set the user session after receiving tokens from a deep link callback.
+     * This is the React Native equivalent of automatic URL token detection on web.
+     *
+     * @param tokens - Auth tokens received from deep link or OAuth callback
+     * @param persist - Whether to persist tokens to storage (default: true)
+     *
+     * @example
+     * // React Native: Handle deep link OAuth callback
+     * import * as Linking from 'expo-linking'
+     *
+     * Linking.addEventListener('url', async ({ url }) => {
+     *   const { queryParams } = Linking.parse(url)
+     *
+     *   if (queryParams.access_token) {
+     *     await blink.auth.setSession({
+     *       access_token: queryParams.access_token,
+     *       refresh_token: queryParams.refresh_token,
+     *       expires_in: parseInt(queryParams.expires_in) || 3600,
+     *       refresh_expires_in: parseInt(queryParams.refresh_expires_in)
+     *     })
+     *
+     *     console.log('User authenticated:', blink.auth.currentUser())
+     *   }
+     * })
+     */
+    setSession(tokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+        refresh_expires_in?: number;
+    }, persist?: boolean): Promise<BlinkUser>;
     /**
      * Refresh access token using refresh token
      */
@@ -1125,11 +1342,6 @@ declare class BlinkAuth {
     private setTokens;
     private clearTokens;
     private getStoredTokens;
-    /**
-     * Extract URL parameters from both search params and hash fragments
-     * Safari OAuth redirects often use hash fragments instead of query params
-     */
-    private extractUrlParams;
     private extractTokensFromUrl;
     private clearUrlTokens;
     private redirectToAuth;
@@ -1139,6 +1351,10 @@ declare class BlinkAuth {
      * Generate secure random state for OAuth flows
      */
     private generateState;
+    /**
+     * Generate unique session ID for mobile OAuth
+     */
+    private generateSessionId;
     /**
      * Extract magic link token from URL
      */
@@ -2080,4 +2296,4 @@ declare class BlinkRealtimeImpl implements BlinkRealtime {
     onPresence(channelName: string, callback: (users: PresenceUser[]) => void): () => void;
 }
 
-export { type AnalyticsEvent, AsyncStorageAdapter, type AuthState, type AuthStateChangeCallback, type AuthTokens, type BlinkAI, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkClientConfig, type BlinkData, BlinkDataImpl, BlinkDatabase, type BlinkRealtime, BlinkRealtimeChannel, BlinkRealtimeError, BlinkRealtimeImpl, type BlinkStorage, BlinkStorageImpl, BlinkTable, type BlinkUser, type CreateOptions, type DataExtraction, type FileObject, type FilterCondition, type ImageGenerationRequest, type ImageGenerationResponse, type Message, NoOpStorageAdapter, type ObjectGenerationRequest, type ObjectGenerationResponse, type PresenceUser, type QueryOptions, type RealtimeChannel, type RealtimeGetMessagesOptions, type RealtimeMessage, type RealtimePublishOptions, type RealtimeSubscribeOptions, type SearchRequest, type SearchResponse, type SpeechGenerationRequest, type SpeechGenerationResponse, type StorageAdapter, type StorageUploadOptions, type StorageUploadResponse, type TableOperations, type TextGenerationRequest, type TextGenerationResponse, type TokenUsage, type TranscriptionRequest, type TranscriptionResponse, type UpdateOptions, type UpsertOptions, WebStorageAdapter, createClient, getDefaultStorageAdapter, isBrowser, isNode, isReactNative, isWeb, platform };
+export { type AnalyticsEvent, AsyncStorageAdapter, type AuthState, type AuthStateChangeCallback, type AuthTokens, type BlinkAI, BlinkAIImpl, type BlinkAnalytics, BlinkAnalyticsImpl, type BlinkClient, type BlinkClientConfig, type BlinkData, BlinkDataImpl, BlinkDatabase, type BlinkRealtime, BlinkRealtimeChannel, BlinkRealtimeError, BlinkRealtimeImpl, type BlinkStorage, BlinkStorageImpl, BlinkTable, type BlinkUser, type CreateOptions, type DataExtraction, type FileObject, type FilterCondition, type ImageGenerationRequest, type ImageGenerationResponse, type Message, NoOpStorageAdapter, type ObjectGenerationRequest, type ObjectGenerationResponse, type PresenceUser, type QueryOptions, type RealtimeChannel, type RealtimeGetMessagesOptions, type RealtimeMessage, type RealtimePublishOptions, type RealtimeSubscribeOptions, type SearchRequest, type SearchResponse, type SpeechGenerationRequest, type SpeechGenerationResponse, type StorageAdapter, type StorageUploadOptions, type StorageUploadResponse, type TableOperations, type TextGenerationRequest, type TextGenerationResponse, type TokenUsage, type TranscriptionRequest, type TranscriptionResponse, type UpdateOptions, type UpsertOptions, type WebBrowserModule, WebStorageAdapter, createClient, getDefaultStorageAdapter, isBrowser, isNode, isReactNative, isWeb, platform };