@djangocfg/api 2.1.10 → 2.1.14

package/dist/auth.d.ts

@@ -0,0 +1,525 @@
+import React$1, { ReactNode } from 'react';
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as consola from 'consola';
+
+/**
+ * Delivery channel: 'email' or 'phone'. Auto-detected if not provided.
+ * * `email` - Email
+ * * `phone` - Phone
+ */
+declare enum OTPRequestRequestChannel {
+    EMAIL = "email",
+    PHONE = "phone"
+}
+/**
+ * Delivery channel: 'email' or 'phone'. Auto-detected if not provided.
+ * * `email` - Email
+ * * `phone` - Phone
+ */
+declare enum OTPVerifyRequestChannel {
+    EMAIL = "email",
+    PHONE = "phone"
+}
+
+/**
+ * Zod schema for OTPRequestRequest
+ *
+ * This schema provides runtime validation and type inference.
+ *  * Serializer for OTP request.
+ *  */
+
+/**
+ * Serializer for OTP request.
+ */
+declare const OTPRequestRequestSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    channel: z.ZodOptional<z.ZodEnum<typeof OTPRequestRequestChannel>>;
+    source_url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type OTPRequestRequest = z.infer<typeof OTPRequestRequestSchema>;
+
+/**
+ * Zod schema for OTPRequestResponse
+ *
+ * This schema provides runtime validation and type inference.
+ *  * OTP request response.
+ *  */
+
+/**
+ * OTP request response.
+ */
+declare const OTPRequestResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type OTPRequestResponse = z.infer<typeof OTPRequestResponseSchema>;
+
+/**
+ * Zod schema for OTPVerifyRequest
+ *
+ * This schema provides runtime validation and type inference.
+ *  * Serializer for OTP verification.
+ *  */
+
+/**
+ * Serializer for OTP verification.
+ */
+declare const OTPVerifyRequestSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    otp: z.ZodString;
+    channel: z.ZodOptional<z.ZodEnum<typeof OTPVerifyRequestChannel>>;
+    source_url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type OTPVerifyRequest = z.infer<typeof OTPVerifyRequestSchema>;
+
+/**
+ * Zod schema for OTPVerifyResponse
+ *
+ * This schema provides runtime validation and type inference.
+ *  * OTP verification response.
+ *  */
+
+/**
+ * OTP verification response.
+ */
+declare const OTPVerifyResponseSchema: z.ZodObject<{
+    refresh: z.ZodString;
+    access: z.ZodString;
+    user: z.ZodObject<{
+        id: z.ZodInt;
+        email: z.ZodEmail;
+        first_name: z.ZodOptional<z.ZodString>;
+        last_name: z.ZodOptional<z.ZodString>;
+        full_name: z.ZodString;
+        initials: z.ZodString;
+        display_username: z.ZodString;
+        company: z.ZodOptional<z.ZodString>;
+        phone: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodString>;
+        avatar: z.ZodNullable<z.ZodURL>;
+        is_staff: z.ZodBoolean;
+        is_superuser: z.ZodBoolean;
+        date_joined: z.ZodISODateTime;
+        last_login: z.ZodNullable<z.ZodISODateTime>;
+        unanswered_messages_count: z.ZodInt;
+        centrifugo: z.ZodNullable<z.ZodObject<{
+            token: z.ZodString;
+            centrifugo_url: z.ZodURL;
+            expires_at: z.ZodISODateTime;
+            channels: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type OTPVerifyResponse = z.infer<typeof OTPVerifyResponseSchema>;
+
+/**
+ * Zod schema for PatchedUserProfileUpdateRequest
+ *
+ * This schema provides runtime validation and type inference.
+ *  * Serializer for updating user profile.
+ *  */
+
+/**
+ * Serializer for updating user profile.
+ */
+declare const PatchedUserProfileUpdateRequestSchema: z.ZodObject<{
+    first_name: z.ZodOptional<z.ZodString>;
+    last_name: z.ZodOptional<z.ZodString>;
+    company: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type PatchedUserProfileUpdateRequest = z.infer<typeof PatchedUserProfileUpdateRequestSchema>;
+
+/**
+ * Zod schema for TokenRefresh
+ *
+ * This schema provides runtime validation and type inference.
+ *  */
+
+declare const TokenRefreshSchema: z.ZodObject<{
+    access: z.ZodString;
+    refresh: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type TokenRefresh = z.infer<typeof TokenRefreshSchema>;
+
+/**
+ * Zod schema for User
+ *
+ * This schema provides runtime validation and type inference.
+ *  * Serializer for user details.
+ *  */
+
+/**
+ * Serializer for user details.
+ */
+declare const UserSchema: z.ZodObject<{
+    id: z.ZodInt;
+    email: z.ZodEmail;
+    first_name: z.ZodOptional<z.ZodString>;
+    last_name: z.ZodOptional<z.ZodString>;
+    full_name: z.ZodString;
+    initials: z.ZodString;
+    display_username: z.ZodString;
+    company: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodNullable<z.ZodURL>;
+    is_staff: z.ZodBoolean;
+    is_superuser: z.ZodBoolean;
+    date_joined: z.ZodISODateTime;
+    last_login: z.ZodNullable<z.ZodISODateTime>;
+    unanswered_messages_count: z.ZodInt;
+    centrifugo: z.ZodNullable<z.ZodObject<{
+        token: z.ZodString;
+        centrifugo_url: z.ZodURL;
+        expires_at: z.ZodISODateTime;
+        channels: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type User = z.infer<typeof UserSchema>;
+
+/**
+ * Zod schema for UserProfileUpdateRequest
+ *
+ * This schema provides runtime validation and type inference.
+ *  * Serializer for updating user profile.
+ *  */
+
+/**
+ * Serializer for updating user profile.
+ */
+declare const UserProfileUpdateRequestSchema: z.ZodObject<{
+    first_name: z.ZodOptional<z.ZodString>;
+    last_name: z.ZodOptional<z.ZodString>;
+    company: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Infer TypeScript type from Zod schema
+ */
+type UserProfileUpdateRequest = z.infer<typeof UserProfileUpdateRequestSchema>;
+
+type UserProfile = User;
+interface AuthConfig {
+    apiUrl?: string;
+    routes?: {
+        auth?: string;
+        defaultCallback?: string;
+        defaultAuthCallback?: string;
+    };
+    onLogout?: () => void;
+    onConfirm?: (options: {
+        title: string;
+        description: string;
+        confirmationButtonText: string;
+        cancellationButtonText: string;
+        color: string;
+    }) => Promise<{
+        confirmed: boolean;
+    }>;
+}
+interface AuthContextType {
+    user: UserProfile | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    isAdminUser: boolean;
+    loadCurrentProfile: (callerId?: string) => Promise<void>;
+    checkAuthAndRedirect: () => Promise<void>;
+    getToken: () => string | null;
+    getRefreshToken: () => string | null;
+    getSavedEmail: () => string | null;
+    saveEmail: (email: string) => void;
+    clearSavedEmail: () => void;
+    getSavedPhone: () => string | null;
+    savePhone: (phone: string) => void;
+    clearSavedPhone: () => void;
+    requestOTP: (identifier: string, channel?: 'email' | 'phone', sourceUrl?: string) => Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    verifyOTP: (identifier: string, otpCode: string, channel?: 'email' | 'phone', sourceUrl?: string) => Promise<{
+        success: boolean;
+        message: string;
+        user?: UserProfile;
+    }>;
+    refreshToken: () => Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    logout: () => Promise<void>;
+    getSavedRedirectUrl: () => string | null;
+    saveRedirectUrl: (url: string) => void;
+    clearSavedRedirectUrl: () => void;
+    getFinalRedirectUrl: () => string;
+    useAndClearRedirectUrl: () => string;
+    saveCurrentUrlForRedirect: () => void;
+}
+interface AuthProviderProps {
+    children: React$1.ReactNode;
+    config?: AuthConfig;
+}
+
+declare const AuthProvider: React$1.FC<AuthProviderProps>;
+declare const useAuth: () => AuthContextType;
+
+interface AccountsContextValue {
+    profile?: User;
+    isLoadingProfile: boolean;
+    profileError: Error | null;
+    updateProfile: (data: UserProfileUpdateRequest) => Promise<User>;
+    partialUpdateProfile: (data: PatchedUserProfileUpdateRequest) => Promise<User>;
+    uploadAvatar: (formData: FormData) => Promise<User>;
+    refreshProfile: (callerId?: string) => Promise<User | undefined>;
+    requestOTP: (data: OTPRequestRequest) => Promise<OTPRequestResponse>;
+    verifyOTP: (data: OTPVerifyRequest) => Promise<OTPVerifyResponse>;
+    refreshToken: (refresh: string) => Promise<TokenRefresh>;
+    logout: () => void;
+}
+interface AccountsProviderProps {
+    children: ReactNode;
+}
+declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAccountsContext(): AccountsContextValue;
+
+interface AuthRedirectOptions {
+    fallbackUrl?: string;
+    clearOnUse?: boolean;
+}
+declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
+    redirectUrl: string;
+    setRedirect: (url: string) => void;
+    getRedirect: () => string;
+    clearRedirect: () => void;
+    hasRedirect: () => boolean;
+    getFinalRedirectUrl: () => string;
+    useAndClearRedirect: () => string;
+};
+
+interface UseAuthGuardOptions {
+    redirectTo?: string;
+    requireAuth?: boolean;
+}
+declare const useAuthGuard: (options?: UseAuthGuardOptions) => {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+};
+
+/**
+ * Simple sessionStorage hook with better error handling
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ */
+declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+/**
+ * Simple localStorage hook with better error handling
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+interface AuthFormState {
+    identifier: string;
+    channel: 'email' | 'phone';
+    otp: string;
+    isLoading: boolean;
+    acceptedTerms: boolean;
+    step: 'identifier' | 'otp';
+    error: string;
+}
+interface AuthFormHandlers {
+    setIdentifier: (identifier: string) => void;
+    setChannel: (channel: 'email' | 'phone') => void;
+    setOtp: (otp: string) => void;
+    setAcceptedTerms: (accepted: boolean) => void;
+    setError: (error: string) => void;
+    clearError: () => void;
+    handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
+    handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
+    handleResendOTP: () => Promise<void>;
+    handleBackToIdentifier: () => void;
+    forceOTPStep: () => void;
+    detectChannelFromIdentifier: (identifier: string) => 'email' | 'phone' | null;
+    validateIdentifier: (identifier: string, channel?: 'email' | 'phone') => boolean;
+}
+interface UseAuthFormOptions {
+    onIdentifierSuccess?: (identifier: string, channel: 'email' | 'phone') => void;
+    onOTPSuccess?: () => void;
+    onError?: (message: string) => void;
+    sourceUrl: string;
+}
+declare const useAuthForm: (options: UseAuthFormOptions) => AuthFormState & AuthFormHandlers;
+
+interface UseAutoAuthOptions {
+    onOTPDetected?: (otp: string) => void;
+    cleanupUrl?: boolean;
+}
+/**
+ * Hook for automatic authentication from URL query parameters
+ * Detects OTP from URL and triggers callback
+ */
+declare const useAutoAuth: (options?: UseAutoAuthOptions) => {
+    isReady: boolean;
+    hasOTP: boolean;
+};
+
+interface UseGithubAuthOptions {
+    sourceUrl?: string;
+    onSuccess?: (user: any, isNewUser: boolean) => void;
+    onError?: (error: string) => void;
+    redirectUrl?: string;
+}
+interface UseGithubAuthReturn {
+    isLoading: boolean;
+    error: string | null;
+    startGithubAuth: () => Promise<void>;
+    handleGithubCallback: (code: string, state: string) => Promise<void>;
+}
+/**
+ * Hook for GitHub OAuth authentication flow.
+ *
+ * Usage:
+ * 1. Call startGithubAuth() to redirect user to GitHub
+ * 2. After GitHub redirects back, call handleGithubCallback(code, state)
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, error, startGithubAuth } = useGithubAuth({
+ *   onSuccess: (user) => router.push('/dashboard'),
+ *   onError: (error) => console.error(error),
+ * });
+ *
+ * <Button onClick={startGithubAuth} disabled={isLoading}>
+ *   Continue with GitHub
+ * </Button>
+ * ```
+ */
+declare const useGithubAuth: (options?: UseGithubAuthOptions) => UseGithubAuthReturn;
+
+/**
+ * Profile Cache Hook
+ *
+ * Provides localStorage-based caching for user profile with:
+ * - TTL (Time To Live) - default 1 hour
+ * - Version control for migrations
+ * - Automatic invalidation on expiry
+ */
+
+interface ProfileCacheOptions {
+    /** Time to live in milliseconds (default: 1 hour) */
+    ttl?: number;
+}
+/**
+ * Get cached profile from localStorage
+ * @returns User profile if valid cache exists, null otherwise
+ */
+declare function getCachedProfile(): User | null;
+/**
+ * Save profile to localStorage cache
+ * @param profile - User profile to cache
+ * @param options - Cache options (TTL)
+ */
+declare function setCachedProfile(profile: User, options?: ProfileCacheOptions): void;
+/**
+ * Clear profile cache from localStorage
+ */
+declare function clearProfileCache(): void;
+/**
+ * Check if cached profile is valid (exists and not expired)
+ */
+declare function hasValidCache(): boolean;
+/**
+ * Get cache metadata (age, TTL, etc.)
+ */
+declare function getCacheMetadata(): {
+    exists: boolean;
+    age?: number;
+    ttl?: number;
+    expiresIn?: number;
+} | null;
+
+/**
+ * Email validation utility
+ */
+declare const validateEmail: (email: string) => boolean;
+
+/**
+ * Format authentication error for display
+ */
+declare const formatAuthError: (error: any) => string;
+
+declare const logger: consola.ConsolaInstance;
+/**
+ * Auth-specific logger
+ */
+declare const authLogger: consola.ConsolaInstance;
+
+/**
+ * Analytics stub for @djangocfg/api/auth
+ * Provides minimal analytics interface without external dependencies
+ *
+ * If you need full analytics, install @djangocfg/layouts and use its Analytics module
+ */
+declare enum AnalyticsEvent {
+    AUTH_OTP_REQUEST = "auth_otp_request",
+    AUTH_LOGIN_SUCCESS = "auth_login_success",
+    AUTH_OTP_VERIFY_FAIL = "auth_otp_verify_fail",
+    AUTH_SESSION_EXPIRED = "auth_session_expired",
+    AUTH_TOKEN_REFRESH = "auth_token_refresh",
+    AUTH_TOKEN_REFRESH_FAIL = "auth_token_refresh_fail",
+    AUTH_LOGOUT = "auth_logout",
+    AUTH_OAUTH_START = "auth_oauth_start",
+    AUTH_OAUTH_FAIL = "auth_oauth_fail"
+}
+declare enum AnalyticsCategory {
+    AUTH = "auth"
+}
+type AnalyticsEventType = `${AnalyticsEvent}`;
+type AnalyticsCategoryType = `${AnalyticsCategory}`;
+interface AnalyticsEventParams {
+    category?: AnalyticsCategoryType;
+    label?: string;
+    value?: number;
+    [key: string]: any;
+}
+/**
+ * Minimal analytics implementation
+ * Logs to console in development, silent in production
+ */
+declare const Analytics: {
+    /**
+     * Track an analytics event
+     */
+    event(eventName: AnalyticsEventType, params?: AnalyticsEventParams): void;
+    /**
+     * Set user ID for tracking
+     */
+    setUser(userId: string): void;
+};
+
+export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, type AuthContextType, AuthProvider, type AuthProviderProps, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type UseGithubAuthOptions, type UseGithubAuthReturn, type UserProfile, authLogger, clearProfileCache, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthGuard, useAuthRedirectManager, useAutoAuth, useGithubAuth, useLocalStorage, useSessionStorage, validateEmail };