@spacelr/sdk 0.1.8 → 0.1.10

package/dist/index.d.mts

@@ -58,8 +58,10 @@ interface RegisterResponse {
         username: string;
         displayName?: string;
     };
-    access_token: string;
-    refresh_token: string;
+    /** Omitted by the server when `emailVerificationRequired` is true. */
+    access_token?: string;
+    /** Omitted by the server when `emailVerificationRequired` is true. */
+    refresh_token?: string;
     emailVerificationRequired?: boolean;
 }
 interface TokenResponse {
@@ -430,11 +432,58 @@ declare class RealtimeClient {
     private resubscribeAll;
 }
 
+type AuthState = 'authenticated' | 'unauthenticated';
+type AuthStateListener = (state: AuthState) => void | Promise<void>;
 declare class AuthModule {
     private http;
     private tokenManager;
     private config;
+    private stateListeners;
+    private unsubscribeAuthLost;
+    private lastEmittedState;
     constructor(http: HttpClient, tokenManager: TokenManager, config: SpacelrClientConfig);
+    /**
+     * Returns true if a non-expired access token is currently in storage.
+     * Does NOT make a network request — safe for route guards and other
+     * hot paths that run on every navigation.
+     *
+     * A token within the refresh buffer (about to expire) still counts as
+     * authenticated because the next protected request will auto-refresh it.
+     *
+     * Any error from the underlying TokenStorage (corrupt JSON, quota, etc.)
+     * is treated as "not authenticated" rather than propagated, so route
+     * guards can't be crashed by a misbehaving storage backend.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Subscribe to auth-state transitions. The callback fires:
+     *   - 'authenticated' after a successful login/register/exchange/2FA-verify
+     *   - 'unauthenticated' after logout or when a token refresh fails
+     *
+     * Only fires for transitions that happen after the subscription. If the
+     * user is already logged in at subscribe time (e.g. tokens restored from
+     * storage on app boot), no 'authenticated' event is emitted — call
+     * `isAuthenticated()` once up-front for the initial state.
+     *
+     * Silent token refreshes do NOT produce an event (auth state is
+     * unchanged). Subscribe to `spacelrClient.onTokenRefreshed(...)` if you
+     * need to observe successful refreshes.
+     *
+     * Listener may return `void` or `Promise<void>`. Rejections are swallowed
+     * so one broken subscriber can't poison others or the auth flow. The
+     * dispatch is fire-and-forget: `logout()` / `login()` resolve as soon as
+     * the dispatch loop returns, without awaiting async listeners.
+     *
+     * Returns an unsubscribe function.
+     */
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    /**
+     * Detach this AuthModule from the TokenManager. Call when discarding the
+     * client (tests, HMR, multi-client setups) to avoid leaking the internal
+     * onAuthLost subscription. Idempotent — safe to call more than once.
+     */
+    dispose(): void;
+    private emitState;
     login(params: LoginParams): Promise<LoginResponse>;
     register(params: RegisterParams): Promise<RegisterResponse>;
     refresh(refreshToken: string): Promise<TokenResponse>;
@@ -692,7 +741,20 @@ declare class NotificationsModule {
 }
 
 interface FunctionInvokeOptions {
-    secret: string;
+    /** Webhook secret — used for `webhook` and `hybrid` invokeMode. */
+    secret?: string;
+    /**
+     * Whether to attach the signed-in user's bearer token via `Authorization`
+     * (managed by the SDK's TokenManager).
+     *
+     * Default: `true` when no `secret` is provided, `false` when `secret` is
+     * set. Override explicitly for the hybrid case (provide both) or to
+     * suppress the header even when logged in.
+     *
+     * If `true` but the user is not signed in, the header is simply omitted —
+     * safe for `public` invokeMode.
+     */
+    authenticated?: boolean;
     payload?: Record<string, unknown>;
 }
 interface FunctionInvokeResult {
@@ -704,11 +766,20 @@ declare class FunctionsModule {
     private http;
     constructor(http: HttpClient);
     /**
-     * Invoke a function via webhook trigger.
-     * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-     * with X-Webhook-Secret header.
+     * Invoke a function.
+     * Calls POST `/functions/:projectId/:functionId/invoke`, resolved against
+     * `config.apiUrl` (which already carries the `/api/v1` prefix).
+     *
+     * Auth defaults, based on `invokeMode` semantics:
+     *  - webhook:       pass `secret` → Authorization is NOT attached
+     *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
+     *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
+     *  - hybrid:        pass both `secret` and `authenticated: true`
+     *
+     * To force a specific behaviour, set `authenticated` explicitly — it wins
+     * over the `secret`-based default.
      */
-    invoke(projectId: string, functionId: string, options: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
+    invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
 interface SpacelrClient {
@@ -768,4 +839,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-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 SearchOptions, 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 AuthState, type AuthStateListener, 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 SearchOptions, 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

@@ -58,8 +58,10 @@ interface RegisterResponse {
         username: string;
         displayName?: string;
     };
-    access_token: string;
-    refresh_token: string;
+    /** Omitted by the server when `emailVerificationRequired` is true. */
+    access_token?: string;
+    /** Omitted by the server when `emailVerificationRequired` is true. */
+    refresh_token?: string;
     emailVerificationRequired?: boolean;
 }
 interface TokenResponse {
@@ -430,11 +432,58 @@ declare class RealtimeClient {
     private resubscribeAll;
 }
 
+type AuthState = 'authenticated' | 'unauthenticated';
+type AuthStateListener = (state: AuthState) => void | Promise<void>;
 declare class AuthModule {
     private http;
     private tokenManager;
     private config;
+    private stateListeners;
+    private unsubscribeAuthLost;
+    private lastEmittedState;
     constructor(http: HttpClient, tokenManager: TokenManager, config: SpacelrClientConfig);
+    /**
+     * Returns true if a non-expired access token is currently in storage.
+     * Does NOT make a network request — safe for route guards and other
+     * hot paths that run on every navigation.
+     *
+     * A token within the refresh buffer (about to expire) still counts as
+     * authenticated because the next protected request will auto-refresh it.
+     *
+     * Any error from the underlying TokenStorage (corrupt JSON, quota, etc.)
+     * is treated as "not authenticated" rather than propagated, so route
+     * guards can't be crashed by a misbehaving storage backend.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Subscribe to auth-state transitions. The callback fires:
+     *   - 'authenticated' after a successful login/register/exchange/2FA-verify
+     *   - 'unauthenticated' after logout or when a token refresh fails
+     *
+     * Only fires for transitions that happen after the subscription. If the
+     * user is already logged in at subscribe time (e.g. tokens restored from
+     * storage on app boot), no 'authenticated' event is emitted — call
+     * `isAuthenticated()` once up-front for the initial state.
+     *
+     * Silent token refreshes do NOT produce an event (auth state is
+     * unchanged). Subscribe to `spacelrClient.onTokenRefreshed(...)` if you
+     * need to observe successful refreshes.
+     *
+     * Listener may return `void` or `Promise<void>`. Rejections are swallowed
+     * so one broken subscriber can't poison others or the auth flow. The
+     * dispatch is fire-and-forget: `logout()` / `login()` resolve as soon as
+     * the dispatch loop returns, without awaiting async listeners.
+     *
+     * Returns an unsubscribe function.
+     */
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    /**
+     * Detach this AuthModule from the TokenManager. Call when discarding the
+     * client (tests, HMR, multi-client setups) to avoid leaking the internal
+     * onAuthLost subscription. Idempotent — safe to call more than once.
+     */
+    dispose(): void;
+    private emitState;
     login(params: LoginParams): Promise<LoginResponse>;
     register(params: RegisterParams): Promise<RegisterResponse>;
     refresh(refreshToken: string): Promise<TokenResponse>;
@@ -692,7 +741,20 @@ declare class NotificationsModule {
 }
 
 interface FunctionInvokeOptions {
-    secret: string;
+    /** Webhook secret — used for `webhook` and `hybrid` invokeMode. */
+    secret?: string;
+    /**
+     * Whether to attach the signed-in user's bearer token via `Authorization`
+     * (managed by the SDK's TokenManager).
+     *
+     * Default: `true` when no `secret` is provided, `false` when `secret` is
+     * set. Override explicitly for the hybrid case (provide both) or to
+     * suppress the header even when logged in.
+     *
+     * If `true` but the user is not signed in, the header is simply omitted —
+     * safe for `public` invokeMode.
+     */
+    authenticated?: boolean;
     payload?: Record<string, unknown>;
 }
 interface FunctionInvokeResult {
@@ -704,11 +766,20 @@ declare class FunctionsModule {
     private http;
     constructor(http: HttpClient);
     /**
-     * Invoke a function via webhook trigger.
-     * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-     * with X-Webhook-Secret header.
+     * Invoke a function.
+     * Calls POST `/functions/:projectId/:functionId/invoke`, resolved against
+     * `config.apiUrl` (which already carries the `/api/v1` prefix).
+     *
+     * Auth defaults, based on `invokeMode` semantics:
+     *  - webhook:       pass `secret` → Authorization is NOT attached
+     *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
+     *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
+     *  - hybrid:        pass both `secret` and `authenticated: true`
+     *
+     * To force a specific behaviour, set `authenticated` explicitly — it wins
+     * over the `secret`-based default.
      */
-    invoke(projectId: string, functionId: string, options: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
+    invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
 interface SpacelrClient {
@@ -768,4 +839,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-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 SearchOptions, 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 AuthState, type AuthStateListener, 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 SearchOptions, 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.js

@@ -901,6 +901,8 @@ var RealtimeClient = class {
 // libs/sdk/src/modules/auth.module.ts
 var AuthModule = class {
   constructor(http, tokenManager, config) {
+    this.stateListeners = /* @__PURE__ */ new Set();
+    this.lastEmittedState = null;
     this.http = http;
     this.tokenManager = tokenManager;
     this.config = config;
@@ -913,6 +915,84 @@ var AuthModule = class {
         expiresAt
       };
     });
+    this.unsubscribeAuthLost = this.tokenManager.onAuthLost(
+      () => this.emitState("unauthenticated")
+    );
+  }
+  /**
+   * Returns true if a non-expired access token is currently in storage.
+   * Does NOT make a network request — safe for route guards and other
+   * hot paths that run on every navigation.
+   *
+   * A token within the refresh buffer (about to expire) still counts as
+   * authenticated because the next protected request will auto-refresh it.
+   *
+   * Any error from the underlying TokenStorage (corrupt JSON, quota, etc.)
+   * is treated as "not authenticated" rather than propagated, so route
+   * guards can't be crashed by a misbehaving storage backend.
+   */
+  async isAuthenticated() {
+    try {
+      const tokens = await this.tokenManager.getStoredTokens();
+      if (!tokens?.accessToken) return false;
+      if (tokens.expiresAt && tokens.expiresAt * 1e3 <= Date.now()) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Subscribe to auth-state transitions. The callback fires:
+   *   - 'authenticated' after a successful login/register/exchange/2FA-verify
+   *   - 'unauthenticated' after logout or when a token refresh fails
+   *
+   * Only fires for transitions that happen after the subscription. If the
+   * user is already logged in at subscribe time (e.g. tokens restored from
+   * storage on app boot), no 'authenticated' event is emitted — call
+   * `isAuthenticated()` once up-front for the initial state.
+   *
+   * Silent token refreshes do NOT produce an event (auth state is
+   * unchanged). Subscribe to `spacelrClient.onTokenRefreshed(...)` if you
+   * need to observe successful refreshes.
+   *
+   * Listener may return `void` or `Promise<void>`. Rejections are swallowed
+   * so one broken subscriber can't poison others or the auth flow. The
+   * dispatch is fire-and-forget: `logout()` / `login()` resolve as soon as
+   * the dispatch loop returns, without awaiting async listeners.
+   *
+   * Returns an unsubscribe function.
+   */
+  onAuthStateChange(listener) {
+    this.stateListeners.add(listener);
+    return () => {
+      this.stateListeners.delete(listener);
+    };
+  }
+  /**
+   * Detach this AuthModule from the TokenManager. Call when discarding the
+   * client (tests, HMR, multi-client setups) to avoid leaking the internal
+   * onAuthLost subscription. Idempotent — safe to call more than once.
+   */
+  dispose() {
+    this.unsubscribeAuthLost();
+    this.unsubscribeAuthLost = () => {
+    };
+    this.stateListeners.clear();
+    this.lastEmittedState = null;
+  }
+  emitState(state) {
+    if (state === this.lastEmittedState) return;
+    this.lastEmittedState = state;
+    for (const listener of this.stateListeners) {
+      try {
+        const result = listener(state);
+        if (result && typeof result.then === "function") {
+          result.then(void 0, () => {
+          });
+        }
+      } catch {
+      }
+    }
   }
   async login(params) {
     const response = await this.http.request({
@@ -958,6 +1038,7 @@ var AuthModule = class {
     } catch {
     }
     await this.tokenManager.clearTokens();
+    this.emitState("unauthenticated");
   }
   async verifyEmail(token) {
     return this.http.request({
@@ -1028,6 +1109,7 @@ var AuthModule = class {
       refreshToken: response.refresh_token,
       expiresAt
     });
+    this.emitState("authenticated");
     return response;
   }
   async generatePKCE() {
@@ -1110,6 +1192,7 @@ var AuthModule = class {
       refreshToken: response.refresh_token,
       expiresAt
     });
+    this.emitState("authenticated");
   }
   async storeTokensFromRegister(response) {
     if (!response.access_token) return;
@@ -1117,6 +1200,7 @@ var AuthModule = class {
       accessToken: response.access_token,
       refreshToken: response.refresh_token
     });
+    this.emitState("authenticated");
   }
 };
 
@@ -1688,19 +1772,32 @@ var FunctionsModule = class {
     this.http = http;
   }
   /**
-   * Invoke a function via webhook trigger.
-   * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-   * with X-Webhook-Secret header.
+   * Invoke a function.
+   * Calls POST `/functions/:projectId/:functionId/invoke`, resolved against
+   * `config.apiUrl` (which already carries the `/api/v1` prefix).
+   *
+   * Auth defaults, based on `invokeMode` semantics:
+   *  - webhook:       pass `secret` → Authorization is NOT attached
+   *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
+   *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
+   *  - hybrid:        pass both `secret` and `authenticated: true`
+   *
+   * To force a specific behaviour, set `authenticated` explicitly — it wins
+   * over the `secret`-based default.
    */
-  async invoke(projectId, functionId, options) {
+  async invoke(projectId, functionId, options = {}) {
+    const hasSecret = (options.secret?.length ?? 0) > 0;
+    const headers = {};
+    if (hasSecret) {
+      headers["X-Webhook-Secret"] = options.secret;
+    }
+    const authenticated = options.authenticated ?? !hasSecret;
     return this.http.request({
       method: "POST",
-      path: `/api/v1/functions/${encodeURIComponent(projectId)}/${encodeURIComponent(functionId)}/invoke`,
-      headers: {
-        "X-Webhook-Secret": options.secret
-      },
+      path: `/functions/${encodeURIComponent(projectId)}/${encodeURIComponent(functionId)}/invoke`,
+      headers,
       body: options.payload ?? {},
-      authenticated: false
+      authenticated
     });
   }
 };