@djangocfg/api 2.1.87 → 2.1.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.87",
+  "version": "2.1.89",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -74,7 +74,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/ui-nextjs": "^2.1.87",
+    "@djangocfg/ui-nextjs": "^2.1.89",
     "consola": "^3.4.2",
     "next": "^14 || ^15",
     "p-retry": "^7.0.0",
@@ -85,7 +85,7 @@
   "devDependencies": {
     "@types/node": "^24.7.2",
     "@types/react": "^19.0.0",
-    "@djangocfg/typescript-config": "^2.1.87",
+    "@djangocfg/typescript-config": "^2.1.89",
     "next": "^15.0.0",
     "react": "^19.0.0",
     "tsup": "^8.5.0",

package/src/auth/context/AccountsContext.tsx

@@ -59,7 +59,7 @@ export interface AccountsContextValue {
   // Profile operations
   updateProfile: (data: UserProfileUpdateRequest) => Promise<User>;
   partialUpdateProfile: (data: PatchedUserProfileUpdateRequest) => Promise<User>;
-  uploadAvatar: (formData: FormData) => Promise<User>;
+  uploadAvatar: (avatar: File | Blob) => Promise<User>;
   refreshProfile: (callerId?: string) => Promise<User | undefined>;
 
   // Authentication
@@ -165,8 +165,8 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
   };
 
   // Upload avatar
-  const uploadAvatar = async (formData: FormData): Promise<User> => {
-    const result = await avatarMutation(formData, apiAccounts);
+  const uploadAvatar = async (avatar: File | Blob): Promise<User> => {
+    const result = await avatarMutation({ avatar }, apiAccounts);
     await refreshProfile('AccountsContext.uploadAvatar');
     return result as User;
   };

package/src/auth/context/AuthContext.tsx

@@ -11,6 +11,7 @@ import { useCfgRouter, useLocalStorage, useQueryParams } from '@djangocfg/ui-nex
 import { api as apiAccounts, Enums } from '../../';
 import { clearProfileCache, getCachedProfile } from '../hooks/useProfileCache';
 import { useAuthRedirectManager } from '../hooks/useAuthRedirect';
+import { useTokenRefresh } from '../hooks/useTokenRefresh';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
 import { authLogger } from '../utils/logger';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
@@ -65,6 +66,18 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   const [storedEmail, setStoredEmail, clearStoredEmail] = useLocalStorage<string | null>(EMAIL_STORAGE_KEY, null);
   const [storedPhone, setStoredPhone, clearStoredPhone] = useLocalStorage<string | null>(PHONE_STORAGE_KEY, null);
 
+  // Automatic token refresh - refreshes token before expiry, on focus, and on network reconnect
+  useTokenRefresh({
+    enabled: true,
+    onRefresh: (newToken) => {
+      authLogger.info('Token auto-refreshed successfully');
+    },
+    onRefreshError: (error) => {
+      authLogger.warn('Token auto-refresh failed:', error.message);
+      // Don't logout on refresh error - user might still have valid session
+    },
+  });
+
   // Map AccountsContext profile to UserProfile
   const user = accounts.profile as UserProfile | null;
 
@@ -95,14 +108,26 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   }, []);
 
   // Global error handler for auth-related errors
+  // Only clears auth on actual authentication errors (401), not on any API error
   const handleGlobalAuthError = useCallback((error: any, context: string = 'API Request') => {
-    // Simple error check - if response has error flag, it's an error
-    if (error?.success === false) {
-      authLogger.warn(`Error detected in ${context}, clearing tokens`);
+    // Only clear auth on actual authentication errors (401)
+    // Don't logout on validation errors, server errors, network issues, etc.
+    const isAuthError = error?.status === 401 ||
+                        error?.statusCode === 401 ||
+                        error?.code === 'token_not_valid' ||
+                        error?.code === 'authentication_failed';
+
+    if (isAuthError) {
+      authLogger.warn(`Authentication error in ${context}, clearing tokens`);
       clearAuthState(`globalAuthError:${context}`);
       return true;
     }
 
+    // Log but don't logout for other errors
+    if (error?.success === false) {
+      authLogger.warn(`Non-auth error in ${context} (not clearing session):`, error?.message || error);
+    }
+
     return false;
   }, [clearAuthState]);
 
@@ -150,11 +175,22 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       // Always mark as initialized if we have valid tokens
       // Don't clear tokens just because profile fetch failed
       setInitialized(true);
-    } catch (error) {
+    } catch (error: any) {
       authLogger.error('Failed to load profile:', error);
-      // Use global error handler first, fallback to clearing state
-      if (!handleGlobalAuthError(error, 'loadCurrentProfile')) {
-        clearAuthState('loadCurrentProfile:error');
+      // Only clear auth state on actual authentication errors (401)
+      // Don't logout on network errors, server errors, etc.
+      const isAuthError = error?.status === 401 ||
+                          error?.statusCode === 401 ||
+                          error?.code === 'token_not_valid' ||
+                          error?.code === 'authentication_failed';
+
+      if (isAuthError) {
+        authLogger.warn('Authentication error, clearing session');
+        clearAuthState('loadCurrentProfile:authError');
+      } else {
+        // Keep tokens, mark as initialized - user can retry
+        authLogger.warn('Profile load failed but keeping session (non-auth error)');
+        setInitialized(true);
       }
     } finally {
       isLoadingProfileRef.current = false;
@@ -214,10 +250,20 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         try {
           authLogger.info('No cached profile found, loading from API...');
           await loadCurrentProfile('AuthContext.initializeAuth');
-        } catch (error) {
+        } catch (error: any) {
           authLogger.error('Failed to load profile during initialization:', error);
-          // If profile loading fails, clear auth state
-          clearAuthState('initializeAuth:loadProfileFailed');
+          // Only clear on 401 auth error, otherwise keep session
+          const isAuthError = error?.status === 401 ||
+                              error?.statusCode === 401 ||
+                              error?.code === 'token_not_valid' ||
+                              error?.code === 'authentication_failed';
+
+          if (isAuthError) {
+            clearAuthState('initializeAuth:authError');
+          } else {
+            authLogger.warn('Init profile load failed but keeping session');
+            setInitialized(true);
+          }
         }
         setIsLoading(false);
       } else {

package/src/auth/hooks/index.ts

@@ -45,3 +45,6 @@ export {
   getCacheMetadata,
   type ProfileCacheOptions,
 } from './useProfileCache';
+
+// Token refresh
+export { useTokenRefresh } from './useTokenRefresh';

package/src/auth/hooks/useProfileCache.ts

@@ -16,7 +16,7 @@ import { decodeBase64, encodeBase64 } from './useBase64';
 // Cache configuration
 const CACHE_KEY = 'user_profile_cache';
 const CACHE_VERSION = 1;
-const DEFAULT_TTL = 3600000; // 1 hour in milliseconds
+const DEFAULT_TTL = 14400000; // 4 hours in milliseconds (reduced API calls, more resilient)
 
 export interface ProfileCacheOptions {
   /** Time to live in milliseconds (default: 1 hour) */

package/src/auth/hooks/useTokenRefresh.ts

@@ -0,0 +1,161 @@
+'use client';
+
+/**
+ * Token Refresh Hook
+ *
+ * Provides automatic token refresh functionality:
+ * - Proactively refreshes token before expiry
+ * - Refreshes on window focus
+ * - Refreshes on network reconnect
+ */
+
+import { useCallback, useEffect, useRef } from 'react';
+import { api as apiAccounts } from '../../';
+import { authLogger } from '../utils/logger';
+
+// Configuration
+const TOKEN_REFRESH_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes before expiry
+const CHECK_INTERVAL_MS = 5 * 60 * 1000; // Check every 5 minutes
+
+interface UseTokenRefreshOptions {
+  /** Enable automatic token refresh (default: true) */
+  enabled?: boolean;
+  /** Callback when token is refreshed */
+  onRefresh?: (newToken: string) => void;
+  /** Callback when refresh fails */
+  onRefreshError?: (error: Error) => void;
+}
+
+/**
+ * Decode JWT and get expiry time
+ */
+function getTokenExpiry(token: string): number | null {
+  try {
+    const payload = JSON.parse(atob(token.split('.')[1]));
+    return payload.exp * 1000; // Convert to milliseconds
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if token is expiring soon
+ */
+function isTokenExpiringSoon(token: string, thresholdMs: number): boolean {
+  const expiry = getTokenExpiry(token);
+  if (!expiry) return false;
+
+  const timeUntilExpiry = expiry - Date.now();
+  return timeUntilExpiry < thresholdMs;
+}
+
+/**
+ * Hook for automatic token refresh
+ */
+export function useTokenRefresh(options: UseTokenRefreshOptions = {}) {
+  const { enabled = true, onRefresh, onRefreshError } = options;
+  const isRefreshingRef = useRef(false);
+
+  /**
+   * Refresh the token
+   */
+  const refreshToken = useCallback(async (): Promise<boolean> => {
+    if (isRefreshingRef.current) {
+      authLogger.debug('Token refresh already in progress');
+      return false;
+    }
+
+    const refreshTokenValue = apiAccounts.getRefreshToken();
+    if (!refreshTokenValue) {
+      authLogger.warn('No refresh token available');
+      return false;
+    }
+
+    isRefreshingRef.current = true;
+    authLogger.info('Refreshing token...');
+
+    try {
+      // Use generated API client with correct URL (/cfg/accounts/token/refresh/)
+      const result = await apiAccounts.auth.accountsTokenRefreshCreate({
+        refresh: refreshTokenValue,
+      });
+
+      const newAccessToken = result.access;
+
+      if (!newAccessToken) {
+        throw new Error('No access token in refresh response');
+      }
+
+      apiAccounts.setToken(newAccessToken, refreshTokenValue);
+      authLogger.info('Token refreshed successfully');
+
+      onRefresh?.(newAccessToken);
+      return true;
+    } catch (error) {
+      authLogger.error('Token refresh error:', error);
+      onRefreshError?.(error instanceof Error ? error : new Error(String(error)));
+      return false;
+    } finally {
+      isRefreshingRef.current = false;
+    }
+  }, [onRefresh, onRefreshError]);
+
+  /**
+   * Check and refresh if needed
+   */
+  const checkAndRefresh = useCallback(async () => {
+    const token = apiAccounts.getToken();
+    if (!token) return;
+
+    if (isTokenExpiringSoon(token, TOKEN_REFRESH_THRESHOLD_MS)) {
+      authLogger.info('Token expiring soon, refreshing proactively');
+      await refreshToken();
+    }
+  }, [refreshToken]);
+
+  // Periodic check
+  useEffect(() => {
+    if (!enabled) return;
+
+    // Check immediately
+    checkAndRefresh();
+
+    // Set up interval
+    const intervalId = setInterval(checkAndRefresh, CHECK_INTERVAL_MS);
+
+    return () => clearInterval(intervalId);
+  }, [enabled, checkAndRefresh]);
+
+  // Refresh on window focus
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleFocus = () => {
+      authLogger.debug('Window focused, checking token...');
+      checkAndRefresh();
+    };
+
+    window.addEventListener('focus', handleFocus);
+    return () => window.removeEventListener('focus', handleFocus);
+  }, [enabled, checkAndRefresh]);
+
+  // Refresh on network reconnect
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleOnline = () => {
+      authLogger.info('Network reconnected, checking token...');
+      checkAndRefresh();
+    };
+
+    window.addEventListener('online', handleOnline);
+    return () => window.removeEventListener('online', handleOnline);
+  }, [enabled, checkAndRefresh]);
+
+  return {
+    refreshToken,
+    checkAndRefresh,
+  };
+}
+
+export default useTokenRefresh;

package/src/auth/middlewares/index.ts

@@ -1 +1,8 @@
-export { proxyMiddleware, proxyMiddlewareConfig } from './proxy'; 
+export { proxyMiddleware, proxyMiddlewareConfig } from './proxy';
+export {
+  refreshAccessToken,
+  createAutoRefreshFetch,
+  isTokenExpiringSoon,
+  refreshIfExpiringSoon,
+  isAuthenticationError,
+} from './tokenRefresh'; 

package/src/auth/middlewares/tokenRefresh.ts

@@ -0,0 +1,158 @@
+/**
+ * Token Auto-Refresh Middleware
+ *
+ * Automatically refreshes access token when receiving 401 responses.
+ * Implements request queuing to prevent multiple simultaneous refresh attempts.
+ */
+
+import { api as apiAccounts } from '../../';
+import { authLogger } from '../utils/logger';
+
+// Refresh state management
+let isRefreshing = false;
+let refreshSubscribers: Array<(token: string | null) => void> = [];
+
+/**
+ * Subscribe to token refresh completion
+ */
+function subscribeTokenRefresh(callback: (token: string | null) => void): void {
+  refreshSubscribers.push(callback);
+}
+
+/**
+ * Notify all subscribers when token is refreshed
+ */
+function onTokenRefreshed(token: string | null): void {
+  refreshSubscribers.forEach(callback => callback(token));
+  refreshSubscribers = [];
+}
+
+/**
+ * Attempt to refresh the access token using the refresh token
+ * @returns New access token or null if refresh failed
+ */
+export async function refreshAccessToken(): Promise<string | null> {
+  // If already refreshing, wait for completion
+  if (isRefreshing) {
+    return new Promise(resolve => {
+      subscribeTokenRefresh(token => resolve(token));
+    });
+  }
+
+  isRefreshing = true;
+  authLogger.info('Starting token refresh...');
+
+  try {
+    const refreshToken = apiAccounts.getRefreshToken();
+    if (!refreshToken) {
+      authLogger.warn('No refresh token available for refresh');
+      onTokenRefreshed(null);
+      return null;
+    }
+
+    // Use generated API client with correct URL (/cfg/accounts/token/refresh/)
+    const result = await apiAccounts.auth.accountsTokenRefreshCreate({
+      refresh: refreshToken,
+    });
+
+    const newAccessToken = result.access;
+
+    if (!newAccessToken) {
+      authLogger.error('Token refresh response missing access token');
+      onTokenRefreshed(null);
+      return null;
+    }
+
+    // Update tokens in storage
+    apiAccounts.setToken(newAccessToken, refreshToken);
+    authLogger.info('Token refreshed successfully');
+
+    onTokenRefreshed(newAccessToken);
+    return newAccessToken;
+  } catch (error) {
+    authLogger.error('Token refresh error:', error);
+    onTokenRefreshed(null);
+    return null;
+  } finally {
+    isRefreshing = false;
+  }
+}
+
+/**
+ * Check if a response indicates an authentication error
+ */
+export function isAuthenticationError(response: Response): boolean {
+  return response.status === 401;
+}
+
+/**
+ * Create a fetch wrapper that automatically refreshes tokens on 401
+ *
+ * @param originalFetch - The original fetch function to wrap
+ * @returns Wrapped fetch function with auto-refresh capability
+ */
+export function createAutoRefreshFetch(originalFetch: typeof fetch): typeof fetch {
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    // Make the initial request
+    let response = await originalFetch(input, init);
+
+    // If 401 and we have a refresh token, try to refresh
+    if (isAuthenticationError(response) && apiAccounts.getRefreshToken()) {
+      authLogger.info('Received 401, attempting token refresh...');
+
+      const newToken = await refreshAccessToken();
+
+      if (newToken) {
+        // Retry the request with new token
+        const newInit: RequestInit = {
+          ...init,
+          headers: {
+            ...init?.headers,
+            Authorization: `Bearer ${newToken}`,
+          },
+        };
+
+        authLogger.info('Retrying request with new token...');
+        response = await originalFetch(input, newInit);
+      } else {
+        authLogger.warn('Token refresh failed, returning original 401 response');
+      }
+    }
+
+    return response;
+  };
+}
+
+/**
+ * Check if token is about to expire (within threshold)
+ * @param thresholdMs - Time in ms before expiry to consider "expiring soon"
+ * @returns true if token expires within threshold
+ */
+export function isTokenExpiringSoon(thresholdMs: number = 5 * 60 * 1000): boolean {
+  const token = apiAccounts.getToken();
+  if (!token) return false;
+
+  try {
+    // Decode JWT payload (base64)
+    const payload = JSON.parse(atob(token.split('.')[1]));
+    const expiresAt = payload.exp * 1000; // Convert to milliseconds
+    const now = Date.now();
+    const timeUntilExpiry = expiresAt - now;
+
+    return timeUntilExpiry < thresholdMs;
+  } catch (error) {
+    authLogger.error('Error checking token expiry:', error);
+    return false;
+  }
+}
+
+/**
+ * Proactively refresh token if it's expiring soon
+ * Call this periodically or before important operations
+ */
+export async function refreshIfExpiringSoon(thresholdMs: number = 5 * 60 * 1000): Promise<void> {
+  if (isTokenExpiringSoon(thresholdMs)) {
+    authLogger.info('Token expiring soon, proactively refreshing...');
+    await refreshAccessToken();
+  }
+}

package/src/generated/cfg_accounts/CLAUDE.md

@@ -12,7 +12,7 @@ python manage.py generate_client --groups cfg_accounts --typescript
 |---|---|
 | Version | 3.0.3 |
 | Operations | 14 |
-| Schemas | 19 |
+| Schemas | 20 |
 
 ## Resources
 
@@ -81,12 +81,5 @@ openapi_client = OpenAPIClientConfig(
 )
 ```
 
-**Copy to Next.js** (if `nextjs_admin` configured):
-```python
-nextjs_admin = NextJsAdminConfig(
-    project_path="../frontend/apps/...",
-    api_output_path="app/_lib/api/generated",
-)
-```
-
 @see https://djangocfg.com/docs/features/api-generation
+

package/src/generated/cfg_accounts/_utils/fetchers/accounts__user_profile.ts

@@ -31,6 +31,7 @@
  * ```
  */
 import { consola } from 'consola'
+import { CfgAccountsProfileAvatarCreateRequestSchema, type CfgAccountsProfileAvatarCreateRequest } from '../schemas/CfgAccountsProfileAvatarCreateRequest.schema'
 import { PatchedUserProfileUpdateRequestSchema, type PatchedUserProfileUpdateRequest } from '../schemas/PatchedUserProfileUpdateRequest.schema'
 import { UserSchema, type User } from '../schemas/User.schema'
 import { UserProfileUpdateRequestSchema, type UserProfileUpdateRequest } from '../schemas/UserProfileUpdateRequest.schema'
@@ -99,7 +100,7 @@ export async function getAccountsProfileRetrieve(  client?: any
  * @method POST
  * @path /cfg/accounts/profile/avatar/
  */
-export async function createAccountsProfileAvatarCreate(  data: any,  client?: any
+export async function createAccountsProfileAvatarCreate(  data: CfgAccountsProfileAvatarCreateRequest,  client?: any
 ): Promise<User> {
   const api = client || getAPIInstance()
   const response = await api.user_profile.accountsProfileAvatarCreate(data)

package/src/generated/cfg_accounts/_utils/hooks/accounts__user_profile.ts

@@ -21,6 +21,7 @@ import useSWR from 'swr'
 import { useSWRConfig } from 'swr'
 import * as Fetchers from '../fetchers/accounts__user_profile'
 import type { API } from '../../index'
+import type { CfgAccountsProfileAvatarCreateRequest } from '../schemas/CfgAccountsProfileAvatarCreateRequest.schema'
 import type { PatchedUserProfileUpdateRequest } from '../schemas/PatchedUserProfileUpdateRequest.schema'
 import type { User } from '../schemas/User.schema'
 import type { UserProfileUpdateRequest } from '../schemas/UserProfileUpdateRequest.schema'
@@ -48,7 +49,7 @@ export function useAccountsProfileRetrieve(client?: API): ReturnType<typeof useS
 export function useCreateAccountsProfileAvatarCreate() {
   const { mutate } = useSWRConfig()
 
-  return async (data: any, client?: API): Promise<User> => {
+  return async (data: CfgAccountsProfileAvatarCreateRequest, client?: API): Promise<User> => {
     const result = await Fetchers.createAccountsProfileAvatarCreate(data, client)
     // Revalidate related queries
     mutate('cfg-accounts-profile-avatar')

package/src/generated/cfg_accounts/_utils/schemas/CfgAccountsProfileAvatarCreateRequest.schema.ts

@@ -0,0 +1,15 @@
+/**
+ * Zod schema for CfgAccountsProfileAvatarCreateRequest
+ *
+ * This schema provides runtime validation and type inference.
+ *  */
+import { z } from 'zod'
+
+export const CfgAccountsProfileAvatarCreateRequestSchema = z.object({
+  avatar: z.union([z.instanceof(File), z.instanceof(Blob)]),
+})
+
+/**
+ * Infer TypeScript type from Zod schema
+ */
+export type CfgAccountsProfileAvatarCreateRequest = z.infer<typeof CfgAccountsProfileAvatarCreateRequestSchema>

package/src/generated/cfg_accounts/_utils/schemas/index.ts

@@ -18,6 +18,7 @@
  */
 
 export * from './CentrifugoToken.schema'
+export * from './CfgAccountsProfileAvatarCreateRequest.schema'
 export * from './OAuthAuthorizeRequestRequest.schema'
 export * from './OAuthAuthorizeResponse.schema'
 export * from './OAuthCallbackRequestRequest.schema'

package/src/generated/cfg_accounts/accounts/models.ts

@@ -104,7 +104,6 @@ export interface User {
   is_superuser: boolean;
   date_joined: string;
   last_login?: string | null;
-  /** Get count of unanswered messages for the user. */
   unanswered_messages_count: number;
   centrifugo: CentrifugoToken | null;
 }

package/src/generated/cfg_accounts/accounts__user_profile/client.ts

@@ -27,8 +27,10 @@ export class UserProfile {
    * Upload avatar image for the current authenticated user. Accepts
    * multipart/form-data with 'avatar' field.
    */
-  async accountsProfileAvatarCreate(data: FormData): Promise<Models.User> {
-    const response = await this.client.request('POST', "/cfg/accounts/profile/avatar/", { formData: data });
+  async accountsProfileAvatarCreate(data: Models.CfgAccountsProfileAvatarCreateRequest): Promise<Models.User> {
+    const formData = new FormData();
+    formData.append('avatar', data.avatar);
+    const response = await this.client.request('POST', "/cfg/accounts/profile/avatar/", { formData });
     return response;
   }
 

package/src/generated/cfg_accounts/accounts__user_profile/models.ts

@@ -25,11 +25,19 @@ export interface User {
   is_superuser: boolean;
   date_joined: string;
   last_login?: string | null;
-  /** Get count of unanswered messages for the user. */
   unanswered_messages_count: number;
   centrifugo: CentrifugoToken | null;
 }
 
+/**
+ * 
+ * Request model (no read-only fields).
+ */
+export interface CfgAccountsProfileAvatarCreateRequest {
+  /** Avatar image file (JPEG, PNG, GIF, WebP, max 5MB) */
+  avatar: File | Blob;
+}
+
 /**
  * Serializer for updating user profile.
  * 

package/src/generated/cfg_accounts/client.ts

@@ -28,6 +28,7 @@ export class APIClient {
   private httpClient: HttpClientAdapter;
   private logger: APILogger | null = null;
   private retryConfig: RetryConfig | null = null;
+  private tokenGetter: (() => string | null) | null = null;
 
   // Sub-clients
   public auth: Auth;
@@ -41,10 +42,12 @@ export class APIClient {
       httpClient?: HttpClientAdapter;
       loggerConfig?: Partial<LoggerConfig>;
       retryConfig?: RetryConfig;
+      tokenGetter?: () => string | null;
     }
   ) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.httpClient = options?.httpClient || new FetchAdapter();
+    this.tokenGetter = options?.tokenGetter || null;
 
     // Initialize logger if config provided
     if (options?.loggerConfig !== undefined) {
@@ -78,6 +81,21 @@ export class APIClient {
     return null;
   }
 
+  /**
+   * Get the base URL for building streaming/download URLs.
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  /**
+   * Get JWT token for URL authentication (used in streaming endpoints).
+   * Returns null if no token getter is configured or no token is available.
+   */
+  getToken(): string | null {
+    return this.tokenGetter ? this.tokenGetter() : null;
+  }
+
   /**
    * Make HTTP request with Django CSRF and session handling.
    * Automatically retries on network errors and 5xx server errors.