create-pardx-scaffold 0.1.0

package/template/apps/web/lib/api/contracts/client.ts

@@ -0,0 +1,336 @@
+'use client';
+
+import { initQueryClient } from '@ts-rest/react-query';
+import { initClient, type ApiFetcherArgs } from '@ts-rest/core';
+import { toast } from 'sonner';
+import {
+  analyticsContract,
+  downloadContract,
+  messageContract,
+  settingContract,
+  signContract,
+  smsContract,
+  uploaderContract,
+  userContract,
+} from '@repo/contracts';
+import { getHeaders } from '@repo/utils/headers';
+import { API_VERSION_HEADER, APP_BUILD_HEADER } from '@repo/constants';
+import { API_CONFIG } from '../../config';
+import { getToken, ensureValidToken, clearToken } from '../../api';
+import { APP_VERSION } from '@/lib/version';
+import {
+  handleVersionMismatch,
+  isVersionMismatchStatus,
+  getMinBuildFromHeaders,
+  VersionMismatchError,
+} from '@/lib/version-mismatch';
+
+/**
+ * ts-rest API Client for type-safe API calls
+ * Uses ts-rest contracts for type-safe API endpoints
+ *
+ * Headers included in every request:
+ * - Authorization: Bearer token (if authenticated)
+ * - Content-Type: application/json
+ * - x-api-version: API version (e.g., "1")
+ * - x-app-build: Frontend build version (e.g., "2025.03.18-abcdef-g42")
+ * - platform: web
+ * - os: detected OS (windows/macos/linux/ios/android)
+ * - deviceid: unique device identifier
+ */
+
+const API_BASE_URL = API_CONFIG.baseUrl;
+
+/**
+ * Base fetch function with standard headers (no auth check)
+ * Used for public endpoints like login, register
+ */
+const baseFetch = async (args: ApiFetcherArgs, requireAuth: boolean = true) => {
+  // Only ensure valid token for authenticated requests
+  if (requireAuth) {
+    try {
+      await ensureValidToken();
+    } catch {
+      // Ignore ensureValidToken errors for non-critical paths
+      // The request will proceed without token
+    }
+  }
+
+  const token = getToken();
+
+  // Get standard headers (platform, os, deviceid)
+  // This ensures consistency with v1 API client
+  const standardHeaders = getHeaders(
+    {},
+    undefined, // mptrail - can be passed if needed
+  );
+
+  // Build final headers: our headers first, then ts-rest headers override
+  // This prevents duplicate Content-Type (ts-rest already sets it)
+  const headers: Record<string, string> = {
+    ...standardHeaders,
+    // Version control headers
+    [API_VERSION_HEADER]: APP_VERSION.apiVersion,
+    [APP_BUILD_HEADER]: APP_VERSION.appBuild,
+  };
+
+  // Merge ts-rest headers, but handle Content-Type specially to avoid duplicates
+  const tsRestHeaders = args.headers as Record<string, string> | undefined;
+  if (tsRestHeaders) {
+    for (const [key, value] of Object.entries(tsRestHeaders)) {
+      // Skip if value contains comma (indicates duplicate header)
+      if (typeof value === 'string' && !value.includes(', ')) {
+        headers[key] = value;
+      } else if (key.toLowerCase() === 'content-type') {
+        // For Content-Type, just use application/json
+        headers[key] = 'application/json';
+      }
+    }
+  }
+
+  // Ensure Content-Type is set for POST/PUT/PATCH requests with body
+  if (args.body && !headers['Content-Type'] && !headers['content-type']) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  // Add Authorization header if token is available
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  // Handle body serialization - avoid double stringify
+  let requestBody: string | undefined;
+  if (args.body !== undefined && args.body !== null) {
+    // If body is already a string, use it directly; otherwise stringify it
+    requestBody =
+      typeof args.body === 'string' ? args.body : JSON.stringify(args.body);
+  }
+
+  const response = await fetch(args.path, {
+    method: args.method,
+    headers,
+    body: requestBody,
+    credentials: 'include',
+  });
+
+  const contentType = response.headers.get('content-type');
+  let body;
+
+  // Handle empty responses (204 No Content, etc.)
+  if (
+    response.status === 204 ||
+    response.headers.get('content-length') === '0'
+  ) {
+    body = null;
+  } else if (contentType?.includes('application/json')) {
+    const text = await response.text();
+    body = text ? JSON.parse(text) : null;
+  } else {
+    body = await response.text();
+  }
+
+  // Handle version mismatch (426 Upgrade Required)
+  if (isVersionMismatchStatus(response.status)) {
+    const minBuild = getMinBuildFromHeaders(response.headers);
+    handleVersionMismatch(minBuild);
+    throw new VersionMismatchError(minBuild);
+  }
+
+  // 错误消息去重机制：记录最近显示的错误消息和时间戳
+  // 在短时间内（2秒）相同的错误消息只显示一次
+  const errorMessageCache = new Map<string, number>();
+  const ERROR_DEDUP_INTERVAL = 2000; // 2秒
+  const MAX_CACHE_SIZE = 50; // 最大缓存数量
+
+  // Global error handling
+  const handleError = (errorMsg: string, statusCode: number) => {
+    if (typeof window === 'undefined') return;
+
+    const pathname = window.location.pathname;
+
+    // 如果已经在登录页面，不需要全局错误处理，由登录组件自己处理
+    if (pathname === '/login' || pathname.endsWith('/login')) {
+      // 登录页面的错误（如密码错误、401 等）由登录组件自己处理，不显示 toast
+      return;
+    }
+
+    // 创建错误消息的唯一标识（包含消息内容和状态码）
+    const errorKey = `${statusCode}:${errorMsg}`;
+    const now = Date.now();
+    const lastShown = errorMessageCache.get(errorKey);
+
+    // 如果在去重时间窗口内已经显示过相同的错误，则跳过
+    if (lastShown && now - lastShown < ERROR_DEDUP_INTERVAL) {
+      return;
+    }
+
+    // 记录当前错误消息的显示时间
+    errorMessageCache.set(errorKey, now);
+
+    // 清理过期缓存：达到最大数量时清理所有过期项
+    if (errorMessageCache.size > MAX_CACHE_SIZE) {
+      for (const [key, timestamp] of errorMessageCache.entries()) {
+        if (now - timestamp >= ERROR_DEDUP_INTERVAL) {
+          errorMessageCache.delete(key);
+        }
+      }
+      // 如果清理后仍超过限制，删除最旧的项
+      if (errorMessageCache.size > MAX_CACHE_SIZE) {
+        const oldestKey = errorMessageCache.keys().next().value;
+        if (oldestKey) errorMessageCache.delete(oldestKey);
+      }
+    }
+
+    // Handle 401 Unauthorized - clear storage and redirect to login
+    if (statusCode === 401) {
+      clearToken();
+      toast.error(errorMsg || '登录已过期，请重新登录');
+      // 重定向到登录页（公开页面在上面已经提前返回，不会执行到这里）
+      window.location.href = '/login';
+    } else {
+      // Show error toast for other error codes
+      toast.error(errorMsg);
+    }
+  };
+
+  // Check HTTP status code first
+  if (!response.ok) {
+    const errorMsg =
+      typeof body === 'object' && body?.msg ? body.msg : '请求失败';
+    handleError(errorMsg, response.status);
+  } else if (
+    typeof body === 'object' &&
+    body?.code !== undefined &&
+    body.code !== 200
+  ) {
+    // HTTP 200 but business code is not 0 - show error
+    const errorMsg = body?.msg || '请求失败';
+    handleError(errorMsg, body.code);
+  }
+
+  return {
+    status: response.status,
+    body,
+    headers: response.headers,
+  };
+};
+
+/**
+ * Authenticated fetch - requires valid token
+ * Used for most API endpoints
+ */
+const customFetch = async (args: ApiFetcherArgs) => baseFetch(args, true);
+
+/**
+ * Public fetch - does not require token
+ * Used for login, register, and other public endpoints
+ */
+const publicFetch = async (args: ApiFetcherArgs) => baseFetch(args, false);
+
+// ============================================================================
+// Direct API Clients (for imperative calls)
+// ============================================================================
+
+/**
+ * Common client options with response validation (authenticated)
+ */
+const clientOptions = {
+  baseUrl: API_BASE_URL,
+  baseHeaders: {},
+  api: customFetch,
+  jsonQuery: true,
+  throwOnUnknownStatus: false,
+};
+
+/**
+ * Public client options (no auth required)
+ */
+const publicClientOptions = {
+  baseUrl: API_BASE_URL,
+  baseHeaders: {},
+  api: publicFetch,
+  jsonQuery: true,
+  throwOnUnknownStatus: false,
+};
+
+/**
+ * Download API - Direct client
+ */
+export const downloadClient = initClient(downloadContract, clientOptions);
+
+/**
+ * Notification API - Direct client
+ */
+/**
+ * Sign API - Direct client (PUBLIC - no auth required)
+ */
+export const signClient = initClient(signContract, publicClientOptions);
+
+/**
+ * User API - Direct client
+ */
+export const userClient = initClient(userContract, clientOptions);
+
+/**
+ * SMS API - Direct client (PUBLIC - no auth required)
+ */
+export const smsClient = initClient(smsContract, publicClientOptions);
+
+/**
+ * Uploader API - Direct client
+ */
+export const uploaderClient = initClient(uploaderContract, clientOptions);
+
+/**
+ * Analytics API - Direct client (for imperative calls)
+ */
+export const analyticsClient = initClient(analyticsContract, clientOptions);
+
+// ============================================================================
+// React Query Clients (for hooks)
+// ============================================================================
+
+/**
+ * Download API - React Query hooks
+ */
+export const downloadApi = initQueryClient(downloadContract, clientOptions);
+
+/**
+ * Message API - React Query hooks
+ */
+export const messageApi = initQueryClient(messageContract, clientOptions);
+
+/**
+ * Setting API - React Query hooks
+ */
+export const settingApi = initQueryClient(settingContract, clientOptions);
+
+/**
+ * Analytics API - React Query hooks
+ */
+export const analyticsApi = initQueryClient(analyticsContract, clientOptions);
+
+// ============================================================================
+// Generic ts-rest Client (for custom contracts)
+// ============================================================================
+
+/**
+ * Generic ts-rest client wrapper
+ * Used by custom hooks that are not part of the main contract
+ * Includes all React Query clients for easy access
+ *
+ * Note: For imperative calls (non-hook usage), use the direct clients:
+ * - analyticsClient (for Analytics)
+ * - messageClient (for Message)
+ * - etc.
+ */
+export const tsRestClient = {
+  request: customFetch,
+  // React Query clients (for hooks)
+  analytics: analyticsApi,
+  message: messageApi,
+  setting: settingApi,
+  download: downloadApi,
+  // Direct clients (for imperative calls)
+  analyticsClient,
+};

package/template/apps/web/lib/api/contracts/hooks/index.ts

@@ -0,0 +1,25 @@
+'use client';
+
+// Notification hooks
+export {
+  notificationKeys,
+  useNotifications,
+  useMarkNotificationRead,
+  useMarkAllNotificationsRead,
+  useDeleteNotification,
+  type NotificationsParams,
+} from './notification';
+
+// Setting hooks
+export {
+  settingKeys,
+  useSaveAccount,
+  useUpdateAvatar,
+  useGetUsage,
+  useGetBranding,
+  useSaveBranding,
+  useSendVerifyEmail,
+  useSetPassword,
+  useBindEmail,
+  useBindPhone,
+} from './setting';

package/template/apps/web/lib/api/contracts/hooks/notification.ts

@@ -0,0 +1,180 @@
+'use client';
+
+/**
+ * Notification API Hooks
+ * 基于 ts-rest 契约的通知 API Hooks
+ *
+ * 性能优化：
+ * - 懒加载模式：支持 enabled 选项，仅在需要时加载数据
+ * - 减少初始 API 调用和 SSE 数据压力
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useNotifications,
+ *   useUnreadNotificationCount,
+ *   useMarkNotificationRead,
+ *   useMarkAllNotificationsRead,
+ * } from '@/lib/api/contracts/hooks/notification';
+ *
+ * function NotificationPanel() {
+ *   const [open, setOpen] = useState(false);
+ *   // 懒加载：仅当面板打开时加载通知列表
+ *   const { data, isLoading } = useNotifications({ limit: 20 }, { enabled: open });
+ *   // 未读数量始终加载，用于显示徽章
+ *   const { data: unreadCount } = useUnreadNotificationCount();
+ *   const markReadMutation = useMarkNotificationRead();
+ *   const markAllReadMutation = useMarkAllNotificationsRead();
+ *
+ *   return (
+ *     <div>
+ *       <p>未读: {unreadCount?.total}</p>
+ *       {data?.list.map(notification => (
+ *         <div key={notification.id} onClick={() => {
+ *           markReadMutation.mutate({ notificationIds: [notification.id] });
+ *         }}>
+ *           {notification.content.type}
+ *         </div>
+ *       ))}
+ *       <button onClick={() => markAllReadMutation.mutate({})}>
+ *         全部标为已读
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { notificationApi, notificationClient } from '../client';
+import type {
+  MessageNotificationType,
+  GetNotificationListRequest,
+} from '@repo/contracts';
+
+// ============================================================================
+// Query Keys
+// ============================================================================
+
+export const notificationKeys = {
+  all: ['notifications'] as const,
+  list: (params?: Partial<GetNotificationListRequest>) =>
+    [...notificationKeys.all, 'list', params] as const,
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface NotificationsParams {
+  type?: MessageNotificationType;
+  isRead?: boolean;
+  limit?: number;
+  page?: number;
+}
+
+export interface NotificationsOptions {
+  /** 是否启用查询，默认 true，可用于懒加载 */
+  enabled?: boolean;
+}
+
+// ============================================================================
+// Query Hooks
+// ============================================================================
+
+/**
+ * 获取通知列表
+ *
+ * 使用 React Query 原生 useQuery 实现 enabled 选项，
+ * 支持懒加载模式，仅在需要时加载数据
+ *
+ * @param params - 查询参数（筛选条件和分页）
+ * @param options - 可选配置项，支持 enabled 懒加载
+ *
+ * @example
+ * ```tsx
+ * // 懒加载：仅当面板打开时才加载列表
+ * const { data, isLoading, refetch } = useNotifications(
+ *   { limit: 20 },
+ *   { enabled: isPanelOpen }
+ * );
+ * ```
+ */
+export function useNotifications(
+  params?: NotificationsParams,
+  options?: NotificationsOptions,
+) {
+  const queryParams = {
+    type: params?.type,
+    isRead: params?.isRead,
+    limit: params?.limit || 20,
+    page: params?.page || 1,
+  };
+
+  const isEnabled = options?.enabled ?? true;
+
+  // 使用 React Query 原生 useQuery，正确支持 enabled 选项
+  return useQuery({
+    queryKey: notificationKeys.list(queryParams),
+    queryFn: async () => {
+      const response = await notificationClient.getList({
+        query: queryParams,
+      });
+      return response;
+    },
+    staleTime: 30 * 1000, // 30 seconds
+    enabled: isEnabled,
+  });
+}
+
+// ============================================================================
+// Mutation Hooks
+// ============================================================================
+
+/**
+ * 标记通知已读
+ */
+export function useMarkNotificationRead() {
+  const queryClient = useQueryClient();
+
+  return notificationApi.markRead.useMutation({
+    onSuccess: () => {
+      // 刷新通知列表和未读数量
+      queryClient.invalidateQueries({
+        queryKey: notificationKeys.all,
+      });
+    },
+  });
+}
+
+/**
+ * 标记全部通知已读
+ */
+export function useMarkAllNotificationsRead() {
+  const queryClient = useQueryClient();
+
+  return notificationApi.markAllRead.useMutation({
+    onSuccess: () => {
+      // 刷新通知列表和未读数量
+      queryClient.invalidateQueries({
+        queryKey: notificationKeys.all,
+      });
+    },
+  });
+}
+
+/**
+ * 删除通知
+ */
+export function useDeleteNotification() {
+  const queryClient = useQueryClient();
+
+  return notificationApi.delete.useMutation({
+    onSuccess: () => {
+      // 刷新通知列表和未读数量
+      queryClient.invalidateQueries({
+        queryKey: notificationKeys.all,
+      });
+    },
+  });
+}

package/template/apps/web/lib/api/contracts/hooks/setting.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { settingApi } from '../client';
+
+export const settingKeys = {
+  all: ['setting'] as const,
+  account: () => [...settingKeys.all, 'account'] as const,
+  avatar: () => [...settingKeys.all, 'avatar'] as const,
+};
+
+export function useSaveAccount() {
+  return settingApi.saveAccount.useMutation();
+}
+
+export function useUpdateAvatar() {
+  return settingApi.updateAvatar.useMutation();
+}
+
+export function useSendVerifyEmail() {
+  return settingApi.sendVerifyEmail.useMutation();
+}
+
+export function useSetPassword() {
+  return settingApi.setPassword.useMutation();
+}
+
+export function useBindEmail() {
+  return settingApi.bindEmail.useMutation();
+}
+
+export function useBindPhone() {
+  return settingApi.bindPhone.useMutation();
+}

package/template/apps/web/lib/api/contracts/index.ts

@@ -0,0 +1,18 @@
+/**
+ * ts-rest API Contracts
+ * Type-safe API client using ts-rest with React Query
+ *
+ * 使用方法：
+ *
+ * 1. 导入底层 API clients（适用于复杂场景）：
+ * ```tsx
+ * import { api } from '@/lib/api/contracts';
+ * const { data } = api.list.useQuery(['users']);
+ * ```
+ */
+
+// ts-rest clients (底层 API clients)
+export * from './client';
+
+// Wrapped hooks (封装好的 Hooks，推荐使用)
+export * from './hooks';