@instroc/auth 1.0.1 → 1.0.2

package/dist/index.d.ts

@@ -1,49 +1,49 @@
 interface AuthUser {
-  id: string;
-  email: string;
-  email_verified: boolean;
-  display_name: string | null;
-  avatar_url: string | null;
-  metadata: Record<string, unknown>;
-  created_at: string;
+    id: string;
+    email: string;
+    email_verified: boolean;
+    display_name: string | null;
+    avatar_url: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
 }
 interface AuthSession {
-  access_token: string;
-  refresh_token: string;
-  expires_at: string;
+    access_token: string;
+    refresh_token: string;
+    expires_at: string;
 }
 interface AuthState {
-  user: AuthUser | null;
-  session: AuthSession | null;
-  loading: boolean;
-  error: string | null;
+    user: AuthUser | null;
+    session: AuthSession | null;
+    loading: boolean;
+    error: string | null;
 }
 interface LoginCredentials {
-  email: string;
-  password: string;
+    email: string;
+    password: string;
 }
 interface SignupCredentials {
-  email: string;
-  password: string;
-  displayName?: string;
-  metadata?: Record<string, unknown>;
+    email: string;
+    password: string;
+    displayName?: string;
+    metadata?: Record<string, unknown>;
 }
 type OAuthProvider = "google" | "github" | "microsoft" | "facebook";
 interface AuthConfig {
-  emailAuthEnabled: boolean;
-  googleAuthEnabled: boolean;
-  githubAuthEnabled: boolean;
-  microsoftAuthEnabled: boolean;
-  facebookAuthEnabled: boolean;
-  allowSignup: boolean;
-  requireEmailVerification: boolean;
+    emailAuthEnabled: boolean;
+    googleAuthEnabled: boolean;
+    githubAuthEnabled: boolean;
+    microsoftAuthEnabled: boolean;
+    facebookAuthEnabled: boolean;
+    allowSignup: boolean;
+    requireEmailVerification: boolean;
 }
 interface VisibilityConfig {
-  projectName: string;
-  visibility: "public" | "private";
-  requireLogin: boolean;
-  logoUrl: string | null;
-  welcomeMessage: string | null;
+    projectName: string;
+    visibility: "public" | "private";
+    requireLogin: boolean;
+    logoUrl: string | null;
+    welcomeMessage: string | null;
 }
 /**
  * Result of signup() — indicates what post-signup flow the caller should show.
@@ -52,108 +52,108 @@ interface VisibilityConfig {
  * - `status: "needs_verification"` — email verification OTP was sent. Show OTP screen.
  * - `status: "needs_approval"` — account pending admin approval. Show waiting screen.
  */
-type SignupResult =
-  | {
-      status: "authenticated";
-      user: AuthUser;
-    }
-  | {
-      status: "needs_verification";
-      email: string;
-    }
-  | {
-      status: "needs_approval";
-      user: AuthUser;
-    };
+type SignupResult = {
+    status: "authenticated";
+    user: AuthUser;
+} | {
+    status: "needs_verification";
+    email: string;
+} | {
+    status: "needs_approval";
+    user: AuthUser;
+};
 interface AuthContextValue extends AuthState {
-  login: (credentials: LoginCredentials) => Promise<void>;
-  signup: (credentials: SignupCredentials) => Promise<SignupResult>;
-  logout: () => Promise<void>;
-  signInWithOAuth: (provider: OAuthProvider) => void;
-  verifyOTP: (email: string, code: string) => Promise<void>;
-  resendOTP: (email: string) => Promise<void>;
-  updateProfile: (data: UpdateProfileData) => Promise<void>;
-  refreshSession: () => Promise<void>;
-  forgotPassword: (email: string) => Promise<void>;
-  resetPassword: (token: string, newPassword: string) => Promise<void>;
-  setProjectId: (projectId: string) => void;
-  projectId: string | null;
-  authConfig: AuthConfig | null;
-  visibilityConfig: VisibilityConfig | null;
+    login: (credentials: LoginCredentials) => Promise<void>;
+    signup: (credentials: SignupCredentials) => Promise<SignupResult>;
+    logout: () => Promise<void>;
+    signInWithOAuth: (provider: OAuthProvider) => void;
+    verifyOTP: (email: string, code: string) => Promise<void>;
+    resendOTP: (email: string) => Promise<void>;
+    updateProfile: (data: UpdateProfileData) => Promise<void>;
+    refreshSession: () => Promise<void>;
+    forgotPassword: (email: string) => Promise<void>;
+    resetPassword: (token: string, newPassword: string) => Promise<void>;
+    setProjectId: (projectId: string) => void;
+    projectId: string | null;
+    authConfig: AuthConfig | null;
+    visibilityConfig: VisibilityConfig | null;
 }
 interface UpdateProfileData {
-  displayName?: string;
-  avatarUrl?: string;
-  metadata?: Record<string, unknown>;
+    displayName?: string;
+    avatarUrl?: string;
+    metadata?: Record<string, unknown>;
 }
 interface AuthProviderProps {
-  children: React.ReactNode;
-  projectId?: string;
-  baseUrl?: string;
-  persistSession?: boolean;
-  onAuthStateChange?: (user: AuthUser | null) => void;
+    children: React.ReactNode;
+    projectId?: string;
+    baseUrl?: string;
+    persistSession?: boolean;
+    onAuthStateChange?: (user: AuthUser | null) => void;
 }
 interface AuthResponse {
-  user: AuthUser;
-  session: AuthSession;
-  /** Set when signup requires email verification — session is a placeholder with empty tokens. */
-  needsVerification?: boolean;
-  /** Set when signup succeeded but account is pending admin approval (private apps). */
-  needsApproval?: boolean;
+    user: AuthUser;
+    session: AuthSession;
+    /** Set when signup requires email verification — session is a placeholder with empty tokens. */
+    needsVerification?: boolean;
+    /** Set when signup succeeded but account is pending admin approval (private apps). */
+    needsApproval?: boolean;
 }
 interface RefreshResponse {
-  access_token: string;
-  expires_at: string;
+    access_token: string;
+    expires_at: string;
 }
 
-declare function AuthProvider({
-  children,
-  projectId: initialProjectId,
-  baseUrl,
-  persistSession,
-  onAuthStateChange,
-}: AuthProviderProps): JSX.Element;
+declare function AuthProvider({ children, projectId: initialProjectId, baseUrl, persistSession, onAuthStateChange, }: AuthProviderProps): JSX.Element;
 declare function useAuthContext(): AuthContextValue;
 
 declare function useAuth(): AuthContextValue;
 declare function useUser(): {
-  user: AuthUser | null;
-  loading: boolean;
+    user: AuthUser | null;
+    loading: boolean;
 };
 declare function useSession(): {
-  session: AuthSession | null;
-  loading: boolean;
+    session: AuthSession | null;
+    loading: boolean;
 };
-declare function useAuthRequired():
-  | {
-      user: null;
-      session: null;
-      loading: boolean;
-    }
-  | {
-      user: AuthUser;
-      session: AuthSession | null;
-      loading: boolean;
-    };
-
-export {
-  type AuthConfig,
-  type AuthContextValue,
-  AuthProvider,
-  type AuthProviderProps,
-  type AuthResponse,
-  type AuthSession,
-  type AuthState,
-  type AuthUser,
-  type LoginCredentials,
-  type OAuthProvider,
-  type RefreshResponse,
-  type SignupCredentials,
-  type UpdateProfileData,
-  type VisibilityConfig,
-  useAuth,
-  useAuthContext,
-  useAuthRequired,
-  useSession,
-  useUser,
+declare function useAuthRequired(): {
+    user: null;
+    session: null;
+    loading: boolean;
+} | {
+    user: AuthUser;
+    session: AuthSession | null;
+    loading: boolean;
 };
+
+/**
+ * Typed error thrown by every `@instroc/auth` method when the server responds
+ * with a non-2xx status. Carries the HTTP status so consumers can branch on
+ * behavioural outcomes (429 = cooldown UI, 403 = redirect to OTP page, etc.)
+ * without string-matching the message.
+ *
+ * Usage:
+ *   try {
+ *     await login({ email, password });
+ *   } catch (err) {
+ *     if (err instanceof AuthError) {
+ *       if (err.status === 429) { setCooldown(60); return; }
+ *       if (err.status === 403) { onNeedsVerification?.(email); return; }
+ *       setLocalError(err.message);
+ *     } else {
+ *       setLocalError("An unexpected error occurred.");
+ *     }
+ *   }
+ */
+declare class AuthError extends Error {
+    /** HTTP status code from the server (400, 401, 403, 404, 409, 429, 500…). */
+    readonly status: number;
+    /**
+     * Optional machine-readable error code from the server (e.g. `"invalid_credentials"`,
+     * `"email_not_verified"`). Present when the server includes a `code` field in the
+     * error body; otherwise `undefined`.
+     */
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+
+export { type AuthConfig, type AuthContextValue, AuthError, AuthProvider, type AuthProviderProps, type AuthResponse, type AuthSession, type AuthState, type AuthUser, type LoginCredentials, type OAuthProvider, type RefreshResponse, type SignupCredentials, type SignupResult, type UpdateProfileData, type VisibilityConfig, useAuth, useAuthContext, useAuthRequired, useSession, useUser };

package/dist/index.js

@@ -7,6 +7,24 @@ import {
   useEffect,
   useRef
 } from "react";
+
+// src/errors.ts
+var AuthError = class _AuthError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "AuthError";
+    this.status = status;
+    this.code = code;
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+function authErrorFromResponse(response, data, fallbackMessage) {
+  const body = data ?? {};
+  const message = body.error || fallbackMessage;
+  return new AuthError(message, response.status, body.code);
+}
+
+// src/provider.tsx
 import { jsx } from "react/jsx-runtime";
 var AuthContext = createContext(null);
 var STORAGE_KEY = "instroc_auth_session";
@@ -182,7 +200,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Login failed");
+          throw authErrorFromResponse(response, data, "Login failed");
         }
         const authResponse = data;
         updateAuthState(authResponse.user, authResponse.session);
@@ -208,7 +226,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Signup failed");
+          throw authErrorFromResponse(response, data, "Signup failed");
         }
         const authResponse = data;
         if (authResponse.needsVerification) {
@@ -261,7 +279,7 @@ function AuthProvider({
   const updateProfile = useCallback(
     async (data) => {
       if (!session) {
-        throw new Error("Not authenticated");
+        throw new AuthError("Not authenticated", 401);
       }
       setError(null);
       try {
@@ -275,7 +293,7 @@ function AuthProvider({
         });
         const result = await response.json();
         if (!response.ok) {
-          throw new Error(result.error || "Update failed");
+          throw authErrorFromResponse(response, result, "Update failed");
         }
         setUser(result.user);
       } catch (err) {
@@ -296,7 +314,7 @@ function AuthProvider({
     });
     const data = await response.json();
     if (!response.ok) {
-      throw new Error(data.error || "Refresh failed");
+      throw authErrorFromResponse(response, data, "Refresh failed");
     }
     const refreshData = data;
     const newSession = {
@@ -317,7 +335,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Request failed");
+          throw authErrorFromResponse(response, data, "Request failed");
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : "Request failed";
@@ -338,7 +356,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Reset failed");
+          throw authErrorFromResponse(response, data, "Reset failed");
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : "Reset failed";
@@ -372,7 +390,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Verification failed");
+          throw authErrorFromResponse(response, data, "Verification failed");
         }
         if (data.session) {
           updateAuthState(data.user, data.session);
@@ -398,7 +416,7 @@ function AuthProvider({
         });
         const data = await response.json();
         if (!response.ok) {
-          throw new Error(data.error || "Failed to resend code");
+          throw authErrorFromResponse(response, data, "Failed to resend code");
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : "Failed to resend code";
@@ -541,6 +559,7 @@ function useAuthRequired() {
   return { user, session, loading: false };
 }
 export {
+  AuthError,
   AuthProvider,
   useAuth,
   useAuthContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instroc/auth",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Authentication hooks for Instroc Cloud — useAuth, useUser, AuthProvider",
   "type": "module",
   "main": "dist/index.js",