@basictech/react 0.8.0-beta.3 → 0.8.0-beta.4

package/changelog.md

@@ -1,5 +1,11 @@
 # 1.3.4
 
+## 0.8.0-beta.4
+
+### Patch Changes
+
+- Auth status state machine and session reconciliation: add `AuthStatus` type (`bootstrapping`, `authenticated`, `recovering`, `reauth_required`, `signed_out`), replace `window.location.reload()` cross-tab handlers with in-place state updates, add `reconcileSession` for sync/visibility/online recovery, handle `tokenUpdateAck` in sync protocol, and expose `authStatus` + `authErrorCode` from `useBasic()`
+
 ## 0.8.0-beta.3
 
 ### Patch Changes

package/dist/index.d.mts

@@ -256,6 +256,26 @@ type User = {
     email?: string;
     picture?: string;
 };
+/**
+ * High-level auth lifecycle state.
+ *
+ * - `bootstrapping` — SDK is initializing; not yet determined if a session exists.
+ * - `authenticated` — User has a valid access token and active session.
+ * - `recovering`    — A session likely exists (refresh token / cached user) but
+ *                     the SDK hasn't confirmed it yet (e.g. offline, mid-refresh).
+ * - `reauth_required` — The session is definitively invalid (revoked, expired
+ *                     refresh token, etc.). The user must sign in again.
+ *                     NOTE: `isSignedIn` remains `true` in this state so the UI
+ *                     can display user info while prompting re-authentication.
+ *                     Use `authStatus === 'reauth_required'` to distinguish
+ *                     this from a healthy signed-in state.
+ * - `signed_out`    — No session. User is not authenticated.
+ *
+ * TODO: revisit naming and ergonomics — consider adding a `needsReauth` or
+ * `shouldPromptSignIn` convenience getter so consumers don't need to inspect
+ * the raw status to decide between "sign in" vs "sign out" UI.
+ */
+type AuthStatus = 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out';
 type AuthResult = {
     success: boolean;
     error?: string;
@@ -272,7 +292,16 @@ declare enum DBStatus {
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
     ERROR = "ERROR",
+    /** Sync-layer error with automatic retry (maps from dexie-syncable status 4). */
     ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    /**
+     * Auth-driven status: set by the provider when `authStatus` transitions to
+     * `reauth_required`, causing sync to disconnect. Unlike the other statuses
+     * this is NOT mapped from a dexie-syncable status code — it is set
+     * programmatically by `BasicProvider` to signal that the token is
+     * definitively invalid and the user must re-authenticate before sync can
+     * resume.
+     */
     ERROR_TOKEN_EXPIRED = "ERROR_TOKEN_EXPIRED"
 }
 /** Snapshot of local schema vs server (for dev toolbar and debugging). */
@@ -290,6 +319,8 @@ type BasicSchemaDevInfo = {
 type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
+    authStatus: AuthStatus;
+    authErrorCode: string | null;
     user: User | null;
     did: string | null;
     scope: string | null;

package/dist/index.d.ts

@@ -256,6 +256,26 @@ type User = {
     email?: string;
     picture?: string;
 };
+/**
+ * High-level auth lifecycle state.
+ *
+ * - `bootstrapping` — SDK is initializing; not yet determined if a session exists.
+ * - `authenticated` — User has a valid access token and active session.
+ * - `recovering`    — A session likely exists (refresh token / cached user) but
+ *                     the SDK hasn't confirmed it yet (e.g. offline, mid-refresh).
+ * - `reauth_required` — The session is definitively invalid (revoked, expired
+ *                     refresh token, etc.). The user must sign in again.
+ *                     NOTE: `isSignedIn` remains `true` in this state so the UI
+ *                     can display user info while prompting re-authentication.
+ *                     Use `authStatus === 'reauth_required'` to distinguish
+ *                     this from a healthy signed-in state.
+ * - `signed_out`    — No session. User is not authenticated.
+ *
+ * TODO: revisit naming and ergonomics — consider adding a `needsReauth` or
+ * `shouldPromptSignIn` convenience getter so consumers don't need to inspect
+ * the raw status to decide between "sign in" vs "sign out" UI.
+ */
+type AuthStatus = 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out';
 type AuthResult = {
     success: boolean;
     error?: string;
@@ -272,7 +292,16 @@ declare enum DBStatus {
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
     ERROR = "ERROR",
+    /** Sync-layer error with automatic retry (maps from dexie-syncable status 4). */
     ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    /**
+     * Auth-driven status: set by the provider when `authStatus` transitions to
+     * `reauth_required`, causing sync to disconnect. Unlike the other statuses
+     * this is NOT mapped from a dexie-syncable status code — it is set
+     * programmatically by `BasicProvider` to signal that the token is
+     * definitively invalid and the user must re-authenticate before sync can
+     * resume.
+     */
     ERROR_TOKEN_EXPIRED = "ERROR_TOKEN_EXPIRED"
 }
 /** Snapshot of local schema vs server (for dev toolbar and debugging). */
@@ -290,6 +319,8 @@ type BasicSchemaDevInfo = {
 type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
+    authStatus: AuthStatus;
+    authErrorCode: string | null;
     user: User | null;
     did: string | null;
     scope: string | null;