@instroc/auth 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -45,9 +45,26 @@ interface VisibilityConfig {
     logoUrl: string | null;
     welcomeMessage: string | null;
 }
+/**
+ * Result of signup() — indicates what post-signup flow the caller should show.
+ *
+ * - `status: "authenticated"` — user is logged in, session is active. Redirect to app.
+ * - `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;
+};
 interface AuthContextValue extends AuthState {
     login: (credentials: LoginCredentials) => Promise<void>;
-    signup: (credentials: SignupCredentials) => Promise<void>;
+    signup: (credentials: SignupCredentials) => Promise<SignupResult>;
     logout: () => Promise<void>;
     signInWithOAuth: (provider: OAuthProvider) => void;
     verifyOTP: (email: string, code: string) => Promise<void>;
@@ -76,6 +93,10 @@ interface AuthProviderProps {
 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;
 }
 interface RefreshResponse {
     access_token: string;
@@ -104,4 +125,35 @@ declare function useAuthRequired(): {
     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 };
+/**
+ * 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";
@@ -36,6 +54,10 @@ function AuthProvider({
     },
     [projectId, baseUrl]
   );
+  const authFetch = useCallback(
+    (url, init) => fetch(url, { ...init, credentials: "include" }),
+    []
+  );
   const saveSession = useCallback(
     (sessionData) => {
       if (persistSession && typeof window !== "undefined") {
@@ -74,7 +96,7 @@ function AuthProvider({
           try {
             await refreshSession();
           } catch (err) {
-            console.error("Token refresh failed:", err);
+            console.warn("Token refresh failed:", err);
             setUser(null);
             setSession(null);
             saveSession(null);
@@ -105,7 +127,7 @@ function AuthProvider({
       return;
     }
     try {
-      const response = await fetch(buildUrl("me"), {
+      const response = await authFetch(buildUrl("me"), {
         headers: {
           Authorization: `Bearer ${storedSession.access_token}`
         }
@@ -115,7 +137,7 @@ function AuthProvider({
         updateAuthState(data.user, storedSession);
       } else if (response.status === 401) {
         try {
-          const refreshResponse = await fetch(buildUrl("refresh"), {
+          const refreshResponse = await authFetch(buildUrl("refresh"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ refreshToken: storedSession.refresh_token })
@@ -127,7 +149,7 @@ function AuthProvider({
               access_token: refreshData.access_token,
               expires_at: refreshData.expires_at
             };
-            const userResponse = await fetch(buildUrl("me"), {
+            const userResponse = await authFetch(buildUrl("me"), {
               headers: {
                 Authorization: `Bearer ${newSession.access_token}`
               }
@@ -171,14 +193,14 @@ function AuthProvider({
       setError(null);
       setLoading(true);
       try {
-        const response = await fetch(buildUrl("login"), {
+        const response = await authFetch(buildUrl("login"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(credentials)
         });
         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);
@@ -197,21 +219,34 @@ function AuthProvider({
       setError(null);
       setLoading(true);
       try {
-        const response = await fetch(buildUrl("signup"), {
+        const response = await authFetch(buildUrl("signup"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(credentials)
         });
         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) {
+          return {
+            status: "needs_verification",
+            email: credentials.email
+          };
+        }
+        if (authResponse.needsApproval) {
+          updateAuthState(authResponse.user, authResponse.session);
+          return { status: "needs_approval", user: authResponse.user };
+        }
         if (authResponse.session.access_token) {
           updateAuthState(authResponse.user, authResponse.session);
-        } else {
-          setUser(authResponse.user);
+          return { status: "authenticated", user: authResponse.user };
         }
+        return {
+          status: "needs_verification",
+          email: credentials.email
+        };
       } catch (err) {
         const message = err instanceof Error ? err.message : "Signup failed";
         setError(message);
@@ -225,7 +260,7 @@ function AuthProvider({
   const logout = useCallback(async () => {
     try {
       if (session) {
-        await fetch(buildUrl("logout"), {
+        await authFetch(buildUrl("logout"), {
           method: "POST",
           headers: {
             Authorization: `Bearer ${session.access_token}`
@@ -244,11 +279,11 @@ function AuthProvider({
   const updateProfile = useCallback(
     async (data) => {
       if (!session) {
-        throw new Error("Not authenticated");
+        throw new AuthError("Not authenticated", 401);
       }
       setError(null);
       try {
-        const response = await fetch(buildUrl("me"), {
+        const response = await authFetch(buildUrl("me"), {
           method: "PATCH",
           headers: {
             "Content-Type": "application/json",
@@ -258,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) {
@@ -270,17 +305,16 @@ function AuthProvider({
     [session, buildUrl]
   );
   const refreshSession = useCallback(async () => {
-    if (!session) {
-      throw new Error("No session to refresh");
-    }
-    const response = await fetch(buildUrl("refresh"), {
+    if (!session)
+      return;
+    const response = await authFetch(buildUrl("refresh"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ refreshToken: session.refresh_token })
     });
     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 = {
@@ -294,14 +328,14 @@ function AuthProvider({
     async (email) => {
       setError(null);
       try {
-        const response = await fetch(buildUrl("forgot-password"), {
+        const response = await authFetch(buildUrl("forgot-password"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ email })
         });
         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";
@@ -315,14 +349,14 @@ function AuthProvider({
     async (token, newPassword) => {
       setError(null);
       try {
-        const response = await fetch(buildUrl("reset-password"), {
+        const response = await authFetch(buildUrl("reset-password"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ token, password: newPassword })
         });
         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";
@@ -349,14 +383,14 @@ function AuthProvider({
       setError(null);
       setLoading(true);
       try {
-        const response = await fetch(buildUrl("verify-email"), {
+        const response = await authFetch(buildUrl("verify-email"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ email, otp: code })
         });
         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);
@@ -375,14 +409,14 @@ function AuthProvider({
     async (email) => {
       setError(null);
       try {
-        const response = await fetch(buildUrl("resend-verification"), {
+        const response = await authFetch(buildUrl("resend-verification"), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ email })
         });
         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";
@@ -396,9 +430,7 @@ function AuthProvider({
     if (!projectId)
       return;
     try {
-      const response = await fetch(
-        `${baseUrl}/${projectId}/auth/config`
-      );
+      const response = await fetch(`${baseUrl}/${projectId}/auth/config`);
       if (response.ok) {
         const data = await response.json();
         setAuthConfig(data.config || null);
@@ -527,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.0",
+  "version": "1.0.2",
   "description": "Authentication hooks for Instroc Cloud — useAuth, useUser, AuthProvider",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"