@djangocfg/api 2.1.332 → 2.1.334

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.332",
+  "version": "2.1.334",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -79,7 +79,7 @@
   "devDependencies": {
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
-    "@djangocfg/typescript-config": "^2.1.332",
+    "@djangocfg/typescript-config": "^2.1.334",
     "next": "^16.2.2",
     "react": "^19.1.0",
     "tsup": "^8.5.0",

package/src/_api/generated/_cfg_accounts/api.ts

@@ -61,6 +61,18 @@ export class API {
   setLocale(locale: string | null): void { auth.setLocale(locale); }
   getApiKey(): string | null { return auth.getApiKey(); }
   setApiKey(key: string | null): void { auth.setApiKey(key); }
+
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb: ((response: Response) => void) | null): void {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(
+    fn: ((refreshToken: string) => Promise<{ access: string; refresh?: string } | null>) | null,
+  ): void {
+    auth.setRefreshHandler(fn);
+  }
 }
 
 export {  };

package/src/_api/generated/_cfg_centrifugo/api.ts

@@ -61,6 +61,18 @@ export class API {
   setLocale(locale: string | null): void { auth.setLocale(locale); }
   getApiKey(): string | null { return auth.getApiKey(); }
   setApiKey(key: string | null): void { auth.setApiKey(key); }
+
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb: ((response: Response) => void) | null): void {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(
+    fn: ((refreshToken: string) => Promise<{ access: string; refresh?: string } | null>) | null,
+  ): void {
+    auth.setRefreshHandler(fn);
+  }
 }
 
 export {  };

package/src/_api/generated/_cfg_totp/api.ts

@@ -61,6 +61,18 @@ export class API {
   setLocale(locale: string | null): void { auth.setLocale(locale); }
   getApiKey(): string | null { return auth.getApiKey(); }
   setApiKey(key: string | null): void { auth.setApiKey(key); }
+
+  // ── 401 handling ────────────────────────────────────────────────────────
+  /** Fired only on terminal 401 (after refresh+retry path is exhausted). */
+  onUnauthorized(cb: ((response: Response) => void) | null): void {
+    auth.onUnauthorized(cb);
+  }
+  /** Provide a refresh strategy. See `auth.setRefreshHandler` for the contract. */
+  setRefreshHandler(
+    fn: ((refreshToken: string) => Promise<{ access: string; refresh?: string } | null>) | null,
+  ): void {
+    auth.setRefreshHandler(fn);
+  }
 }
 
 export {  };

package/src/_api/generated/client.gen.ts

@@ -15,5 +15,6 @@ export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (over
 
 export const client = createClient(createConfig<ClientOptions2>({ baseUrl: 'http://localhost:8000' }));
 
-// auto-init: load auth interceptor
-import './helpers/auth';
+// auto-init: install auth on client
+import { installAuthOnClient } from './helpers/auth';
+installAuthOnClient(client);

package/src/_api/generated/helpers/auth.ts

@@ -1,10 +1,9 @@
 // AUTO-GENERATED by django_generator / ts_extras.wrapper
-// Global auth store. ONE source of truth for token / API key / locale /
-// baseUrl. Installs the request interceptor as a side-effect on import.
+// Global auth store. Wired into the shared `client` from `client.gen.ts`
+// via `installAuthOnClient(client)` — called synchronously by the
+// post-processed bottom of client.gen.ts. No circular import here.
 // DO NOT EDIT — re-run `make gen`.
 
-import { client } from '../client.gen';
-
 const ACCESS_KEY = 'cfg.access_token';
 const REFRESH_KEY = 'cfg.refresh_token';
 const API_KEY_KEY = 'cfg.api_key';
@@ -106,6 +105,45 @@ let _baseUrlOverride: string | null = null;
 let _withCredentials = true;
 let _onUnauthorized: ((response: Response) => void) | null = null;
 
+/**
+ * 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>;
+let _refreshHandler: RefreshHandler | null = null;
+
+/** Single-flight: every concurrent 401 awaits the same refresh. */
+let _refreshInflight: Promise<string | null> | null = null;
+
+/** Marker header — set on retried requests so we never loop on 401. */
+const RETRY_MARKER = 'X-Auth-Retry';
+
+/**
+ * Captured reference to the shared Hey API client. Set exactly once by
+ * `installAuthOnClient(client)` (called from client.gen.ts). All `auth.set*`
+ * methods that mutate transport config (baseUrl / credentials) push through
+ * this reference. Until installed, those mutations are silently buffered as
+ * in-memory state — the next request after install will pick them up.
+ */
+type HeyClient = {
+  setConfig(opts: Record<string, unknown>): void;
+  interceptors: {
+    request: { use(fn: (req: Request) => Request | Promise<Request>): void };
+    response: { use(fn: (res: Response, req: Request) => Response | Promise<Response>): void };
+  };
+};
+let _client: HeyClient | null = null;
+
+function pushClientConfig(): void {
+  if (!_client) return;
+  _client.setConfig({
+    baseUrl: auth.getBaseUrl(),
+    credentials: _withCredentials ? 'include' : 'same-origin',
+  });
+}
+
 /**
  * Global auth/config store. All getters read live state every call —
  * the interceptor below uses these to attach headers per-request.
@@ -116,24 +154,13 @@ let _onUnauthorized: ((response: Response) => void) | null = null;
  *
  * @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');
  */
 export const auth = {
   // ── Storage mode ──────────────────────────────────────────────────
   getStorageMode(): StorageMode { return _storageMode; },
-  /**
-   * Switch the storage backend. Existing values in the *previous*
-   * backend are NOT migrated — set fresh values after switching.
-   */
   setStorageMode(mode: StorageMode): void {
     _storageMode = mode;
     _storage = mode === 'cookie' ? cookieBackend : localStorageBackend;
@@ -148,13 +175,10 @@ export const auth = {
   isAuthenticated(): boolean { return _storage.get(ACCESS_KEY) !== null; },
 
   // ── API key ───────────────────────────────────────────────────────
-  /** In-memory API key. Falls back to storage, then NEXT_PUBLIC_API_KEY. */
   getApiKey(): string | null {
     return _apiKeyOverride ?? _storage.get(API_KEY_KEY) ?? defaultApiKey();
   },
-  /** In-memory only (cleared on reload). */
   setApiKey(key: string | null): void { _apiKeyOverride = key; },
-  /** Persist to active storage backend (localStorage or cookie). */
   setApiKeyPersist(key: string | null): void {
     _apiKeyOverride = key;
     _storage.set(API_KEY_KEY, key);
@@ -162,7 +186,6 @@ export const auth = {
   clearApiKey(): void { _apiKeyOverride = null; _storage.set(API_KEY_KEY, null); },
 
   // ── Locale ────────────────────────────────────────────────────────
-  /** Override locale → falls back to NEXT_LOCALE cookie / navigator.language. */
   getLocale(): string | null { return _localeOverride ?? detectLocale(); },
   setLocale(locale: string | null): void { _localeOverride = locale; },
 
@@ -173,51 +196,144 @@ export const auth = {
   },
   setBaseUrl(url: string | null): void {
     _baseUrlOverride = url ? url.replace(/\/$/, '') : null;
-    client.setConfig({ baseUrl: this.getBaseUrl() });
+    pushClientConfig();
   },
 
-  // ── Credentials toggle (Django session/CSRF cross-origin) ─────────
+  // ── Credentials toggle ────────────────────────────────────────────
   getWithCredentials(): boolean { return _withCredentials; },
   setWithCredentials(value: boolean): void {
     _withCredentials = value;
-    client.setConfig({ credentials: value ? 'include' : 'same-origin' });
+    pushClientConfig();
   },
 
   // ── 401 handler ───────────────────────────────────────────────────
   /**
-   * 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 {
     _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 | null): void {
+    _refreshHandler = fn;
+  },
 };
 
-// ── One-time client wiring (side-effect on first import) ───────────────────
-client.setConfig({
-  baseUrl: auth.getBaseUrl(),
-  credentials: _withCredentials ? 'include' : 'same-origin',
-});
+/**
+ * Run the user-supplied refresh handler under single-flight, persist
+ * the new tokens, and return the fresh access token (or null on any
+ * failure path). All concurrent 401s share the same in-flight promise.
+ */
+async function tryRefresh(): Promise<string | null> {
+  if (_refreshInflight) return _refreshInflight;
+  if (!_refreshHandler) return null;
+  const refresh = auth.getRefreshToken();
+  if (!refresh) return null;
 
-client.interceptors.request.use((request) => {
-  const token = auth.getToken();
-  if (token) request.headers.set('Authorization', `Bearer ${token}`);
+  _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;
+}
+
+/**
+ * Wire the shared client to the global auth store. Called exactly
+ * once from `client.gen.ts` (post-processed) right after
+ * `createClient()`. Synchronous — no microtask, no TDZ races.
+ *
+ * Safe to call from server / SSR: storage backends short-circuit on
+ * non-browser environments, so headers populated by the interceptor
+ * are simply absent server-side (which is the correct behaviour
+ * unless the caller explicitly sets a server-side token).
+ */
+export function installAuthOnClient(client: HeyClient): void {
+  if (_client) return; // idempotent
+  _client = client;
+
+  client.setConfig({
+    baseUrl: auth.getBaseUrl(),
+    credentials: _withCredentials ? 'include' : 'same-origin',
+  });
+
+  client.interceptors.request.use((request) => {
+    const token = auth.getToken();
+    if (token) request.headers.set('Authorization', `Bearer ${token}`);
+
+    const locale = auth.getLocale();
+    if (locale) request.headers.set('Accept-Language', locale);
 
-  const locale = auth.getLocale();
-  if (locale) request.headers.set('Accept-Language', locale);
+    const apiKey = auth.getApiKey();
+    if (apiKey) request.headers.set('X-API-Key', apiKey);
 
-  const apiKey = auth.getApiKey();
-  if (apiKey) request.headers.set('X-API-Key', apiKey);
+    return request;
+  });
 
-  return request;
-});
+  client.interceptors.response.use(async (response, request) => {
+    if (response.status !== 401) return response;
 
-client.interceptors.response.use((response) => {
-  if (response.status === 401 && _onUnauthorized) {
-    try { _onUnauthorized(response); } catch {}
-  }
-  return response;
-});
+    // Already retried once — give up to avoid loops.
+    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;
+    }
+
+    // Retry the original request once with the new token. We mutate a
+    // clone so the original Request body (already consumed by the
+    // failed call) doesn't trip "body already used".
+    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 {
+      // Network error on retry — surface the original 401.
+      if (_onUnauthorized) {
+        try { _onUnauthorized(response); } catch {}
+      }
+      return response;
+    }
+  });
+}
 
 export type Auth = typeof auth;