@djangocfg/api 2.1.332 → 2.1.334

package/dist/index.d.cts

@@ -2,6 +2,16 @@ import { ConsolaInstance } from 'consola';
 import { ZodError } from 'zod';
 
 type StorageMode = 'localStorage' | 'cookie';
+/**
+ * User-supplied refresh handler. Receives the current refresh token,
+ * must return a fresh access (and optional refresh) pair or null on failure.
+ * Set once at app bootstrap via `auth.setRefreshHandler(...)`.
+ */
+type RefreshResult = {
+    access: string;
+    refresh?: string;
+} | null;
+type RefreshHandler = (refreshToken: string) => Promise<RefreshResult>;
 /**
  * Global auth/config store. All getters read live state every call —
  * the interceptor below uses these to attach headers per-request.
@@ -12,23 +22,12 @@ type StorageMode = 'localStorage' | 'cookie';
  *
  * @example
  *   import { auth } from '@your/api';
- *
- *   // After login
  *   auth.setToken(jwt);
- *   auth.setRefreshToken(refresh);
- *
- *   // After logout
  *   auth.clearTokens();
- *
- *   // Switch to cookie storage (call once during app init)
  *   auth.setStorageMode('cookie');
  */
 declare const auth: {
     getStorageMode(): StorageMode;
-    /**
-     * Switch the storage backend. Existing values in the *previous*
-     * backend are NOT migrated — set fresh values after switching.
-     */
     setStorageMode(mode: StorageMode): void;
     getToken(): string | null;
     setToken(token: string | null): void;
@@ -36,14 +35,10 @@ declare const auth: {
     setRefreshToken(token: string | null): void;
     clearTokens(): void;
     isAuthenticated(): boolean;
-    /** In-memory API key. Falls back to storage, then NEXT_PUBLIC_API_KEY. */
     getApiKey(): string | null;
-    /** In-memory only (cleared on reload). */
     setApiKey(key: string | null): void;
-    /** Persist to active storage backend (localStorage or cookie). */
     setApiKeyPersist(key: string | null): void;
     clearApiKey(): void;
-    /** Override locale → falls back to NEXT_LOCALE cookie / navigator.language. */
     getLocale(): string | null;
     setLocale(locale: string | null): void;
     getBaseUrl(): string;
@@ -51,11 +46,26 @@ declare const auth: {
     getWithCredentials(): boolean;
     setWithCredentials(value: boolean): void;
     /**
-     * Register a callback fired on every 401 response. Use this to wire
-     * a token-refresh flow or a forced logout. Setting `null` removes
-     * the handler.
+     * Fired when the server returns 401 AND no refresh path recovers it
+     * (no refresh token, no refresh handler, refresh failed, or retry
+     * still 401). The app should clear local state and redirect to login.
+     *
+     * NOT fired for 401 that gets transparently recovered by the refresh
+     * handler — those are invisible to callers.
      */
     onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /**
+     * Register the refresh strategy. The handler receives the current
+     * refresh token and must call your refresh endpoint, returning
+     * `{ access, refresh? }` on success or `null` on failure.
+     *
+     * @example
+     *   auth.setRefreshHandler(async (refresh) => {
+     *     const { data } = await Auth.tokenRefreshCreate({ body: { refresh } });
+     *     return data ? { access: data.access, refresh: data.refresh } : null;
+     *   });
+     */
+    setRefreshHandler(fn: RefreshHandler | null): void;
 };
 
 interface RequestLog {
@@ -143,6 +153,13 @@ declare class API$2 {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 interface StorageAdapter {
@@ -1406,6 +1423,13 @@ declare class API$1 {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 interface APIOptions {
@@ -1443,6 +1467,13 @@ declare class API {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 declare const CfgAccountsApi: API$2;

package/dist/index.d.ts

@@ -2,6 +2,16 @@ import { ConsolaInstance } from 'consola';
 import { ZodError } from 'zod';
 
 type StorageMode = 'localStorage' | 'cookie';
+/**
+ * User-supplied refresh handler. Receives the current refresh token,
+ * must return a fresh access (and optional refresh) pair or null on failure.
+ * Set once at app bootstrap via `auth.setRefreshHandler(...)`.
+ */
+type RefreshResult = {
+    access: string;
+    refresh?: string;
+} | null;
+type RefreshHandler = (refreshToken: string) => Promise<RefreshResult>;
 /**
  * Global auth/config store. All getters read live state every call —
  * the interceptor below uses these to attach headers per-request.
@@ -12,23 +22,12 @@ type StorageMode = 'localStorage' | 'cookie';
  *
  * @example
  *   import { auth } from '@your/api';
- *
- *   // After login
  *   auth.setToken(jwt);
- *   auth.setRefreshToken(refresh);
- *
- *   // After logout
  *   auth.clearTokens();
- *
- *   // Switch to cookie storage (call once during app init)
  *   auth.setStorageMode('cookie');
  */
 declare const auth: {
     getStorageMode(): StorageMode;
-    /**
-     * Switch the storage backend. Existing values in the *previous*
-     * backend are NOT migrated — set fresh values after switching.
-     */
     setStorageMode(mode: StorageMode): void;
     getToken(): string | null;
     setToken(token: string | null): void;
@@ -36,14 +35,10 @@ declare const auth: {
     setRefreshToken(token: string | null): void;
     clearTokens(): void;
     isAuthenticated(): boolean;
-    /** In-memory API key. Falls back to storage, then NEXT_PUBLIC_API_KEY. */
     getApiKey(): string | null;
-    /** In-memory only (cleared on reload). */
     setApiKey(key: string | null): void;
-    /** Persist to active storage backend (localStorage or cookie). */
     setApiKeyPersist(key: string | null): void;
     clearApiKey(): void;
-    /** Override locale → falls back to NEXT_LOCALE cookie / navigator.language. */
     getLocale(): string | null;
     setLocale(locale: string | null): void;
     getBaseUrl(): string;
@@ -51,11 +46,26 @@ declare const auth: {
     getWithCredentials(): boolean;
     setWithCredentials(value: boolean): void;
     /**
-     * Register a callback fired on every 401 response. Use this to wire
-     * a token-refresh flow or a forced logout. Setting `null` removes
-     * the handler.
+     * Fired when the server returns 401 AND no refresh path recovers it
+     * (no refresh token, no refresh handler, refresh failed, or retry
+     * still 401). The app should clear local state and redirect to login.
+     *
+     * NOT fired for 401 that gets transparently recovered by the refresh
+     * handler — those are invisible to callers.
      */
     onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /**
+     * Register the refresh strategy. The handler receives the current
+     * refresh token and must call your refresh endpoint, returning
+     * `{ access, refresh? }` on success or `null` on failure.
+     *
+     * @example
+     *   auth.setRefreshHandler(async (refresh) => {
+     *     const { data } = await Auth.tokenRefreshCreate({ body: { refresh } });
+     *     return data ? { access: data.access, refresh: data.refresh } : null;
+     *   });
+     */
+    setRefreshHandler(fn: RefreshHandler | null): void;
 };
 
 interface RequestLog {
@@ -143,6 +153,13 @@ declare class API$2 {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 interface StorageAdapter {
@@ -1406,6 +1423,13 @@ declare class API$1 {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 interface APIOptions {
@@ -1443,6 +1467,13 @@ declare class API {
     setLocale(locale: string | null): void;
     getApiKey(): string | null;
     setApiKey(key: string | null): void;
+    /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+    onUnauthorized(cb: ((response: Response) => void) | null): void;
+    /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+    setRefreshHandler(fn: ((refreshToken: string) => Promise<{
+        access: string;
+        refresh?: string;
+    } | null>) | null): void;
 }
 
 declare const CfgAccountsApi: API$2;