@insforge/sdk 1.0.1-refresh.3 → 1.0.1-refresh.5

package/dist/index.d.mts

@@ -146,8 +146,9 @@ interface SessionStorageStrategy {
  * Secure Session Storage Strategy
  *
  * Stores access token in memory only (cleared on page refresh).
- * Refresh token is stored in httpOnly cookie by the backend.
- * Uses an 'isAuthenticated' flag cookie to detect if refresh should be attempted.
+ * Refresh token is stored in httpOnly cookie by the backend (on backend domain).
+ * The `isAuthenticated` cookie is set by the SDK on the frontend domain to signal
+ * that a secure session exists and token refresh should be attempted on page reload.
  *
  * Security benefits:
  * - Access token not accessible to XSS attacks (in memory only)
@@ -165,7 +166,6 @@ declare class SecureSessionStorage implements SessionStorageStrategy {
     setUser(user: UserSchema): void;
     clearSession(): void;
     shouldAttemptRefresh(): boolean;
-    private setAuthFlag;
     private hasAuthFlag;
 }
 /**
@@ -191,64 +191,6 @@ declare class LocalSessionStorage implements SessionStorageStrategy {
     shouldAttemptRefresh(): boolean;
 }
 
-/**
- * Backend Configuration for InsForge SDK
- *
- * Fetches backend configuration via the /api/health endpoint
- * and creates appropriate storage strategies based on that configuration.
- */
-
-/**
- * Backend configuration returned from /api/health
- */
-interface BackendConfig {
-    /** Whether backend supports secure httpOnly cookie storage for refresh tokens */
-    secureSessionStorage: boolean;
-    /** Whether backend supports token refresh endpoint */
-    refreshTokens: boolean;
-}
-/**
- * Fetch backend configuration from the /api/health endpoint
- *
- * This is the primary method for determining which features the backend supports.
- * The SDK uses this information to select appropriate storage strategies.
- *
- * @param baseUrl - The backend base URL
- * @param fetchImpl - Optional custom fetch implementation
- * @returns Backend configuration object
- *
- * @example
- * ```typescript
- * const config = await discoverBackendConfig('https://api.example.com');
- * if (config.secureSessionStorage) {
- *   // Use secure storage strategy
- * }
- * ```
- */
-declare function discoverBackendConfig(baseUrl: string, fetchImpl?: typeof fetch): Promise<BackendConfig>;
-/**
- * Create the appropriate session storage strategy based on backend configuration
- *
- * This is the factory function that implements the Strategy Pattern.
- * It selects the storage implementation based on what the backend supports.
- *
- * @param config - Backend configuration from discoverBackendConfig()
- * @param storage - Optional custom storage adapter (for LocalSessionStorage)
- * @returns Appropriate SessionStorageStrategy implementation
- *
- * @example
- * ```typescript
- * const config = await discoverBackendConfig(baseUrl);
- * const storage = createSessionStorage(config);
- * storage.saveSession({ accessToken: '...', user: {...} });
- * ```
- */
-declare function createSessionStorage(config: BackendConfig, storage?: TokenStorage): SessionStorageStrategy;
-/**
- * Get default backend configuration (useful for testing or manual override)
- */
-declare function getDefaultBackendConfig(): BackendConfig;
-
 /**
  * Token Manager for InsForge SDK
  *
@@ -334,66 +276,43 @@ type ProfileData = Record<string, any> & {
  * Supports any fields that exist in the profile table
  */
 type UpdateProfileData = Partial<Record<string, any>>;
-/**
- * Auth state change event types
- * Following Supabase pattern for consistency
- */
-type AuthStateChangeEvent = 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED';
-/**
- * Auth state change callback type
- */
-type AuthStateChangeCallback = (event: AuthStateChangeEvent, session: AuthSession | null) => void;
 declare class Auth {
     private http;
     private tokenManager;
     private database;
-    private authStateListeners;
-    private initializePromise;
-    constructor(http: HttpClient, tokenManager: TokenManager, initializePromise?: Promise<void>);
+    constructor(http: HttpClient, tokenManager: TokenManager);
     /**
-     * Subscribe to auth state changes
-     *
-     * New subscribers will receive an INITIAL_SESSION event after initialization completes.
-     * This ensures no race condition where subscribers miss the initial state.
-     *
-     * @param callback - Function called when auth state changes
-     * @returns Unsubscribe function
-     *
-     * @example
-     * ```typescript
-     * const { data: { subscription } } = client.auth.onAuthStateChange((event, session) => {
-     *   if (event === 'SIGNED_IN') {
-     *     console.log('User signed in:', session?.user.email);
-     *   } else if (event === 'SIGNED_OUT') {
-     *     console.log('User signed out');
-     *   }
-     * });
-     *
-     * // Later: unsubscribe
-     * subscription.unsubscribe();
-     * ```
+     * Set the isAuthenticated cookie flag on the frontend domain
+     * This is managed by SDK, not backend, to work in cross-origin scenarios
      */
-    onAuthStateChange(callback: AuthStateChangeCallback): {
-        data: {
-            subscription: {
-                unsubscribe: () => void;
-            };
-        };
-    };
+    private setAuthenticatedCookie;
+    /**
+     * Clear the isAuthenticated cookie flag from the frontend domain
+     */
+    private clearAuthenticatedCookie;
     /**
-     * Emit auth state change to all listeners
+     * Switch to SecureSessionStorage (cookie-based auth)
+     * Called when backend returns sessionMode: 'secure'
      * @internal
      */
-    _emitAuthStateChange(event: AuthStateChangeEvent, session: AuthSession | null): void;
+    _switchToSecureStorage(): void;
     /**
-     * Check if an error represents an authentication failure
-     * Used to determine appropriate HTTP status code (401 vs 500)
+     * Switch to LocalSessionStorage (localStorage-based auth)
+     * Called when cookie-based auth fails (fallback)
+     * @internal
      */
-    private isAuthenticationError;
+    _switchToLocalStorage(): void;
     /**
-     * Detect and handle OAuth callback parameters in the URL.
-     * Called by client after initialization.
+     * Detect storage strategy based on backend response
+     * @param sessionMode - The sessionMode returned by backend ('secure' or undefined)
+     * @internal
      */
+    private _detectStorageFromResponse;
+    /**
+   * Automatically detect and handle OAuth callback parameters in the URL
+   * This runs on initialization to seamlessly complete the OAuth flow
+   * Matches the backend's OAuth callback response (backend/src/api/routes/auth.ts:540-544)
+   */
     detectAuthCallback(): void;
     /**
      * Sign up a new user
@@ -460,6 +379,9 @@ declare class Auth {
     /**
      * Get the current user with full profile information
      * Returns both auth info (id, email, role) and profile data (dynamic fields from users table)
+     *
+     * In secure session mode (httpOnly cookie), this method will automatically attempt
+     * to refresh the session if no access token is available (e.g., after page reload).
      */
     getCurrentUser(): Promise<{
         data: {
@@ -856,98 +778,65 @@ declare class Functions {
 /**
  * Main InsForge SDK Client
  *
- * The client automatically initializes in the background and emits auth state changes.
- * Subscribe to `auth.onAuthStateChange` to be notified when initialization completes.
- *
  * @example
  * ```typescript
  * import { InsForgeClient } from '@insforge/sdk';
  *
- * // Create client - synchronous, immediately usable
  * const client = new InsForgeClient({
  *   baseUrl: 'http://localhost:7130'
  * });
  *
- * // Subscribe to auth state changes
- * client.auth.onAuthStateChange((event, session) => {
- *   console.log('Auth event:', event);
- *   if (session) {
- *     console.log('User:', session.user.email);
- *   }
+ * // Authentication
+ * const { data, error } = await client.auth.signUp({
+ *   email: 'user@example.com',
+ *   password: 'password123',
+ *   name: 'John Doe'
  * });
  *
- * // Client is immediately usable for auth operations
- * const { data, error } = await client.auth.signInWithPassword({
- *   email: 'user@example.com',
- *   password: 'password123'
+ * // Database operations
+ * const { data, error } = await client.database
+ *   .from('posts')
+ *   .select('*')
+ *   .eq('user_id', session.user.id)
+ *   .order('created_at', { ascending: false })
+ *   .limit(10);
+ *
+ * // Insert data
+ * const { data: newPost } = await client.database
+ *   .from('posts')
+ *   .insert({ title: 'Hello', content: 'World' })
+ *   .single();
+ *
+ * // Invoke edge functions
+ * const { data, error } = await client.functions.invoke('my-function', {
+ *   body: { message: 'Hello from SDK' }
  * });
  * ```
  */
 declare class InsForgeClient {
     private http;
     private tokenManager;
-    private backendConfig;
-    /**
-     * Promise that resolves when initialization is complete.
-     * Use this to ensure operations wait for the client to be ready.
-     */
-    private initializePromise;
-    private initializeResolve;
     readonly auth: Auth;
     readonly database: Database;
     readonly storage: Storage;
     readonly ai: AI;
     readonly functions: Functions;
     constructor(config?: InsForgeConfig);
-    /**
-     * Internal async initialization - discovers backend config and recovers session.
-     * Emits INITIAL_SESSION event when complete.
-     * @internal
-     */
-    private _initializeAsync;
-    /**
-     * Wait for client initialization to complete
-     * @returns Promise that resolves when initialization is done
-     */
-    waitForInitialization(): Promise<void>;
     /**
      * Get the underlying HTTP client for custom requests
+     *
+     * @example
+     * ```typescript
+     * const httpClient = client.getHttpClient();
+     * const customData = await httpClient.get('/api/custom-endpoint');
+     * ```
      */
     getHttpClient(): HttpClient;
-    /**
-     * Get the discovered backend configuration
-     */
-    getBackendConfig(): BackendConfig | null;
     /**
      * Get the current storage strategy identifier
      */
     getStorageStrategy(): string;
 }
-/**
- * Create an InsForge client.
- * This is a convenience alias for `new InsForgeClient(config)`.
- *
- * Note: The client initializes asynchronously in the background.
- * Subscribe to `auth.onAuthStateChange` to be notified when ready.
- *
- * @example
- * ```typescript
- * import { createClient } from '@insforge/sdk';
- *
- * const client = createClient({
- *   baseUrl: 'http://localhost:7130'
- * });
- *
- * // Subscribe to auth state changes
- * client.auth.onAuthStateChange((event, session) => {
- *   if (event === 'INITIAL_SESSION') {
- *     // Initialization complete
- *     console.log('Ready!', session ? 'Logged in' : 'Not logged in');
- *   }
- * });
- * ```
- */
-declare function createClient(config?: InsForgeConfig): InsForgeClient;
 
 /**
  * @insforge/sdk - TypeScript SDK for InsForge Backend-as-a-Service
@@ -955,4 +844,6 @@ declare function createClient(config?: InsForgeConfig): InsForgeClient;
  * @packageDocumentation
  */
 
-export { AI, type ApiError, Auth, type AuthSession, type AuthStateChangeCallback, type AuthStateChangeEvent, type BackendConfig, type InsForgeConfig as ClientOptions, Database, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, LocalSessionStorage, type ProfileData, SecureSessionStorage, type SessionStorageStrategy, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, createSessionStorage, InsForgeClient as default, discoverBackendConfig, getDefaultBackendConfig };
+declare function createClient(config: InsForgeConfig): InsForgeClient;
+
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, Database, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, LocalSessionStorage, type ProfileData, SecureSessionStorage, type SessionStorageStrategy, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, InsForgeClient as default };

package/dist/index.d.ts

@@ -146,8 +146,9 @@ interface SessionStorageStrategy {
  * Secure Session Storage Strategy
  *
  * Stores access token in memory only (cleared on page refresh).
- * Refresh token is stored in httpOnly cookie by the backend.
- * Uses an 'isAuthenticated' flag cookie to detect if refresh should be attempted.
+ * Refresh token is stored in httpOnly cookie by the backend (on backend domain).
+ * The `isAuthenticated` cookie is set by the SDK on the frontend domain to signal
+ * that a secure session exists and token refresh should be attempted on page reload.
  *
  * Security benefits:
  * - Access token not accessible to XSS attacks (in memory only)
@@ -165,7 +166,6 @@ declare class SecureSessionStorage implements SessionStorageStrategy {
     setUser(user: UserSchema): void;
     clearSession(): void;
     shouldAttemptRefresh(): boolean;
-    private setAuthFlag;
     private hasAuthFlag;
 }
 /**
@@ -191,64 +191,6 @@ declare class LocalSessionStorage implements SessionStorageStrategy {
     shouldAttemptRefresh(): boolean;
 }
 
-/**
- * Backend Configuration for InsForge SDK
- *
- * Fetches backend configuration via the /api/health endpoint
- * and creates appropriate storage strategies based on that configuration.
- */
-
-/**
- * Backend configuration returned from /api/health
- */
-interface BackendConfig {
-    /** Whether backend supports secure httpOnly cookie storage for refresh tokens */
-    secureSessionStorage: boolean;
-    /** Whether backend supports token refresh endpoint */
-    refreshTokens: boolean;
-}
-/**
- * Fetch backend configuration from the /api/health endpoint
- *
- * This is the primary method for determining which features the backend supports.
- * The SDK uses this information to select appropriate storage strategies.
- *
- * @param baseUrl - The backend base URL
- * @param fetchImpl - Optional custom fetch implementation
- * @returns Backend configuration object
- *
- * @example
- * ```typescript
- * const config = await discoverBackendConfig('https://api.example.com');
- * if (config.secureSessionStorage) {
- *   // Use secure storage strategy
- * }
- * ```
- */
-declare function discoverBackendConfig(baseUrl: string, fetchImpl?: typeof fetch): Promise<BackendConfig>;
-/**
- * Create the appropriate session storage strategy based on backend configuration
- *
- * This is the factory function that implements the Strategy Pattern.
- * It selects the storage implementation based on what the backend supports.
- *
- * @param config - Backend configuration from discoverBackendConfig()
- * @param storage - Optional custom storage adapter (for LocalSessionStorage)
- * @returns Appropriate SessionStorageStrategy implementation
- *
- * @example
- * ```typescript
- * const config = await discoverBackendConfig(baseUrl);
- * const storage = createSessionStorage(config);
- * storage.saveSession({ accessToken: '...', user: {...} });
- * ```
- */
-declare function createSessionStorage(config: BackendConfig, storage?: TokenStorage): SessionStorageStrategy;
-/**
- * Get default backend configuration (useful for testing or manual override)
- */
-declare function getDefaultBackendConfig(): BackendConfig;
-
 /**
  * Token Manager for InsForge SDK
  *
@@ -334,66 +276,43 @@ type ProfileData = Record<string, any> & {
  * Supports any fields that exist in the profile table
  */
 type UpdateProfileData = Partial<Record<string, any>>;
-/**
- * Auth state change event types
- * Following Supabase pattern for consistency
- */
-type AuthStateChangeEvent = 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED';
-/**
- * Auth state change callback type
- */
-type AuthStateChangeCallback = (event: AuthStateChangeEvent, session: AuthSession | null) => void;
 declare class Auth {
     private http;
     private tokenManager;
     private database;
-    private authStateListeners;
-    private initializePromise;
-    constructor(http: HttpClient, tokenManager: TokenManager, initializePromise?: Promise<void>);
+    constructor(http: HttpClient, tokenManager: TokenManager);
     /**
-     * Subscribe to auth state changes
-     *
-     * New subscribers will receive an INITIAL_SESSION event after initialization completes.
-     * This ensures no race condition where subscribers miss the initial state.
-     *
-     * @param callback - Function called when auth state changes
-     * @returns Unsubscribe function
-     *
-     * @example
-     * ```typescript
-     * const { data: { subscription } } = client.auth.onAuthStateChange((event, session) => {
-     *   if (event === 'SIGNED_IN') {
-     *     console.log('User signed in:', session?.user.email);
-     *   } else if (event === 'SIGNED_OUT') {
-     *     console.log('User signed out');
-     *   }
-     * });
-     *
-     * // Later: unsubscribe
-     * subscription.unsubscribe();
-     * ```
+     * Set the isAuthenticated cookie flag on the frontend domain
+     * This is managed by SDK, not backend, to work in cross-origin scenarios
      */
-    onAuthStateChange(callback: AuthStateChangeCallback): {
-        data: {
-            subscription: {
-                unsubscribe: () => void;
-            };
-        };
-    };
+    private setAuthenticatedCookie;
+    /**
+     * Clear the isAuthenticated cookie flag from the frontend domain
+     */
+    private clearAuthenticatedCookie;
     /**
-     * Emit auth state change to all listeners
+     * Switch to SecureSessionStorage (cookie-based auth)
+     * Called when backend returns sessionMode: 'secure'
      * @internal
      */
-    _emitAuthStateChange(event: AuthStateChangeEvent, session: AuthSession | null): void;
+    _switchToSecureStorage(): void;
     /**
-     * Check if an error represents an authentication failure
-     * Used to determine appropriate HTTP status code (401 vs 500)
+     * Switch to LocalSessionStorage (localStorage-based auth)
+     * Called when cookie-based auth fails (fallback)
+     * @internal
      */
-    private isAuthenticationError;
+    _switchToLocalStorage(): void;
     /**
-     * Detect and handle OAuth callback parameters in the URL.
-     * Called by client after initialization.
+     * Detect storage strategy based on backend response
+     * @param sessionMode - The sessionMode returned by backend ('secure' or undefined)
+     * @internal
      */
+    private _detectStorageFromResponse;
+    /**
+   * Automatically detect and handle OAuth callback parameters in the URL
+   * This runs on initialization to seamlessly complete the OAuth flow
+   * Matches the backend's OAuth callback response (backend/src/api/routes/auth.ts:540-544)
+   */
     detectAuthCallback(): void;
     /**
      * Sign up a new user
@@ -460,6 +379,9 @@ declare class Auth {
     /**
      * Get the current user with full profile information
      * Returns both auth info (id, email, role) and profile data (dynamic fields from users table)
+     *
+     * In secure session mode (httpOnly cookie), this method will automatically attempt
+     * to refresh the session if no access token is available (e.g., after page reload).
      */
     getCurrentUser(): Promise<{
         data: {
@@ -856,98 +778,65 @@ declare class Functions {
 /**
  * Main InsForge SDK Client
  *
- * The client automatically initializes in the background and emits auth state changes.
- * Subscribe to `auth.onAuthStateChange` to be notified when initialization completes.
- *
  * @example
  * ```typescript
  * import { InsForgeClient } from '@insforge/sdk';
  *
- * // Create client - synchronous, immediately usable
  * const client = new InsForgeClient({
  *   baseUrl: 'http://localhost:7130'
  * });
  *
- * // Subscribe to auth state changes
- * client.auth.onAuthStateChange((event, session) => {
- *   console.log('Auth event:', event);
- *   if (session) {
- *     console.log('User:', session.user.email);
- *   }
+ * // Authentication
+ * const { data, error } = await client.auth.signUp({
+ *   email: 'user@example.com',
+ *   password: 'password123',
+ *   name: 'John Doe'
  * });
  *
- * // Client is immediately usable for auth operations
- * const { data, error } = await client.auth.signInWithPassword({
- *   email: 'user@example.com',
- *   password: 'password123'
+ * // Database operations
+ * const { data, error } = await client.database
+ *   .from('posts')
+ *   .select('*')
+ *   .eq('user_id', session.user.id)
+ *   .order('created_at', { ascending: false })
+ *   .limit(10);
+ *
+ * // Insert data
+ * const { data: newPost } = await client.database
+ *   .from('posts')
+ *   .insert({ title: 'Hello', content: 'World' })
+ *   .single();
+ *
+ * // Invoke edge functions
+ * const { data, error } = await client.functions.invoke('my-function', {
+ *   body: { message: 'Hello from SDK' }
  * });
  * ```
  */
 declare class InsForgeClient {
     private http;
     private tokenManager;
-    private backendConfig;
-    /**
-     * Promise that resolves when initialization is complete.
-     * Use this to ensure operations wait for the client to be ready.
-     */
-    private initializePromise;
-    private initializeResolve;
     readonly auth: Auth;
     readonly database: Database;
     readonly storage: Storage;
     readonly ai: AI;
     readonly functions: Functions;
     constructor(config?: InsForgeConfig);
-    /**
-     * Internal async initialization - discovers backend config and recovers session.
-     * Emits INITIAL_SESSION event when complete.
-     * @internal
-     */
-    private _initializeAsync;
-    /**
-     * Wait for client initialization to complete
-     * @returns Promise that resolves when initialization is done
-     */
-    waitForInitialization(): Promise<void>;
     /**
      * Get the underlying HTTP client for custom requests
+     *
+     * @example
+     * ```typescript
+     * const httpClient = client.getHttpClient();
+     * const customData = await httpClient.get('/api/custom-endpoint');
+     * ```
      */
     getHttpClient(): HttpClient;
-    /**
-     * Get the discovered backend configuration
-     */
-    getBackendConfig(): BackendConfig | null;
     /**
      * Get the current storage strategy identifier
      */
     getStorageStrategy(): string;
 }
-/**
- * Create an InsForge client.
- * This is a convenience alias for `new InsForgeClient(config)`.
- *
- * Note: The client initializes asynchronously in the background.
- * Subscribe to `auth.onAuthStateChange` to be notified when ready.
- *
- * @example
- * ```typescript
- * import { createClient } from '@insforge/sdk';
- *
- * const client = createClient({
- *   baseUrl: 'http://localhost:7130'
- * });
- *
- * // Subscribe to auth state changes
- * client.auth.onAuthStateChange((event, session) => {
- *   if (event === 'INITIAL_SESSION') {
- *     // Initialization complete
- *     console.log('Ready!', session ? 'Logged in' : 'Not logged in');
- *   }
- * });
- * ```
- */
-declare function createClient(config?: InsForgeConfig): InsForgeClient;
 
 /**
  * @insforge/sdk - TypeScript SDK for InsForge Backend-as-a-Service
@@ -955,4 +844,6 @@ declare function createClient(config?: InsForgeConfig): InsForgeClient;
  * @packageDocumentation
  */
 
-export { AI, type ApiError, Auth, type AuthSession, type AuthStateChangeCallback, type AuthStateChangeEvent, type BackendConfig, type InsForgeConfig as ClientOptions, Database, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, LocalSessionStorage, type ProfileData, SecureSessionStorage, type SessionStorageStrategy, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, createSessionStorage, InsForgeClient as default, discoverBackendConfig, getDefaultBackendConfig };
+declare function createClient(config: InsForgeConfig): InsForgeClient;
+
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, Database, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, LocalSessionStorage, type ProfileData, SecureSessionStorage, type SessionStorageStrategy, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, InsForgeClient as default };