@fluxbase/sdk 0.0.1-rc.26 → 0.0.1-rc.28

package/dist/index.d.ts

@@ -131,7 +131,7 @@ interface OrderBy {
     nulls?: 'first' | 'last';
 }
 interface RealtimeMessage {
-    type: 'subscribe' | 'unsubscribe' | 'heartbeat' | 'broadcast' | 'ack' | 'error';
+    type: 'subscribe' | 'unsubscribe' | 'heartbeat' | 'broadcast' | 'presence' | 'ack' | 'error';
     channel?: string;
     event?: string;
     schema?: string;
@@ -140,6 +140,8 @@ interface RealtimeMessage {
     payload?: unknown;
     error?: string;
     config?: PostgresChangesConfig;
+    presence?: any;
+    broadcast?: any;
 }
 interface PostgresChangesConfig {
     event: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
@@ -183,6 +185,57 @@ interface RealtimeChangePayload {
     timestamp: string;
 }
 type RealtimeCallback = (payload: RealtimePostgresChangesPayload) => void;
+/**
+ * Realtime channel configuration options
+ */
+interface RealtimeChannelConfig {
+    broadcast?: {
+        self?: boolean;
+        ack?: boolean;
+    };
+    presence?: {
+        key?: string;
+    };
+}
+/**
+ * Presence state for a user
+ */
+interface PresenceState {
+    [key: string]: any;
+}
+/**
+ * Realtime presence payload structure
+ */
+interface RealtimePresencePayload {
+    event: 'sync' | 'join' | 'leave';
+    key?: string;
+    newPresences?: PresenceState[];
+    leftPresences?: PresenceState[];
+    currentPresences?: Record<string, PresenceState[]>;
+}
+/**
+ * Presence callback type
+ */
+type PresenceCallback = (payload: RealtimePresencePayload) => void;
+/**
+ * Broadcast message structure
+ */
+interface BroadcastMessage {
+    type: 'broadcast';
+    event: string;
+    payload: any;
+}
+/**
+ * Realtime broadcast payload structure
+ */
+interface RealtimeBroadcastPayload {
+    event: string;
+    payload: any;
+}
+/**
+ * Broadcast callback type
+ */
+type BroadcastCallback = (payload: RealtimeBroadcastPayload) => void;
 /**
  * File object returned by storage operations
  * Compatible with Supabase FileObject structure
@@ -201,11 +254,24 @@ interface FileObject {
  * @deprecated Use FileObject instead. This alias is provided for backwards compatibility.
  */
 type StorageObject = FileObject;
+/**
+ * Upload progress information
+ */
+interface UploadProgress {
+    /** Number of bytes uploaded so far */
+    loaded: number;
+    /** Total number of bytes to upload */
+    total: number;
+    /** Upload percentage (0-100) */
+    percentage: number;
+}
 interface UploadOptions {
     contentType?: string;
     metadata?: Record<string, string>;
     cacheControl?: string;
     upsert?: boolean;
+    /** Optional callback to track upload progress */
+    onUploadProgress?: (progress: UploadProgress) => void;
 }
 interface ListOptions {
     prefix?: string;
@@ -1124,12 +1190,17 @@ declare class RealtimeChannel {
     private token;
     private channelName;
     private callbacks;
+    private presenceCallbacks;
+    private broadcastCallbacks;
     private subscriptionConfig;
+    private _presenceState;
+    private myPresenceKey;
+    private config;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectDelay;
     private heartbeatInterval;
-    constructor(url: string, channelName: string, token?: string | null);
+    constructor(url: string, channelName: string, token?: string | null, config?: RealtimeChannelConfig);
     /**
      * Listen to postgres_changes with optional row-level filtering
      *
@@ -1166,6 +1237,42 @@ declare class RealtimeChannel {
      * ```
      */
     on(event: "INSERT" | "UPDATE" | "DELETE" | "*", callback: RealtimeCallback): this;
+    /**
+     * Listen to broadcast messages
+     *
+     * @param event - 'broadcast'
+     * @param config - Configuration with event name
+     * @param callback - Function to call when broadcast received
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('broadcast', { event: 'cursor-pos' }, (payload) => {
+     *   console.log('Cursor moved:', payload)
+     * })
+     * ```
+     */
+    on(event: "broadcast", config: {
+        event: string;
+    }, callback: BroadcastCallback): this;
+    /**
+     * Listen to presence events
+     *
+     * @param event - 'presence'
+     * @param config - Configuration with event type (sync, join, leave)
+     * @param callback - Function to call when presence changes
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('presence', { event: 'sync' }, (payload) => {
+     *   console.log('Presence synced:', payload)
+     * })
+     * ```
+     */
+    on(event: "presence", config: {
+        event: "sync" | "join" | "leave";
+    }, callback: PresenceCallback): this;
     /**
      * Remove a callback
      */
@@ -1182,6 +1289,60 @@ declare class RealtimeChannel {
      * @returns Promise resolving to status string (Supabase-compatible)
      */
     unsubscribe(timeout?: number): Promise<"ok" | "timed out" | "error">;
+    /**
+     * Send a broadcast message to all subscribers on this channel
+     *
+     * @param message - Broadcast message with type, event, and payload
+     * @returns Promise resolving to status
+     *
+     * @example
+     * ```typescript
+     * await channel.send({
+     *   type: 'broadcast',
+     *   event: 'cursor-pos',
+     *   payload: { x: 100, y: 200 }
+     * })
+     * ```
+     */
+    send(message: BroadcastMessage): Promise<"ok" | "error">;
+    /**
+     * Track user presence on this channel
+     *
+     * @param state - Presence state to track
+     * @returns Promise resolving to status
+     *
+     * @example
+     * ```typescript
+     * await channel.track({
+     *   user_id: 123,
+     *   status: 'online'
+     * })
+     * ```
+     */
+    track(state: PresenceState): Promise<"ok" | "error">;
+    /**
+     * Stop tracking presence on this channel
+     *
+     * @returns Promise resolving to status
+     *
+     * @example
+     * ```typescript
+     * await channel.untrack()
+     * ```
+     */
+    untrack(): Promise<"ok" | "error">;
+    /**
+     * Get current presence state for all users on this channel
+     *
+     * @returns Current presence state
+     *
+     * @example
+     * ```typescript
+     * const state = channel.presenceState()
+     * console.log('Online users:', Object.keys(state).length)
+     * ```
+     */
+    presenceState(): Record<string, PresenceState[]>;
     /**
      * Internal: Connect to WebSocket
      */
@@ -1193,7 +1354,7 @@ declare class RealtimeChannel {
     /**
      * Internal: Send a message
      */
-    private send;
+    private sendMessage;
     /**
      * Internal: Handle incoming message
      */
@@ -1201,7 +1362,15 @@ declare class RealtimeChannel {
     /**
      * Internal: Handle broadcast message
      */
-    private handleBroadcast;
+    private handleBroadcastMessage;
+    /**
+     * Internal: Handle presence message
+     */
+    private handlePresenceMessage;
+    /**
+     * Internal: Handle postgres_changes message
+     */
+    private handlePostgresChanges;
     /**
      * Internal: Start heartbeat interval
      */
@@ -1221,18 +1390,43 @@ declare class FluxbaseRealtime {
     private channels;
     constructor(url: string, token?: string | null);
     /**
-     * Create or get a channel
+     * Create or get a channel with optional configuration
+     *
      * @param channelName - Channel name (e.g., 'table:public.products')
+     * @param config - Optional channel configuration
+     * @returns RealtimeChannel instance
+     *
+     * @example
+     * ```typescript
+     * const channel = realtime.channel('room-1', {
+     *   broadcast: { self: true, ack: true },
+     *   presence: { key: 'user-123' }
+     * })
+     * ```
      */
-    channel(channelName: string): RealtimeChannel;
+    channel(channelName: string, config?: RealtimeChannelConfig): RealtimeChannel;
+    /**
+     * Remove a specific channel
+     *
+     * @param channel - The channel to remove
+     * @returns Promise resolving to status
+     *
+     * @example
+     * ```typescript
+     * const channel = realtime.channel('room-1')
+     * await realtime.removeChannel(channel)
+     * ```
+     */
+    removeChannel(channel: RealtimeChannel): Promise<"ok" | "error">;
     /**
      * Remove all channels
      */
     removeAllChannels(): void;
     /**
      * Update auth token for all channels
+     * @param token - The new auth token
      */
-    setToken(token: string | null): void;
+    setAuth(token: string | null): void;
 }
 
 /**
@@ -1302,21 +1496,28 @@ declare class FluxbaseAuth {
     private stateChangeListeners;
     constructor(fetch: FluxbaseFetch, autoRefresh?: boolean, persist?: boolean);
     /**
-     * Get the current session
+     * Get the current session (Supabase-compatible)
+     * Returns the session from the client-side cache without making a network request
      */
-    getSession(): AuthSession | null;
+    getSession(): Promise<FluxbaseResponse<{
+        session: AuthSession | null;
+    }>>;
     /**
-     * Get the current user
+     * Get the current user (Supabase-compatible)
+     * Returns the user from the client-side session without making a network request
+     * For server-side validation, use getCurrentUser() instead
      */
-    getUser(): User | null;
+    getUser(): Promise<FluxbaseResponse<{
+        user: User | null;
+    }>>;
     /**
      * Get the current access token
      */
     getAccessToken(): string | null;
     /**
-     * Listen to auth state changes
+     * Listen to auth state changes (Supabase-compatible)
      * @param callback - Function called when auth state changes
-     * @returns Subscription object with unsubscribe method
+     * @returns Object containing subscription data
      *
      * @example
      * ```typescript
@@ -1328,7 +1529,11 @@ declare class FluxbaseAuth {
      * subscription.unsubscribe()
      * ```
      */
-    onAuthStateChange(callback: AuthStateChangeCallback): AuthSubscription;
+    onAuthStateChange(callback: AuthStateChangeCallback): {
+        data: {
+            subscription: AuthSubscription;
+        };
+    };
     /**
      * Sign in with email and password
      * Returns AuthSession if successful, or SignInWith2FAResponse if 2FA is required
@@ -1349,9 +1554,13 @@ declare class FluxbaseAuth {
      */
     signOut(): Promise<VoidResponse>;
     /**
-     * Refresh the access token
+     * Refresh the session (Supabase-compatible)
+     * Returns a new session with refreshed tokens
      */
-    refreshToken(): Promise<SessionResponse>;
+    refreshSession(): Promise<FluxbaseResponse<{
+        session: AuthSession;
+        user: User;
+    }>>;
     /**
      * Get the current user from the server
      */
@@ -1361,9 +1570,15 @@ declare class FluxbaseAuth {
      */
     updateUser(data: Partial<Pick<User, "email" | "metadata">>): Promise<UserResponse>;
     /**
-     * Set the auth token manually
+     * Set the session manually (Supabase-compatible)
+     * Useful for restoring a session from storage or SSR scenarios
+     * @param session - Object containing access_token and refresh_token
+     * @returns Promise with session data
      */
-    setToken(token: string): void;
+    setSession(session: {
+        access_token: string;
+        refresh_token: string;
+    }): Promise<FluxbaseAuthResponse>;
     /**
      * Setup 2FA for the current user
      * Returns TOTP secret and QR code URL
@@ -1463,7 +1678,7 @@ declare class FluxbaseAuth {
     /**
      * Internal: Set the session and persist it
      */
-    private setSession;
+    private setSessionInternal;
     /**
      * Internal: Clear the session
      */
@@ -1504,6 +1719,11 @@ declare class StorageBucket {
         } | null;
         error: Error | null;
     }>;
+    /**
+     * Upload with progress tracking using XMLHttpRequest
+     * @private
+     */
+    private uploadWithProgress;
     /**
      * Download a file from the bucket
      * @param path - The path/key of the file
@@ -4383,33 +4603,42 @@ declare class FluxbaseClient<Database = any, _SchemaName extends string & keyof
      */
     setAuthToken(token: string | null): void;
     /**
-     * Create or get a realtime channel (Supabase-compatible alias)
-     *
-     * This is a convenience method that delegates to client.realtime.channel().
-     * Both patterns work identically:
-     * - client.channel('room-1') - Supabase-style
-     * - client.realtime.channel('room-1') - Fluxbase-style
+     * Create or get a realtime channel (Supabase-compatible)
      *
      * @param name - Channel name
+     * @param config - Optional channel configuration
      * @returns RealtimeChannel instance
      *
      * @example
      * ```typescript
-     * // Supabase-compatible usage
-     * const channel = client.channel('room-1')
-     *   .on('postgres_changes', {
-     *     event: '*',
-     *     schema: 'public',
-     *     table: 'messages'
-     *   }, (payload) => {
-     *     console.log('Change:', payload)
+     * const channel = client.channel('room-1', {
+     *   broadcast: { self: true },
+     *   presence: { key: 'user-123' }
+     * })
+     *   .on('broadcast', { event: 'message' }, (payload) => {
+     *     console.log('Message:', payload)
      *   })
      *   .subscribe()
      * ```
      *
      * @category Realtime
      */
-    channel(name: string): RealtimeChannel;
+    channel(name: string, config?: RealtimeChannelConfig): RealtimeChannel;
+    /**
+     * Remove a realtime channel (Supabase-compatible)
+     *
+     * @param channel - The channel to remove
+     * @returns Promise resolving to status
+     *
+     * @example
+     * ```typescript
+     * const channel = client.channel('room-1')
+     * await client.removeChannel(channel)
+     * ```
+     *
+     * @category Realtime
+     */
+    removeChannel(channel: RealtimeChannel): Promise<"error" | "ok">;
     /**
      * Get the internal HTTP client
      *
@@ -4465,4 +4694,4 @@ declare class FluxbaseClient<Database = any, _SchemaName extends string & keyof
  */
 declare function createClient<Database = any, SchemaName extends string & keyof Database = any>(fluxbaseUrl: string, fluxbaseKey: string, options?: FluxbaseClientOptions): FluxbaseClient<Database, SchemaName>;
 
-export { type APIKey, APIKeysManager, type AcceptInvitationRequest, type AcceptInvitationResponse, type AdminAuthResponse, type AdminLoginRequest, type AdminMeResponse, type AdminRefreshRequest, type AdminRefreshResponse, type AdminSetupRequest, type AdminSetupStatusResponse, type AdminUser, type AppSettings, AppSettingsManager, type AuthResponse, type AuthSession, type AuthSettings, AuthSettingsManager, type AuthenticationSettings, type Column, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateColumnRequest, type CreateFunctionRequest, type CreateInvitationRequest, type CreateInvitationResponse, type CreateOAuthProviderRequest, type CreateOAuthProviderResponse, type CreateSchemaRequest, type CreateSchemaResponse, type CreateTableRequest, type CreateTableResponse, type CreateWebhookRequest, DDLManager, type DataResponse, type DeleteAPIKeyResponse, type DeleteOAuthProviderResponse, type DeleteTableResponse, type DeleteUserResponse, type DeleteWebhookResponse, type EdgeFunction, type EdgeFunctionExecution, type EmailSettings, type EmailTemplate, EmailTemplateManager, type EmailTemplateType, type EnrichedUser, type FeatureSettings, type FileObject, type FilterOperator, FluxbaseAdmin, FluxbaseAuth, type FluxbaseAuthResponse, FluxbaseClient, type FluxbaseClientOptions, type FluxbaseError, FluxbaseFetch, FluxbaseFunctions, FluxbaseManagement, FluxbaseOAuth, FluxbaseRealtime, type FluxbaseResponse, FluxbaseSettings, FluxbaseStorage, type FunctionInvokeOptions, type GetImpersonationResponse, type HttpMethod, type ImpersonateAnonRequest, type ImpersonateServiceRequest, type ImpersonateUserRequest, ImpersonationManager, type ImpersonationSession, type ImpersonationTargetUser, type ImpersonationType, type Invitation, InvitationsManager, type InviteUserRequest, type InviteUserResponse, type ListAPIKeysResponse, type ListEmailTemplatesResponse, type ListImpersonationSessionsOptions, type ListImpersonationSessionsResponse, type ListInvitationsOptions, type ListInvitationsResponse, type ListOAuthProvidersResponse, type ListOptions, type ListSchemasResponse, type ListSystemSettingsResponse, type ListTablesResponse, type ListUsersOptions, type ListUsersResponse, type ListWebhookDeliveriesResponse, type ListWebhooksResponse, type MailgunSettings, type OAuthProvider, OAuthProviderManager, type OrderBy, type OrderDirection, type PostgresChangesConfig, type PostgrestError, type PostgrestResponse, QueryBuilder, type QueryFilter, type RealtimeCallback, type RealtimeChangePayload, RealtimeChannel, type RealtimeMessage, type RealtimePostgresChangesPayload, type RequestOptions, type ResetUserPasswordResponse, type RevokeAPIKeyResponse, type RevokeInvitationResponse, type SESSettings, type SMTPSettings, type Schema, type SecuritySettings, type SendGridSettings, type SessionResponse, SettingsClient, type SignInCredentials, type SignInWith2FAResponse, type SignUpCredentials, type SignedUrlOptions, type StartImpersonationResponse, type StopImpersonationResponse, StorageBucket, type StorageObject, type SupabaseAuthResponse, type SupabaseResponse, type SystemSetting, SystemSettingsManager, type Table, type TestEmailTemplateRequest, type TestWebhookResponse, type TwoFactorEnableResponse, type TwoFactorSetupResponse, type TwoFactorStatusResponse, type TwoFactorVerifyRequest, type UpdateAPIKeyRequest, type UpdateAppSettingsRequest, type UpdateAuthSettingsRequest, type UpdateAuthSettingsResponse, type UpdateEmailTemplateRequest, type UpdateFunctionRequest, type UpdateOAuthProviderRequest, type UpdateOAuthProviderResponse, type UpdateSystemSettingRequest, type UpdateUserRoleRequest, type UpdateWebhookRequest, type UploadOptions, type User, type UserResponse, type ValidateInvitationResponse, type VoidResponse, type Webhook, type WebhookDelivery, WebhooksManager, createClient };
+export { type APIKey, APIKeysManager, type AcceptInvitationRequest, type AcceptInvitationResponse, type AdminAuthResponse, type AdminLoginRequest, type AdminMeResponse, type AdminRefreshRequest, type AdminRefreshResponse, type AdminSetupRequest, type AdminSetupStatusResponse, type AdminUser, type AppSettings, AppSettingsManager, type AuthResponse, type AuthSession, type AuthSettings, AuthSettingsManager, type AuthenticationSettings, type BroadcastCallback, type BroadcastMessage, type Column, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateColumnRequest, type CreateFunctionRequest, type CreateInvitationRequest, type CreateInvitationResponse, type CreateOAuthProviderRequest, type CreateOAuthProviderResponse, type CreateSchemaRequest, type CreateSchemaResponse, type CreateTableRequest, type CreateTableResponse, type CreateWebhookRequest, DDLManager, type DataResponse, type DeleteAPIKeyResponse, type DeleteOAuthProviderResponse, type DeleteTableResponse, type DeleteUserResponse, type DeleteWebhookResponse, type EdgeFunction, type EdgeFunctionExecution, type EmailSettings, type EmailTemplate, EmailTemplateManager, type EmailTemplateType, type EnrichedUser, type FeatureSettings, type FileObject, type FilterOperator, FluxbaseAdmin, FluxbaseAuth, type FluxbaseAuthResponse, FluxbaseClient, type FluxbaseClientOptions, type FluxbaseError, FluxbaseFetch, FluxbaseFunctions, FluxbaseManagement, FluxbaseOAuth, FluxbaseRealtime, type FluxbaseResponse, FluxbaseSettings, FluxbaseStorage, type FunctionInvokeOptions, type GetImpersonationResponse, type HttpMethod, type ImpersonateAnonRequest, type ImpersonateServiceRequest, type ImpersonateUserRequest, ImpersonationManager, type ImpersonationSession, type ImpersonationTargetUser, type ImpersonationType, type Invitation, InvitationsManager, type InviteUserRequest, type InviteUserResponse, type ListAPIKeysResponse, type ListEmailTemplatesResponse, type ListImpersonationSessionsOptions, type ListImpersonationSessionsResponse, type ListInvitationsOptions, type ListInvitationsResponse, type ListOAuthProvidersResponse, type ListOptions, type ListSchemasResponse, type ListSystemSettingsResponse, type ListTablesResponse, type ListUsersOptions, type ListUsersResponse, type ListWebhookDeliveriesResponse, type ListWebhooksResponse, type MailgunSettings, type OAuthProvider, OAuthProviderManager, type OrderBy, type OrderDirection, type PostgresChangesConfig, type PostgrestError, type PostgrestResponse, type PresenceCallback, type PresenceState, QueryBuilder, type QueryFilter, type RealtimeBroadcastPayload, type RealtimeCallback, type RealtimeChangePayload, RealtimeChannel, type RealtimeChannelConfig, type RealtimeMessage, type RealtimePostgresChangesPayload, type RealtimePresencePayload, type RequestOptions, type ResetUserPasswordResponse, type RevokeAPIKeyResponse, type RevokeInvitationResponse, type SESSettings, type SMTPSettings, type Schema, type SecuritySettings, type SendGridSettings, type SessionResponse, SettingsClient, type SignInCredentials, type SignInWith2FAResponse, type SignUpCredentials, type SignedUrlOptions, type StartImpersonationResponse, type StopImpersonationResponse, StorageBucket, type StorageObject, type SupabaseAuthResponse, type SupabaseResponse, type SystemSetting, SystemSettingsManager, type Table, type TestEmailTemplateRequest, type TestWebhookResponse, type TwoFactorEnableResponse, type TwoFactorSetupResponse, type TwoFactorStatusResponse, type TwoFactorVerifyRequest, type UpdateAPIKeyRequest, type UpdateAppSettingsRequest, type UpdateAuthSettingsRequest, type UpdateAuthSettingsResponse, type UpdateEmailTemplateRequest, type UpdateFunctionRequest, type UpdateOAuthProviderRequest, type UpdateOAuthProviderResponse, type UpdateSystemSettingRequest, type UpdateUserRoleRequest, type UpdateWebhookRequest, type UploadOptions, type UploadProgress, type User, type UserResponse, type ValidateInvitationResponse, type VoidResponse, type Webhook, type WebhookDelivery, WebhooksManager, createClient };