@djangocfg/api 2.1.322 → 2.1.327

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.322",
+  "version": "2.1.327",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -40,11 +40,6 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
-    "./hooks": {
-      "types": "./dist/hooks.d.ts",
-      "import": "./dist/hooks.mjs",
-      "require": "./dist/hooks.cjs"
-    },
     "./auth": {
       "types": "./dist/auth.d.ts",
       "import": "./dist/auth.mjs",
@@ -84,7 +79,7 @@
   "devDependencies": {
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
-    "@djangocfg/typescript-config": "^2.1.322",
+    "@djangocfg/typescript-config": "^2.1.327",
     "next": "^16.2.2",
     "react": "^19.1.0",
     "tsup": "^8.5.0",

package/src/_api/generated/_shared/errors.ts

@@ -0,0 +1,70 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Typed error classes with DRF field-error support.
+// DO NOT EDIT — re-run `make gen`.
+
+/**
+ * HTTP API Error with DRF field-specific validation errors.
+ */
+export class APIError extends Error {
+  constructor(
+    public statusCode: number,
+    public statusText: string,
+    public response: any,
+    public url: string,
+    message?: string,
+  ) {
+    super(message || `HTTP ${statusCode}: ${statusText}`);
+    this.name = "APIError";
+  }
+
+  get details(): Record<string, any> | null {
+    if (typeof this.response === "object" && this.response !== null) {
+      return this.response;
+    }
+    return null;
+  }
+
+  get fieldErrors(): Record<string, string[]> | null {
+    const details = this.details;
+    if (!details) return null;
+    const fieldErrors: Record<string, string[]> = {};
+    for (const [key, value] of Object.entries(details)) {
+      if (Array.isArray(value)) fieldErrors[key] = value;
+    }
+    return Object.keys(fieldErrors).length > 0 ? fieldErrors : null;
+  }
+
+  get errorMessage(): string {
+    const details = this.details;
+    if (!details) return this.message;
+    if (details.detail) {
+      return Array.isArray(details.detail) ? details.detail.join(", ") : String(details.detail);
+    }
+    if (details.error) return String(details.error);
+    if (details.message) return String(details.message);
+    const fieldErrors = this.fieldErrors;
+    if (fieldErrors) {
+      const firstField = Object.keys(fieldErrors)[0];
+      if (firstField) return `${firstField}: ${fieldErrors[firstField]?.join(", ")}`;
+    }
+    return this.message;
+  }
+
+  get isValidationError(): boolean { return this.statusCode === 400; }
+  get isAuthError(): boolean { return this.statusCode === 401; }
+  get isPermissionError(): boolean { return this.statusCode === 403; }
+  get isNotFoundError(): boolean { return this.statusCode === 404; }
+  get isServerError(): boolean { return this.statusCode >= 500 && this.statusCode < 600; }
+}
+
+/** Network Error (connection failed, timeout, etc.) */
+export class NetworkError extends Error {
+  constructor(
+    message: string,
+    public url: string,
+    public originalError?: Error,
+  ) {
+    super(message);
+    this.name = "NetworkError";
+  }
+}

package/src/_api/generated/_shared/index.ts

@@ -0,0 +1,25 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Shared utilities barrel. DO NOT EDIT — re-run `make gen`.
+
+export {
+  type StorageAdapter,
+  LocalStorageAdapter,
+  MemoryStorageAdapter,
+  CookieStorageAdapter,
+} from './storage';
+export { APIError, NetworkError } from './errors';
+export {
+  APILogger,
+  defaultLogger,
+  type LoggerConfig,
+  type RequestLog,
+  type ResponseLog,
+  type ErrorLog,
+} from './logger';
+export {
+  dispatchValidationError,
+  onValidationError,
+  formatZodError,
+  type ValidationErrorDetail,
+  type ValidationErrorEvent,
+} from './validation-events';

package/src/_api/generated/_shared/logger.ts

@@ -0,0 +1,123 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// API logger built on consola. Optional dependency — install if you enable logging:
+//   npm install consola
+// DO NOT EDIT — re-run `make gen`.
+
+import { type ConsolaInstance, createConsola } from "consola";
+
+export interface RequestLog {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: any;
+  timestamp: number;
+}
+
+export interface ResponseLog {
+  status: number;
+  statusText: string;
+  data?: any;
+  duration: number;
+  timestamp: number;
+}
+
+export interface ErrorLog {
+  message: string;
+  statusCode?: number;
+  fieldErrors?: Record<string, string[]>;
+  duration: number;
+  timestamp: number;
+}
+
+export interface LoggerConfig {
+  enabled: boolean;
+  logRequests: boolean;
+  logResponses: boolean;
+  logErrors: boolean;
+  logBodies: boolean;
+  logHeaders: boolean;
+  consola?: ConsolaInstance;
+}
+
+const DEFAULT_CONFIG: LoggerConfig = {
+  enabled: typeof process !== "undefined" && process.env?.NODE_ENV !== "production",
+  logRequests: true,
+  logResponses: true,
+  logErrors: true,
+  logBodies: true,
+  logHeaders: false,
+};
+
+const SENSITIVE_HEADERS = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-csrf-token",
+];
+
+export class APILogger {
+  private config: LoggerConfig;
+  private consola: ConsolaInstance;
+
+  constructor(config: Partial<LoggerConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.consola = config.consola || createConsola({
+      level: this.config.enabled ? 4 : 0,
+    });
+  }
+
+  enable(): void { this.config.enabled = true; }
+  disable(): void { this.config.enabled = false; }
+  setConfig(config: Partial<LoggerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  private filterHeaders(headers?: Record<string, string>): Record<string, string> {
+    if (!headers) return {};
+    const filtered: Record<string, string> = {};
+    Object.keys(headers).forEach((key) => {
+      filtered[key] = SENSITIVE_HEADERS.includes(key.toLowerCase()) ? "***" : (headers[key] || "");
+    });
+    return filtered;
+  }
+
+  logRequest(request: RequestLog): void {
+    if (!this.config.enabled || !this.config.logRequests) return;
+    const { method, url, headers, body } = request;
+    this.consola.start(`${method} ${url}`);
+    if (this.config.logHeaders && headers) this.consola.debug("Headers:", this.filterHeaders(headers));
+    if (this.config.logBodies && body) this.consola.debug("Body:", body);
+  }
+
+  logResponse(request: RequestLog, response: ResponseLog): void {
+    if (!this.config.enabled || !this.config.logResponses) return;
+    const { method, url } = request;
+    const { status, statusText, data, duration } = response;
+    this.consola.success(`${method} ${url} ${status} ${statusText} (${duration}ms)`);
+    if (this.config.logBodies && data) this.consola.debug("Response:", data);
+  }
+
+  logError(request: RequestLog, error: ErrorLog): void {
+    if (!this.config.enabled || !this.config.logErrors) return;
+    const { method, url } = request;
+    const { message, statusCode, fieldErrors, duration } = error;
+    this.consola.error(`${method} ${url} ${statusCode || "Network"} Error (${duration}ms)`);
+    this.consola.error("Message:", message);
+    if (fieldErrors && Object.keys(fieldErrors).length > 0) {
+      this.consola.error("Field Errors:");
+      Object.entries(fieldErrors).forEach(([field, errors]) => {
+        errors.forEach((err) => this.consola.error(`  • ${field}: ${err}`));
+      });
+    }
+  }
+
+  info(message: string, ...args: any[]): void { if (this.config.enabled) this.consola.info(message, ...args); }
+  warn(message: string, ...args: any[]): void { if (this.config.enabled) this.consola.warn(message, ...args); }
+  error(message: string, ...args: any[]): void { if (this.config.enabled) this.consola.error(message, ...args); }
+  debug(message: string, ...args: any[]): void { if (this.config.enabled) this.consola.debug(message, ...args); }
+  success(message: string, ...args: any[]): void { if (this.config.enabled) this.consola.success(message, ...args); }
+  withTag(tag: string): ConsolaInstance { return this.consola.withTag(tag); }
+}
+
+export const defaultLogger = new APILogger();

package/src/_api/generated/_shared/storage.ts

@@ -0,0 +1,83 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Storage adapters for token persistence.
+// DO NOT EDIT — re-run `make gen`.
+
+export interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear?(): void;
+}
+
+/** Browser localStorage. Falls back to no-op on SSR / private mode. */
+export class LocalStorageAdapter implements StorageAdapter {
+  getItem(key: string): string | null {
+    if (typeof window === "undefined") return null;
+    try { return window.localStorage.getItem(key); } catch { return null; }
+  }
+  setItem(key: string, value: string): void {
+    if (typeof window === "undefined") return;
+    try { window.localStorage.setItem(key, value); } catch { /* quota / private */ }
+  }
+  removeItem(key: string): void {
+    if (typeof window === "undefined") return;
+    try { window.localStorage.removeItem(key); } catch { /* ignore */ }
+  }
+  clear(): void {
+    if (typeof window === "undefined") return;
+    try { window.localStorage.clear(); } catch { /* ignore */ }
+  }
+}
+
+/** In-memory store. Use for SSR, Electron main process, or tests. */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private store = new Map<string, string>();
+  getItem(key: string): string | null { return this.store.get(key) ?? null; }
+  setItem(key: string, value: string): void { this.store.set(key, value); }
+  removeItem(key: string): void { this.store.delete(key); }
+  clear(): void { this.store.clear(); }
+}
+
+/** Cookie-backed storage (browser only). */
+export class CookieStorageAdapter implements StorageAdapter {
+  constructor(
+    private opts: {
+      domain?: string;
+      path?: string;
+      secure?: boolean;
+      sameSite?: "Strict" | "Lax" | "None";
+      maxAgeSeconds?: number;
+    } = {},
+  ) {}
+
+  getItem(key: string): string | null {
+    if (typeof document === "undefined") return null;
+    const prefix = `${encodeURIComponent(key)}=`;
+    for (const part of document.cookie.split("; ")) {
+      if (part.startsWith(prefix)) {
+        return decodeURIComponent(part.slice(prefix.length));
+      }
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    if (typeof document === "undefined") return;
+    const parts = [
+      `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
+      `Path=${this.opts.path ?? "/"}`,
+    ];
+    if (this.opts.domain) parts.push(`Domain=${this.opts.domain}`);
+    if (this.opts.secure) parts.push("Secure");
+    if (this.opts.sameSite) parts.push(`SameSite=${this.opts.sameSite}`);
+    if (this.opts.maxAgeSeconds != null) {
+      parts.push(`Max-Age=${this.opts.maxAgeSeconds}`);
+    }
+    document.cookie = parts.join("; ");
+  }
+
+  removeItem(key: string): void {
+    if (typeof document === "undefined") return;
+    document.cookie = `${encodeURIComponent(key)}=; Max-Age=0; Path=${this.opts.path ?? "/"}`;
+  }
+}

package/src/_api/generated/_shared/validation-events.ts

@@ -0,0 +1,52 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Browser CustomEvent integration for Zod validation errors.
+// DO NOT EDIT — re-run `make gen`.
+
+import type { ZodError } from "zod";
+
+export interface ValidationErrorDetail {
+  operation: string;
+  path: string;
+  method: string;
+  error: ZodError;
+  response: any;
+  timestamp: Date;
+}
+
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>;
+
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  if (typeof window === "undefined") return;
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>("zod-validation-error", {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    });
+    window.dispatchEvent(event);
+  } catch (error) {
+    console.warn("Failed to dispatch validation error event:", error);
+  }
+}
+
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void,
+): () => void {
+  if (typeof window === "undefined") return () => {};
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) callback(event.detail);
+  };
+  window.addEventListener("zod-validation-error", handler);
+  return () => window.removeEventListener("zod-validation-error", handler);
+}
+
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join(".") || "root";
+    const parts = [`${index + 1}. ${path}: ${issue.message}`];
+    if ("expected" in issue && issue.expected) parts.push(`   Expected: ${issue.expected}`);
+    if ("received" in issue && issue.received) parts.push(`   Received: ${issue.received}`);
+    return parts.join("\n");
+  });
+  return issues.join("\n");
+}

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

@@ -0,0 +1,187 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Self-contained API wrapper for this group. DO NOT EDIT — re-run `make gen`.
+
+import { client } from './client.gen';
+import type { StorageAdapter } from '../_shared/storage';
+import { LocalStorageAdapter } from '../_shared/storage';
+import { APILogger, type LoggerConfig } from '../_shared/logger';
+
+import { Cfg } from './sdk.gen';
+import { Accounts } from './sdk.gen';
+import { OAuth } from './sdk.gen';
+import { UserProfile } from './sdk.gen';
+import { Auth } from './sdk.gen';
+import type { ZodTypeAny } from 'zod';
+import {
+  AccountDeleteResponseSchema,
+  OAuthAuthorizeResponseSchema,
+  OAuthProvidersResponseSchema,
+  OAuthTokenResponseSchema,
+  OTPRequestResponseSchema,
+  OTPVerifyResponseSchema,
+  TokenRefreshSchema,
+  UserSchema,
+} from './schemas';
+import { dispatchValidationError } from '../_shared/validation-events';
+
+const ACCESS_KEY = 'cfg.access_token';
+const REFRESH_KEY = 'cfg.refresh_token';
+
+interface ValidationRoute {
+  method: string;
+  re: RegExp;
+  schema: ZodTypeAny;
+  path: string;
+}
+const VALIDATION_ROUTES: ReadonlyArray<ValidationRoute> = [
+  { method: 'POST', re: new RegExp('^/cfg/accounts/oauth/github/authorize/?$'), schema: OAuthAuthorizeResponseSchema, path: '/cfg/accounts/oauth/github/authorize/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/oauth/github/callback/?$'), schema: OAuthTokenResponseSchema, path: '/cfg/accounts/oauth/github/callback/' },
+  { method: 'GET', re: new RegExp('^/cfg/accounts/oauth/providers/?$'), schema: OAuthProvidersResponseSchema, path: '/cfg/accounts/oauth/providers/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/otp/request/?$'), schema: OTPRequestResponseSchema, path: '/cfg/accounts/otp/request/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/otp/verify/?$'), schema: OTPVerifyResponseSchema, path: '/cfg/accounts/otp/verify/' },
+  { method: 'GET', re: new RegExp('^/cfg/accounts/profile/?$'), schema: UserSchema, path: '/cfg/accounts/profile/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/profile/avatar/?$'), schema: UserSchema, path: '/cfg/accounts/profile/avatar/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/profile/delete/?$'), schema: AccountDeleteResponseSchema, path: '/cfg/accounts/profile/delete/' },
+  { method: 'PUT', re: new RegExp('^/cfg/accounts/profile/partial/?$'), schema: UserSchema, path: '/cfg/accounts/profile/partial/' },
+  { method: 'PATCH', re: new RegExp('^/cfg/accounts/profile/partial/?$'), schema: UserSchema, path: '/cfg/accounts/profile/partial/' },
+  { method: 'PUT', re: new RegExp('^/cfg/accounts/profile/update/?$'), schema: UserSchema, path: '/cfg/accounts/profile/update/' },
+  { method: 'PATCH', re: new RegExp('^/cfg/accounts/profile/update/?$'), schema: UserSchema, path: '/cfg/accounts/profile/update/' },
+  { method: 'POST', re: new RegExp('^/cfg/accounts/token/refresh/?$'), schema: TokenRefreshSchema, path: '/cfg/accounts/token/refresh/' }
+];
+
+/** Auto-detect locale from cookie NEXT_LOCALE or navigator.language. */
+function detectLocale(): string | null {
+  try {
+    if (typeof document !== 'undefined') {
+      const m = document.cookie.match(/(?:^|;\s*)NEXT_LOCALE=([^;]*)/);
+      if (m) return decodeURIComponent(m[1]);
+    }
+    if (typeof navigator !== 'undefined' && navigator.language) {
+      return navigator.language;
+    }
+  } catch {}
+  return null;
+}
+
+export interface APIOptions {
+  /** Override storage backend (LocalStorage by default; Memory for SSR/tests). */
+  storage?: StorageAdapter;
+  /** Logger config (defaults to dev-only). */
+  logger?: Partial<LoggerConfig>;
+  /** Locale for `Accept-Language`. If omitted, auto-detected from cookie/navigator. */
+  locale?: string;
+  /** API key sent as `X-API-Key`. Falls back to NEXT_PUBLIC_API_KEY. */
+  apiKey?: string;
+  /** Send Django session/CSRF cookies cross-origin. Defaults to true. */
+  withCredentials?: boolean;
+}
+
+/**
+ * Self-contained API wrapper for this group.
+ *
+ * Each group has its own client + interceptor + token store. The interceptor
+ * automatically attaches:
+ *   - `Authorization: Bearer <jwt>` from storage
+ *   - `Accept-Language` from `opts.locale` or `NEXT_LOCALE` cookie
+ *   - `X-API-Key` from `opts.apiKey` or `NEXT_PUBLIC_API_KEY`
+ *   - `credentials: 'include'` for Django session/CSRF cookies (toggle via opts)
+ */
+export class API {
+  private baseUrl: string;
+  private storage: StorageAdapter;
+  private locale: string | null;
+  private apiKey: string | null;
+  readonly logger: APILogger;
+
+  readonly cfg = Cfg;
+  readonly accounts = Accounts;
+  readonly oAuth = OAuth;
+  readonly userProfile = UserProfile;
+  readonly auth = Auth;
+
+  constructor(baseUrl: string, opts: APIOptions = {}) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.storage = opts.storage ?? new LocalStorageAdapter();
+    this.logger = new APILogger(opts.logger);
+    this.locale = opts.locale ?? null;
+    this.apiKey = opts.apiKey ?? (typeof process !== 'undefined' ? (process.env?.NEXT_PUBLIC_API_KEY ?? null) : null);
+
+    const credentials: RequestCredentials = (opts.withCredentials ?? true) ? 'include' : 'same-origin';
+    client.setConfig({ baseUrl: this.baseUrl, credentials });
+
+    client.interceptors.request.use((request) => {
+      const access = this.getToken();
+      if (access) request.headers.set('Authorization', `Bearer ${access}`);
+
+      const locale = this.locale ?? detectLocale();
+      if (locale) request.headers.set('Accept-Language', locale);
+
+      if (this.apiKey) request.headers.set('X-API-Key', this.apiKey);
+
+      return request;
+    });
+
+    client.interceptors.response.use(async (response, request) => {
+      if (!response.ok) return response;
+      const ct = response.headers.get('content-type') || '';
+      if (!ct.includes('application/json')) return response;
+      const url = new URL(request.url);
+      const method = request.method.toUpperCase();
+      const route = VALIDATION_ROUTES.find(
+        (r) => r.method === method && r.re.test(url.pathname),
+      );
+      if (!route) return response;
+      let payload: unknown;
+      try {
+        payload = await response.clone().json();
+      } catch {
+        return response;
+      }
+      const result = route.schema.safeParse(payload);
+      if (!result.success) {
+        dispatchValidationError({
+          operation: `${method} ${route.path}`,
+          path: route.path,
+          method,
+          error: result.error,
+          response: payload,
+          timestamp: new Date(),
+        });
+      }
+      return response;
+    });
+  }
+
+  // ── Base URL ────────────────────────────────────────────────────────────
+  getBaseUrl(): string { return this.baseUrl; }
+  setBaseUrl(url: string): void {
+    this.baseUrl = url.replace(/\/$/, '');
+    client.setConfig({ baseUrl: this.baseUrl });
+  }
+
+  // ── Tokens ──────────────────────────────────────────────────────────────
+  getToken(): string | null { return this.storage.getItem(ACCESS_KEY); }
+  setToken(token: string | null): void {
+    if (token) this.storage.setItem(ACCESS_KEY, token);
+    else this.storage.removeItem(ACCESS_KEY);
+  }
+  getRefreshToken(): string | null { return this.storage.getItem(REFRESH_KEY); }
+  setRefreshToken(token: string | null): void {
+    if (token) this.storage.setItem(REFRESH_KEY, token);
+    else this.storage.removeItem(REFRESH_KEY);
+  }
+  clearToken(): void {
+    this.storage.removeItem(ACCESS_KEY);
+    this.storage.removeItem(REFRESH_KEY);
+  }
+  isAuthenticated(): boolean { return this.getToken() !== null; }
+
+  // ── Locale / API key ────────────────────────────────────────────────────
+  getLocale(): string | null { return this.locale ?? detectLocale(); }
+  setLocale(locale: string | null): void { this.locale = locale; }
+  getApiKey(): string | null { return this.apiKey; }
+  setApiKey(key: string | null): void { this.apiKey = key; }
+}
+
+export { Cfg, Accounts, OAuth, UserProfile, Auth };
+export { client };