Fix/expiry-time-format-conversion-bug

[NightYuYyy]

Summary

Fix expiresAt field parsing and validation in the user creation API, and enhance the response to include detailed user information with the generated default key.

Problem

After PR #273 introduced user expiration management, the expiresAt field in the CreateUserSchema had issues:

1. Format conversion bug: The schema only accepted strings and performed a simple empty-string check, not properly converting ISO 8601 date strings to Date objects
2. Missing validation: No validation for ensuring the date is in the future or within a reasonable limit
3. Field bypass: isEnabled and expiresAt values weren't passed through validation in addUser(), using raw input data instead of validated data
4. Incomplete response: The API only returned { ok: true } without the created user details or the generated API key

Related PRs:

• Follow-up to Feature-user-expiration #273 - This PR fixes bugs in the user expiration feature introduced there
• Related to Fix-expiration-time-display #286 - Both PRs improve user expiration handling

Solution

Schema Enhancement (src/lib/validation/schemas.ts)

• Replaced simple string transform with z.preprocess() for robust type handling:
  • Accepts Date objects, ISO 8601 strings, null, undefined, and empty strings
  • Properly validates Date objects (checks for NaN time)
  • Converts valid strings to Date objects
• Added validation refinements:
  • Future date check: "过期时间必须是将来时间" (Expiration must be in the future)
  • 10-year limit: "过期时间不能超过10年" (Expiration cannot exceed 10 years)

API Fix (src/actions/users.ts)

• Fixed isEnabled and expiresAt to use validated data instead of raw input
• Enhanced response to return complete user object and default key details
• The generated API key is returned only once during creation (security best practice)

Documentation Enhancement (src/app/api/actions/[...route]/route.ts, src/lib/api/action-adapter-openapi.ts)

• Added response schema with detailed user and key information
• Added requestExamples support to the OpenAPI adapter
• Provided three example scenarios:
  • basic: Simple user with defaults
  • withExpiry: User with ISO 8601 expiration date
  • withLimits: Enterprise user with full quota configuration

Changes

Core Changes

• src/lib/validation/schemas.ts - Robust expiresAt parsing with validation (+44/-5)
• src/actions/users.ts - Fix field pass-through and enhance response (+32/-4)

Supporting Changes

• src/app/api/actions/[...route]/route.ts - Add response schema and request examples (+69/-1)
• src/lib/api/action-adapter-openapi.ts - Add requestExamples option support (+14/-0)

Breaking Changes

Change	Impact	Migration
expiresAt now requires future date	API calls with past dates will fail validation	Update client code to ensure valid future dates
Response structure changed	Clients expecting { ok: true } will receive richer response	Update client code to handle new data.user and data.defaultKey fields

Testing

Manual Testing

1. Create user via API without expiresAt - should succeed with null expiration
2. Create user with ISO 8601 date string - should parse and validate correctly
3. Create user with past date - should fail with "过期时间必须是将来时间"
4. Create user with date > 10 years - should fail with "过期时间不能超过10年"
5. Verify response includes full user info and default key

Automated Tests

• Existing lint/typecheck should pass

Checklist

• Code follows project conventions
• Self-review completed
• Validation logic properly handles edge cases
• API documentation updated with examples

---

Description enhanced by Claude AI

[gemini-code-assist]

Summary of Changes

Hello @NightYuYyy, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求主要修复了 expiresAt 字段的格式转换和验证问题，并全面增强了用户创建功能。它通过引入新的用户属性、改进 API 响应结构以及在 API 文档中提供详细示例，提升了用户管理的灵活性和 API 的可理解性。同时，对 expiresAt 字段的严格验证确保了用户有效期数据的准确性和合理性。

Highlights

• 用户创建字段增强: 在用户创建过程中增加了 isEnabled 和 expiresAt 字段，以支持更灵活的用户状态和有效期管理。
• 用户创建响应模式更新: 更新了用户创建的响应模式，现在会返回详细的用户信息和新创建的默认密钥，提升了 API 的可用性。
• API 文档请求示例: 在 API 文档中引入了 requestExamples 功能，允许为不同的用户创建场景提供请求示例，从而改善了 API 文档的清晰度和易用性。
• expiresAt 字段验证优化: 对 expiresAt 字段的验证逻辑进行了优化，确保其必须是未来的日期，并且有效期不能超过当前日期起的十年，增强了数据完整性。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

此拉取请求成功地为用户创建过程增加了 isEnabled 和 expiresAt 字段，并通过返回详细的用户信息和默认密钥来增强 API。对 expiresAt 的验证也得到了显著改进。我的主要反馈是建议重构 CreateUserSchema 中的日期验证逻辑，以提高其健壮性和可维护性。

[github-actions]

Code Review Summary

This PR fixes expiry time format conversion and enhances the user creation API with a richer response schema, request examples, and proper validation. The changes are well-structured and improve both the API documentation and validation logic.

PR Size: S

• Lines changed: 169 (159 additions, 10 deletions)
• Files changed: 4

Issues Found

Category	Critical	High	Medium	Low
Logic/Bugs	0	0	0	0
Security	0	0	0	0
Error Handling	0	0	0	0
Types	0	0	0	0
Comments/Docs	0	0	0	0
Tests	0	0	0	0
Simplification	0	0	0	0

Review Coverage

• Logic and correctness - Clean
• Security (OWASP Top 10) - Clean
• Error handling - Clean
• Type safety - Clean
• Documentation accuracy - Clean
• Test coverage - No new tests required (validation logic changes)
• Code clarity - Good

Notes

The changes improve the codebase in several ways:

1. Enhanced expiresAt validation (src/lib/validation/schemas.ts:70-113): The new z.preprocess approach correctly handles multiple input types (Date objects, ISO strings, null/undefined/empty strings) and includes proper validation for future dates and 10-year limit.

2. Improved response schema (src/app/api/actions/[...route]/route.ts:66-89): The new responseSchema provides detailed type information for the API response, improving documentation and type safety.

3. Request examples (src/app/api/actions/[...route]/route.ts:94-137): The three examples (basic, withExpiry, withLimits) provide clear guidance for API consumers.

4. Correct use of validated data (src/actions/users.ts:293-294): The change from data.isEnabled to validatedData.isEnabled ensures the schema-processed value is used consistently.

5. Enhanced response data (src/actions/users.ts:308-333): Returning the created user and default key information provides better UX for API consumers.

---

Automated review by Claude AI