Add JSDoc documentation and file headers to all source files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/api/auth.js

@@ -1,10 +1,21 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/** @module auth Authentication token refresh utilities. */
+
 import axios from 'axios';
 import { getCookie, setCookie, setCookieWithoutExpiration } from '@/utils/cookieUtil.js';
 
 /**
- * Refresh the access token using the refresh token cookie.
- * Uses plain axios (not apiClient) to avoid interceptor loops.
+ * Refreshes the access token using the stored refresh token cookie.
+ *
+ * Uses plain axios (not apiClient) to avoid interceptor loops. Updates
+ * both the access token (session cookie) and refresh token (6-month
+ * expiry) cookies.
+ *
  * @returns {Promise<string>} The new access token.
+ * @throws {Error} If the refresh request fails.
  */
 export async function refreshTokenAndGetNew() {
   const api = '/api/oauth/token';

src/api/client.js

@@ -1,6 +1,17 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/**
+ * @module apiClient Centralized axios instance with request/response
+ *   interceptors for authentication token management and automatic
+ *   401 token refresh with request queuing.
+ */
+
 import axios from 'axios';
 import { getCookie, deleteCookie } from '@/utils/cookieUtil.js';
 
+/** Axios instance configured with auth interceptors. */
 const apiClient = axios.create();
 
 // Request interceptor: automatically attach Authorization header
@@ -16,11 +27,19 @@ apiClient.interceptors.request.use((config) => {
 let isRefreshing = false;
 let pendingRequests = [];
 
+/**
+ * Resolves all pending requests with the new access token.
+ * @param {string} newToken - The refreshed access token.
+ */
 function onRefreshSuccess(newToken) {
   pendingRequests.forEach((cb) => cb(newToken));
   pendingRequests = [];
 }
 
+/**
+ * Rejects all pending requests with the refresh error.
+ * @param {Error} error - The token refresh error.
+ */
 function onRefreshFailure(error) {
   pendingRequests.forEach((cb) => cb(null, error));
   pendingRequests = [];