LukeParke/usage-statistics
1
0
Fork 0
mirror of https://github.com/LukeHagar/usage-statistics.git synced 2025-12-06 04:21:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Usage Statistics Tracker GitHub Action with configuration options, outputs, and README integration

Browse Source
This commit is contained in:
Luke Hagar
2025-07-29 14:19:22 -05:00
parent 7975dc0cbe
commit 1f24188c62
9 changed files with 937 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

405
README.md
View File

@@ -1,184 +1,323 @@
# Usage Statistics
# Usage Statistics Tracker
A Bun TypeScript script project for analyzing usage statistics with a clean, modern architecture.
A comprehensive GitHub Action for tracking download statistics across multiple platforms (NPM, GitHub, PyPI, Homebrew, PowerShell, Postman, Go) with configurable outputs and README integration.
## Features
## 🚀 Features
- 🚀 **Fast Execution**: Built with Bun for lightning-fast TypeScript execution
- 📊 **Usage Analytics**: Track user actions and generate statistics
- 🧪 **Comprehensive Testing**: Full test suite with Bun's built-in test runner
- 📦 **Modern Tooling**: TypeScript, ES modules, and modern JavaScript features
- 🔧 **Developer Friendly**: Hot reloading, watch mode, and excellent DX
- 📊 **Multi-Platform Tracking**: NPM, GitHub, PyPI, Homebrew, PowerShell, Postman, Go
- 🎭 **Preview Mode**: Test with mock data without external API calls
- 📄 **Flexible Outputs**: JSON, CSV, and human-readable reports
- 📝 **README Integration**: Auto-update README with statistics
- ⚙️ **Configurable**: Custom configurations via JSON or preset modes
- 🔄 **GitHub Actions Ready**: Built for CI/CD workflows
- 🧪 **Comprehensive Testing**: Full test suite with Bun
## Prerequisites
## 📦 Installation
- [Bun](https://bun.sh/) (version 1.0.0 or higher)
### As a GitHub Action
## Installation
```yaml
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: 'production'
json-output-path: 'stats.json'
csv-output-path: 'stats.csv'
report-output-path: 'report.md'
update-readme: 'true'
github-token: ${{ secrets.GITHUB_TOKEN }}
```
### Local Development
```bash
# Install dependencies
bun install
```
## Usage
### Running the Script
```bash
# Run the main script
# Run the tracker
bun start
# Preview the report with mock data (no external API calls)
# Preview mode (no external API calls)
bun preview
# Run in development mode with hot reloading
bun run dev
# Run directly with bun
bun run src/index.ts
# Run tests
bun test
```
### Preview Mode
## 🔧 Configuration
The preview mode allows you to see how the report will look without making any external API calls or writing files:
### Input Parameters
```bash
# Generate a preview report with mock data
bun preview
| Parameter | Description | Required | Default |
|-----------|-------------|----------|---------|
| `config` | Configuration mode or JSON | No | `production` |
| `json-output-path` | Path for JSON output | No | `stats.json` |
| `csv-output-path` | Path for CSV output | No | (empty) |
| `report-output-path` | Path for human-readable report | No | (empty) |
| `update-readme` | Whether to update README | No | `true` |
| `readme-path` | Path to README file | No | `README.md` |
| `github-token` | GitHub token for API access | No | `${{ github.token }}` |
| `postman-api-key` | Postman API key | No | (empty) |
| `commit-message` | Commit message for changes | No | `chore: update usage statistics [skip ci]` |
| `preview-mode` | Run with mock data | No | `false` |
# Or use the long flag
bun start --preview
### Configuration Modes
#### Production Mode
```yaml
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: 'production'
```
This is useful for:
- Testing the report format
- Demonstrating the functionality
- Development and debugging
- CI/CD testing without external dependencies
### Building
```bash
# Build the project
bun run build
#### Development Mode
```yaml
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: 'development'
```
### Testing
#### Custom JSON Configuration
```yaml
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: '{"npmPackages": ["lodash", "axios"], "githubRepositories": ["microsoft/vscode"]}'
```
### Outputs
| Output | Description |
|--------|-------------|
| `json-output` | Path to the generated JSON file |
| `csv-output` | Path to the generated CSV file |
| `report-output` | Path to the generated report file |
| `total-downloads` | Total downloads across all platforms |
| `unique-packages` | Number of unique packages tracked |
| `platforms-tracked` | Comma-separated list of platforms tracked |
## 📋 Usage Examples
### Basic Usage
```yaml
name: Update Usage Statistics
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight
workflow_dispatch:
jobs:
update-stats:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: 'production'
json-output-path: 'stats.json'
update-readme: 'true'
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Commit and push changes
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add stats.json README.md
git commit -m "chore: update usage statistics [skip ci]" || echo "No changes to commit"
git push
```
### Advanced Usage with Multiple Outputs
```yaml
- name: Usage Statistics Tracker
uses: your-username/usage-statistics@v1
with:
config: 'production'
json-output-path: 'data/stats.json'
csv-output-path: 'data/stats.csv'
report-output-path: 'docs/usage-report.md'
update-readme: 'true'
readme-path: 'README.md'
github-token: ${{ secrets.GITHUB_TOKEN }}
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
commit-message: 'feat: update usage statistics with detailed report'
```
### Preview Mode for Testing
```yaml
- name: Test Usage Statistics
uses: your-username/usage-statistics@v1
with:
preview-mode: 'true'
json-output-path: 'test-stats.json'
csv-output-path: 'test-stats.csv'
report-output-path: 'test-report.md'
update-readme: 'false'
```
### Using Outputs in Subsequent Steps
```yaml
- name: Usage Statistics Tracker
id: stats
uses: your-username/usage-statistics@v1
with:
config: 'production'
json-output-path: 'stats.json'
- name: Use Statistics Data
run: |
echo "Total downloads: ${{ steps.stats.outputs.total-downloads }}"
echo "Unique packages: ${{ steps.stats.outputs.unique-packages }}"
echo "Platforms: ${{ steps.stats.outputs.platforms-tracked }}"
echo "JSON file: ${{ steps.stats.outputs.json-output }}"
```
## 📊 README Integration
To enable automatic README updates, add these markers to your README.md:
```markdown
<!-- USAGE_STATS_START -->
## 📊 Usage Statistics
Last updated: 2025-07-29T18:53:52.619Z
### Summary
- **Total Downloads**: 414,533
- **Unique Packages**: 8
- **Platforms Tracked**: npm, pypi, homebrew, go
### Top Packages
1. **node** (homebrew) - 226,882 downloads
2. **git** (homebrew) - 153,281 downloads
3. **axios** (npm) - 18,397 downloads
4. **lodash** (npm) - 15,914 downloads
5. **github.com/go-chi/chi** (go) - 33 downloads
### Recent Activity
- **node** (homebrew) - 226,882 downloads on 7/29/2025
- **git** (homebrew) - 153,281 downloads on 7/29/2025
- **axios** (npm) - 722 downloads on 7/29/2025
- **lodash** (npm) - 857 downloads on 7/29/2025
- **axios** (npm) - 936 downloads on 7/28/2025
<!-- USAGE_STATS_END -->
```
## 🔧 Development
### Prerequisites
- [Bun](https://bun.sh/) (version 1.0.0 or higher)
### Local Development
```bash
# Run all tests
# Install dependencies
bun install
# Run in development mode
bun dev
# Run tests
bun test
# Run tests in watch mode
bun test --watch
# Build the action
bun run action:build
# Test the action locally
bun run action:test
```
## Project Structure
### Project Structure
```
usage-statistics/
├── src/
│ ├── index.ts # Main entry point
│ ├── index.test.ts # Test suite
│ └── test-setup.ts # Test configuration
│ ├── index.ts # Main library entry point
│ ├── action.ts # GitHub Action entry point
│ ├── config.ts # Configuration management
│ ├── aggregator.ts # Statistics aggregation
│ ├── types/ # TypeScript type definitions
│ ├── trackers/ # Platform-specific trackers
│ └── utils/ # Utility functions
├── .github/
│ └── workflows/ # GitHub Actions workflows
├── action.yml # Action metadata
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── bunfig.toml # Bun configuration
├── .gitignore # Git ignore rules
└── README.md # This file
```
## API Reference
## 🚀 Publishing to GitHub Marketplace
### UsageStatistics Class
### 1. Prepare Your Repository
The main class for tracking and analyzing usage data.
1. **Create a release tag**:
```bash
git tag v1.0.0
git push origin v1.0.0
```
#### Methods
2. **Build the action**:
```bash
bun run action:build
```
- `addUsage(userId: string, action: string, metadata?: Record<string, any>)`: Add a new usage record
- `getAllData()`: Get all usage data
- `getUserData(userId: string)`: Get usage data for a specific user
- `getActionData(action: string)`: Get usage data for a specific action
- `getStatistics()`: Get comprehensive statistics summary
3. **Commit the built files**:
```bash
git add dist/
git commit -m "build: add action distribution files"
git push
```
#### Example Usage
### 2. Publish to Marketplace
```typescript
import { UsageStatistics } from './src/index';
1. Go to your repository on GitHub
2. Click on the **Actions** tab
3. Click **Publish this Action to the GitHub Marketplace**
4. Fill in the required information:
- **Action name**: `usage-statistics-tracker`
- **Description**: `Track download statistics across multiple platforms`
- **Category**: `Data` or `Utilities`
- **Icon**: Upload an appropriate icon
- **Color**: Choose a brand color
- **README**: Use the content from this README
const stats = new UsageStatistics();
### 3. Version Management
// Add usage data
stats.addUsage("user1", "login", { browser: "chrome" });
stats.addUsage("user2", "logout");
// Get statistics
const summary = stats.getStatistics();
console.log(`Total records: ${summary.totalRecords}`);
```
## Development
### Scripts
- `bun start`: Run the main script
- `bun run dev`: Run in development mode with file watching
- `bun run build`: Build the project for production
- `bun test`: Run the test suite
### Adding Dependencies
For each new version:
```bash
# Add a production dependency
bun add <package-name>
# Update version in package.json
# Build the action
bun run action:build
# Add a development dependency
bun add -d <package-name>
# Create and push a new tag
git tag v1.1.0
git push origin v1.1.0
```
## GitHub Actions Integration
## 📈 Supported Platforms
This project includes a GitHub Actions workflow that automatically updates usage statistics and commits the results to the repository.
- **NPM**: Package download statistics
- **GitHub**: Release download statistics
- **PyPI**: Python package downloads
- **Homebrew**: Formula installation statistics
- **PowerShell**: Module download statistics
- **Postman**: Collection fork/download statistics
- **Go**: Module proxy statistics
### Setup
1. **Enable the workflow**: The workflow file is located at `.github/workflows/update-stats.yml`
2. **Configure your packages**: Update `src/config.ts` with your actual package names
3. **Set up environment variables** (if needed):
- `GITHUB_TOKEN`: Automatically provided by GitHub Actions
- `POSTMAN_API_KEY`: If tracking Postman collections
### Workflow Features
- **Scheduled runs**: Updates stats daily at 2 AM UTC
- **Manual triggering**: Can be run manually via GitHub Actions UI
- **Rate limiting**: Built-in rate limiting to avoid API abuse
- **Auto-commit**: Automatically commits `stats.json` and updates README
- **Error handling**: Graceful handling of API failures
### Customization
Edit `src/config.ts` to track your specific packages:
```typescript
export const defaultConfig: TrackingConfig = {
npmPackages: ['your-package-name'],
githubRepos: ['your-org/your-repo'],
// ... other platforms
};
```
### Manual Execution
Run locally with GitHub Action mode:
```bash
GITHUB_TOKEN=your_token bun run src/index.ts --action
```
## Contributing
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
@@ -187,6 +326,12 @@ GITHUB_TOKEN=your_token bun run src/index.ts --action
5. Run the test suite
6. Submit a pull request
## License
## 📄 License
This project is open source and available under the [MIT License](LICENSE).
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [Bun](https://bun.sh/) for fast TypeScript execution
- Uses [Octokit](https://github.com/octokit/octokit.js) for GitHub API integration
- Inspired by the need for comprehensive usage analytics across multiple platforms