This PR adds comprehensive documentation for cnpmcore's internal APIs,
enabling users to make direct HTTP requests without needing the cnpm
client with outdated dependencies.
## Background
Users requested documentation for internal APIs to avoid using the cnpm
client, which has outdated dependencies like `bagpipe` (11 years old)
and `npm-request` (9 years old). The primary use case is package
synchronization functionality that was previously only accessible
through the cnpm CLI.
## Changes
### New Documentation: `docs/internal-api.md`
Created a comprehensive 988-line API reference covering:
**Package Sync API** - The primary requested functionality:
- `PUT /-/package/:fullname/syncs` - Modern sync API
- `PUT /:fullname/sync` - Legacy sync API (cnpmjs.org compatibility)
- `GET /-/package/:fullname/syncs/:taskId` - Check sync status
- `GET /-/package/:fullname/syncs/:taskId/log` - View sync logs
**Additional APIs documented:**
- **Token Management**: Create, list, delete authentication tokens
- **Hook Management**: CRUD operations for webhooks
- **Package Administration**: Block/unblock packages (admin only)
- **Registry Management**: Manage multiple npm registries
- **Binary Sync**: List and browse binary packages
- **User Management**: User registration and authentication
### Documentation Features
- Complete curl examples for all endpoints
- Request/response schemas with validation rules
- Authentication requirements clearly marked
- Error handling with HTTP status codes
- Security considerations and best practices
- Real-world workflow examples
### Updated README.md
Added reference to the new internal API documentation to make it
discoverable.
## Usage Examples
Users can now sync packages directly:
```bash
# Trigger package sync
curl -X PUT \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{"tips": "API sync request"}' \
https://your-registry.com/-/package/lodash/syncs
# Check sync status
curl -H "Authorization: Bearer your-token" \
https://your-registry.com/-/package/lodash/syncs/task-id
# View sync logs
curl -H "Authorization: Bearer your-token" \
https://your-registry.com/-/package/lodash/syncs/task-id/log
```
## Validation
All documented endpoints have been verified against the actual
implementation in the controllers. The API paths, parameters, and
response formats match the codebase exactly.
This enables users to extract sync functionality and other operations
without dealing with outdated cnpm dependencies, directly addressing the
issue's core request.
Fixes#709.
<!-- START COPILOT CODING AGENT TIPS -->
---
💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: fengmk2 <156269+fengmk2@users.noreply.github.com>
Co-authored-by: MK (fengmk2) <fengmk2@gmail.com>
[skip ci]
close https://github.com/cnpm/cnpmcore/issues/821
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Introduced a GitHub Actions workflow to automate building, tagging,
publishing, and attesting Docker images for multiple platforms.
* **Documentation**
* Updated Docker deployment documentation to reflect the new image
repository and usage instructions.
* **Chores**
* Updated Docker build scripts and Dockerfiles for improved image
building and logging.
* Upgraded the "oxlint" development dependency.
* Removed the "prepare" script from project scripts.
* Adjusted TypeScript configuration to disable declaration file
generation and exclude test files from compilation.
* Updated linter configuration to allow additional code patterns.
* Improved code comments for better linting and error suppression.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
closes https://github.com/cnpm/cnpmcore/issues/731
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
- **New Features**
- Added support for PostgreSQL alongside MySQL, including a new database
setup script and comprehensive documentation for local development.
- Introduced a new CI job for PostgreSQL testing in the GitHub Actions
workflow.
- Enhanced the `README.md` and `DEVELOPER.md` files to provide clearer
instructions for using both database systems.
- Added new environment variable configurations for PostgreSQL in the
Docker deployment documentation.
- **Bug Fixes**
- Improved error handling in tests for duplicate entries to accommodate
both MySQL and PostgreSQL error messages.
- **Documentation**
- Updated setup instructions for PostgreSQL and clarified MySQL setup in
the documentation.
- Enhanced contributor information in the README.
- Expanded instructions for setting up Elasticsearch and Kibana,
including environment variable configurations.
- **Chores**
- Updated package dependencies to include PostgreSQL client libraries
and modified scripts to support both databases.
- Changed the base image in the Dockerfile to a newer Node.js version.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated setup instructions to reflect the requirement for MySQL 9,
removing references to MySQL 5.7 and 8.
- Removed outdated troubleshooting information related to MySQL 8
authentication issues.
- **Chores**
- Updated `.gitignore` to include `.egg/` and improved formatting for
`.DS_Store`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
* 📚 add doc for the trends API.
---------
* 📚 添加 trends api 相关文档
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added sections for `[Token]` and `[Trend]` in the Registry API
documentation.
- Introduced a new endpoint `GET /downloads/range/:start::end/:pkgName`
for fetching package download trends.
- Included sample response data for the `Trend` endpoint.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
> close#664 Missing a startup document for sync pkgs.
* 📚 Add doc for sync-setup
-------
> close#664 目前缺少一个启动文档，开启包同步服务
* 📚 添加 sync-setup 使用文档
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added a new guide for setting up package synchronization services
using `cnpmcore`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
