docs: Add project documentation and metadata files

wangrunlin · wangrunlin · commit 14b3e9fb7ab8 · 2025-02-19T19:58:00.000+08:00
This commit adds several important documentation and metadata files to improve project transparency, contribution guidelines, and user information:

- Created CHANGELOG.md with initial release details
- Added CODE_OF_CONDUCT.md to establish community standards
- Created CONTRIBUTING.md with guidelines for bug reports, enhancements, and development
- Updated README files (English and Chinese) with comprehensive project information
- Added SECURITY.md to outline vulnerability reporting process
- Enhanced index.ts and types.ts with additional metadata and usage information
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-02-14
+
+### Added
+
+- Initial release
+- Basic GitHub achievements fetching functionality
+- Cache support
+- CORS support
+- Basic error handling
+- Documentation
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers responsible for enforcement at
+[INSERT CONTACT METHOD].
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing to GitHub Achievements API
+
+First off, thanks for taking the time to contribute! 🎉
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+- Use a clear and descriptive title
+- Describe the exact steps which reproduce the problem
+- Provide specific examples to demonstrate the steps
+- Describe the behavior you observed after following the steps
+- Explain which behavior you expected to see instead and why
+- Include screenshots if possible
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When you are creating an enhancement suggestion, please include:
+
+- Use a clear and descriptive title
+- Provide a step-by-step description of the suggested enhancement
+- Provide specific examples to demonstrate the steps
+- Describe the current behavior and explain which behavior you expected to see instead
+- Explain why this enhancement would be useful
+
+### Pull Requests
+
+- Fill in the required template
+- Follow the TypeScript coding style
+- Include appropriate test cases
+- Update the documentation accordingly
+
+## Development Process
+
+1. Fork the repo and create your branch from `main`
+2. Run `pnpm install` to install dependencies
+3. Make your changes
+4. Run `pnpm test` to ensure tests pass
+5. Push your changes and create a pull request
+
+## Style Guidelines
+
+- Use TypeScript
+- Follow the existing code style
+- Write meaningful commit messages
+- Keep code clean and well-documented
+
+## Additional Notes
+
+- Please don't include unrelated changes in your pull request
+- Feel free to ask for help if you're unsure about something
diff --git a/README.md b/README.md
@@ -1,9 +1,22 @@
 # GitHub Achievements API
 
+<p align="center">
+  <img src="https://github.githubassets.com/images/modules/profile/achievements/pull-shark-default.png" width="100" height="100" alt="Pull Shark Achievement" />
+</p>
+
 [![License](https://img.shields.io/github/license/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/blob/main/LICENSE)
 [![GitHub package.json version](https://img.shields.io/github/package-json/v/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/blob/main/package.json)
 [![GitHub last commit](https://img.shields.io/github/last-commit/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/commits)
 [![Test Status](https://img.shields.io/github/actions/workflow/status/wangrunlin/github-achievements-api/test.yml?label=test)](https://github.com/wangrunlin/github-achievements-api/actions)
+[![Node Version](https://img.shields.io/node/v/github-achievements-api)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5.2-blue.svg)](https://www.typescriptlang.org/)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
+[![GitHub stars](https://img.shields.io/github/stars/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/network)
+[![GitHub issues](https://img.shields.io/github/issues/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/issues)
+[![Visitors](https://visitor-badge.laobi.icu/badge?page_id=wangrunlin.github-achievements-api)](https://github.com/wangrunlin/github-achievements-api)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-orange)](https://ko-fi.com/wangrunlin)
 
 English | [简体中文](README_zh.md)
 
@@ -65,6 +78,56 @@ GET https://<your-worker>.workers.dev/wangrunlin
 }
 ```
 
+## API Documentation
+
+### Rate Limiting
+
+This API inherits GitHub's rate limiting. Please be mindful of GitHub's rate limits when making requests.
+
+### Caching
+
+- Responses are cached for 1 hour to improve performance
+- Cache is automatically invalidated when new achievements are earned
+- Cache can be bypassed by adding `?nocache=true` to the request
+
+### Error Responses
+
+| Status Code | Description           |
+| ----------- | --------------------- |
+| 404         | User not found        |
+| 429         | Rate limit exceeded   |
+| 500         | Internal server error |
+
+Example error response:
+
+```json
+{
+	"error": "Failed to fetch GitHub achievements: Not Found"
+}
+```
+
+## Roadmap
+
+- [ ] Add support for achievement descriptions
+- [ ] Add support for achievement dates
+- [ ] Add support for achievement images
+- [ ] Add API key authentication
+- [ ] Add more detailed statistics
+- [ ] Add support for organization achievements
+- [ ] Add webhook notifications for new achievements
+
+## Sponsors
+
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
+
+[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/wangrunlin)
+
+[Other sponsorship options](https://alin.run/sponsor)
+
+## Who's using GitHub Achievements API?
+
+Are you using this API? [Let us know](https://github.com/wangrunlin/github-achievements-api/issues/new) and we'll add your logo here!
+
 ## Local Development
 
 ### Prerequisites
@@ -129,7 +192,32 @@ Issues and Pull Requests are welcome!
 
 [Leo Wang](https://github.com/wangrunlin)
 
+## Available Achievements
+
+Here are all the achievements currently available on GitHub:
+
+[View more details about GitHub Achievements](https://github.com/drknzz/GitHub-Achievements)
+
+| Achievement                                                                                                                            | Name                  | Description                                                         | Max Tiers |
+| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------- | --------- |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/starstruck-default.png" width="60px">                    | Starstruck            | Created a repository that has 16 stars                              | 4         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/quickdraw-default.png" width="60px">                     | Quickdraw             | Closed an issue/PR within 5 minutes of opening                      | 1         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/pair-extraordinaire-default.png" width="60px">           | Pair Extraordinaire   | Coauthored in merged pull request                                   | 3         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/pull-shark-default.png" width="60px">                    | Pull Shark            | Opened a pull request that has been merged                          | 3         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/galaxy-brain-default.png" width="60px">                  | Galaxy Brain          | Answered a discussion with an accepted answer                       | 4         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/yolo-default.png" width="60px">                          | YOLO                  | Merged a pull request without code review                           | 1         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/arctic-code-vault-contributor-default.png" width="60px"> | Arctic Code Vault     | Contributed code to repositories in the 2020 GitHub Archive Program | 1         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/public-sponsor-default.png" width="60px">                | Public Sponsor        | Sponsored an open source contributor through GitHub Sponsors        | 1         |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/mars-2020-contributor-default.png" width="60px">         | Mars 2020 Contributor | Contributed code to repositories used in the Mars 2020 Mission      | 1         |
+
 ## Acknowledgments
 
-- GitHub Achievement System
-- Cloudflare Workers Platform
+Thanks to these awesome projects and resources:
+
+- [GitHub](https://github.com) - For providing the achievement system
+- [Cloudflare Workers](https://workers.cloudflare.com) - For the serverless platform
+- [GitHub Achievements List](https://github.com/drknzz/GitHub-Achievements) - For the comprehensive achievements documentation
+- [TypeScript](https://www.typescriptlang.org) - For the typed JavaScript
+- [Vitest](https://vitest.dev) - For the testing framework
+- [Wrangler](https://developers.cloudflare.com/workers/wrangler/) - For the development & deployment tool
+- [pnpm](https://pnpm.io) - For the fast package manager
diff --git a/README_zh.md b/README_zh.md
@@ -1,9 +1,22 @@
 # GitHub Achievements API
 
+<p align="center">
+  <img src="https://github.githubassets.com/images/modules/profile/achievements/pull-shark-default.png" width="100" height="100" alt="Pull Shark 成就" />
+</p>
+
 [![License](https://img.shields.io/github/license/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/blob/main/LICENSE)
 [![GitHub package.json version](https://img.shields.io/github/package-json/v/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/blob/main/package.json)
 [![GitHub last commit](https://img.shields.io/github/last-commit/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/commits)
 [![Test Status](https://img.shields.io/github/actions/workflow/status/wangrunlin/github-achievements-api/test.yml?label=test)](https://github.com/wangrunlin/github-achievements-api/actions)
+[![Node Version](https://img.shields.io/node/v/github-achievements-api)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5.2-blue.svg)](https://www.typescriptlang.org/)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
+[![GitHub stars](https://img.shields.io/github/stars/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/network)
+[![GitHub issues](https://img.shields.io/github/issues/wangrunlin/github-achievements-api)](https://github.com/wangrunlin/github-achievements-api/issues)
+[![Visitors](https://visitor-badge.laobi.icu/badge?page_id=wangrunlin.github-achievements-api)](https://github.com/wangrunlin/github-achievements-api)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-orange)](https://ko-fi.com/wangrunlin)
 
 [English](README.md) | 简体中文
 
@@ -65,6 +78,56 @@ GET https://<your-worker>.workers.dev/wangrunlin
 }
 ```
 
+## API 文档
+
+### 速率限制
+
+本 API 继承了 GitHub 的速率限制。请注意在发送请求时遵守 GitHub 的速率限制规则。
+
+### 缓存机制
+
+- 响应结果缓存时间为 1 小时，以提高性能
+- 当获得新成就时，缓存会自动失效
+- 可以通过在请求中添加 `?nocache=true` 来绕过缓存
+
+### 错误响应
+
+| 状态码 | 描述           |
+| ------ | -------------- |
+| 404    | 用户未找到     |
+| 429    | 超出速率限制   |
+| 500    | 内部服务器错误 |
+
+错误响应示例：
+
+```json
+{
+	"error": "Failed to fetch GitHub achievements: Not Found"
+}
+```
+
+## 项目路线图
+
+- [ ] 添加成就描述支持
+- [ ] 添加成就获得日期支持
+- [ ] 添加成就图片支持
+- [ ] 添加 API 密钥认证
+- [ ] 添加更详细的统计信息
+- [ ] 添加组织成就支持
+- [ ] 添加新成就获得时的 webhook 通知
+
+## 赞助商
+
+成为赞助商来支持这个项目。您的 logo 将会出现在这里并链接到您的网站。
+
+[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/wangrunlin)
+
+[其他赞助方式](https://alin.run/sponsor)
+
+## 谁在使用 GitHub Achievements API？
+
+您正在使用这个 API 吗？[告诉我们](https://github.com/wangrunlin/github-achievements-api/issues/new)，我们会在这里添加您的 logo！
+
 ## 本地开发
 
 ### 前置要求
@@ -129,7 +192,32 @@ MIT
 
 [Leo Wang](https://github.com/wangrunlin)
 
+## 可获得的成就
+
+以下是目前 GitHub 上可获得的所有成就：
+
+[查看更多 GitHub 成就相关信息](https://github.com/drknzz/GitHub-Achievements)
+
+| 成就图标                                                                                                                               | 名称                  | 描述                                    | 最高等级 |
+| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------- | -------- |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/starstruck-default.png" width="60px">                    | Starstruck            | 创建的仓库获得 16 个星标                | 4        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/quickdraw-default.png" width="60px">                     | Quickdraw             | 在开启后 5 分钟内关闭了 Issue 或 PR     | 1        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/pair-extraordinaire-default.png" width="60px">           | Pair Extraordinaire   | 在已合并的 PR 中作为合作者              | 3        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/pull-shark-default.png" width="60px">                    | Pull Shark            | 创建的 PR 被合并                        | 3        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/galaxy-brain-default.png" width="60px">                  | Galaxy Brain          | 在讨论中的回答被采纳                    | 4        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/yolo-default.png" width="60px">                          | YOLO                  | 在没有代码审查的情况下合并 PR           | 1        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/arctic-code-vault-contributor-default.png" width="60px"> | Arctic Code Vault     | 为 2020 GitHub 存档计划中的仓库贡献代码 | 1        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/public-sponsor-default.png" width="60px">                | Public Sponsor        | 通过 GitHub Sponsors 赞助开源贡献者     | 1        |
+| <img src="https://github.githubassets.com/images/modules/profile/achievements/mars-2020-contributor-default.png" width="60px">         | Mars 2020 Contributor | 为火星 2020 任务中使用的仓库贡献代码    | 1        |
+
 ## 致谢
 
-- GitHub 提供的成就系统
-- Cloudflare Workers 平台
+感谢这些优秀的项目和资源：
+
+- [GitHub](https://github.com) - 提供成就系统
+- [Cloudflare Workers](https://workers.cloudflare.com) - 提供无服务器平台
+- [GitHub Achievements List](https://github.com/drknzz/GitHub-Achievements) - 提供完整的成就文档
+- [TypeScript](https://www.typescriptlang.org) - 提供类型化的 JavaScript
+- [Vitest](https://vitest.dev) - 提供测试框架
+- [Wrangler](https://developers.cloudflare.com/workers/wrangler/) - 提供开发和部署工具
+- [pnpm](https://pnpm.io) - 提供快速的包管理器
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within GitHub Achievements API, please send an email to [alin.runlin@gmail.com](mailto:alin.runlin@gmail.com). All security vulnerabilities will be promptly addressed.
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+## Security Update Process
+
+1. The security report will be reviewed
+2. A fix will be prepared
+3. A security advisory will be published
+4. The fix will be released
+
+Thank you for helping keep GitHub Achievements API secure!
diff --git a/src/index.ts b/src/index.ts
diff --git a/src/types.ts b/src/types.ts
