@djangocfg/api 2.1.103 → 2.1.104

package/dist/auth.d.cts

@@ -342,6 +342,82 @@ interface AccountsProviderProps {
 declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAccountsContext(): AccountsContextValue;
 
+/**
+ * Universal Router Hook with BasePath Support
+ *
+ * Wrapper around Next.js useRouter that automatically handles basePath
+ * for static builds served via iframe or subdirectory
+ *
+ * IMPORTANT: In Next.js 15 App Router, router.push() does NOT automatically
+ * handle basePath (unlike Pages Router). This is a breaking change in App Router.
+ *
+ * This hook ensures basePath is always included when navigating, especially
+ * important for static exports served via iframe where basePath is critical.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration
+ */
+/**
+ * Router with basePath support
+ *
+ * Automatically adds basePath to all navigation methods when basePath is configured.
+ * In Next.js 15 App Router, router.push() doesn't handle basePath automatically,
+ * so this hook uses window.location to ensure basePath is always included.
+ *
+ * @example
+ * ```tsx
+ * const router = useCfgRouter();
+ *
+ * // With basePath='/cfg/admin':
+ * router.push('/dashboard');     // Client-side navigation to '/cfg/admin/dashboard'
+ * router.replace('/auth');       // Client-side replace with '/cfg/admin/auth'
+ * router.hardPush('/dashboard'); // Full page reload to '/cfg/admin/dashboard'
+ * router.hardReplace('/auth');   // Full page replace with '/cfg/admin/auth'
+ * ```
+ */
+declare function useCfgRouter(): {
+    push: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+    replace: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+    hardPush: (href: string) => void;
+    hardReplace: (href: string) => void;
+    prefetch: (href: string) => void;
+    back: () => void;
+    forward: () => void;
+    refresh: () => void;
+};
+
+/**
+ * useQueryParams Hook
+ *
+ * Safe hook to access URL query parameters without requiring Suspense boundary.
+ * Works on client-side only, returns empty URLSearchParams during SSR/prerendering.
+ *
+ * @example
+ * ```tsx
+ * const params = useQueryParams();
+ * const flow = params.get('flow');
+ * const hasFlow = params.has('flow');
+ * const allTags = params.getAll('tags');
+ * ```
+ */
+/**
+ * Hook to safely access URL query parameters without useSearchParams()
+ *
+ * This hook reads query parameters directly from window.location.search,
+ * avoiding the need for Suspense boundaries that useSearchParams() requires.
+ *
+ * Automatically updates when URL changes (navigation, back/forward, etc.)
+ * Uses pathname from Next.js to detect route changes and polls for query param changes.
+ *
+ * Returns a URLSearchParams object with get(), getAll(), has(), etc.
+ *
+ * @returns URLSearchParams object (empty during SSR)
+ */
+declare function useQueryParams(): URLSearchParams;
+
 /**
  * Auth Form Types
  *
@@ -953,4 +1029,4 @@ declare const Analytics: {
     setUser(userId: string): void;
 };
 
-export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthChannel, type AuthConfig, type AuthContextType, type AuthFormAutoSubmit, type AuthFormContextType, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, type AuthHelpProps, type AuthLayoutConfig, type AuthLayoutProps, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, detectChannelFromIdentifier, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useDeleteAccount, useGithubAuth, useLocalStorage, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };
+export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthChannel, type AuthConfig, type AuthContextType, type AuthFormAutoSubmit, type AuthFormContextType, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, type AuthHelpProps, type AuthLayoutConfig, type AuthLayoutProps, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, detectChannelFromIdentifier, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };

package/dist/auth.d.ts

@@ -342,6 +342,82 @@ interface AccountsProviderProps {
 declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAccountsContext(): AccountsContextValue;
 
+/**
+ * Universal Router Hook with BasePath Support
+ *
+ * Wrapper around Next.js useRouter that automatically handles basePath
+ * for static builds served via iframe or subdirectory
+ *
+ * IMPORTANT: In Next.js 15 App Router, router.push() does NOT automatically
+ * handle basePath (unlike Pages Router). This is a breaking change in App Router.
+ *
+ * This hook ensures basePath is always included when navigating, especially
+ * important for static exports served via iframe where basePath is critical.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration
+ */
+/**
+ * Router with basePath support
+ *
+ * Automatically adds basePath to all navigation methods when basePath is configured.
+ * In Next.js 15 App Router, router.push() doesn't handle basePath automatically,
+ * so this hook uses window.location to ensure basePath is always included.
+ *
+ * @example
+ * ```tsx
+ * const router = useCfgRouter();
+ *
+ * // With basePath='/cfg/admin':
+ * router.push('/dashboard');     // Client-side navigation to '/cfg/admin/dashboard'
+ * router.replace('/auth');       // Client-side replace with '/cfg/admin/auth'
+ * router.hardPush('/dashboard'); // Full page reload to '/cfg/admin/dashboard'
+ * router.hardReplace('/auth');   // Full page replace with '/cfg/admin/auth'
+ * ```
+ */
+declare function useCfgRouter(): {
+    push: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+    replace: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+    hardPush: (href: string) => void;
+    hardReplace: (href: string) => void;
+    prefetch: (href: string) => void;
+    back: () => void;
+    forward: () => void;
+    refresh: () => void;
+};
+
+/**
+ * useQueryParams Hook
+ *
+ * Safe hook to access URL query parameters without requiring Suspense boundary.
+ * Works on client-side only, returns empty URLSearchParams during SSR/prerendering.
+ *
+ * @example
+ * ```tsx
+ * const params = useQueryParams();
+ * const flow = params.get('flow');
+ * const hasFlow = params.has('flow');
+ * const allTags = params.getAll('tags');
+ * ```
+ */
+/**
+ * Hook to safely access URL query parameters without useSearchParams()
+ *
+ * This hook reads query parameters directly from window.location.search,
+ * avoiding the need for Suspense boundaries that useSearchParams() requires.
+ *
+ * Automatically updates when URL changes (navigation, back/forward, etc.)
+ * Uses pathname from Next.js to detect route changes and polls for query param changes.
+ *
+ * Returns a URLSearchParams object with get(), getAll(), has(), etc.
+ *
+ * @returns URLSearchParams object (empty during SSR)
+ */
+declare function useQueryParams(): URLSearchParams;
+
 /**
  * Auth Form Types
  *
@@ -953,4 +1029,4 @@ declare const Analytics: {
     setUser(userId: string): void;
 };
 
-export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthChannel, type AuthConfig, type AuthContextType, type AuthFormAutoSubmit, type AuthFormContextType, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, type AuthHelpProps, type AuthLayoutConfig, type AuthLayoutProps, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, detectChannelFromIdentifier, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useDeleteAccount, useGithubAuth, useLocalStorage, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };
+export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthChannel, type AuthConfig, type AuthContextType, type AuthFormAutoSubmit, type AuthFormContextType, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, type AuthHelpProps, type AuthLayoutConfig, type AuthLayoutProps, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, detectChannelFromIdentifier, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };