@instroc/auth 1.0.2 → 1.1.1

package/dist/forms.d.ts

@@ -0,0 +1 @@
+export { M as MessageOverrides, O as OnErrorResult, m as UseForgotPasswordFormOptions, n as UseForgotPasswordFormReturn, U as UseLoginFormOptions, h as UseLoginFormReturn, k as UseOtpFormOptions, l as UseOtpFormReturn, o as UseResetPasswordFormOptions, p as UseResetPasswordFormReturn, i as UseSignupFormOptions, j as UseSignupFormReturn, f as useForgotPasswordForm, u as useLoginForm, e as useOtpForm, g as useResetPasswordForm, d as useSignupForm } from './index-D4rCSC9H.js';

package/dist/forms.js

@@ -0,0 +1,14 @@
+import {
+  useForgotPasswordForm,
+  useLoginForm,
+  useOtpForm,
+  useResetPasswordForm,
+  useSignupForm
+} from "./chunk-T7NGX4DQ.js";
+export {
+  useForgotPasswordForm,
+  useLoginForm,
+  useOtpForm,
+  useResetPasswordForm,
+  useSignupForm
+};

package/dist/index-D4rCSC9H.d.ts

@@ -0,0 +1,365 @@
+interface AuthUser {
+    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;
+}
+interface AuthState {
+    user: AuthUser | null;
+    session: AuthSession | null;
+    loading: boolean;
+    error: string | null;
+}
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+interface SignupCredentials {
+    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;
+}
+interface VisibilityConfig {
+    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.
+ *
+ * - `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<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>;
+}
+interface AuthProviderProps {
+    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;
+}
+interface RefreshResponse {
+    access_token: string;
+    expires_at: string;
+}
+
+/**
+ * Optional override map: for a given HTTP status, display this message instead
+ * of the server's `error` string. The AI uses this to customize copy per app
+ * (e.g. `{ 429: "Whoa, slow down." }`).
+ */
+type MessageOverrides = Partial<Record<number, string>>;
+/**
+ * Return type for `onError` callbacks across form hooks. Controls what message
+ * (if any) gets set on the form's `error` state:
+ *
+ *  - `string`        → use this as the error message (overrides defaults)
+ *  - `null`          → suppress entirely; no error banner shown
+ *  - `undefined`/void → fall through to the default `resolveErrorMessage` logic
+ *
+ * This is the main extension point for custom flows — e.g. reading `err.code`
+ * to produce tailored copy, or suppressing the banner while handling the error
+ * with a different UI surface (a toast, a redirect, a modal).
+ */
+type OnErrorResult = string | null | void;
+
+interface UseLoginFormOptions {
+    /** Called after a successful login — typically `() => navigate("/")`. */
+    onSuccess?: (user: AuthUser) => void;
+    /**
+     * Called when the server returns 403 (`email_not_verified`). Typically
+     * `(email) => navigate("/verify-email", { state: { email } })`. When this
+     * callback is provided, the 403 is treated as a routing signal, not an
+     * error — `error` state is NOT set.
+     */
+    onNeedsVerification?: (email: string) => void;
+    /**
+     * Customize error handling. Receives the raw thrown value — inspect
+     * `err instanceof AuthError`, `err.status`, or `err.code` to branch.
+     *
+     * Return value controls the form's `error` state:
+     *  - `string` → use this as the error message
+     *  - `null`   → suppress (no error banner)
+     *  - `void`   → fall through to the default message
+     */
+    onError?: (err: unknown) => OnErrorResult;
+    /** Override user-facing copy by HTTP status. Keys are status codes. */
+    messages?: MessageOverrides;
+}
+interface UseLoginFormReturn {
+    submit: (credentials: LoginCredentials) => Promise<void>;
+    loading: boolean;
+    /** User-facing message, or null. Always a string — never an Error object. */
+    error: string | null;
+    /** Imperatively set the error message (e.g. for custom pre-submit validation). */
+    setError: (message: string | null) => void;
+    clearError: () => void;
+}
+/**
+ * Headless login form hook. Eliminates the handleSubmit + try/catch boilerplate
+ * that every auth page would otherwise reinvent.
+ *
+ * Usage:
+ *   const navigate = useNavigate();
+ *   const { submit, loading, error } = useLoginForm({
+ *     onSuccess: () => navigate("/"),
+ *     onNeedsVerification: (email) =>
+ *       navigate("/verify-email", { state: { email } }),
+ *   });
+ *
+ *   <form onSubmit={(e) => { e.preventDefault(); submit({ email, password }); }}>
+ *     …
+ *     {error && <p className="text-red-600">{error}</p>}
+ *     <button disabled={loading}>{loading ? "Signing in…" : "Sign in"}</button>
+ *   </form>
+ *
+ * For custom flows — e.g. showing a 15-minute cooldown on `account_locked` —
+ * pass `onError` and inspect `err.code`:
+ *
+ *   onError: (err) => {
+ *     if (err instanceof AuthError && err.code === "account_locked") {
+ *       return "Too many attempts. Try again in 15 minutes.";
+ *     }
+ *   }
+ */
+declare function useLoginForm(options?: UseLoginFormOptions): UseLoginFormReturn;
+
+interface UseSignupFormOptions {
+    /** Called when signup completes and the user is fully authenticated. */
+    onSuccess?: (user: AuthUser) => void;
+    /**
+     * Called when the server sent a verification OTP. Typically
+     * `(email) => navigate("/verify-email", { state: { email } })`.
+     *
+     * `needs_verification` is a SUCCESS state, NOT an error — do not route it
+     * through the error banner.
+     */
+    onNeedsVerification?: (email: string) => void;
+    /**
+     * Called when the account is pending admin approval (private projects).
+     * Typically `(user) => navigate("/pending-approval")`.
+     *
+     * `needs_approval` is a SUCCESS state, NOT an error.
+     */
+    onNeedsApproval?: (user: AuthUser) => void;
+    /**
+     * Customize error handling — see useLoginForm.onError for the return
+     * contract (`string` overrides, `null` suppresses, `void` defaults).
+     */
+    onError?: (err: unknown) => OnErrorResult;
+    /** Override user-facing copy by HTTP status. */
+    messages?: MessageOverrides;
+}
+interface UseSignupFormReturn {
+    submit: (credentials: SignupCredentials) => Promise<void>;
+    loading: boolean;
+    error: string | null;
+    setError: (message: string | null) => void;
+    clearError: () => void;
+}
+/**
+ * Headless signup form hook.
+ *
+ * The `SignupResult` routing (`authenticated` | `needs_verification` |
+ * `needs_approval`) is handled internally — callers wire each outcome to its
+ * own callback. None of the success states touch `error` state.
+ *
+ * Usage:
+ *   const navigate = useNavigate();
+ *   const { submit, loading, error } = useSignupForm({
+ *     onSuccess: () => navigate("/"),
+ *     onNeedsVerification: (email) =>
+ *       navigate("/verify-email", { state: { email } }),
+ *     onNeedsApproval: () => navigate("/pending-approval"),
+ *   });
+ */
+declare function useSignupForm(options?: UseSignupFormOptions): UseSignupFormReturn;
+
+interface UseOtpFormOptions {
+    /** The email that the OTP was sent to. Required — typically from route state. */
+    email: string;
+    /** Called after `verifyOTP` succeeds and the user is authenticated. */
+    onSuccess?: () => void;
+    /** Called after `resendOTP` succeeds. Typically used to show a toast. */
+    onResendSuccess?: () => void;
+    /** Error customization contract — see useLoginForm.onError. */
+    onError?: (err: unknown) => OnErrorResult;
+    /** Override user-facing copy by HTTP status. */
+    messages?: MessageOverrides;
+    /** Cooldown seconds between resend attempts. Defaults to 60. */
+    resendCooldownSeconds?: number;
+}
+interface UseOtpFormReturn {
+    /** Verify the OTP code. */
+    submit: (code: string) => Promise<void>;
+    /** Ask the server to re-send the OTP. Respects `resendCooldownSeconds`. */
+    resend: () => Promise<void>;
+    loading: boolean;
+    resending: boolean;
+    /** Seconds remaining until the user can resend again (0 when ready). */
+    resendCooldown: number;
+    error: string | null;
+    setError: (message: string | null) => void;
+    clearError: () => void;
+}
+/**
+ * Headless OTP verification form hook. Handles both verify and resend, with
+ * a cooldown timer to prevent 429s.
+ *
+ * Usage:
+ *   const navigate = useNavigate();
+ *   const location = useLocation();
+ *   const email = location.state?.email as string;
+ *   const { submit, resend, loading, resendCooldown, error } = useOtpForm({
+ *     email,
+ *     onSuccess: () => navigate("/"),
+ *   });
+ *
+ *   <form onSubmit={(e) => { e.preventDefault(); submit(code); }}>
+ *     …
+ *     <button type="button" disabled={resendCooldown > 0} onClick={resend}>
+ *       {resendCooldown > 0 ? `Resend (${resendCooldown}s)` : "Resend code"}
+ *     </button>
+ *   </form>
+ */
+declare function useOtpForm(options: UseOtpFormOptions): UseOtpFormReturn;
+
+interface UseForgotPasswordFormOptions {
+    /**
+     * Called after the server accepts the request. This fires for both "email
+     * exists, we sent a link" and "email doesn't exist, we silently succeeded"
+     * — don't tell the user which (account-enumeration leak). Typically used
+     * to show a "Check your email" confirmation screen.
+     */
+    onSuccess?: (email: string) => void;
+    onError?: (err: unknown) => OnErrorResult;
+    messages?: MessageOverrides;
+}
+interface UseForgotPasswordFormReturn {
+    submit: (email: string) => Promise<void>;
+    loading: boolean;
+    /** Once true, the request completed — show the "check your email" UI. */
+    submitted: boolean;
+    error: string | null;
+    setError: (message: string | null) => void;
+    clearError: () => void;
+    /** Reset `submitted` back to false (e.g. if the user wants to try another email). */
+    reset: () => void;
+}
+/**
+ * Headless forgot-password form hook.
+ *
+ * Usage:
+ *   const { submit, loading, error, submitted } = useForgotPasswordForm();
+ *
+ *   if (submitted) {
+ *     return <p>Check your email for a reset link.</p>;
+ *   }
+ *
+ *   <form onSubmit={(e) => { e.preventDefault(); submit(email); }}>
+ *     …
+ *   </form>
+ */
+declare function useForgotPasswordForm(options?: UseForgotPasswordFormOptions): UseForgotPasswordFormReturn;
+
+interface UseResetPasswordFormOptions {
+    /**
+     * The reset token from the URL (e.g. `useSearchParams().get("token")`).
+     * Required — the hook does not read `window.location` to stay router-agnostic.
+     */
+    token: string;
+    /**
+     * Called after the password is successfully reset. Typically
+     * `() => navigate("/login")`.
+     */
+    onSuccess?: () => void;
+    onError?: (err: unknown) => OnErrorResult;
+    messages?: MessageOverrides;
+}
+interface UseResetPasswordFormReturn {
+    submit: (newPassword: string) => Promise<void>;
+    loading: boolean;
+    error: string | null;
+    setError: (message: string | null) => void;
+    clearError: () => void;
+}
+/**
+ * Headless reset-password form hook.
+ *
+ * Usage:
+ *   const [searchParams] = useSearchParams();
+ *   const token = searchParams.get("token") ?? "";
+ *   const navigate = useNavigate();
+ *
+ *   const { submit, loading, error } = useResetPasswordForm({
+ *     token,
+ *     onSuccess: () => navigate("/login"),
+ *   });
+ *
+ *   <form onSubmit={(e) => { e.preventDefault(); submit(newPassword); }}>
+ *     …
+ *   </form>
+ */
+declare function useResetPasswordForm(options: UseResetPasswordFormOptions): UseResetPasswordFormReturn;
+
+export { type AuthProviderProps as A, type LoginCredentials as L, type MessageOverrides as M, type OnErrorResult as O, type RefreshResponse as R, type SignupCredentials as S, type UseLoginFormOptions as U, type VisibilityConfig as V, type AuthContextValue as a, type AuthUser as b, type AuthSession as c, useSignupForm as d, useOtpForm as e, useForgotPasswordForm as f, useResetPasswordForm as g, type UseLoginFormReturn as h, type UseSignupFormOptions as i, type UseSignupFormReturn as j, type UseOtpFormOptions as k, type UseOtpFormReturn as l, type UseForgotPasswordFormOptions as m, type UseForgotPasswordFormReturn as n, type UseResetPasswordFormOptions as o, type UseResetPasswordFormReturn as p, type AuthState as q, type AuthConfig as r, type OAuthProvider as s, type SignupResult as t, useLoginForm as u, type UpdateProfileData as v, type AuthResponse as w };

package/dist/index.d.ts

@@ -1,107 +1,5 @@
-interface AuthUser {
-    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;
-}
-interface AuthState {
-    user: AuthUser | null;
-    session: AuthSession | null;
-    loading: boolean;
-    error: string | null;
-}
-interface LoginCredentials {
-    email: string;
-    password: string;
-}
-interface SignupCredentials {
-    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;
-}
-interface VisibilityConfig {
-    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.
- *
- * - `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<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>;
-}
-interface AuthProviderProps {
-    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;
-}
-interface RefreshResponse {
-    access_token: string;
-    expires_at: string;
-}
+import { A as AuthProviderProps, a as AuthContextValue, b as AuthUser, c as AuthSession } from './index-D4rCSC9H.js';
+export { r as AuthConfig, w as AuthResponse, q as AuthState, L as LoginCredentials, M as MessageOverrides, s as OAuthProvider, O as OnErrorResult, R as RefreshResponse, S as SignupCredentials, t as SignupResult, v as UpdateProfileData, m as UseForgotPasswordFormOptions, n as UseForgotPasswordFormReturn, U as UseLoginFormOptions, h as UseLoginFormReturn, k as UseOtpFormOptions, l as UseOtpFormReturn, o as UseResetPasswordFormOptions, p as UseResetPasswordFormReturn, i as UseSignupFormOptions, j as UseSignupFormReturn, V as VisibilityConfig, f as useForgotPasswordForm, u as useLoginForm, e as useOtpForm, g as useResetPasswordForm, d as useSignupForm } from './index-D4rCSC9H.js';
 
 declare function AuthProvider({ children, projectId: initialProjectId, baseUrl, persistSession, onAuthStateChange, }: AuthProviderProps): JSX.Element;
 declare function useAuthContext(): AuthContextValue;
@@ -156,4 +54,4 @@ declare class AuthError extends Error {
     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 };
+export { AuthContextValue, AuthError, AuthProvider, AuthProviderProps, AuthSession, AuthUser, useAuth, useAuthContext, useAuthRequired, useSession, useUser };