@mitway/sdk 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -33,22 +33,42 @@ interface User {
 /**
  * Token Manager for the MITWAY-BaaS SDK.
  *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
+ * Stores the access token + user in memory and optionally persists them
+ * to `localStorage` so sessions survive page reloads (F5). Browser CSRF
+ * token lives in a cookie for the cookie-based refresh flow.
  */
 
+interface TokenManagerOptions {
+    /** Persist session to localStorage so it survives page reloads. Default: true. */
+    persistSession?: boolean;
+    /** localStorage key. Default: 'mitway_baas_session'. */
+    storageKey?: string;
+}
 declare class TokenManager {
     private accessToken;
+    private refreshToken;
     private user;
+    private readonly persistSession;
+    private readonly storageKey;
     /** Fired when the access token changes (used by long-lived consumers). */
     onTokenChange: (() => void) | null;
+    constructor(opts?: TokenManagerOptions);
     saveSession(session: AuthSession): void;
     getSession(): AuthSession | null;
     getAccessToken(): string | null;
     setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
     getUser(): User | null;
     setUser(user: User): void;
     clearSession(): void;
+    /**
+     * Restore the session from localStorage. Returns true if a persisted
+     * session was found and loaded into memory.
+     */
+    restoreSession(): boolean;
+    private persist;
+    private removePersisted;
 }
 
 /**
@@ -451,6 +471,18 @@ interface MitwayBaasConfig {
      * Realtime transport options. See `RealtimeOptions`.
      */
     realtime?: RealtimeOptions;
+    /**
+     * Persist the auth session to `localStorage` so it survives page reloads.
+     * Set to `false` for SSR / Node.js environments where `localStorage` is
+     * not available.
+     * @default true
+     */
+    persistSession?: boolean;
+    /**
+     * `localStorage` key used to persist the session.
+     * @default "mitway_baas_session"
+     */
+    storageKey?: string;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -458,6 +490,7 @@ interface MitwayBaasConfig {
 interface AuthSession {
     user: User;
     accessToken: string;
+    refreshToken?: string;
     expiresAt?: Date;
 }
 /**
@@ -654,6 +687,23 @@ declare class Auth {
      * not need to call it directly.
      */
     refreshSession(): Promise<AuthResult<AuthResponse>>;
+    /**
+     * Restore the session from localStorage and validate it with the backend.
+     * Call this once on app startup (e.g. in a React AuthProvider useEffect).
+     *
+     * Flow:
+     *   1. Read persisted session from localStorage.
+     *   2. Populate in-memory state (TokenManager + HttpClient).
+     *   3. Validate with `GET /api/auth/sessions/current`.
+     *      - If the access token expired, the HttpClient auto-refresh kicks in
+     *        using the persisted refresh token (sent in the POST body, not
+     *        cookies — works cross-site).
+     *   4. Return the validated user or an error.
+     *
+     * If no persisted session exists, returns `{ data: null, error }` — the
+     * app should show the login page.
+     */
+    initialize(): Promise<AuthResult<AuthResponse>>;
     /**
      * Get the current in-memory session, or null if the user is not signed in.
      * Synchronous — does not hit the network.

package/dist/index.d.ts

@@ -33,22 +33,42 @@ interface User {
 /**
  * Token Manager for the MITWAY-BaaS SDK.
  *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
+ * Stores the access token + user in memory and optionally persists them
+ * to `localStorage` so sessions survive page reloads (F5). Browser CSRF
+ * token lives in a cookie for the cookie-based refresh flow.
  */
 
+interface TokenManagerOptions {
+    /** Persist session to localStorage so it survives page reloads. Default: true. */
+    persistSession?: boolean;
+    /** localStorage key. Default: 'mitway_baas_session'. */
+    storageKey?: string;
+}
 declare class TokenManager {
     private accessToken;
+    private refreshToken;
     private user;
+    private readonly persistSession;
+    private readonly storageKey;
     /** Fired when the access token changes (used by long-lived consumers). */
     onTokenChange: (() => void) | null;
+    constructor(opts?: TokenManagerOptions);
     saveSession(session: AuthSession): void;
     getSession(): AuthSession | null;
     getAccessToken(): string | null;
     setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
     getUser(): User | null;
     setUser(user: User): void;
     clearSession(): void;
+    /**
+     * Restore the session from localStorage. Returns true if a persisted
+     * session was found and loaded into memory.
+     */
+    restoreSession(): boolean;
+    private persist;
+    private removePersisted;
 }
 
 /**
@@ -451,6 +471,18 @@ interface MitwayBaasConfig {
      * Realtime transport options. See `RealtimeOptions`.
      */
     realtime?: RealtimeOptions;
+    /**
+     * Persist the auth session to `localStorage` so it survives page reloads.
+     * Set to `false` for SSR / Node.js environments where `localStorage` is
+     * not available.
+     * @default true
+     */
+    persistSession?: boolean;
+    /**
+     * `localStorage` key used to persist the session.
+     * @default "mitway_baas_session"
+     */
+    storageKey?: string;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -458,6 +490,7 @@ interface MitwayBaasConfig {
 interface AuthSession {
     user: User;
     accessToken: string;
+    refreshToken?: string;
     expiresAt?: Date;
 }
 /**
@@ -654,6 +687,23 @@ declare class Auth {
      * not need to call it directly.
      */
     refreshSession(): Promise<AuthResult<AuthResponse>>;
+    /**
+     * Restore the session from localStorage and validate it with the backend.
+     * Call this once on app startup (e.g. in a React AuthProvider useEffect).
+     *
+     * Flow:
+     *   1. Read persisted session from localStorage.
+     *   2. Populate in-memory state (TokenManager + HttpClient).
+     *   3. Validate with `GET /api/auth/sessions/current`.
+     *      - If the access token expired, the HttpClient auto-refresh kicks in
+     *        using the persisted refresh token (sent in the POST body, not
+     *        cookies — works cross-site).
+     *   4. Return the validated user or an error.
+     *
+     * If no persisted session exists, returns `{ data: null, error }` — the
+     * app should show the login page.
+     */
+    initialize(): Promise<AuthResult<AuthResponse>>;
     /**
      * Get the current in-memory session, or null if the user is not signed in.
      * Synchronous — does not hit the network.

package/dist/index.js

@@ -161,6 +161,7 @@ var Logger = class {
 
 // src/lib/token-manager.ts
 var CSRF_TOKEN_COOKIE = "mitway_baas_csrf_token";
+var DEFAULT_STORAGE_KEY = "mitway_baas_session";
 function getCsrfToken() {
   if (typeof document === "undefined") return null;
   const match = document.cookie.split(";").find((c) => c.trim().startsWith(`${CSRF_TOKEN_COOKIE}=`));
@@ -180,13 +181,24 @@ function clearCsrfToken() {
 }
 var TokenManager = class {
   accessToken = null;
+  refreshToken = null;
   user = null;
+  persistSession;
+  storageKey;
   /** Fired when the access token changes (used by long-lived consumers). */
   onTokenChange = null;
+  constructor(opts) {
+    this.persistSession = opts?.persistSession ?? true;
+    this.storageKey = opts?.storageKey ?? DEFAULT_STORAGE_KEY;
+  }
   saveSession(session) {
     const tokenChanged = session.accessToken !== this.accessToken;
     this.accessToken = session.accessToken;
     this.user = session.user;
+    if (session.refreshToken !== void 0) {
+      this.refreshToken = session.refreshToken ?? null;
+    }
+    this.persist();
     if (tokenChanged && this.onTokenChange) {
       this.onTokenChange();
     }
@@ -195,6 +207,7 @@ var TokenManager = class {
     if (!this.accessToken || !this.user) return null;
     return {
       accessToken: this.accessToken,
+      refreshToken: this.refreshToken ?? void 0,
       user: this.user
     };
   }
@@ -204,24 +217,76 @@ var TokenManager = class {
   setAccessToken(token) {
     const tokenChanged = token !== this.accessToken;
     this.accessToken = token;
+    this.persist();
     if (tokenChanged && this.onTokenChange) {
       this.onTokenChange();
     }
   }
+  getRefreshToken() {
+    return this.refreshToken;
+  }
+  setRefreshToken(token) {
+    this.refreshToken = token;
+    this.persist();
+  }
   getUser() {
     return this.user;
   }
   setUser(user) {
     this.user = user;
+    this.persist();
   }
   clearSession() {
     const hadToken = this.accessToken !== null;
     this.accessToken = null;
+    this.refreshToken = null;
     this.user = null;
+    this.removePersisted();
     if (hadToken && this.onTokenChange) {
       this.onTokenChange();
     }
   }
+  /**
+   * Restore the session from localStorage. Returns true if a persisted
+   * session was found and loaded into memory.
+   */
+  restoreSession() {
+    if (!this.persistSession || typeof localStorage === "undefined") return false;
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (!raw) return false;
+      const stored = JSON.parse(raw);
+      if (!stored.accessToken || !stored.user) return false;
+      this.accessToken = stored.accessToken;
+      this.refreshToken = stored.refreshToken ?? null;
+      this.user = stored.user;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  persist() {
+    if (!this.persistSession || typeof localStorage === "undefined") return;
+    if (!this.accessToken || !this.user) return;
+    try {
+      const data = {
+        accessToken: this.accessToken,
+        user: this.user
+      };
+      if (this.refreshToken) {
+        data.refreshToken = this.refreshToken;
+      }
+      localStorage.setItem(this.storageKey, JSON.stringify(data));
+    } catch {
+    }
+  }
+  removePersisted() {
+    if (!this.persistSession || typeof localStorage === "undefined") return;
+    try {
+      localStorage.removeItem(this.storageKey);
+    } catch {
+    }
+  }
 };
 
 // src/lib/auth-envelope.ts
@@ -641,6 +706,7 @@ var Auth = class {
   saveSessionFromResponse(response) {
     const session = {
       accessToken: response.accessToken,
+      refreshToken: response.refreshToken,
       user: response.user
     };
     if (response.csrfToken) {
@@ -734,6 +800,70 @@ var Auth = class {
       return wrapError(error, "Session refresh failed");
     }
   }
+  /**
+   * Restore the session from localStorage and validate it with the backend.
+   * Call this once on app startup (e.g. in a React AuthProvider useEffect).
+   *
+   * Flow:
+   *   1. Read persisted session from localStorage.
+   *   2. Populate in-memory state (TokenManager + HttpClient).
+   *   3. Validate with `GET /api/auth/sessions/current`.
+   *      - If the access token expired, the HttpClient auto-refresh kicks in
+   *        using the persisted refresh token (sent in the POST body, not
+   *        cookies — works cross-site).
+   *   4. Return the validated user or an error.
+   *
+   * If no persisted session exists, returns `{ data: null, error }` — the
+   * app should show the login page.
+   */
+  async initialize() {
+    const restored = this.tokenManager.restoreSession();
+    if (!restored) {
+      return {
+        data: null,
+        error: new MitwayBaasError("No persisted session", 0, "NO_SESSION")
+      };
+    }
+    const session = this.tokenManager.getSession();
+    if (!session) {
+      return {
+        data: null,
+        error: new MitwayBaasError("No persisted session", 0, "NO_SESSION")
+      };
+    }
+    this.http.setAuthToken(session.accessToken);
+    const refreshToken = this.tokenManager.getRefreshToken();
+    if (refreshToken) {
+      this.http.setRefreshToken(refreshToken);
+    }
+    try {
+      const response = await this.http.get(
+        "/api/auth/sessions/current"
+      );
+      if (response?.user) {
+        this.tokenManager.setUser(response.user);
+        return {
+          data: {
+            user: response.user,
+            accessToken: session.accessToken
+          },
+          error: null
+        };
+      }
+      this.tokenManager.clearSession();
+      this.http.setAuthToken(null);
+      this.http.setRefreshToken(null);
+      return {
+        data: null,
+        error: new MitwayBaasError("Invalid session", 401, "INVALID_SESSION")
+      };
+    } catch (error) {
+      this.tokenManager.clearSession();
+      this.http.setAuthToken(null);
+      this.http.setRefreshToken(null);
+      return wrapError(error, "Session restore failed");
+    }
+  }
   /**
    * Get the current in-memory session, or null if the user is not signed in.
    * Synchronous — does not hit the network.
@@ -1877,7 +2007,10 @@ var MitwayBaasClient = class {
   storage;
   constructor(config = {}) {
     const logger = new Logger(config.debug);
-    this.tokenManager = new TokenManager();
+    this.tokenManager = new TokenManager({
+      persistSession: config.persistSession,
+      storageKey: config.storageKey
+    });
     this.http = new HttpClient(config, this.tokenManager, logger);
     this.auth = new Auth(this.http, this.tokenManager);
     this.database = new Database(this.http, this.tokenManager, config.anonKey);