@fluxbase/sdk 0.0.2-rc.2 → 0.1.0-rc.1

package/dist/index.d.cts

@@ -135,8 +135,19 @@ interface OrderBy {
 interface RealtimeMessage {
     type: 'subscribe' | 'unsubscribe' | 'heartbeat' | 'broadcast' | 'ack' | 'error';
     channel?: string;
+    event?: string;
+    schema?: string;
+    table?: string;
+    filter?: string;
     payload?: unknown;
     error?: string;
+    config?: PostgresChangesConfig;
+}
+interface PostgresChangesConfig {
+    event: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+    schema: string;
+    table: string;
+    filter?: string;
 }
 interface RealtimeChangePayload {
     type: 'INSERT' | 'UPDATE' | 'DELETE';
@@ -788,6 +799,23 @@ interface ListImpersonationSessionsResponse {
     sessions: ImpersonationSession[];
     total: number;
 }
+/**
+ * Auth state change events
+ */
+type AuthChangeEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'PASSWORD_RECOVERY' | 'MFA_CHALLENGE_VERIFIED';
+/**
+ * Callback for auth state changes
+ */
+type AuthStateChangeCallback = (event: AuthChangeEvent, session: AuthSession | null) => void;
+/**
+ * Subscription object returned by onAuthStateChange
+ */
+interface AuthSubscription {
+    /**
+     * Unsubscribe from auth state changes
+     */
+    unsubscribe: () => void;
+}
 
 /**
  * HTTP client for making requests to the Fluxbase API
@@ -853,6 +881,7 @@ declare class FluxbaseAuth {
     private persist;
     private autoRefresh;
     private refreshTimer;
+    private stateChangeListeners;
     constructor(fetch: FluxbaseFetch, autoRefresh?: boolean, persist?: boolean);
     /**
      * Get the current session
@@ -866,6 +895,22 @@ declare class FluxbaseAuth {
      * Get the current access token
      */
     getAccessToken(): string | null;
+    /**
+     * Listen to auth state changes
+     * @param callback - Function called when auth state changes
+     * @returns Subscription object with unsubscribe method
+     *
+     * @example
+     * ```typescript
+     * const { data: { subscription } } = client.auth.onAuthStateChange((event, session) => {
+     *   console.log('Auth event:', event, session)
+     * })
+     *
+     * // Later, to unsubscribe:
+     * subscription.unsubscribe()
+     * ```
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): AuthSubscription;
     /**
      * Sign in with email and password
      * Returns AuthSession if successful, or SignInWith2FAResponse if 2FA is required
@@ -996,6 +1041,10 @@ declare class FluxbaseAuth {
      * Internal: Schedule automatic token refresh
      */
     private scheduleTokenRefresh;
+    /**
+     * Internal: Emit auth state change event to all listeners
+     */
+    private emitAuthChange;
 }
 
 /**
@@ -1008,15 +1057,46 @@ declare class RealtimeChannel {
     private token;
     private channelName;
     private callbacks;
+    private subscriptionConfig;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectDelay;
     private heartbeatInterval;
     constructor(url: string, channelName: string, token?: string | null);
     /**
-     * Listen to a specific event type
+     * Listen to postgres_changes with optional row-level filtering
+     *
+     * @param event - 'postgres_changes'
+     * @param config - Configuration including optional filter
+     * @param callback - Function to call when changes occur
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('postgres_changes', {
+     *   event: '*',
+     *   schema: 'public',
+     *   table: 'jobs',
+     *   filter: 'created_by=eq.user123'
+     * }, (payload) => {
+     *   console.log('Job updated:', payload)
+     * })
+     * ```
+     */
+    on(event: 'postgres_changes', config: PostgresChangesConfig, callback: RealtimeCallback): this;
+    /**
+     * Listen to a specific event type (backwards compatibility)
+     *
      * @param event - The event type (INSERT, UPDATE, DELETE, or '*' for all)
      * @param callback - The callback function
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('INSERT', (payload) => {
+     *   console.log('New record inserted:', payload.new_record)
+     * })
+     * ```
      */
     on(event: 'INSERT' | 'UPDATE' | 'DELETE' | '*', callback: RealtimeCallback): this;
     /**
@@ -2727,6 +2807,27 @@ declare class FluxbaseAdmin {
      * ```
      */
     listUsers(options?: ListUsersOptions): Promise<ListUsersResponse>;
+    /**
+     * Get a user by ID
+     *
+     * Fetch a single user's details by their user ID
+     *
+     * @param userId - User ID to fetch
+     * @param type - User type ('app' or 'dashboard')
+     * @returns User details with metadata
+     *
+     * @example
+     * ```typescript
+     * // Get an app user
+     * const user = await admin.getUserById('user-123');
+     *
+     * // Get a dashboard user
+     * const dashboardUser = await admin.getUserById('admin-456', 'dashboard');
+     * console.log('User email:', dashboardUser.email);
+     * console.log('Last login:', dashboardUser.last_login_at);
+     * ```
+     */
+    getUserById(userId: string, type?: "app" | "dashboard"): Promise<EnrichedUser>;
     /**
      * Invite a new user
      *
@@ -2748,7 +2849,7 @@ declare class FluxbaseAdmin {
      * console.log('Invitation link:', response.invitation_link);
      * ```
      */
-    inviteUser(request: InviteUserRequest, type?: 'app' | 'dashboard'): Promise<InviteUserResponse>;
+    inviteUser(request: InviteUserRequest, type?: "app" | "dashboard"): Promise<InviteUserResponse>;
     /**
      * Delete a user
      *
@@ -2764,7 +2865,7 @@ declare class FluxbaseAdmin {
      * console.log('User deleted');
      * ```
      */
-    deleteUser(userId: string, type?: 'app' | 'dashboard'): Promise<DeleteUserResponse>;
+    deleteUser(userId: string, type?: "app" | "dashboard"): Promise<DeleteUserResponse>;
     /**
      * Update user role
      *
@@ -2781,7 +2882,7 @@ declare class FluxbaseAdmin {
      * console.log('User role updated:', user.role);
      * ```
      */
-    updateUserRole(userId: string, role: string, type?: 'app' | 'dashboard'): Promise<EnrichedUser>;
+    updateUserRole(userId: string, role: string, type?: "app" | "dashboard"): Promise<EnrichedUser>;
     /**
      * Reset user password
      *
@@ -2797,7 +2898,7 @@ declare class FluxbaseAdmin {
      * console.log(response.message);
      * ```
      */
-    resetUserPassword(userId: string, type?: 'app' | 'dashboard'): Promise<ResetUserPasswordResponse>;
+    resetUserPassword(userId: string, type?: "app" | "dashboard"): Promise<ResetUserPasswordResponse>;
 }
 
 /**
@@ -2805,7 +2906,7 @@ declare class FluxbaseAdmin {
  * Inspired by Supabase's PostgREST client
  */
 
-declare class QueryBuilder<T = unknown> {
+declare class QueryBuilder<T = unknown> implements PromiseLike<PostgrestResponse<T>> {
     private fetch;
     private table;
     private selectQuery;
@@ -3122,6 +3223,20 @@ declare class QueryBuilder<T = unknown> {
      * Execute the query and return results
      */
     execute(): Promise<PostgrestResponse<T>>;
+    /**
+     * Make QueryBuilder awaitable (implements PromiseLike)
+     * This allows using `await client.from('table').select()` without calling `.execute()`
+     *
+     * @example
+     * ```typescript
+     * // Without .execute() (new way)
+     * const { data } = await client.from('users').select('*')
+     *
+     * // With .execute() (old way, still supported)
+     * const { data } = await client.from('users').select('*').execute()
+     * ```
+     */
+    then<TResult1 = PostgrestResponse<T>, TResult2 = never>(onfulfilled?: ((value: PostgrestResponse<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
     /**
      * Build the query string from filters, ordering, etc.
      */

package/dist/index.d.ts

@@ -135,8 +135,19 @@ interface OrderBy {
 interface RealtimeMessage {
     type: 'subscribe' | 'unsubscribe' | 'heartbeat' | 'broadcast' | 'ack' | 'error';
     channel?: string;
+    event?: string;
+    schema?: string;
+    table?: string;
+    filter?: string;
     payload?: unknown;
     error?: string;
+    config?: PostgresChangesConfig;
+}
+interface PostgresChangesConfig {
+    event: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+    schema: string;
+    table: string;
+    filter?: string;
 }
 interface RealtimeChangePayload {
     type: 'INSERT' | 'UPDATE' | 'DELETE';
@@ -788,6 +799,23 @@ interface ListImpersonationSessionsResponse {
     sessions: ImpersonationSession[];
     total: number;
 }
+/**
+ * Auth state change events
+ */
+type AuthChangeEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'PASSWORD_RECOVERY' | 'MFA_CHALLENGE_VERIFIED';
+/**
+ * Callback for auth state changes
+ */
+type AuthStateChangeCallback = (event: AuthChangeEvent, session: AuthSession | null) => void;
+/**
+ * Subscription object returned by onAuthStateChange
+ */
+interface AuthSubscription {
+    /**
+     * Unsubscribe from auth state changes
+     */
+    unsubscribe: () => void;
+}
 
 /**
  * HTTP client for making requests to the Fluxbase API
@@ -853,6 +881,7 @@ declare class FluxbaseAuth {
     private persist;
     private autoRefresh;
     private refreshTimer;
+    private stateChangeListeners;
     constructor(fetch: FluxbaseFetch, autoRefresh?: boolean, persist?: boolean);
     /**
      * Get the current session
@@ -866,6 +895,22 @@ declare class FluxbaseAuth {
      * Get the current access token
      */
     getAccessToken(): string | null;
+    /**
+     * Listen to auth state changes
+     * @param callback - Function called when auth state changes
+     * @returns Subscription object with unsubscribe method
+     *
+     * @example
+     * ```typescript
+     * const { data: { subscription } } = client.auth.onAuthStateChange((event, session) => {
+     *   console.log('Auth event:', event, session)
+     * })
+     *
+     * // Later, to unsubscribe:
+     * subscription.unsubscribe()
+     * ```
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): AuthSubscription;
     /**
      * Sign in with email and password
      * Returns AuthSession if successful, or SignInWith2FAResponse if 2FA is required
@@ -996,6 +1041,10 @@ declare class FluxbaseAuth {
      * Internal: Schedule automatic token refresh
      */
     private scheduleTokenRefresh;
+    /**
+     * Internal: Emit auth state change event to all listeners
+     */
+    private emitAuthChange;
 }
 
 /**
@@ -1008,15 +1057,46 @@ declare class RealtimeChannel {
     private token;
     private channelName;
     private callbacks;
+    private subscriptionConfig;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectDelay;
     private heartbeatInterval;
     constructor(url: string, channelName: string, token?: string | null);
     /**
-     * Listen to a specific event type
+     * Listen to postgres_changes with optional row-level filtering
+     *
+     * @param event - 'postgres_changes'
+     * @param config - Configuration including optional filter
+     * @param callback - Function to call when changes occur
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('postgres_changes', {
+     *   event: '*',
+     *   schema: 'public',
+     *   table: 'jobs',
+     *   filter: 'created_by=eq.user123'
+     * }, (payload) => {
+     *   console.log('Job updated:', payload)
+     * })
+     * ```
+     */
+    on(event: 'postgres_changes', config: PostgresChangesConfig, callback: RealtimeCallback): this;
+    /**
+     * Listen to a specific event type (backwards compatibility)
+     *
      * @param event - The event type (INSERT, UPDATE, DELETE, or '*' for all)
      * @param callback - The callback function
+     * @returns This channel for chaining
+     *
+     * @example
+     * ```typescript
+     * channel.on('INSERT', (payload) => {
+     *   console.log('New record inserted:', payload.new_record)
+     * })
+     * ```
      */
     on(event: 'INSERT' | 'UPDATE' | 'DELETE' | '*', callback: RealtimeCallback): this;
     /**
@@ -2727,6 +2807,27 @@ declare class FluxbaseAdmin {
      * ```
      */
     listUsers(options?: ListUsersOptions): Promise<ListUsersResponse>;
+    /**
+     * Get a user by ID
+     *
+     * Fetch a single user's details by their user ID
+     *
+     * @param userId - User ID to fetch
+     * @param type - User type ('app' or 'dashboard')
+     * @returns User details with metadata
+     *
+     * @example
+     * ```typescript
+     * // Get an app user
+     * const user = await admin.getUserById('user-123');
+     *
+     * // Get a dashboard user
+     * const dashboardUser = await admin.getUserById('admin-456', 'dashboard');
+     * console.log('User email:', dashboardUser.email);
+     * console.log('Last login:', dashboardUser.last_login_at);
+     * ```
+     */
+    getUserById(userId: string, type?: "app" | "dashboard"): Promise<EnrichedUser>;
     /**
      * Invite a new user
      *
@@ -2748,7 +2849,7 @@ declare class FluxbaseAdmin {
      * console.log('Invitation link:', response.invitation_link);
      * ```
      */
-    inviteUser(request: InviteUserRequest, type?: 'app' | 'dashboard'): Promise<InviteUserResponse>;
+    inviteUser(request: InviteUserRequest, type?: "app" | "dashboard"): Promise<InviteUserResponse>;
     /**
      * Delete a user
      *
@@ -2764,7 +2865,7 @@ declare class FluxbaseAdmin {
      * console.log('User deleted');
      * ```
      */
-    deleteUser(userId: string, type?: 'app' | 'dashboard'): Promise<DeleteUserResponse>;
+    deleteUser(userId: string, type?: "app" | "dashboard"): Promise<DeleteUserResponse>;
     /**
      * Update user role
      *
@@ -2781,7 +2882,7 @@ declare class FluxbaseAdmin {
      * console.log('User role updated:', user.role);
      * ```
      */
-    updateUserRole(userId: string, role: string, type?: 'app' | 'dashboard'): Promise<EnrichedUser>;
+    updateUserRole(userId: string, role: string, type?: "app" | "dashboard"): Promise<EnrichedUser>;
     /**
      * Reset user password
      *
@@ -2797,7 +2898,7 @@ declare class FluxbaseAdmin {
      * console.log(response.message);
      * ```
      */
-    resetUserPassword(userId: string, type?: 'app' | 'dashboard'): Promise<ResetUserPasswordResponse>;
+    resetUserPassword(userId: string, type?: "app" | "dashboard"): Promise<ResetUserPasswordResponse>;
 }
 
 /**
@@ -2805,7 +2906,7 @@ declare class FluxbaseAdmin {
  * Inspired by Supabase's PostgREST client
  */
 
-declare class QueryBuilder<T = unknown> {
+declare class QueryBuilder<T = unknown> implements PromiseLike<PostgrestResponse<T>> {
     private fetch;
     private table;
     private selectQuery;
@@ -3122,6 +3223,20 @@ declare class QueryBuilder<T = unknown> {
      * Execute the query and return results
      */
     execute(): Promise<PostgrestResponse<T>>;
+    /**
+     * Make QueryBuilder awaitable (implements PromiseLike)
+     * This allows using `await client.from('table').select()` without calling `.execute()`
+     *
+     * @example
+     * ```typescript
+     * // Without .execute() (new way)
+     * const { data } = await client.from('users').select('*')
+     *
+     * // With .execute() (old way, still supported)
+     * const { data } = await client.from('users').select('*').execute()
+     * ```
+     */
+    then<TResult1 = PostgrestResponse<T>, TResult2 = never>(onfulfilled?: ((value: PostgrestResponse<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
     /**
      * Build the query string from filters, ordering, etc.
      */