@windrun-huaiin/backend-core 29.0.3 → 31.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @windrun-huaiin/backend-core
+
+Shared backend primitives for Next.js applications, including Prisma access, database services, authentication helpers, Stripe integration, credit and pricing server utilities, Upstash utilities, AI services, and ready-to-wire API route handlers.
+
+This package is organized around public subpath exports. Import the narrowest entry point that matches the backend capability you need, especially when separating server-only code from route handlers.
+
+## Feature Areas
+
+### Core Backend Utilities
+
+The root entry provides shared backend exports for application code that needs the common backend surface of the package.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core` | Shared backend primitives and common exports |
+
+### Prisma and Database Services
+
+The Prisma and database entries provide the data-access layer for applications that share database models, service methods, and transaction-oriented backend logic.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/prisma` | Prisma client and Prisma-related utilities |
+| `@windrun-huaiin/backend-core/database` | Database service layer |
+| `@windrun-huaiin/backend-core/aggregate` | Aggregate service layer |
+| `@windrun-huaiin/backend-core/context` | Backend context helpers |
+
+### Authentication
+
+Authentication entries provide shared server utilities, shared auth definitions, and middleware helpers for applications that need consistent auth handling.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/auth/server` | Server-side authentication helpers |
+| `@windrun-huaiin/backend-core/auth/shared` | Shared authentication utilities and definitions |
+| `@windrun-huaiin/backend-core/auth/middleware` | Authentication middleware helpers |
+
+### Stripe, Pricing, and Credits
+
+Commerce entries cover Stripe integration, checkout and customer portal route handlers, pricing server helpers, and credit server helpers.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/stripe` | Stripe service layer |
+| `@windrun-huaiin/backend-core/stripe/server` | Server-side Stripe configuration helpers |
+| `@windrun-huaiin/backend-core/pricing/server` | Server-side pricing helpers |
+| `@windrun-huaiin/backend-core/credit/server` | Server-side credit helpers |
+| `@windrun-huaiin/backend-core/config/money-price` | Money-price configuration |
+| `@windrun-huaiin/backend-core/app/api/stripe/checkout/route` | Stripe checkout API route handler |
+| `@windrun-huaiin/backend-core/app/api/stripe/customer-portal/route` | Stripe customer portal API route handler |
+| `@windrun-huaiin/backend-core/app/api/webhook/stripe/route` | Stripe webhook API route handler |
+
+### User and Clerk Routes
+
+User route handlers provide reusable API endpoints for anonymous user initialization, credit overview, pricing context, and Clerk user webhooks.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/app/api/user/anonymous/init/route` | Anonymous user initialization API route handler |
+| `@windrun-huaiin/backend-core/app/api/user/credit-overview/route` | User credit overview API route handler |
+| `@windrun-huaiin/backend-core/app/api/user/pricing-context/route` | User pricing context API route handler |
+| `@windrun-huaiin/backend-core/app/api/webhook/clerk/user/route` | Clerk user webhook API route handler |
+
+### Fingerprint and Upstash
+
+Fingerprint and Upstash entries expose server-side configuration and infrastructure helpers for identity and storage-related backend workflows.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/config/fingerprint` | Fingerprint configuration |
+| `@windrun-huaiin/backend-core/upstash/server` | Server-side Upstash helpers |
+
+### AI Services
+
+AI entries provide shared AI service utilities and a reusable API route handler for AI endpoints.
+
+| Entry | Purpose |
+| --- | --- |
+| `@windrun-huaiin/backend-core/ai` | AI service layer |
+| `@windrun-huaiin/backend-core/app/api/ai/route` | AI API route handler |
+
+## Usage Notes
+
+- Use server-only entries from server components, route handlers, server actions, or backend modules.
+- Use API route handler entries when an application wants to mount the package-provided route behavior directly in a Next.js route.
+- Keep Prisma, database, Stripe, auth, and Upstash imports out of client-side code.
+- Prefer feature-specific subpath imports so each application depends only on the backend capabilities it actually uses.
+
+## Installation
+
+```bash
+pnpm add @windrun-huaiin/backend-core
+```
+
+This package is intended for Next.js backend usage. The consuming application is responsible for its environment variables, database setup, authentication provider setup, Stripe setup, and deployment configuration.

package/dist/app/api/user/anonymous/init/route.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 /**
- * 匿名用户初始化API
+ * Anonymous user initialization API.
  * POST /api/user/anonymous/init
  */
 export declare function POST(request: NextRequest): Promise<NextResponse<unknown>>;

package/dist/app/api/user/anonymous/init/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../src/app/api/user/anonymous/init/route.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA6rBxD;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,kCAE9C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../src/app/api/user/anonymous/init/route.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4rBxD;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,kCAE9C"}

package/dist/app/api/user/anonymous/init/route.js

@@ -13,13 +13,13 @@ var userContextFinalizer = require('../../../../../services/context/user-context
 BigInt.prototype.toJSON = function () {
     return this.toString();
 };
-// ==================== 工具函数 ====================
-/** 创建成功响应对象 */
+// ==================== Utilities ====================
+/** Create a successful response payload */
 function createSuccessResponse(params) {
     const response = Object.assign({ success: true, xUser: userContextService.mapUserToXUser(params.entities.user), xCredit: params.entities.credit ? userContextService.mapCreditToXCredit(params.entities.credit) : null, xSubscription: userContextService.mapSubscriptionToXSubscription(params.entities.subscription), isNewUser: params.isNewUser }, params.options);
     return userContextFinalizer.finalizeUserContext(response);
 }
-/** 创建错误响应 */
+/** Create an error response */
 function createErrorResponse(message, status = 400) {
     const errorResponse = { error: message };
     return server$1.NextResponse.json(errorResponse, { status });
@@ -414,7 +414,7 @@ function finalizeAttribution(sourceRef) {
     sourceRef.sourceChannel = 'direct';
     sourceRef.sourceType = 'direct';
 }
-// 提取用户首次访问来源
+// Extract the user's first-touch attribution source.
 function extractSourceRef(request) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     const headerRef = request.headers.get('referer') || request.headers.get('referrer');
@@ -455,7 +455,7 @@ function extractSourceRef(request) {
     return Object.keys(sourceRef).length > 0 ? sourceRef : null;
 }
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by Clerk user ID and return response data.
  */
 function getUserByClerkId(clerkUserId) {
     return tslib.__awaiter(this, void 0, void 0, function* () {
@@ -470,7 +470,7 @@ function getUserByClerkId(clerkUserId) {
     });
 }
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by fingerprint ID and return response data.
  */
 function getUserByFingerprintId(fingerprintId) {
     return tslib.__awaiter(this, void 0, void 0, function* () {
@@ -490,14 +490,14 @@ function getUserByFingerprintId(fingerprintId) {
     });
 }
 /**
- * 通用的fingerprint处理逻辑
+ * Shared fingerprint request handling logic.
  */
 function handleFingerprintRequest(request_1) {
     return tslib.__awaiter(this, arguments, void 0, function* (request, options = {}) {
         var _a;
-        // 从请求中提取fingerprint ID
+        // Extract the fingerprint ID from the request.
         const fingerprintId = server.extractFingerprintFromNextRequest(request);
-        // 验证fingerprint ID
+        // Validate the fingerprint ID.
         if (!fingerprintId) {
             return createErrorResponse('Invalid or missing fingerprint ID');
         }
@@ -505,27 +505,26 @@ function handleFingerprintRequest(request_1) {
         const authIdentity = yield authUtils.getOptionalServerAuthIdentity();
         const clerkUserId = (_a = authIdentity === null || authIdentity === void 0 ? void 0 : authIdentity.providerUserId) !== null && _a !== void 0 ? _a : null;
         try {
-            // 优先根据 Clerk ID 查询（如果已登录）
+            // Prefer Clerk user ID lookup when the user is authenticated.
             let existingUserResult = null;
             if (clerkUserId) {
-                // 已登录一律按照clerkUserId去查
+                // Authenticated users are always resolved by clerkUserId.
                 existingUserResult = yield getUserByClerkId(clerkUserId);
                 if (existingUserResult && existingUserResult.xUser.fingerprintId !== fingerprintId) {
-                    // 说明当前用户的指纹ID发生了改变，为什么呢？因为它使用同一账号去注册Clerk，Clerk判定是同一用户！
-                    // 这个时候一定以登录用户clerkUserId为准
-                    // 但是考虑到同一指纹ID本身可以绑定多个账号，所以这里什么都不做
-                    // 就是以当前登录用户去查他自己的数据就行！
+                    // The authenticated user's fingerprint changed. Clerk still identifies the account as the same user.
+                    // Trust clerkUserId as the source of truth and keep resolving the user's own data by login identity.
+                    // A single fingerprint can be associated with multiple accounts, so no mutation is needed here.
                     console.warn(`Current login user used diff fp_ids: ${clerkUserId}, db_fp_id=${existingUserResult.xUser.fingerprintId}, req_fp_id=${fingerprintId}`);
                 }
             }
             else {
-                // 其次才是检查是否已存在该fingerprint的用户
+                // For anonymous requests, fall back to fingerprint lookup.
                 existingUserResult = yield getUserByFingerprintId(fingerprintId);
             }
             if (existingUserResult) {
                 return server$1.NextResponse.json(existingUserResult);
             }
-            // 如果不存在用户且不允许创建，返回404
+            // If the user does not exist and creation is disabled, return 404.
             if (!options.createIfNotExists) {
                 return createErrorResponse('User not found', 404);
             }
@@ -534,7 +533,7 @@ function handleFingerprintRequest(request_1) {
             if (anonymousInitResult.isNewUser) {
                 console.log(`Created new anonymous user ${anonymousInitResult.user.userId} with fingerprint ${fingerprintId}`);
             }
-            // 返回创建结果
+            // Return the created or existing context.
             const response = createSuccessResponse({
                 entities: {
                     user: anonymousInitResult.user,
@@ -556,7 +555,7 @@ function handleFingerprintRequest(request_1) {
     });
 }
 /**
- * 匿名用户初始化API
+ * Anonymous user initialization API.
  * POST /api/user/anonymous/init
  */
 function POST(request) {

package/dist/app/api/user/anonymous/init/route.mjs

@@ -11,13 +11,13 @@ import { finalizeUserContext } from '../../../../../services/context/user-contex
 BigInt.prototype.toJSON = function () {
     return this.toString();
 };
-// ==================== 工具函数 ====================
-/** 创建成功响应对象 */
+// ==================== Utilities ====================
+/** Create a successful response payload */
 function createSuccessResponse(params) {
     const response = Object.assign({ success: true, xUser: mapUserToXUser(params.entities.user), xCredit: params.entities.credit ? mapCreditToXCredit(params.entities.credit) : null, xSubscription: mapSubscriptionToXSubscription(params.entities.subscription), isNewUser: params.isNewUser }, params.options);
     return finalizeUserContext(response);
 }
-/** 创建错误响应 */
+/** Create an error response */
 function createErrorResponse(message, status = 400) {
     const errorResponse = { error: message };
     return NextResponse.json(errorResponse, { status });
@@ -412,7 +412,7 @@ function finalizeAttribution(sourceRef) {
     sourceRef.sourceChannel = 'direct';
     sourceRef.sourceType = 'direct';
 }
-// 提取用户首次访问来源
+// Extract the user's first-touch attribution source.
 function extractSourceRef(request) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     const headerRef = request.headers.get('referer') || request.headers.get('referrer');
@@ -453,7 +453,7 @@ function extractSourceRef(request) {
     return Object.keys(sourceRef).length > 0 ? sourceRef : null;
 }
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by Clerk user ID and return response data.
  */
 function getUserByClerkId(clerkUserId) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -468,7 +468,7 @@ function getUserByClerkId(clerkUserId) {
     });
 }
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by fingerprint ID and return response data.
  */
 function getUserByFingerprintId(fingerprintId) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -488,14 +488,14 @@ function getUserByFingerprintId(fingerprintId) {
     });
 }
 /**
- * 通用的fingerprint处理逻辑
+ * Shared fingerprint request handling logic.
  */
 function handleFingerprintRequest(request_1) {
     return __awaiter(this, arguments, void 0, function* (request, options = {}) {
         var _a;
-        // 从请求中提取fingerprint ID
+        // Extract the fingerprint ID from the request.
         const fingerprintId = extractFingerprintFromNextRequest(request);
-        // 验证fingerprint ID
+        // Validate the fingerprint ID.
         if (!fingerprintId) {
             return createErrorResponse('Invalid or missing fingerprint ID');
         }
@@ -503,27 +503,26 @@ function handleFingerprintRequest(request_1) {
         const authIdentity = yield getOptionalServerAuthIdentity();
         const clerkUserId = (_a = authIdentity === null || authIdentity === void 0 ? void 0 : authIdentity.providerUserId) !== null && _a !== void 0 ? _a : null;
         try {
-            // 优先根据 Clerk ID 查询（如果已登录）
+            // Prefer Clerk user ID lookup when the user is authenticated.
             let existingUserResult = null;
             if (clerkUserId) {
-                // 已登录一律按照clerkUserId去查
+                // Authenticated users are always resolved by clerkUserId.
                 existingUserResult = yield getUserByClerkId(clerkUserId);
                 if (existingUserResult && existingUserResult.xUser.fingerprintId !== fingerprintId) {
-                    // 说明当前用户的指纹ID发生了改变，为什么呢？因为它使用同一账号去注册Clerk，Clerk判定是同一用户！
-                    // 这个时候一定以登录用户clerkUserId为准
-                    // 但是考虑到同一指纹ID本身可以绑定多个账号，所以这里什么都不做
-                    // 就是以当前登录用户去查他自己的数据就行！
+                    // The authenticated user's fingerprint changed. Clerk still identifies the account as the same user.
+                    // Trust clerkUserId as the source of truth and keep resolving the user's own data by login identity.
+                    // A single fingerprint can be associated with multiple accounts, so no mutation is needed here.
                     console.warn(`Current login user used diff fp_ids: ${clerkUserId}, db_fp_id=${existingUserResult.xUser.fingerprintId}, req_fp_id=${fingerprintId}`);
                 }
             }
             else {
-                // 其次才是检查是否已存在该fingerprint的用户
+                // For anonymous requests, fall back to fingerprint lookup.
                 existingUserResult = yield getUserByFingerprintId(fingerprintId);
             }
             if (existingUserResult) {
                 return NextResponse.json(existingUserResult);
             }
-            // 如果不存在用户且不允许创建，返回404
+            // If the user does not exist and creation is disabled, return 404.
             if (!options.createIfNotExists) {
                 return createErrorResponse('User not found', 404);
             }
@@ -532,7 +531,7 @@ function handleFingerprintRequest(request_1) {
             if (anonymousInitResult.isNewUser) {
                 console.log(`Created new anonymous user ${anonymousInitResult.user.userId} with fingerprint ${fingerprintId}`);
             }
-            // 返回创建结果
+            // Return the created or existing context.
             const response = createSuccessResponse({
                 entities: {
                     user: anonymousInitResult.user,
@@ -554,7 +553,7 @@ function handleFingerprintRequest(request_1) {
     });
 }
 /**
- * 匿名用户初始化API
+ * Anonymous user initialization API.
  * POST /api/user/anonymous/init
  */
 function POST(request) {

package/dist/app/api/webhook/clerk/user/route.js

@@ -20,10 +20,10 @@ function POST(request) {
     return tslib.__awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
         try {
-            // 获取原始请求体
+            // Read the raw request body.
             const rawBody = yield request.text();
             let event;
-            // 开发环境跳过签名校验
+            // Skip signature verification in development.
             if (process.env.NODE_ENV === 'development') {
                 console.log('Development mode: skipping webhook signature verification');
                 try {
@@ -35,22 +35,22 @@ function POST(request) {
                 }
             }
             else {
-                // 生产环境进行签名校验
+                // Verify the signature in production.
                 const headerPayload = yield headers.headers();
                 const svix_id = headerPayload.get('svix-id');
                 const svix_timestamp = headerPayload.get('svix-timestamp');
                 const svix_signature = headerPayload.get('svix-signature');
-                // 如果缺少必要的header，返回错误
+                // Reject requests missing required headers.
                 if (!svix_id || !svix_timestamp || !svix_signature) {
                     return server.NextResponse.json({ error: 'Missing webhook headers' }, { status: 400 });
                 }
-                // 获取webhook signing secret
+                // Load the webhook signing secret.
                 const webhookSecret = process.env.CLERK_WEBHOOK_SECRET;
                 if (!webhookSecret) {
                     console.error('CLERK_WEBHOOK_SECRET is not configured');
                     return server.NextResponse.json({ error: 'Webhook configuration error' }, { status: 500 });
                 }
-                // 验证webhook签名
+                // Verify the webhook signature.
                 try {
                     const wh = new svix.Webhook(webhookSecret);
                     event = wh.verify(rawBody, {
@@ -72,7 +72,7 @@ function POST(request) {
             }, event);
             let processingResult = { success: true, message: 'Event processed successfully' };
             try {
-                // 处理不同的事件类型
+                // Dispatch by event type.
                 const { type } = event;
                 switch (type) {
                     case 'user.created':
@@ -108,7 +108,7 @@ function POST(request) {
     });
 }
 /**
- * 处理用户创建事件
+ * Handle the user.created event.
  */
 function handleUserCreated(event) {
     return tslib.__awaiter(this, void 0, void 0, function* () {
@@ -127,7 +127,7 @@ function handleUserCreated(event) {
             fingerprintId,
             userName
         });
-        // 检查必要参数
+        // Validate required fields.
         if (!fingerprintId) {
             console.error('Missing fingerprintId in webhook data, process flow error');
             return;
@@ -137,16 +137,16 @@ function handleUserCreated(event) {
             return;
         }
         try {
-            // 按fingerprintId查询该设备的所有未注销过的用户记录，注销过的记录相当于是死数据
+            // Find all non-deleted users for this device fingerprint.
             const existingUsers = yield user_service.userService.findListByFingerprintId(fingerprintId);
             if (!existingUsers || existingUsers.length === 0) {
                 console.error('Invalid fingerprintId in webhook data, process flow error');
                 return;
             }
-            // 查找email相同的记录
+            // Find an existing user with the same email.
             const sameEmailUser = existingUsers.find(user => user.email === email);
             if (sameEmailUser) {
-                // 同一账号，检查是否需要更新clerkUserId
+                // Same account; update clerkUserId if needed.
                 if (sameEmailUser.clerkUserId !== clerkUserId) {
                     yield user_service.userService.updateUser(sameEmailUser.userId, { clerkUserId, userName: userName, status: constants.UserStatus.REGISTERED });
                     console.log(`Updated clerkUserId for user ${sameEmailUser.userId}`);
@@ -156,15 +156,15 @@ function handleUserCreated(event) {
                 }
                 return;
             }
-            // 查找匿名用户（email为空且clerkUserId为空）
+            // Find an anonymous user with no email or clerkUserId.
             const anonymousUser = existingUsers.find(user => !user.email && !user.clerkUserId && user.status === constants.UserStatus.ANONYMOUS);
             if (anonymousUser) {
-                // 匿名用户升级
+                // Upgrade the anonymous user.
                 yield user_aggregate_service.userAggregateService.upgradeToRegistered(anonymousUser.userId, email, clerkUserId, userName);
                 console.log(`Successfully upgraded anonymous user ${anonymousUser.userId} to registered user`);
                 return;
             }
-            // 同设备新账号，创建新用户
+            // New account on the same device; create a new user.
             yield user_aggregate_service.userAggregateService.createNewRegisteredUser(clerkUserId, email, fingerprintId, userName);
             console.log(`Created new user for device ${fingerprintId} with email ${email}`);
         }
@@ -175,7 +175,7 @@ function handleUserCreated(event) {
     });
 }
 /**
- * 处理用户删除事件
+ * Handle the user.deleted event.
  */
 function handleUserDeleted(event) {
     return tslib.__awaiter(this, void 0, void 0, function* () {

package/dist/app/api/webhook/clerk/user/route.mjs

@@ -18,10 +18,10 @@ function POST(request) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
         try {
-            // 获取原始请求体
+            // Read the raw request body.
             const rawBody = yield request.text();
             let event;
-            // 开发环境跳过签名校验
+            // Skip signature verification in development.
             if (process.env.NODE_ENV === 'development') {
                 console.log('Development mode: skipping webhook signature verification');
                 try {
@@ -33,22 +33,22 @@ function POST(request) {
                 }
             }
             else {
-                // 生产环境进行签名校验
+                // Verify the signature in production.
                 const headerPayload = yield headers();
                 const svix_id = headerPayload.get('svix-id');
                 const svix_timestamp = headerPayload.get('svix-timestamp');
                 const svix_signature = headerPayload.get('svix-signature');
-                // 如果缺少必要的header，返回错误
+                // Reject requests missing required headers.
                 if (!svix_id || !svix_timestamp || !svix_signature) {
                     return NextResponse.json({ error: 'Missing webhook headers' }, { status: 400 });
                 }
-                // 获取webhook signing secret
+                // Load the webhook signing secret.
                 const webhookSecret = process.env.CLERK_WEBHOOK_SECRET;
                 if (!webhookSecret) {
                     console.error('CLERK_WEBHOOK_SECRET is not configured');
                     return NextResponse.json({ error: 'Webhook configuration error' }, { status: 500 });
                 }
-                // 验证webhook签名
+                // Verify the webhook signature.
                 try {
                     const wh = new Webhook(webhookSecret);
                     event = wh.verify(rawBody, {
@@ -70,7 +70,7 @@ function POST(request) {
             }, event);
             let processingResult = { success: true, message: 'Event processed successfully' };
             try {
-                // 处理不同的事件类型
+                // Dispatch by event type.
                 const { type } = event;
                 switch (type) {
                     case 'user.created':
@@ -106,7 +106,7 @@ function POST(request) {
     });
 }
 /**
- * 处理用户创建事件
+ * Handle the user.created event.
  */
 function handleUserCreated(event) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -125,7 +125,7 @@ function handleUserCreated(event) {
             fingerprintId,
             userName
         });
-        // 检查必要参数
+        // Validate required fields.
         if (!fingerprintId) {
             console.error('Missing fingerprintId in webhook data, process flow error');
             return;
@@ -135,16 +135,16 @@ function handleUserCreated(event) {
             return;
         }
         try {
-            // 按fingerprintId查询该设备的所有未注销过的用户记录，注销过的记录相当于是死数据
+            // Find all non-deleted users for this device fingerprint.
             const existingUsers = yield userService.findListByFingerprintId(fingerprintId);
             if (!existingUsers || existingUsers.length === 0) {
                 console.error('Invalid fingerprintId in webhook data, process flow error');
                 return;
             }
-            // 查找email相同的记录
+            // Find an existing user with the same email.
             const sameEmailUser = existingUsers.find(user => user.email === email);
             if (sameEmailUser) {
-                // 同一账号，检查是否需要更新clerkUserId
+                // Same account; update clerkUserId if needed.
                 if (sameEmailUser.clerkUserId !== clerkUserId) {
                     yield userService.updateUser(sameEmailUser.userId, { clerkUserId, userName: userName, status: UserStatus.REGISTERED });
                     console.log(`Updated clerkUserId for user ${sameEmailUser.userId}`);
@@ -154,15 +154,15 @@ function handleUserCreated(event) {
                 }
                 return;
             }
-            // 查找匿名用户（email为空且clerkUserId为空）
+            // Find an anonymous user with no email or clerkUserId.
             const anonymousUser = existingUsers.find(user => !user.email && !user.clerkUserId && user.status === UserStatus.ANONYMOUS);
             if (anonymousUser) {
-                // 匿名用户升级
+                // Upgrade the anonymous user.
                 yield userAggregateService.upgradeToRegistered(anonymousUser.userId, email, clerkUserId, userName);
                 console.log(`Successfully upgraded anonymous user ${anonymousUser.userId} to registered user`);
                 return;
             }
-            // 同设备新账号，创建新用户
+            // New account on the same device; create a new user.
             yield userAggregateService.createNewRegisteredUser(clerkUserId, email, fingerprintId, userName);
             console.log(`Created new user for device ${fingerprintId} with email ${email}`);
         }
@@ -173,7 +173,7 @@ function handleUserCreated(event) {
     });
 }
 /**
- * 处理用户删除事件
+ * Handle the user.deleted event.
  */
 function handleUserDeleted(event) {
     return __awaiter(this, void 0, void 0, function* () {

package/dist/auth/auth-utils.d.ts

@@ -1,9 +1,6 @@
 import { NextRequest } from 'next/server';
 import { User } from '../services/database/prisma-model-type';
 import { type AuthProvider, type ProviderIdentity } from './auth-shared';
-/**
- * 认证结果类型
- */
 export interface AuthResult {
     userId: string;
     user: User;
@@ -11,48 +8,36 @@ export interface AuthResult {
     providerUserId: string;
 }
 /**
- * 从中间件设置的 Clerk ID 获取完整用户信息
+ * Fetch User's info from header field by Middleware
  */
 export declare function getAuthenticatedUser(req: NextRequest): Promise<AuthResult>;
 /**
- * 要求用户必须已认证，返回用户ID
+ * Require Auth, success back user's id
  */
 export declare function requireAuth(req: NextRequest): Promise<string>;
 /**
- * 要求用户必须已认证，返回完整用户信息
+ * Require Auth, success back user's info
  */
 export declare function requireAuthWithUser(req: NextRequest): Promise<AuthResult>;
 /**
- * 服务端场景下获取当前已认证身份（如果存在）
- * 适用于只依赖登录态、不需要查询业务用户的逻辑
+ * Only use in server side
+ * Server Component / Server Action, just need user's login status
  */
 export declare function getOptionalServerAuthIdentity(): Promise<ProviderIdentity | null>;
 /**
- * 服务端场景下获取当前已认证用户（如果存在）
- * 适用于 Server Component / Server Action 中基于登录态控制展示的逻辑
+ * Only use in server side
+ * Server Component / Server Action, need user's login status and user's data, will check db
  */
 export declare function getOptionalServerAuthUser(): Promise<AuthResult | null>;
 /**
- * API Route版本的认证工具函数
+ * API Route Auth Util
  */
 export declare class ApiAuthUtils {
     private req;
     constructor(req: NextRequest);
-    /**
-     * 要求用户必须已认证，返回用户ID
-     */
     requireAuth(): Promise<string>;
-    /**
-     * 要求用户必须已认证，返回完整用户信息
-     */
     requireAuthWithUser(): Promise<AuthResult>;
-    /**
-     * 获取用户ID（如果已认证）
-     */
     getUserId(): Promise<string | null>;
-    /**
-     * 获取完整用户信息（如果已认证）
-     */
     getUser(): Promise<AuthResult | null>;
 }
 //# sourceMappingURL=auth-utils.d.ts.map

package/dist/auth/auth-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-utils.d.ts","sourceRoot":"","sources":["../../src/auth/auth-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,IAAI,EAAE,MAAM,wCAAwC,CAAC;AAC9D,OAAO,EAA6B,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,YAAY,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuBhF;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAE/E;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAetF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAsB5E;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAc;gBAEb,GAAG,EAAE,WAAW;IAI5B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAIpC;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,UAAU,CAAC;IAIhD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASzC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAO5C"}
+{"version":3,"file":"auth-utils.d.ts","sourceRoot":"","sources":["../../src/auth/auth-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,IAAI,EAAE,MAAM,wCAAwC,CAAC;AAC9D,OAAO,EAA6B,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEpG,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,YAAY,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuBhF;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAE/E;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAetF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAsB5E;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAc;gBAEb,GAAG,EAAE,WAAW;IAItB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAI9B,mBAAmB,IAAI,OAAO,CAAC,UAAU,CAAC;IAI1C,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASnC,OAAO,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAO5C"}