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

package/dist/index.d.ts

@@ -115,7 +115,7 @@ declare class HttpClient {
  *
  * Implements the Strategy Pattern for token storage:
  * - SecureSessionStorage: In-memory tokens + httpOnly cookie refresh (XSS-resistant)
- * - PersistentSessionStorage: localStorage-based storage (legacy/fallback)
+ * - LocalSessionStorage: localStorage-based storage (legacy/fallback)
  */
 
 /**
@@ -169,7 +169,7 @@ declare class SecureSessionStorage implements SessionStorageStrategy {
     private hasAuthFlag;
 }
 /**
- * Persistent Session Storage Strategy
+ * Local Session Storage Strategy
  *
  * Stores tokens in localStorage for persistence across page reloads.
  * Used for legacy backends or environments where httpOnly cookies aren't available.
@@ -177,8 +177,8 @@ declare class SecureSessionStorage implements SessionStorageStrategy {
  * Note: This approach exposes tokens to XSS attacks. Use SecureSessionStorage
  * when possible.
  */
-declare class PersistentSessionStorage implements SessionStorageStrategy {
-    readonly strategyId = "persistent";
+declare class LocalSessionStorage implements SessionStorageStrategy {
+    readonly strategyId = "local";
     private storage;
     constructor(storage?: TokenStorage);
     saveSession(session: AuthSession): void;
@@ -192,62 +192,62 @@ declare class PersistentSessionStorage implements SessionStorageStrategy {
 }
 
 /**
- * Backend Capability Discovery for InsForge SDK
+ * Backend Configuration for InsForge SDK
  *
- * Discovers backend capabilities via the /api/health endpoint
- * and creates appropriate storage strategies based on those capabilities.
+ * Fetches backend configuration via the /api/health endpoint
+ * and creates appropriate storage strategies based on that configuration.
  */
 
 /**
- * Backend capabilities returned from /api/health
+ * Backend configuration returned from /api/health
  */
-interface BackendCapabilities {
+interface BackendConfig {
     /** Whether backend supports secure httpOnly cookie storage for refresh tokens */
     secureSessionStorage: boolean;
     /** Whether backend supports token refresh endpoint */
     refreshTokens: boolean;
 }
 /**
- * Discover backend capabilities from the /api/health endpoint
+ * 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 capabilities object
+ * @returns Backend configuration object
  *
  * @example
  * ```typescript
- * const capabilities = await discoverCapabilities('https://api.example.com');
- * if (capabilities.secureSessionStorage) {
+ * const config = await discoverBackendConfig('https://api.example.com');
+ * if (config.secureSessionStorage) {
  *   // Use secure storage strategy
  * }
  * ```
  */
-declare function discoverCapabilities(baseUrl: string, fetchImpl?: typeof fetch): Promise<BackendCapabilities>;
+declare function discoverBackendConfig(baseUrl: string, fetchImpl?: typeof fetch): Promise<BackendConfig>;
 /**
- * Create the appropriate session storage strategy based on backend capabilities
+ * 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 capabilities - Backend capabilities from discoverCapabilities()
- * @param storage - Optional custom storage adapter (for PersistentSessionStorage)
+ * @param config - Backend configuration from discoverBackendConfig()
+ * @param storage - Optional custom storage adapter (for LocalSessionStorage)
  * @returns Appropriate SessionStorageStrategy implementation
  *
  * @example
  * ```typescript
- * const capabilities = await discoverCapabilities(baseUrl);
- * const storage = createSessionStorage(capabilities);
+ * const config = await discoverBackendConfig(baseUrl);
+ * const storage = createSessionStorage(config);
  * storage.saveSession({ accessToken: '...', user: {...} });
  * ```
  */
-declare function createSessionStorage(capabilities: BackendCapabilities, storage?: TokenStorage): SessionStorageStrategy;
+declare function createSessionStorage(config: BackendConfig, storage?: TokenStorage): SessionStorageStrategy;
 /**
- * Get default capabilities (useful for testing or manual override)
+ * Get default backend configuration (useful for testing or manual override)
  */
-declare function getDefaultCapabilities(): BackendCapabilities;
+declare function getDefaultBackendConfig(): BackendConfig;
 
 /**
  * Token Manager for InsForge SDK
@@ -260,14 +260,14 @@ declare function getDefaultCapabilities(): BackendCapabilities;
  * TokenManager - Manages session storage using the Strategy Pattern
  *
  * The actual storage implementation is delegated to a SessionStorageStrategy.
- * By default, uses PersistentSessionStorage until a strategy is explicitly set
+ * By default, uses LocalSessionStorage until a strategy is explicitly set
  * via setStrategy() during client initialization.
  */
 declare class TokenManager {
     private strategy;
     /**
      * Create a new TokenManager
-     * @param storage - Optional custom storage adapter (used for initial PersistentSessionStorage)
+     * @param storage - Optional custom storage adapter (used for initial LocalSessionStorage)
      */
     constructor(storage?: TokenStorage);
     /**
@@ -334,32 +334,67 @@ 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 initPromise;
-    constructor(http: HttpClient, tokenManager: TokenManager);
+    private authStateListeners;
+    private initializePromise;
+    constructor(http: HttpClient, tokenManager: TokenManager, initializePromise?: Promise<void>);
     /**
-     * Check if an error represents an authentication failure
-     * Used to determine appropriate HTTP status code (401 vs 500)
+     * 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();
+     * ```
      */
-    private isAuthenticationError;
+    onAuthStateChange(callback: AuthStateChangeCallback): {
+        data: {
+            subscription: {
+                unsubscribe: () => void;
+            };
+        };
+    };
     /**
-     * Set the initialization promise that auth operations should wait for
-     * This ensures TokenManager mode is set before any auth operations
+     * Emit auth state change to all listeners
+     * @internal
      */
-    setInitPromise(promise: Promise<void>): void;
+    _emitAuthStateChange(event: AuthStateChangeEvent, session: AuthSession | null): void;
     /**
-     * Wait for initialization to complete (if set)
+     * Check if an error represents an authentication failure
+     * Used to determine appropriate HTTP status code (401 vs 500)
      */
-    private waitForInit;
+    private isAuthenticationError;
     /**
-     * Automatically detect and handle OAuth callback parameters in the URL
-     * This runs after initialization to seamlessly complete the OAuth flow
-     * Matches the backend's OAuth callback response (backend/src/api/routes/auth.ts:540-544)
+     * Detect and handle OAuth callback parameters in the URL.
+     * Called by client after initialization.
      */
-    private detectAuthCallbackAsync;
+    detectAuthCallback(): void;
     /**
      * Sign up a new user
      */
@@ -821,50 +856,43 @@ 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'
  * });
  *
- * // Wait for initialization (optional but recommended)
- * await client.initialize();
- *
- * // Authentication
- * const session = await client.auth.signUp({
- *   email: 'user@example.com',
- *   password: 'password123',
- *   name: 'John Doe'
+ * // Subscribe to auth state changes
+ * client.auth.onAuthStateChange((event, session) => {
+ *   console.log('Auth event:', event);
+ *   if (session) {
+ *     console.log('User:', session.user.email);
+ *   }
  * });
  *
- * // 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' }
+ * // Client is immediately usable for auth operations
+ * const { data, error } = await client.auth.signInWithPassword({
+ *   email: 'user@example.com',
+ *   password: 'password123'
  * });
  * ```
  */
 declare class InsForgeClient {
     private http;
     private tokenManager;
-    private initialized;
-    private initializationPromise;
-    private capabilities;
+    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;
@@ -872,43 +900,54 @@ declare class InsForgeClient {
     readonly functions: Functions;
     constructor(config?: InsForgeConfig);
     /**
-     * Initialize the client by discovering backend capabilities
-     * This is called automatically on construction but can be awaited for guaranteed initialization
-     *
-     * @example
-     * ```typescript
-     * const client = new InsForgeClient({ baseUrl: 'https://api.example.com' });
-     * await client.initialize(); // Wait for capability discovery
-     * ```
+     * Internal async initialization - discovers backend config and recovers session.
+     * Emits INITIAL_SESSION event when complete.
+     * @internal
      */
-    initialize(): Promise<void>;
+    private _initializeAsync;
     /**
-     * Internal async initialization - discovers capabilities and configures storage strategy
+     * Wait for client initialization to complete
+     * @returns Promise that resolves when initialization is done
      */
-    private initializeAsync;
+    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 capabilities
+     * Get the discovered backend configuration
      */
-    getCapabilities(): BackendCapabilities | null;
+    getBackendConfig(): BackendConfig | null;
     /**
      * Get the current storage strategy identifier
      */
     getStorageStrategy(): string;
-    /**
-     * Check if the client has been fully initialized
-     */
-    isInitialized(): boolean;
 }
+/**
+ * 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
@@ -916,6 +955,4 @@ declare class InsForgeClient {
  * @packageDocumentation
  */
 
-declare function createClient(config: InsForgeConfig): InsForgeClient;
-
-export { AI, type ApiError, Auth, type AuthSession, type BackendCapabilities, type InsForgeConfig as ClientOptions, Database, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, PersistentSessionStorage, type ProfileData, SecureSessionStorage, type SessionStorageStrategy, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, createSessionStorage, InsForgeClient as default, discoverCapabilities, getDefaultCapabilities };
+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 };