@djangocfg/api 2.1.542 → 2.1.544

package/dist/auth.d.cts

@@ -39,6 +39,59 @@ type CfgUserUpdateRequest = {
      */
     timezone?: string;
 };
+/**
+ * Response with JWT tokens after OAuth authentication.
+ *
+ * When 2FA is required:
+ * - requires_2fa: True
+ * - session_id: UUID of 2FA verification session
+ * - access/refresh/user: null
+ *
+ * When 2FA is not required:
+ * - requires_2fa: False
+ * - session_id: null
+ * - access/refresh/user: populated
+ */
+type OAuthTokenResponse = {
+    /**
+     * True if 2FA verification is required
+     */
+    requires_2fa?: boolean;
+    /**
+     * 2FA session ID (only when requires_2fa=True)
+     */
+    session_id?: string | null;
+    /**
+     * JWT access token (null when requires_2fa=True)
+     */
+    access?: string | null;
+    /**
+     * JWT refresh token (null when requires_2fa=True)
+     */
+    refresh?: string | null;
+    /**
+     * Authenticated user info (null when requires_2fa=True)
+     */
+    user?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * True if a new user was created during this OAuth flow
+     */
+    is_new_user?: boolean;
+    /**
+     * True if a new OAuth connection was created
+     */
+    is_new_connection?: boolean;
+    /**
+     * True if user should be prompted to enable 2FA
+     */
+    should_prompt_2fa?: boolean;
+    /**
+     * Whether this login should persist across browser restarts
+     */
+    persistent_session?: boolean;
+};
 /**
  * Serializer for OTP request.
  */
@@ -149,6 +202,49 @@ type PatchedCfgUserUpdateRequest = {
      */
     timezone?: string;
 };
+/**
+ * User data returned after 2FA verification.
+ */
+type TotpVerifyUser = {
+    readonly id: number;
+    readonly email: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    /**
+     * Get user's full name.
+     */
+    readonly full_name: string;
+    /**
+     * Get user's initials for avatar fallback.
+     */
+    readonly initials: string;
+    /**
+     * Get formatted username for display.
+     */
+    readonly display_username: string;
+    company?: string | null;
+    phone?: string | null;
+    position?: string | null;
+    language?: string | null;
+    timezone?: string | null;
+    readonly avatar: string | null;
+    /**
+     * Staff status
+     *
+     * Designates whether the user can log into this admin site.
+     */
+    readonly is_staff: boolean;
+    /**
+     * Superuser status
+     *
+     * Designates that this user has all permissions without explicitly assigning them.
+     */
+    readonly is_superuser: boolean;
+    readonly date_joined: string;
+    readonly last_login: string | null;
+    readonly unanswered_messages_count: number;
+    readonly api_key: string | null;
+};
 /**
  * Serializer for user details.
  */
@@ -522,7 +618,7 @@ interface AuthProviderProps {
     enabled?: boolean;
 }
 
-declare const AuthContext: React__default.Context<AuthContextType>;
+declare const AuthContext: React__default.Context<AuthContextType | undefined>;
 /**
  * AuthProvider — wraps AccountsProvider + AuthProviderInternal.
  *
@@ -683,11 +779,25 @@ declare const useAutoAuth: (options?: UseAutoAuthOptions) => {
     isAllowedPath: boolean;
 };
 
+/**
+ * The user payload as the OAuth endpoint declares it.
+ *
+ * Derived from the generated response rather than restated, so a schema change
+ * reaches callers through `make gen` instead of drifting silently. Today the
+ * backend types it as a free-form object; when it names a real user model, this
+ * narrows on its own.
+ */
+type OAuthUser = NonNullable<OAuthTokenResponse['user']>;
 interface UseGithubAuthOptions {
     sourceUrl?: string;
     /** Keep the completed browser session for 30 days. */
     rememberMe?: boolean;
-    onSuccess?: (user: any, isNewUser: boolean) => void;
+    /**
+     * The OAuth endpoint's OpenAPI schema types `user` as a free-form object, so
+     * this is what the server actually promises — not a `User`. Narrow it at the
+     * call site; typing it tighter here would be an assertion, not a fact.
+     */
+    onSuccess?: (user: OAuthUser, isNewUser: boolean) => void;
     onError?: (error: string) => void;
     /** Callback when 2FA is required */
     onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
@@ -724,7 +834,7 @@ declare const useGithubAuth: (options?: UseGithubAuthOptions) => UseGithubAuthRe
 
 interface UseTwoFactorVerifyOptions {
     /** Callback on successful 2FA verification */
-    onSuccess?: (user: any) => void;
+    onSuccess?: (user: TotpVerifyUser) => void;
     /** Callback on error */
     onError?: (error: string) => void;
     /** URL to redirect after successful verification */
@@ -1014,9 +1124,14 @@ declare const useDeleteAccount: () => UseDeleteAccountReturn;
 declare const validateEmail: (email: string) => boolean;
 
 /**
- * Format authentication error for display
+ * Format authentication error for display.
+ *
+ * Each candidate is checked to be a string before it is returned. Under the
+ * previous `any` the check was only that the property was truthy, so a DRF
+ * field-error object (`{detail: {email: [...]}}`) reached the UI as
+ * "[object Object]" — an error message that tells the user nothing.
  */
-declare const formatAuthError: (error: any) => string;
+declare const formatAuthError: (error: unknown) => string;
 
 /**
  * Pure auth-guard state resolution.
@@ -1114,15 +1229,27 @@ declare enum AnalyticsCategory {
 }
 type AnalyticsEventType = `${AnalyticsEvent}`;
 type AnalyticsCategoryType = `${AnalyticsCategory}`;
+/**
+ * What an analytics backend can actually carry.
+ *
+ * GA4 and OpenPanel serialise a property to a scalar; an object or a function
+ * arrives as "[object Object]" without erroring anywhere. Declaring the wider
+ * `unknown` here promised a forwarding guarantee no implementation keeps, and
+ * it made this sink incompatible with `AnalyticsEventProperties` in
+ * `@djangocfg/analytics` — the two describe the same channel and must agree.
+ * Kept as a local declaration rather than an import: `api` does not depend on
+ * `analytics`, and one shared four-member union is not worth that edge.
+ */
+type AnalyticsPropertyValue = string | number | boolean | null;
 interface AnalyticsEventParams {
     category?: AnalyticsCategoryType;
     label?: string;
     value?: number;
-    [key: string]: any;
+    [key: string]: AnalyticsPropertyValue | undefined;
 }
 /** What an analytics implementation must provide to receive auth events. */
 interface AnalyticsSink {
-    event(name: string, params?: Record<string, any>): void;
+    event(name: string, params?: Record<string, AnalyticsPropertyValue | undefined>): void;
     setUser(userId: string | null): void;
 }
 /**

package/dist/auth.d.ts

@@ -39,6 +39,59 @@ type CfgUserUpdateRequest = {
      */
     timezone?: string;
 };
+/**
+ * Response with JWT tokens after OAuth authentication.
+ *
+ * When 2FA is required:
+ * - requires_2fa: True
+ * - session_id: UUID of 2FA verification session
+ * - access/refresh/user: null
+ *
+ * When 2FA is not required:
+ * - requires_2fa: False
+ * - session_id: null
+ * - access/refresh/user: populated
+ */
+type OAuthTokenResponse = {
+    /**
+     * True if 2FA verification is required
+     */
+    requires_2fa?: boolean;
+    /**
+     * 2FA session ID (only when requires_2fa=True)
+     */
+    session_id?: string | null;
+    /**
+     * JWT access token (null when requires_2fa=True)
+     */
+    access?: string | null;
+    /**
+     * JWT refresh token (null when requires_2fa=True)
+     */
+    refresh?: string | null;
+    /**
+     * Authenticated user info (null when requires_2fa=True)
+     */
+    user?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * True if a new user was created during this OAuth flow
+     */
+    is_new_user?: boolean;
+    /**
+     * True if a new OAuth connection was created
+     */
+    is_new_connection?: boolean;
+    /**
+     * True if user should be prompted to enable 2FA
+     */
+    should_prompt_2fa?: boolean;
+    /**
+     * Whether this login should persist across browser restarts
+     */
+    persistent_session?: boolean;
+};
 /**
  * Serializer for OTP request.
  */
@@ -149,6 +202,49 @@ type PatchedCfgUserUpdateRequest = {
      */
     timezone?: string;
 };
+/**
+ * User data returned after 2FA verification.
+ */
+type TotpVerifyUser = {
+    readonly id: number;
+    readonly email: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    /**
+     * Get user's full name.
+     */
+    readonly full_name: string;
+    /**
+     * Get user's initials for avatar fallback.
+     */
+    readonly initials: string;
+    /**
+     * Get formatted username for display.
+     */
+    readonly display_username: string;
+    company?: string | null;
+    phone?: string | null;
+    position?: string | null;
+    language?: string | null;
+    timezone?: string | null;
+    readonly avatar: string | null;
+    /**
+     * Staff status
+     *
+     * Designates whether the user can log into this admin site.
+     */
+    readonly is_staff: boolean;
+    /**
+     * Superuser status
+     *
+     * Designates that this user has all permissions without explicitly assigning them.
+     */
+    readonly is_superuser: boolean;
+    readonly date_joined: string;
+    readonly last_login: string | null;
+    readonly unanswered_messages_count: number;
+    readonly api_key: string | null;
+};
 /**
  * Serializer for user details.
  */
@@ -522,7 +618,7 @@ interface AuthProviderProps {
     enabled?: boolean;
 }
 
-declare const AuthContext: React__default.Context<AuthContextType>;
+declare const AuthContext: React__default.Context<AuthContextType | undefined>;
 /**
  * AuthProvider — wraps AccountsProvider + AuthProviderInternal.
  *
@@ -683,11 +779,25 @@ declare const useAutoAuth: (options?: UseAutoAuthOptions) => {
     isAllowedPath: boolean;
 };
 
+/**
+ * The user payload as the OAuth endpoint declares it.
+ *
+ * Derived from the generated response rather than restated, so a schema change
+ * reaches callers through `make gen` instead of drifting silently. Today the
+ * backend types it as a free-form object; when it names a real user model, this
+ * narrows on its own.
+ */
+type OAuthUser = NonNullable<OAuthTokenResponse['user']>;
 interface UseGithubAuthOptions {
     sourceUrl?: string;
     /** Keep the completed browser session for 30 days. */
     rememberMe?: boolean;
-    onSuccess?: (user: any, isNewUser: boolean) => void;
+    /**
+     * The OAuth endpoint's OpenAPI schema types `user` as a free-form object, so
+     * this is what the server actually promises — not a `User`. Narrow it at the
+     * call site; typing it tighter here would be an assertion, not a fact.
+     */
+    onSuccess?: (user: OAuthUser, isNewUser: boolean) => void;
     onError?: (error: string) => void;
     /** Callback when 2FA is required */
     onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
@@ -724,7 +834,7 @@ declare const useGithubAuth: (options?: UseGithubAuthOptions) => UseGithubAuthRe
 
 interface UseTwoFactorVerifyOptions {
     /** Callback on successful 2FA verification */
-    onSuccess?: (user: any) => void;
+    onSuccess?: (user: TotpVerifyUser) => void;
     /** Callback on error */
     onError?: (error: string) => void;
     /** URL to redirect after successful verification */
@@ -1014,9 +1124,14 @@ declare const useDeleteAccount: () => UseDeleteAccountReturn;
 declare const validateEmail: (email: string) => boolean;
 
 /**
- * Format authentication error for display
+ * Format authentication error for display.
+ *
+ * Each candidate is checked to be a string before it is returned. Under the
+ * previous `any` the check was only that the property was truthy, so a DRF
+ * field-error object (`{detail: {email: [...]}}`) reached the UI as
+ * "[object Object]" — an error message that tells the user nothing.
  */
-declare const formatAuthError: (error: any) => string;
+declare const formatAuthError: (error: unknown) => string;
 
 /**
  * Pure auth-guard state resolution.
@@ -1114,15 +1229,27 @@ declare enum AnalyticsCategory {
 }
 type AnalyticsEventType = `${AnalyticsEvent}`;
 type AnalyticsCategoryType = `${AnalyticsCategory}`;
+/**
+ * What an analytics backend can actually carry.
+ *
+ * GA4 and OpenPanel serialise a property to a scalar; an object or a function
+ * arrives as "[object Object]" without erroring anywhere. Declaring the wider
+ * `unknown` here promised a forwarding guarantee no implementation keeps, and
+ * it made this sink incompatible with `AnalyticsEventProperties` in
+ * `@djangocfg/analytics` — the two describe the same channel and must agree.
+ * Kept as a local declaration rather than an import: `api` does not depend on
+ * `analytics`, and one shared four-member union is not worth that edge.
+ */
+type AnalyticsPropertyValue = string | number | boolean | null;
 interface AnalyticsEventParams {
     category?: AnalyticsCategoryType;
     label?: string;
     value?: number;
-    [key: string]: any;
+    [key: string]: AnalyticsPropertyValue | undefined;
 }
 /** What an analytics implementation must provide to receive auth events. */
 interface AnalyticsSink {
-    event(name: string, params?: Record<string, any>): void;
+    event(name: string, params?: Record<string, AnalyticsPropertyValue | undefined>): void;
     setUser(userId: string | null): void;
 }
 /**