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

📊 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

📦 Installation

As a GitHub Action

- name: Usage Statistics Tracker
  uses: LukeHagar/usage-statistics@v1
  with:
    npm-packages: 'lodash,axios'
    github-repositories: 'microsoft/vscode,facebook/react'
    pypi-packages: 'requests,numpy'
    homebrew-formulas: 'git,node'
    powershell-modules: 'PowerShellGet,PSReadLine'
    postman-collections: '12345,67890'
    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'
    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

# Install dependencies
bun install

# Run the tracker
bun start

# Preview mode (no external API calls)
bun preview

# Run tests
bun test

🔧 Configuration

Input Parameters

Parameter	Description	Required	Default
`npm-packages`	Comma-separated list of NPM packages	No	(empty)
`github-repositories`	Comma-separated list of GitHub repos (owner/repo)	No	(empty)
`pypi-packages`	Comma-separated list of PyPI packages	No	(empty)
`homebrew-formulas`	Comma-separated list of Homebrew formulas	No	(empty)
`powershell-modules`	Comma-separated list of PowerShell modules	No	(empty)
`postman-collections`	Comma-separated list of Postman collection IDs	No	(empty)
`go-modules`	Comma-separated list of Go modules	No	(empty)
`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`

Configuration Examples

NPM Packages Only

- name: Usage Statistics Tracker
  uses: LukeHagar/usage-statistics@v1
  with:
    npm-packages: 'lodash,axios,react'

GitHub Repositories Only

- name: Usage Statistics Tracker
  uses: LukeHagar/usage-statistics@v1
  with:
    github-repositories: 'microsoft/vscode,facebook/react,vercel/next.js'

Mixed Platform Configuration

- name: Usage Statistics Tracker
  uses: LukeHagar/usage-statistics@v1
  with:
    npm-packages: 'lodash,axios'
    github-repositories: 'microsoft/vscode,facebook/react'
    pypi-packages: 'requests,numpy'
    homebrew-formulas: 'git,node'
    powershell-modules: 'PowerShellGet,PSReadLine'
    postman-collections: '12345,67890'
    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'

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

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: LukeHagar/usage-statistics@v1
      with:
        npm-packages: 'lodash,axios'
        github-repositories: 'microsoft/vscode,facebook/react'
        pypi-packages: 'requests,numpy'
        homebrew-formulas: 'git,node'
        powershell-modules: 'PowerShellGet,PSReadLine'
        postman-collections: '12345,67890'
        go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'
        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

- name: Usage Statistics Tracker
  uses: LukeHagar/usage-statistics@v1
  with:
    npm-packages: 'lodash,axios,react'
    github-repositories: 'microsoft/vscode,facebook/react'
    pypi-packages: 'requests,numpy'
    homebrew-formulas: 'git,node'
    powershell-modules: 'PowerShellGet,PSReadLine'
    postman-collections: '12345,67890'
    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'
    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

- name: Test Usage Statistics
  uses: LukeHagar/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

- name: Usage Statistics Tracker
  id: stats
  uses: LukeHagar/usage-statistics@v1
  with:
    npm-packages: 'lodash,axios'
    github-repositories: 'microsoft/vscode,facebook/react'
    powershell-modules: 'PowerShellGet'
    postman-collections: '12345'
    go-modules: 'github.com/gin-gonic/gin'
    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:

<!-- 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

### Platform Totals
- **HOMEBREW**: 380,163 downloads (2 packages)
- **NPM**: 34,311 downloads (2 packages)
- **GO**: 33 downloads (2 packages)

### 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
<!-- USAGE_STATS_END -->

🔧 Development

Prerequisites

Bun (version 1.0.0 or higher)

Local Development

# Install dependencies
bun install

# Run in development mode
bun dev

# Run tests
bun test

# Build the action
bun run action:build

# Test the action locally
bun run action:test

Project Structure

usage-statistics/
├── src/
│   ├── index.ts          # Main library entry point
│   ├── action.ts         # GitHub Action entry point
│   ├── 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
└── README.md            # This file

🚀 Publishing to GitHub Marketplace

1. Prepare Your Repository

Create a release tag:
```
git tag v1.0.0
git push origin v1.0.0
```
Build the action:
```
bun run action:build
```

Commit the built files:

git add dist/
git commit -m "build: add action distribution files"
git push

2. Publish to Marketplace

Go to your repository on GitHub
Click on the Actions tab
Click Publish this Action to the GitHub Marketplace
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

3. Version Management

For each new version:

# Update version in package.json
# Build the action
bun run action:build

# Create and push a new tag
git tag v1.1.0
git push origin v1.1.0

📈 Supported Platforms

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

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Bun for fast TypeScript execution
Uses Octokit for GitHub API integration
Inspired by the need for comprehensive usage analytics across multiple platforms