@spacelr/sdk 0.1.5 → 0.1.6

package/dist/index.d.mts

@@ -250,21 +250,39 @@ interface UploadProgress {
 }
 
 type RefreshCallback = (refreshToken: string) => Promise<StoredTokens>;
+type AuthLostReason = 'refresh-failed' | 'unauthorized';
+type TokenRefreshedListener = (tokens: StoredTokens) => void;
+type AuthLostListener = (reason: AuthLostReason) => void;
 declare class TokenManager {
     private storage;
     private refreshBufferSeconds;
     private refreshCallback;
     private refreshPromise;
+    private tokenRefreshedListeners;
+    private authLostListeners;
+    private authLostEmitted;
     constructor(storage?: TokenStorage, refreshBufferSeconds?: number);
     setRefreshCallback(callback: RefreshCallback): void;
     getAccessToken(): Promise<string | null>;
     setTokens(tokens: StoredTokens): Promise<void>;
     clearTokens(): Promise<void>;
     getStoredTokens(): Promise<StoredTokens | null>;
+    /**
+     * Force a refresh using the current stored refresh token.
+     * Returns the new access token, or null if refresh is not possible or fails.
+     * A rejecting custom `TokenStorage.getTokens()` is treated as "no tokens"
+     * so callers (notably `HttpClient`'s 401 retry path) see a clean `null`
+     * rather than an exception that would get wrapped as a network error.
+     */
+    forceRefresh(): Promise<string | null>;
+    onTokenRefreshed(listener: TokenRefreshedListener): () => void;
+    onAuthLost(listener: AuthLostListener): () => void;
+    emitAuthLost(reason: AuthLostReason): void;
     private isTokenExpired;
     private shouldRefresh;
     private tryRefresh;
     private executeRefresh;
+    private emitTokenRefreshed;
 }
 
 interface HttpRequestOptions {
@@ -282,10 +300,22 @@ declare class HttpClient {
     private tokenManager;
     constructor(config: SpacelrClientConfig, tokenManager: TokenManager);
     request<T>(options: HttpRequestOptions): Promise<T>;
+    private requestWithRetry;
     uploadForm<T>(path: string, formData: FormData, onProgress?: (event: {
         loaded: number;
         total: number;
     }) => void): Promise<T>;
+    private uploadFormWithRetry;
+    /**
+     * Shared handler for a 401 on an authenticated request. Returns true if the
+     * caller should retry with a refreshed token. 403 is never routed here —
+     * it means "forbidden for this action" and must not trigger logout.
+     *
+     * `emitAuthLost('unauthorized')` is deduped inside TokenManager, so it's a
+     * no-op if `executeRefresh` already emitted 'refresh-failed'.
+     */
+    private recoverFromAuthFailure;
+    private uploadFormOnce;
     private uploadFormWithProgress;
     private buildUrl;
     private buildHeaders;
@@ -335,6 +365,7 @@ declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
     constructor(emailSent: boolean, details?: Record<string, unknown>);
 }
 
+type ConnectionState = 'connected' | 'reconnecting' | 'disconnected';
 interface DatabaseChangeEvent {
     type: 'insert' | 'update' | 'delete';
     projectId: string;
@@ -346,6 +377,13 @@ interface DatabaseChangeEvent {
 interface RealtimeConfig {
     baseUrl: string;
     getToken: () => Promise<string | null>;
+    /**
+     * Optional subscription to token-refresh events. When wired, the realtime
+     * client will push the fresh access token to the server via a
+     * `reauthenticate` message so the open socket stays authenticated without
+     * dropping the connection.
+     */
+    onTokenRefreshed?: (listener: (accessToken: string) => void) => () => void;
 }
 declare class RealtimeClient {
     private socket;
@@ -353,13 +391,42 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private unsubscribeFromTokenRefreshed;
+    private onVisibilityChange;
+    private onOnline;
+    private disposed;
+    private rebuildRetryTimer;
+    private connectionState;
+    private connectionStateListeners;
     constructor(config: RealtimeConfig);
     subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    /**
+     * Tear down the realtime client permanently. After this call the instance
+     * is disposed — subsequent `subscribe()` calls will not re-establish a
+     * connection. Create a new `RealtimeClient` (via `createClient`) if you
+     * need to reconnect after a logout.
+     */
     disconnect(): void;
+    getConnectionState(): ConnectionState;
+    onConnectionStateChanged(listener: (state: ConnectionState) => void): () => void;
+    private setConnectionState;
     private buildRoomKey;
     private ensureConnected;
     private connect;
     private eventMatchesRoom;
+    /**
+     * Tear down the current socket and create a fresh one. Used by both
+     * `reconnect_failed` (socket.io gave up) and the visibility/online wake-up
+     * listeners. Preserves the `subscriptions` map so existing rooms can be
+     * replayed to the server on the new connection. If the rebuild itself
+     * fails it schedules one retry after 5 s — beyond that we rely on the
+     * next wake-up event (visibility/online) to try again.
+     */
+    private rebuildSocket;
+    private handlePostRebuild;
+    private scheduleRebuildRetry;
+    private ensureWakeListeners;
+    private detachWakeListeners;
     private resubscribeAll;
 }
 
@@ -623,9 +690,55 @@ interface SpacelrClient {
     readonly db: DatabaseModule;
     readonly notifications: NotificationsModule;
     readonly functions: FunctionsModule;
+    /**
+     * Store auth tokens externally (e.g. obtained via the auth-components
+     * library that bypasses the SDK). Makes the tokens available to HTTP +
+     * realtime clients. Refresh is on-demand: the SDK will refresh the
+     * access token when it next makes a request and the token is within the
+     * expiry buffer (or on a 401 retry).
+     */
+    setTokens(tokens: StoredTokens): Promise<void>;
+    /** Clear stored tokens and reset auth-loss state. */
+    clearTokens(): Promise<void>;
     /** Disconnect realtime WebSocket (if connected) */
     disconnect(): void;
+    /**
+     * Subscribe to auth loss. Fires in three situations:
+     *  - `'refresh-failed'` — a refresh call was rejected by the server
+     *    (refresh token revoked or expired). Note: this can also fire from a
+     *    *background* refresh triggered inside the expiry buffer window, at
+     *    which point the current access token may still be valid for up to
+     *    `refreshBufferSeconds` (default 60). Treat the session as over anyway;
+     *    the refresh token is dead.
+     *  - `'unauthorized'` — an authenticated request came back 401 and no
+     *    fresh token could be produced (no refresh token, or the retry after
+     *    a successful refresh was itself 401).
+     *
+     * Typical consumer reaction: clear UI state and show the login screen.
+     * The event is deduped until `setTokens`/`clearTokens` is called again.
+     */
+    onAuthLost(listener: (reason: AuthLostReason) => void): () => void;
+    /** Subscribe to successful token refreshes. */
+    onTokenRefreshed(listener: (tokens: StoredTokens) => void): () => void;
+    /**
+     * Subscribe to realtime socket connection-state changes. Fires on every
+     * transition (dedup: identical consecutive states are skipped). Returns
+     * an unsubscribe function.
+     *
+     * States:
+     * - `'disconnected'` — initial state before the first subscribe, or after
+     *   the SDK has torn the realtime socket down (e.g. on logout via the
+     *   internal `realtime.disconnect()`). This is a terminal state for the
+     *   current realtime client; reconnect happens on the next `subscribe()`.
+     * - `'reconnecting'` — connecting or rebuilding the socket (initial
+     *   connect, socket drop, `reconnect_failed` rebuild, or a wake-up event
+     *   after suspend).
+     * - `'connected'` — authenticated and actively listening for events.
+     */
+    onConnectionStateChanged(listener: (state: ConnectionState) => void): () => void;
+    /** Read the current realtime socket state without waiting for an event. */
+    getConnectionState(): ConnectionState;
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge };
+export { type ApiResponse, type AuthLostReason, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge };

package/dist/index.d.ts

@@ -250,21 +250,39 @@ interface UploadProgress {
 }
 
 type RefreshCallback = (refreshToken: string) => Promise<StoredTokens>;
+type AuthLostReason = 'refresh-failed' | 'unauthorized';
+type TokenRefreshedListener = (tokens: StoredTokens) => void;
+type AuthLostListener = (reason: AuthLostReason) => void;
 declare class TokenManager {
     private storage;
     private refreshBufferSeconds;
     private refreshCallback;
     private refreshPromise;
+    private tokenRefreshedListeners;
+    private authLostListeners;
+    private authLostEmitted;
     constructor(storage?: TokenStorage, refreshBufferSeconds?: number);
     setRefreshCallback(callback: RefreshCallback): void;
     getAccessToken(): Promise<string | null>;
     setTokens(tokens: StoredTokens): Promise<void>;
     clearTokens(): Promise<void>;
     getStoredTokens(): Promise<StoredTokens | null>;
+    /**
+     * Force a refresh using the current stored refresh token.
+     * Returns the new access token, or null if refresh is not possible or fails.
+     * A rejecting custom `TokenStorage.getTokens()` is treated as "no tokens"
+     * so callers (notably `HttpClient`'s 401 retry path) see a clean `null`
+     * rather than an exception that would get wrapped as a network error.
+     */
+    forceRefresh(): Promise<string | null>;
+    onTokenRefreshed(listener: TokenRefreshedListener): () => void;
+    onAuthLost(listener: AuthLostListener): () => void;
+    emitAuthLost(reason: AuthLostReason): void;
     private isTokenExpired;
     private shouldRefresh;
     private tryRefresh;
     private executeRefresh;
+    private emitTokenRefreshed;
 }
 
 interface HttpRequestOptions {
@@ -282,10 +300,22 @@ declare class HttpClient {
     private tokenManager;
     constructor(config: SpacelrClientConfig, tokenManager: TokenManager);
     request<T>(options: HttpRequestOptions): Promise<T>;
+    private requestWithRetry;
     uploadForm<T>(path: string, formData: FormData, onProgress?: (event: {
         loaded: number;
         total: number;
     }) => void): Promise<T>;
+    private uploadFormWithRetry;
+    /**
+     * Shared handler for a 401 on an authenticated request. Returns true if the
+     * caller should retry with a refreshed token. 403 is never routed here —
+     * it means "forbidden for this action" and must not trigger logout.
+     *
+     * `emitAuthLost('unauthorized')` is deduped inside TokenManager, so it's a
+     * no-op if `executeRefresh` already emitted 'refresh-failed'.
+     */
+    private recoverFromAuthFailure;
+    private uploadFormOnce;
     private uploadFormWithProgress;
     private buildUrl;
     private buildHeaders;
@@ -335,6 +365,7 @@ declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
     constructor(emailSent: boolean, details?: Record<string, unknown>);
 }
 
+type ConnectionState = 'connected' | 'reconnecting' | 'disconnected';
 interface DatabaseChangeEvent {
     type: 'insert' | 'update' | 'delete';
     projectId: string;
@@ -346,6 +377,13 @@ interface DatabaseChangeEvent {
 interface RealtimeConfig {
     baseUrl: string;
     getToken: () => Promise<string | null>;
+    /**
+     * Optional subscription to token-refresh events. When wired, the realtime
+     * client will push the fresh access token to the server via a
+     * `reauthenticate` message so the open socket stays authenticated without
+     * dropping the connection.
+     */
+    onTokenRefreshed?: (listener: (accessToken: string) => void) => () => void;
 }
 declare class RealtimeClient {
     private socket;
@@ -353,13 +391,42 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private unsubscribeFromTokenRefreshed;
+    private onVisibilityChange;
+    private onOnline;
+    private disposed;
+    private rebuildRetryTimer;
+    private connectionState;
+    private connectionStateListeners;
     constructor(config: RealtimeConfig);
     subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    /**
+     * Tear down the realtime client permanently. After this call the instance
+     * is disposed — subsequent `subscribe()` calls will not re-establish a
+     * connection. Create a new `RealtimeClient` (via `createClient`) if you
+     * need to reconnect after a logout.
+     */
     disconnect(): void;
+    getConnectionState(): ConnectionState;
+    onConnectionStateChanged(listener: (state: ConnectionState) => void): () => void;
+    private setConnectionState;
     private buildRoomKey;
     private ensureConnected;
     private connect;
     private eventMatchesRoom;
+    /**
+     * Tear down the current socket and create a fresh one. Used by both
+     * `reconnect_failed` (socket.io gave up) and the visibility/online wake-up
+     * listeners. Preserves the `subscriptions` map so existing rooms can be
+     * replayed to the server on the new connection. If the rebuild itself
+     * fails it schedules one retry after 5 s — beyond that we rely on the
+     * next wake-up event (visibility/online) to try again.
+     */
+    private rebuildSocket;
+    private handlePostRebuild;
+    private scheduleRebuildRetry;
+    private ensureWakeListeners;
+    private detachWakeListeners;
     private resubscribeAll;
 }
 
@@ -623,9 +690,55 @@ interface SpacelrClient {
     readonly db: DatabaseModule;
     readonly notifications: NotificationsModule;
     readonly functions: FunctionsModule;
+    /**
+     * Store auth tokens externally (e.g. obtained via the auth-components
+     * library that bypasses the SDK). Makes the tokens available to HTTP +
+     * realtime clients. Refresh is on-demand: the SDK will refresh the
+     * access token when it next makes a request and the token is within the
+     * expiry buffer (or on a 401 retry).
+     */
+    setTokens(tokens: StoredTokens): Promise<void>;
+    /** Clear stored tokens and reset auth-loss state. */
+    clearTokens(): Promise<void>;
     /** Disconnect realtime WebSocket (if connected) */
     disconnect(): void;
+    /**
+     * Subscribe to auth loss. Fires in three situations:
+     *  - `'refresh-failed'` — a refresh call was rejected by the server
+     *    (refresh token revoked or expired). Note: this can also fire from a
+     *    *background* refresh triggered inside the expiry buffer window, at
+     *    which point the current access token may still be valid for up to
+     *    `refreshBufferSeconds` (default 60). Treat the session as over anyway;
+     *    the refresh token is dead.
+     *  - `'unauthorized'` — an authenticated request came back 401 and no
+     *    fresh token could be produced (no refresh token, or the retry after
+     *    a successful refresh was itself 401).
+     *
+     * Typical consumer reaction: clear UI state and show the login screen.
+     * The event is deduped until `setTokens`/`clearTokens` is called again.
+     */
+    onAuthLost(listener: (reason: AuthLostReason) => void): () => void;
+    /** Subscribe to successful token refreshes. */
+    onTokenRefreshed(listener: (tokens: StoredTokens) => void): () => void;
+    /**
+     * Subscribe to realtime socket connection-state changes. Fires on every
+     * transition (dedup: identical consecutive states are skipped). Returns
+     * an unsubscribe function.
+     *
+     * States:
+     * - `'disconnected'` — initial state before the first subscribe, or after
+     *   the SDK has torn the realtime socket down (e.g. on logout via the
+     *   internal `realtime.disconnect()`). This is a terminal state for the
+     *   current realtime client; reconnect happens on the next `subscribe()`.
+     * - `'reconnecting'` — connecting or rebuilding the socket (initial
+     *   connect, socket drop, `reconnect_failed` rebuild, or a wake-up event
+     *   after suspend).
+     * - `'connected'` — authenticated and actively listening for events.
+     */
+    onConnectionStateChanged(listener: (state: ConnectionState) => void): () => void;
+    /** Read the current realtime socket state without waiting for an event. */
+    getConnectionState(): ConnectionState;
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge };
+export { type ApiResponse, type AuthLostReason, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge };