@imtbl/auth 2.12.5 → 2.12.6-alpha.0

package/src/types.ts

@@ -26,10 +26,12 @@ export enum EvmChain {
 }
 
 export type ChainAddress = {
-  ethAddress: string;
-  userAdminAddress: string;
+  ethAddress: `0x${string}`;
+  userAdminAddress: `0x${string}`;
 };
 
+export type ZkEvmInfo = ChainAddress;
+
 export type User = {
   idToken?: string;
   accessToken: string;
@@ -163,12 +165,44 @@ export type LoginOptions = {
 export enum AuthEvents {
   LOGGED_OUT = 'loggedOut',
   LOGGED_IN = 'loggedIn',
+  /**
+   * Emitted when tokens are refreshed via signinSilent().
+   * This is critical for refresh token rotation - when client-side refresh happens,
+   * the new tokens must be synced to server-side session to prevent race conditions.
+   */
+  TOKEN_REFRESHED = 'tokenRefreshed',
+  /**
+   * Emitted when the user is removed from local storage due to a permanent auth error.
+   * Only emitted for errors where the refresh token is truly invalid:
+   * - invalid_grant: refresh token expired, revoked, or already used
+   * - login_required: user must re-authenticate
+   * - consent_required / interaction_required: user must interact with auth server
+   *
+   * NOT emitted for transient errors (network, timeout, server errors) - user stays logged in.
+   * Consumers should sync this state by clearing their session (e.g., NextAuth signOut).
+   */
+  USER_REMOVED = 'userRemoved',
 }
 
+/**
+ * Error reason for USER_REMOVED event.
+ * Note: Network/timeout errors do NOT emit USER_REMOVED (user stays logged in),
+ * so 'network_error' is not a valid reason.
+ */
+export type UserRemovedReason =
+  // OAuth permanent errors (invalid_grant, login_required, etc.)
+  | 'refresh_token_invalid'
+  // Unknown non-OAuth errors
+  | 'refresh_failed'
+  // Fallback for truly unknown error types
+  | 'unknown';
+
 /**
  * Event map for typed event emitter
  */
 export interface AuthEventMap extends Record<string, any> {
   [AuthEvents.LOGGED_OUT]: [];
   [AuthEvents.LOGGED_IN]: [User];
+  [AuthEvents.TOKEN_REFRESHED]: [User];
+  [AuthEvents.USER_REMOVED]: [{ reason: UserRemovedReason; error?: string }];
 }