vibeusage 0.3.0 → 0.3.1

package/node_modules/@insforge/sdk/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, GetPublicAuthConfigResponse, GetProfileResponse, SendVerificationEmailRequest, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, VerifyEmailRequest, VerifyEmailResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse } from '@insforge/shared-schemas';
+import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, RefreshSessionResponse, GetProfileResponse, SendVerificationEmailRequest, VerifyEmailRequest, VerifyEmailResponse, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, ExchangeResetPasswordTokenResponse, ResetPasswordResponse, GetPublicAuthConfigResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, EmbeddingsRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse } from '@insforge/shared-schemas';
 export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SendRawEmailRequest as SendEmailOptions, SendEmailResponse, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
@@ -24,39 +24,74 @@ interface InsForgeConfig {
      * This token will be used for all authenticated requests
      */
     edgeFunctionToken?: string;
+    /**
+     * Direct URL to Deno Subhosting functions (optional)
+     * When provided, SDK will try this URL first for function invocations.
+     * Falls back to proxy URL if subhosting returns 404.
+     * @example "https://{appKey}.functions.insforge.app"
+     */
+    functionsUrl?: string;
     /**
      * Custom fetch implementation (useful for Node.js environments)
      */
     fetch?: typeof fetch;
     /**
-     * Storage adapter for persisting tokens
+     * Enable server-side auth mode (SSR/Node runtime)
+     * In this mode auth endpoints use `client_type=mobile` and refresh_token body flow.
+     * @default false
      */
-    storage?: TokenStorage;
+    isServerMode?: boolean;
     /**
-     * Whether to automatically refresh tokens before they expire
-     * @default true
+     * Custom headers to include with every request
      */
-    autoRefreshToken?: boolean;
+    headers?: Record<string, string>;
     /**
-     * Whether to persist session in storage
-     * @default true
+     * Enable debug logging for HTTP requests and responses.
+     * When true, request/response details are logged to the console.
+     * Can also be a custom log function for advanced use cases.
+     * @default false
      */
-    persistSession?: boolean;
+    debug?: boolean | ((message: string, ...args: any[]) => void);
     /**
-     * Custom headers to include with every request
+     * Request timeout in milliseconds.
+     * Requests that exceed this duration will be aborted.
+     * Set to 0 to disable timeout.
+     * @default 30000
      */
-    headers?: Record<string, string>;
-}
-interface TokenStorage {
-    getItem(key: string): string | null | Promise<string | null>;
-    setItem(key: string, value: string): void | Promise<void>;
-    removeItem(key: string): void | Promise<void>;
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts for failed requests.
+     * Retries are triggered on network errors and server errors (5xx).
+     * Client errors (4xx) are never retried.
+     * Set to 0 to disable retries.
+     * @default 3
+     */
+    retryCount?: number;
+    /**
+     * Initial delay in milliseconds before the first retry.
+     * The delay doubles with each subsequent attempt (exponential backoff)
+     * with ±15% jitter to prevent thundering herd.
+     * @default 500
+     */
+    retryDelay?: number;
+    /**
+     * Automatically refresh the access token when a request fails with 401 INVALID_TOKEN.
+     * When true, the SDK will attempt a token refresh and retry the original request.
+     * @default true
+     */
+    autoRefreshToken?: boolean;
 }
 interface AuthSession {
     user: UserSchema;
     accessToken: string;
     expiresAt?: Date;
 }
+interface AuthRefreshResponse {
+    user: UserSchema;
+    accessToken: string;
+    csrfToken?: string;
+    refreshToken?: string;
+}
 interface ApiError {
     error: string;
     message: string;
@@ -71,60 +106,83 @@ declare class InsForgeError extends Error {
     static fromApiError(apiError: ApiError): InsForgeError;
 }
 
-interface RequestOptions extends RequestInit {
-    params?: Record<string, string>;
-}
-declare class HttpClient {
-    readonly baseUrl: string;
-    readonly fetch: typeof fetch;
-    private defaultHeaders;
-    private anonKey;
-    private userToken;
-    constructor(config: InsForgeConfig);
-    private buildUrl;
-    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
-    get<T>(path: string, options?: RequestOptions): Promise<T>;
-    post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
-    put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
-    patch<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
-    delete<T>(path: string, options?: RequestOptions): Promise<T>;
-    setAuthToken(token: string | null): void;
-    getHeaders(): Record<string, string>;
-}
-
+type LogFunction = (message: string, ...args: any[]) => void;
 /**
- * Token Manager for InsForge SDK
+ * Debug logger for the InsForge SDK.
+ * Logs HTTP request/response details with automatic redaction of sensitive data.
  *
- * Simple token storage that supports two modes:
- * - Memory mode (new backend): tokens stored in memory only, more secure
- * - Storage mode (legacy backend): tokens persisted in localStorage
+ * @example
+ * ```typescript
+ * // Enable via SDK config
+ * const client = new InsForgeClient({ debug: true });
+ *
+ * // Or with a custom log function
+ * const client = new InsForgeClient({
+ *   debug: (msg) => myLogger.info(msg)
+ * });
+ * ```
  */
-
-declare class TokenManager {
-    private accessToken;
-    private user;
-    private storage;
-    private _mode;
-    constructor(storage?: TokenStorage);
+declare class Logger {
+    /** Whether debug logging is currently enabled */
+    enabled: boolean;
+    private customLog;
     /**
-     * Get current mode
+     * Creates a new Logger instance.
+     * @param debug - Set to true to enable console logging, or pass a custom log function
      */
-    get mode(): 'memory' | 'storage';
+    constructor(debug?: boolean | LogFunction);
     /**
-     * Set mode to memory (new backend with cookies + memory)
+     * Logs a debug message at the info level.
+     * @param message - The message to log
+     * @param args - Additional arguments to pass to the log function
      */
-    setMemoryMode(): void;
+    log(message: string, ...args: any[]): void;
     /**
-     * Set mode to storage (legacy backend with localStorage)
-     * Also loads existing session from localStorage
+     * Logs a debug message at the warning level.
+     * @param message - The message to log
+     * @param args - Additional arguments to pass to the log function
      */
-    setStorageMode(): void;
+    warn(message: string, ...args: any[]): void;
     /**
-     * Load session from localStorage
+     * Logs a debug message at the error level.
+     * @param message - The message to log
+     * @param args - Additional arguments to pass to the log function
      */
-    private loadFromStorage;
+    error(message: string, ...args: any[]): void;
     /**
-     * Save session (memory always, localStorage only in storage mode)
+     * Logs an outgoing HTTP request with method, URL, headers, and body.
+     * Sensitive headers and body fields are automatically redacted.
+     * @param method - HTTP method (GET, POST, etc.)
+     * @param url - The full request URL
+     * @param headers - Request headers (sensitive values will be redacted)
+     * @param body - Request body (sensitive fields will be masked)
+     */
+    logRequest(method: string, url: string, headers?: Record<string, string>, body?: any): void;
+    /**
+     * Logs an incoming HTTP response with method, URL, status, duration, and body.
+     * Error responses (4xx/5xx) are logged at the error level.
+     * @param method - HTTP method (GET, POST, etc.)
+     * @param url - The full request URL
+     * @param status - HTTP response status code
+     * @param durationMs - Request duration in milliseconds
+     * @param body - Response body (sensitive fields will be masked, large bodies truncated)
+     */
+    logResponse(method: string, url: string, status: number, durationMs: number, body?: any): void;
+}
+
+/**
+ * Token Manager for InsForge SDK
+ *
+ * Memory-only token storage.
+ */
+
+declare class TokenManager {
+    private accessToken;
+    private user;
+    onTokenChange: (() => void) | null;
+    constructor();
+    /**
+     * Save session in memory
      */
     saveSession(session: AuthSession): void;
     /**
@@ -148,143 +206,203 @@ declare class TokenManager {
      */
     setUser(user: UserSchema): void;
     /**
-     * Clear session (both memory and localStorage)
+     * Clear in-memory session
      */
     clearSession(): void;
+}
+
+type JsonRequestBody = Record<string, unknown> | unknown[] | null;
+interface RequestOptions extends Omit<RequestInit, 'body'> {
+    params?: Record<string, string>;
+    body?: RequestInit['body'] | JsonRequestBody;
+    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
+    idempotent?: boolean;
+}
+/**
+ * HTTP client with built-in retry, timeout, and exponential backoff support.
+ * Handles authentication, request serialization, and error normalization.
+ */
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly fetch: typeof fetch;
+    private defaultHeaders;
+    private anonKey;
+    private userToken;
+    private logger;
+    private autoRefreshToken;
+    private isRefreshing;
+    private refreshPromise;
+    private tokenManager;
+    private refreshToken;
+    private timeout;
+    private retryCount;
+    private retryDelay;
     /**
-     * Check if there's a session in localStorage (for legacy detection)
+     * Creates a new HttpClient instance.
+     * @param config - SDK configuration including baseUrl, timeout, retry settings, and fetch implementation.
+     * @param tokenManager - Token manager for session persistence.
+     * @param logger - Optional logger instance for request/response debugging.
      */
-    hasStoredSession(): boolean;
+    constructor(config: InsForgeConfig, tokenManager?: TokenManager, logger?: Logger);
+    /**
+     * Builds a full URL from a path and optional query parameters.
+     * Normalizes PostgREST select parameters for proper syntax.
+     */
+    private buildUrl;
+    /** Checks if an HTTP status code is eligible for retry (5xx server errors). */
+    private isRetryableStatus;
+    /**
+     * Computes the delay before the next retry using exponential backoff with jitter.
+     * @param attempt - The current retry attempt number (1-based).
+     * @returns Delay in milliseconds.
+     */
+    private computeRetryDelay;
+    /**
+     * Performs an HTTP request with automatic retry and timeout handling.
+     * Retries on network errors and 5xx server errors with exponential backoff.
+     * Client errors (4xx) and timeouts are thrown immediately without retry.
+     * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE).
+     * @param path - API path relative to the base URL.
+     * @param options - Optional request configuration including headers, body, and query params.
+     * @returns Parsed response data.
+     * @throws {InsForgeError} On timeout, network failure, or HTTP error responses.
+     */
+    private handleRequest;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a GET request. */
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a POST request with an optional JSON body. */
+    post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PUT request with an optional JSON body. */
+    put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PATCH request with an optional JSON body. */
+    patch<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a DELETE request. */
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Sets or clears the user authentication token for subsequent requests. */
+    setAuthToken(token: string | null): void;
+    setRefreshToken(token: string | null): void;
+    /** Returns the current default headers including the authorization header if set. */
+    getHeaders(): Record<string, string>;
+    handleTokenRefresh(): Promise<AuthRefreshResponse>;
 }
 
 /**
  * Auth module for InsForge SDK
- * Uses shared schemas for type safety
+ * Handles authentication, sessions, profiles, and email verification
  */
 
+interface AuthOptions {
+    isServerMode?: boolean;
+}
 declare class Auth {
     private http;
     private tokenManager;
-    constructor(http: HttpClient, tokenManager: TokenManager);
+    private options;
+    private authCallbackHandled;
+    constructor(http: HttpClient, tokenManager: TokenManager, options?: AuthOptions);
+    private isServerMode;
     /**
-     * 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)
+     * Save session from API response
+     * Handles token storage, CSRF token, and HTTP auth header
      */
-    private detectAuthCallback;
+    private saveSessionFromResponse;
     /**
-     * Sign up a new user
+     * Detect and handle OAuth callback parameters in URL
+     * Supports PKCE flow (insforge_code)
      */
+    private detectAuthCallback;
     signUp(request: CreateUserRequest): Promise<{
         data: CreateUserResponse | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Sign in with email and password
-     */
     signInWithPassword(request: CreateSessionRequest): Promise<{
         data: CreateSessionResponse | null;
         error: InsForgeError | null;
     }>;
+    signOut(): Promise<{
+        error: InsForgeError | null;
+    }>;
     /**
-     * Sign in with OAuth provider
+     * Sign in with OAuth provider using PKCE flow
      */
     signInWithOAuth(options: {
-        provider: OAuthProvidersSchema;
+        provider: OAuthProvidersSchema | string;
         redirectTo?: string;
         skipBrowserRedirect?: boolean;
     }): Promise<{
         data: {
             url?: string;
             provider?: string;
+            codeVerifier?: string;
         };
         error: InsForgeError | null;
     }>;
     /**
-     * Sign out the current user
+     * Exchange OAuth authorization code for tokens (PKCE flow)
+     * Called automatically on initialization when insforge_code is in URL
      */
-    signOut(): Promise<{
+    exchangeOAuthCode(code: string, codeVerifier?: string): Promise<{
+        data: CreateSessionResponse | null;
         error: InsForgeError | null;
     }>;
     /**
-     * Get all public authentication configuration (OAuth + Email)
-     * Returns both OAuth providers and email authentication settings in one request
-     * This is a public endpoint that doesn't require authentication
+     * Sign in with an ID token from a native SDK (Google One Tap, etc.)
+     * Use this for native mobile apps or Google One Tap on web.
      *
-     * @returns Complete public authentication configuration including OAuth providers and email auth settings
-     *
-     * @example
-     * ```ts
-     * const { data, error } = await insforge.auth.getPublicAuthConfig();
-     * if (data) {
-     *   console.log(`OAuth providers: ${data.oauth.data.length}`);
-     *   console.log(`Password min length: ${data.email.passwordMinLength}`);
-     * }
-     * ```
+     * @param credentials.provider - The identity provider (currently only 'google' is supported)
+     * @param credentials.token - The ID token from the native SDK
      */
-    getPublicAuthConfig(): Promise<{
-        data: GetPublicAuthConfigResponse | null;
+    signInWithIdToken(credentials: {
+        provider: 'google';
+        token: string;
+    }): Promise<{
+        data: CreateSessionResponse | null;
         error: InsForgeError | null;
     }>;
     /**
-     * Get the current user with full profile information
-     * Returns both auth info (id, email, role) and profile data (dynamic fields from users table)
-     */
-    getCurrentUser(): Promise<{
-        data: {
-            user: UserSchema;
-        } | null;
-        error: any | null;
-    }>;
-    /**
-     * Get any user's profile by ID
-     * Returns profile information from the users table
+     * Refresh the current auth session.
+     *
+     * Browser mode:
+     * - Uses httpOnly refresh cookie and optional CSRF header.
+     *
+     * Server mode (`isServerMode: true`):
+     * - Uses mobile auth flow and requires `refreshToken` in request body.
      */
-    getProfile(userId: string): Promise<{
-        data: GetProfileResponse | null;
+    refreshSession(options?: {
+        refreshToken?: string;
+    }): Promise<{
+        data: RefreshSessionResponse | null;
         error: InsForgeError | null;
     }>;
     /**
-     * Get the current session (only session data, no API call)
-     * Returns the stored JWT token and basic user info from local storage
+     * Get current user, automatically waits for pending OAuth callback
      */
-    getCurrentSession(): Promise<{
+    getCurrentUser(): Promise<{
         data: {
-            session: AuthSession | null;
+            user: UserSchema | null;
         };
         error: InsForgeError | null;
     }>;
-    /**
-     * Set/Update the current user's profile
-     * Updates profile information in the users table (supports any dynamic fields)
-     * Requires authentication
-     */
+    getProfile(userId: string): Promise<{
+        data: GetProfileResponse | null;
+        error: InsForgeError | null;
+    }>;
     setProfile(profile: Record<string, unknown>): Promise<{
         data: GetProfileResponse | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Send email verification (code or link based on config)
-     *
-     * Send email verification using the method configured in auth settings (verifyEmailMethod).
-     * When method is 'code', sends a 6-digit numeric code. When method is 'link', sends a magic link.
-     * Prevents user enumeration by returning success even if email doesn't exist.
-     */
-    sendVerificationEmail(request: SendVerificationEmailRequest): Promise<{
+    resendVerificationEmail(request: SendVerificationEmailRequest): Promise<{
         data: {
             success: boolean;
             message: string;
         } | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Send password reset (code or link based on config)
-     *
-     * Send password reset email using the method configured in auth settings (resetPasswordMethod).
-     * When method is 'code', sends a 6-digit numeric code for two-step flow.
-     * When method is 'link', sends a magic link.
-     * Prevents user enumeration by returning success even if email doesn't exist.
-     */
+    verifyEmail(request: VerifyEmailRequest): Promise<{
+        data: VerifyEmailResponse | null;
+        error: InsForgeError | null;
+    }>;
     sendResetPasswordEmail(request: SendResetPasswordEmailRequest): Promise<{
         data: {
             success: boolean;
@@ -292,60 +410,19 @@ declare class Auth {
         } | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Exchange reset password code for reset token
-     *
-     * Step 1 of two-step password reset flow (only used when resetPasswordMethod is 'code'):
-     * 1. Verify the 6-digit code sent to user's email
-     * 2. Return a reset token that can be used to actually reset the password
-     *
-     * This endpoint is not used when resetPasswordMethod is 'link' (magic link flow is direct).
-     */
     exchangeResetPasswordToken(request: ExchangeResetPasswordTokenRequest): Promise<{
-        data: {
-            token: string;
-            expiresAt: string;
-        } | null;
+        data: ExchangeResetPasswordTokenResponse | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Reset password with token
-     *
-     * Reset user password with a token. The token can be:
-     * - Magic link token (64-character hex token from send-reset-password when method is 'link')
-     * - Reset token (from exchange-reset-password-token after code verification when method is 'code')
-     *
-     * Both token types use RESET_PASSWORD purpose and are verified the same way.
-     *
-     * Flow summary:
-     * - Code method: send-reset-password → exchange-reset-password-token → reset-password (with resetToken)
-     * - Link method: send-reset-password → reset-password (with link token directly)
-     */
     resetPassword(request: {
         newPassword: string;
         otp: string;
     }): Promise<{
-        data: {
-            message: string;
-            redirectTo?: string;
-        } | null;
+        data: ResetPasswordResponse | null;
         error: InsForgeError | null;
     }>;
-    /**
-     * Verify email with code or link
-     *
-     * Verify email address using the method configured in auth settings (verifyEmailMethod):
-     * - Code verification: Provide both `email` and `otp` (6-digit numeric code)
-     * - Link verification: Provide only `otp` (64-character hex token from magic link)
-     *
-     * Successfully verified users will receive a session token.
-     *
-     * The email verification link sent to users always points to the backend API endpoint.
-     * If `verifyEmailRedirectTo` is configured, the backend will redirect to that URL after successful verification.
-     * Otherwise, a default success page is displayed.
-     */
-    verifyEmail(request: VerifyEmailRequest): Promise<{
-        data: VerifyEmailResponse | null;
+    getPublicAuthConfig(): Promise<{
+        data: GetPublicAuthConfigResponse | null;
         error: InsForgeError | null;
     }>;
 }
@@ -393,6 +470,27 @@ declare class Database {
      * - Upserts
      */
     from(table: string): _supabase_postgrest_js.PostgrestQueryBuilder<any, any, any, string, unknown>;
+    /**
+     * Call a PostgreSQL function (RPC)
+     *
+     * @example
+     * // Call a function with parameters
+     * const { data, error } = await client.database
+     *   .rpc('get_user_stats', { user_id: 123 });
+     *
+     * // Call a function with no parameters
+     * const { data, error } = await client.database
+     *   .rpc('get_all_active_users');
+     *
+     * // With options (head, count, get)
+     * const { data, count } = await client.database
+     *   .rpc('search_posts', { query: 'hello' }, { count: 'exact' });
+     */
+    rpc(fn: string, args?: Record<string, unknown>, options?: {
+        head?: boolean;
+        get?: boolean;
+        count?: 'exact' | 'planned' | 'estimated';
+    }): _supabase_postgrest_js.PostgrestFilterBuilder<any, any, any, any, string, null, "RPC">;
 }
 
 /**
@@ -489,6 +587,7 @@ declare class AI {
     private http;
     readonly chat: Chat;
     readonly images: Images;
+    readonly embeddings: Embeddings;
     constructor(http: HttpClient);
 }
 declare class Chat {
@@ -510,16 +609,46 @@ declare class ChatCompletions {
      * });
      * console.log(completion.choices[0].message.content);
      *
-     * // With images
+     * // With images (OpenAI-compatible format)
      * const response = await client.ai.chat.completions.create({
      *   model: 'gpt-4-vision',
      *   messages: [{
      *     role: 'user',
-     *     content: 'What is in this image?',
-     *     images: [{ url: 'https://example.com/image.jpg' }]
+     *     content: [
+     *       { type: 'text', text: 'What is in this image?' },
+     *       { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } }
+     *     ]
      *   }]
      * });
      *
+     * // With PDF files
+     * const pdfResponse = await client.ai.chat.completions.create({
+     *   model: 'anthropic/claude-3.5-sonnet',
+     *   messages: [{
+     *     role: 'user',
+     *     content: [
+     *       { type: 'text', text: 'Summarize this document' },
+     *       { type: 'file', file: { filename: 'doc.pdf', file_data: 'https://example.com/doc.pdf' } }
+     *     ]
+     *   }],
+     *   fileParser: { enabled: true, pdf: { engine: 'mistral-ocr' } }
+     * });
+     *
+     * // With web search
+     * const searchResponse = await client.ai.chat.completions.create({
+     *   model: 'openai/gpt-4',
+     *   messages: [{ role: 'user', content: 'What are the latest news about AI?' }],
+     *   webSearch: { enabled: true, maxResults: 5 }
+     * });
+     * // Access citations from response.choices[0].message.annotations
+     *
+     * // With thinking/reasoning mode (Anthropic models)
+     * const thinkingResponse = await client.ai.chat.completions.create({
+     *   model: 'anthropic/claude-3.5-sonnet',
+     *   messages: [{ role: 'user', content: 'Solve this complex math problem...' }],
+     *   thinking: true
+     * });
+     *
      * // Streaming - returns async iterable
      * const stream = await client.ai.chat.completions.create({
      *   model: 'gpt-4',
@@ -540,6 +669,47 @@ declare class ChatCompletions {
      */
     private parseSSEStream;
 }
+declare class Embeddings {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create embeddings for text input - OpenAI-like response format
+     *
+     * @example
+     * ```typescript
+     * // Single text input
+     * const response = await client.ai.embeddings.create({
+     *   model: 'openai/text-embedding-3-small',
+     *   input: 'Hello world'
+     * });
+     * console.log(response.data[0].embedding); // number[]
+     *
+     * // Multiple text inputs
+     * const response = await client.ai.embeddings.create({
+     *   model: 'openai/text-embedding-3-small',
+     *   input: ['Hello world', 'Goodbye world']
+     * });
+     * response.data.forEach((item, i) => {
+     *   console.log(`Embedding ${i}:`, item.embedding.slice(0, 5)); // First 5 dimensions
+     * });
+     *
+     * // With custom dimensions (if supported by model)
+     * const response = await client.ai.embeddings.create({
+     *   model: 'openai/text-embedding-3-small',
+     *   input: 'Hello world',
+     *   dimensions: 256
+     * });
+     *
+     * // With base64 encoding format
+     * const response = await client.ai.embeddings.create({
+     *   model: 'openai/text-embedding-3-small',
+     *   input: 'Hello world',
+     *   encoding_format: 'base64'
+     * });
+     * ```
+     */
+    create(params: EmbeddingsRequest): Promise<any>;
+}
 declare class Images {
     private http;
     constructor(http: HttpClient);
@@ -602,15 +772,27 @@ interface FunctionInvokeOptions {
  */
 declare class Functions {
     private http;
-    constructor(http: HttpClient);
+    private functionsUrl;
+    constructor(http: HttpClient, functionsUrl?: string);
+    /**
+     * Derive the subhosting URL from the base URL.
+     * Base URL pattern: https://{appKey}.{region}.insforge.app
+     * Functions URL:    https://{appKey}.functions.insforge.app
+     * Only applies to .insforge.app domains.
+     */
+    private static deriveSubhostingUrl;
     /**
      * Invokes an Edge Function
+     *
+     * If functionsUrl is configured, tries direct subhosting first.
+     * Falls back to proxy URL if subhosting returns 404.
+     *
      * @param slug The function slug to invoke
      * @param options Request options
      */
     invoke<T = any>(slug: string, options?: FunctionInvokeOptions): Promise<{
         data: T | null;
-        error: Error | null;
+        error: InsForgeError | null;
     }>;
 }
 
@@ -658,7 +840,8 @@ declare class Realtime {
     private connectPromise;
     private subscribedChannels;
     private eventListeners;
-    constructor(baseUrl: string, tokenManager: TokenManager);
+    private anonKey?;
+    constructor(baseUrl: string, tokenManager: TokenManager, anonKey?: string);
     private notifyListeners;
     /**
      * Connect to the realtime server
@@ -669,6 +852,12 @@ declare class Realtime {
      * Disconnect from the realtime server
      */
     disconnect(): void;
+    /**
+     * Handle token changes (e.g., after auth refresh)
+     * Updates socket auth so reconnects use the new token
+     * If connected, triggers reconnect to apply new token immediately
+     */
+    private onTokenChange;
     /**
      * Check if connected to the realtime server
      */
@@ -778,7 +967,7 @@ declare class Emails {
      */
     send(options: SendRawEmailRequest): Promise<{
         data: SendEmailResponse | null;
-        error: Error | null;
+        error: InsForgeError | null;
     }>;
 }
 
@@ -818,6 +1007,12 @@ declare class Emails {
  * const { data, error } = await client.functions.invoke('my-function', {
  *   body: { message: 'Hello from SDK' }
  * });
+ *
+ * // Enable debug logging
+ * const debugClient = new InsForgeClient({
+ *   baseUrl: 'http://localhost:7130',
+ *   debug: true
+ * });
  * ```
  */
 declare class InsForgeClient {
@@ -851,4 +1046,4 @@ declare class InsForgeClient {
 
 declare function createClient(config: InsForgeConfig): InsForgeClient;
 
-export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, createClient, InsForgeClient as default };
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Logger, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, createClient, InsForgeClient as default };