@djangocfg/api 2.1.333 → 2.1.335

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.
@@ -35,7 +45,27 @@ declare const auth: {
     setBaseUrl(url: string | null): void;
     getWithCredentials(): boolean;
     setWithCredentials(value: boolean): void;
+    /**
+     * 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 {
@@ -123,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 {
@@ -1386,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 {
@@ -1423,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.
@@ -35,7 +45,27 @@ declare const auth: {
     setBaseUrl(url: string | null): void;
     getWithCredentials(): boolean;
     setWithCredentials(value: boolean): void;
+    /**
+     * 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 {
@@ -123,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 {
@@ -1386,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 {
@@ -1423,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.mjs

@@ -93,6 +93,9 @@ var _apiKeyOverride = null;
 var _baseUrlOverride = null;
 var _withCredentials = true;
 var _onUnauthorized = null;
+var _refreshHandler = null;
+var _refreshInflight = null;
+var RETRY_MARKER = "X-Auth-Retry";
 var _client = null;
 function pushClientConfig() {
   if (!_client) return;
@@ -171,10 +174,53 @@ var auth = {
     pushClientConfig();
   },
   // ── 401 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) {
     _onUnauthorized = cb;
+  },
+  /**
+   * 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 = fn;
   }
 };
+async function tryRefresh() {
+  if (_refreshInflight) return _refreshInflight;
+  if (!_refreshHandler) return null;
+  const refresh = auth.getRefreshToken();
+  if (!refresh) return null;
+  _refreshInflight = (async () => {
+    try {
+      const result = await _refreshHandler(refresh);
+      if (!result?.access) return null;
+      auth.setToken(result.access);
+      if (result.refresh) auth.setRefreshToken(result.refresh);
+      return result.access;
+    } catch {
+      return null;
+    } finally {
+      _refreshInflight = null;
+    }
+  })();
+  return _refreshInflight;
+}
+__name(tryRefresh, "tryRefresh");
 function installAuthOnClient(client2) {
   if (_client) return;
   _client = client2;
@@ -191,14 +237,48 @@ function installAuthOnClient(client2) {
     if (apiKey) request.headers.set("X-API-Key", apiKey);
     return request;
   });
-  client2.interceptors.response.use((response) => {
-    if (response.status === 401 && _onUnauthorized) {
-      try {
-        _onUnauthorized(response);
-      } catch {
+  client2.interceptors.response.use(async (response, request) => {
+    if (response.status !== 401) return response;
+    if (request.headers.get(RETRY_MARKER)) {
+      if (_onUnauthorized) {
+        try {
+          _onUnauthorized(response);
+        } catch {
+        }
+      }
+      return response;
+    }
+    const newToken = await tryRefresh();
+    if (!newToken) {
+      if (_onUnauthorized) {
+        try {
+          _onUnauthorized(response);
+        } catch {
+        }
+      }
+      return response;
+    }
+    const retry = request.clone();
+    retry.headers.set("Authorization", `Bearer ${newToken}`);
+    retry.headers.set(RETRY_MARKER, "1");
+    try {
+      const retried = await fetch(retry);
+      if (retried.status === 401 && _onUnauthorized) {
+        try {
+          _onUnauthorized(retried);
+        } catch {
+        }
+      }
+      return retried;
+    } catch {
+      if (_onUnauthorized) {
+        try {
+          _onUnauthorized(response);
+        } catch {
+        }
       }
+      return response;
     }
-    return response;
   });
 }
 __name(installAuthOnClient, "installAuthOnClient");
@@ -349,6 +429,15 @@ var API = class {
   setApiKey(key) {
     auth.setApiKey(key);
   }
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb) {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(fn) {
+    auth.setRefreshHandler(fn);
+  }
 };
 
 // src/_api/generated/helpers/storage.ts
@@ -601,6 +690,15 @@ var API2 = class {
   setApiKey(key) {
     auth.setApiKey(key);
   }
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb) {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(fn) {
+    auth.setRefreshHandler(fn);
+  }
 };
 
 // src/_api/generated/_cfg_totp/api.ts
@@ -655,6 +753,15 @@ var API3 = class {
   setApiKey(key) {
     auth.setApiKey(key);
   }
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb) {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(fn) {
+    auth.setRefreshHandler(fn);
+  }
 };
 
 // src/_api/generated/index.ts