@spacelr/sdk 0.1.7 → 0.1.9

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>;
@@ -544,6 +593,21 @@ interface DeleteResult {
 interface FindByIdOptions {
     populate?: PopulateOption[];
 }
+/**
+ * Options for a server-side substring search.
+ *
+ * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
+ * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+ */
+interface SearchOptions {
+    query: string;
+    fields: string[];
+    filter?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    offset?: number;
+    select?: string[];
+}
 interface SubscribeHandlers<T = Record<string, unknown>> {
     where?: Record<string, string | number | boolean>;
     onInsert?: (doc: T & {
@@ -586,6 +650,18 @@ declare class CollectionRef<T = Record<string, unknown>> {
         _id?: string;
     })[]): Promise<InsertResult>;
     find(filter?: Record<string, unknown>): QueryBuilder<T>;
+    /**
+     * Server-side substring search across the specified fields.
+     *
+     * The query is regex-escaped server-side and matched case-insensitively via
+     * MongoDB `$regex`. Performance note: unanchored case-insensitive regex
+     * cannot use a standard B-tree index — on very large collections consider
+     * narrowing with `filter` to scope the scan.
+     *
+     * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
+     * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+     */
+    search(opts: SearchOptions): Promise<FindResult<T>>;
     findById(id: string, options?: FindByIdOptions): Promise<T & {
         _id: string;
     }>;
@@ -665,7 +741,14 @@ declare class NotificationsModule {
 }
 
 interface FunctionInvokeOptions {
-    secret: string;
+    /** Webhook secret — used for `webhook` and `hybrid` invokeMode. */
+    secret?: string;
+    /**
+     * If true, the SDK attaches the currently signed-in user's bearer token
+     * via `Authorization` (managed by the SDK's TokenManager). Use for
+     * `authenticated`, `hybrid`, or `public` invokeMode.
+     */
+    authenticated?: boolean;
     payload?: Record<string, unknown>;
 }
 interface FunctionInvokeResult {
@@ -677,11 +760,15 @@ declare class FunctionsModule {
     private http;
     constructor(http: HttpClient);
     /**
-     * Invoke a function via webhook trigger.
+     * Invoke a function.
      * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-     * with X-Webhook-Secret header.
+     *
+     * Provide `secret` for webhook/hybrid functions, `authenticated: true` for
+     * JWT-based invocation, or both for hybrid (JWT wins). Public mode needs
+     * neither, though `authenticated: true` still populates `event.auth` inside
+     * the function.
      */
-    invoke(projectId: string, functionId: string, options: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
+    invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
 interface SpacelrClient {
@@ -741,4 +828,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 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>;
@@ -544,6 +593,21 @@ interface DeleteResult {
 interface FindByIdOptions {
     populate?: PopulateOption[];
 }
+/**
+ * Options for a server-side substring search.
+ *
+ * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
+ * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+ */
+interface SearchOptions {
+    query: string;
+    fields: string[];
+    filter?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    offset?: number;
+    select?: string[];
+}
 interface SubscribeHandlers<T = Record<string, unknown>> {
     where?: Record<string, string | number | boolean>;
     onInsert?: (doc: T & {
@@ -586,6 +650,18 @@ declare class CollectionRef<T = Record<string, unknown>> {
         _id?: string;
     })[]): Promise<InsertResult>;
     find(filter?: Record<string, unknown>): QueryBuilder<T>;
+    /**
+     * Server-side substring search across the specified fields.
+     *
+     * The query is regex-escaped server-side and matched case-insensitively via
+     * MongoDB `$regex`. Performance note: unanchored case-insensitive regex
+     * cannot use a standard B-tree index — on very large collections consider
+     * narrowing with `filter` to scope the scan.
+     *
+     * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
+     * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+     */
+    search(opts: SearchOptions): Promise<FindResult<T>>;
     findById(id: string, options?: FindByIdOptions): Promise<T & {
         _id: string;
     }>;
@@ -665,7 +741,14 @@ declare class NotificationsModule {
 }
 
 interface FunctionInvokeOptions {
-    secret: string;
+    /** Webhook secret — used for `webhook` and `hybrid` invokeMode. */
+    secret?: string;
+    /**
+     * If true, the SDK attaches the currently signed-in user's bearer token
+     * via `Authorization` (managed by the SDK's TokenManager). Use for
+     * `authenticated`, `hybrid`, or `public` invokeMode.
+     */
+    authenticated?: boolean;
     payload?: Record<string, unknown>;
 }
 interface FunctionInvokeResult {
@@ -677,11 +760,15 @@ declare class FunctionsModule {
     private http;
     constructor(http: HttpClient);
     /**
-     * Invoke a function via webhook trigger.
+     * Invoke a function.
      * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-     * with X-Webhook-Secret header.
+     *
+     * Provide `secret` for webhook/hybrid functions, `authenticated: true` for
+     * JWT-based invocation, or both for hybrid (JWT wins). Public mode needs
+     * neither, though `authenticated: true` still populates `event.auth` inside
+     * the function.
      */
-    invoke(projectId: string, functionId: string, options: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
+    invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
 interface SpacelrClient {
@@ -741,4 +828,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 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");
   }
 };
 
@@ -1413,6 +1497,25 @@ var CollectionRef = class {
   find(filter) {
     return new QueryBuilder(this.http, this.basePath, filter);
   }
+  /**
+   * Server-side substring search across the specified fields.
+   *
+   * The query is regex-escaped server-side and matched case-insensitively via
+   * MongoDB `$regex`. Performance note: unanchored case-insensitive regex
+   * cannot use a standard B-tree index — on very large collections consider
+   * narrowing with `filter` to scope the scan.
+   *
+   * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
+   * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+   */
+  async search(opts) {
+    return this.http.request({
+      method: "POST",
+      path: `${this.basePath}/search`,
+      body: opts,
+      authenticated: true
+    });
+  }
   async findById(id, options) {
     const query = {};
     if (options?.populate?.length) {
@@ -1669,19 +1772,25 @@ var FunctionsModule = class {
     this.http = http;
   }
   /**
-   * Invoke a function via webhook trigger.
+   * Invoke a function.
    * Calls POST /api/v1/functions/:projectId/:functionId/invoke
-   * with X-Webhook-Secret header.
+   *
+   * Provide `secret` for webhook/hybrid functions, `authenticated: true` for
+   * JWT-based invocation, or both for hybrid (JWT wins). Public mode needs
+   * neither, though `authenticated: true` still populates `event.auth` inside
+   * the function.
    */
-  async invoke(projectId, functionId, options) {
+  async invoke(projectId, functionId, options = {}) {
+    const headers = {};
+    if (options.secret) {
+      headers["X-Webhook-Secret"] = options.secret;
+    }
     return this.http.request({
       method: "POST",
       path: `/api/v1/functions/${encodeURIComponent(projectId)}/${encodeURIComponent(functionId)}/invoke`,
-      headers: {
-        "X-Webhook-Secret": options.secret
-      },
+      headers,
       body: options.payload ?? {},
-      authenticated: false
+      authenticated: options.authenticated ?? false
     });
   }
 };