{"id":29857136,"url":"https://github.com/lukehagar/usage-statistics","last_synced_at":"2025-07-30T00:38:08.866Z","repository":{"id":307172107,"uuid":"1028596774","full_name":"LukeHagar/usage-statistics","owner":"LukeHagar","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-29T19:53:13.000Z","size":219,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T21:53:17.951Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukeHagar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T19:08:34.000Z","updated_at":"2025-07-29T19:53:08.000Z","dependencies_parsed_at":"2025-07-29T21:59:20.825Z","dependency_job_id":"5bce1802-e303-4cdd-af62-30a493d4f3a3","html_url":"https://github.com/LukeHagar/usage-statistics","commit_stats":null,"previous_names":["lukehagar/usage-statistics"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/LukeHagar/usage-statistics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeHagar%2Fusage-statistics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeHagar%2Fusage-statistics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeHagar%2Fusage-statistics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeHagar%2Fusage-statistics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukeHagar","download_url":"https://codeload.github.com/LukeHagar/usage-statistics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeHagar%2Fusage-statistics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267785980,"owners_count":24144124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-30T00:38:07.419Z","updated_at":"2025-07-30T00:38:08.855Z","avatar_url":"https://github.com/LukeHagar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Usage Statistics Tracker\n\nA comprehensive GitHub Action for tracking download statistics across multiple platforms (NPM, GitHub, PyPI, Homebrew, PowerShell, Postman, Go) with configurable outputs and README integration.\n\n## 🚀 Features\n\n- 📊 **Multi-Platform Tracking**: NPM, GitHub, PyPI, Homebrew, PowerShell, Postman, Go\n- 🎭 **Preview Mode**: Test with mock data without external API calls\n- 📄 **Flexible Outputs**: JSON, CSV, and human-readable reports\n- 📝 **README Integration**: Auto-update README with statistics\n- ⚙️ **Configurable**: Custom configurations via JSON or preset modes\n- 🔄 **GitHub Actions Ready**: Built for CI/CD workflows\n- 🧪 **Comprehensive Testing**: Full test suite with Bun\n\n## 📦 Installation\n\n### As a GitHub Action\n\n```yaml\n- name: Usage Statistics Tracker\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    npm-packages: 'lodash,axios'\n    github-repositories: 'microsoft/vscode,facebook/react'\n    pypi-packages: 'requests,numpy'\n    homebrew-formulas: 'git,node'\n    powershell-modules: 'PowerShellGet,PSReadLine'\n    postman-collections: '12345,67890'\n    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'\n    json-output-path: 'stats.json'\n    csv-output-path: 'stats.csv'\n    report-output-path: 'report.md'\n    update-readme: 'true'\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n### Local Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run the tracker\nbun start\n\n# Preview mode (no external API calls)\nbun preview\n\n# Run tests\nbun test\n```\n\n## 🔧 Configuration\n\n### Input Parameters\n\n| Parameter | Description | Required | Default |\n|-----------|-------------|----------|---------|\n| `npm-packages` | Comma-separated list of NPM packages | No | (empty) |\n| `github-repositories` | Comma-separated list of GitHub repos (owner/repo) | No | (empty) |\n| `pypi-packages` | Comma-separated list of PyPI packages | No | (empty) |\n| `homebrew-formulas` | Comma-separated list of Homebrew formulas | No | (empty) |\n| `powershell-modules` | Comma-separated list of PowerShell modules | No | (empty) |\n| `postman-collections` | Comma-separated list of Postman collection IDs | No | (empty) |\n| `go-modules` | Comma-separated list of Go modules | No | (empty) |\n| `json-output-path` | Path for JSON output | No | `stats.json` |\n| `csv-output-path` | Path for CSV output | No | (empty) |\n| `report-output-path` | Path for human-readable report | No | (empty) |\n| `update-readme` | Whether to update README | No | `true` |\n| `readme-path` | Path to README file | No | `README.md` |\n| `github-token` | GitHub token for API access | No | `${{ github.token }}` |\n| `postman-api-key` | Postman API key | No | (empty) |\n| `commit-message` | Commit message for changes | No | `chore: update usage statistics [skip ci]` |\n| `preview-mode` | Run with mock data | No | `false` |\n\n### Configuration Examples\n\n#### NPM Packages Only\n```yaml\n- name: Usage Statistics Tracker\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    npm-packages: 'lodash,axios,react'\n```\n\n#### GitHub Repositories Only\n```yaml\n- name: Usage Statistics Tracker\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    github-repositories: 'microsoft/vscode,facebook/react,vercel/next.js'\n```\n\n#### Mixed Platform Configuration\n```yaml\n- name: Usage Statistics Tracker\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    npm-packages: 'lodash,axios'\n    github-repositories: 'microsoft/vscode,facebook/react'\n    pypi-packages: 'requests,numpy'\n    homebrew-formulas: 'git,node'\n    powershell-modules: 'PowerShellGet,PSReadLine'\n    postman-collections: '12345,67890'\n    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'\n```\n\n### Outputs\n\n| Output | Description |\n|--------|-------------|\n| `json-output` | Path to the generated JSON file |\n| `csv-output` | Path to the generated CSV file |\n| `report-output` | Path to the generated report file |\n| `total-downloads` | Total downloads across all platforms |\n| `unique-packages` | Number of unique packages tracked |\n| `platforms-tracked` | Comma-separated list of platforms tracked |\n\n## 📋 Usage Examples\n\n### Basic Usage\n\n```yaml\nname: Update Usage Statistics\n\non:\n  schedule:\n    - cron: '0 0 * * *'  # Daily at midnight\n  workflow_dispatch:\n\njobs:\n  update-stats:\n    runs-on: ubuntu-latest\n    \n    steps:\n    - name: Checkout code\n      uses: actions/checkout@v4\n\n    - name: Usage Statistics Tracker\n      uses: LukeHagar/usage-statistics@v1\n      with:\n        npm-packages: 'lodash,axios'\n        github-repositories: 'microsoft/vscode,facebook/react'\n        pypi-packages: 'requests,numpy'\n        homebrew-formulas: 'git,node'\n        powershell-modules: 'PowerShellGet,PSReadLine'\n        postman-collections: '12345,67890'\n        go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'\n        json-output-path: 'stats.json'\n        update-readme: 'true'\n        github-token: ${{ secrets.GITHUB_TOKEN }}\n\n    - name: Commit and push changes\n      run: |\n        git config user.name \"github-actions[bot]\"\n        git config user.email \"github-actions[bot]@users.noreply.github.com\"\n        git add stats.json README.md\n        git commit -m \"chore: update usage statistics [skip ci]\" || echo \"No changes to commit\"\n        git push\n```\n\n### Advanced Usage with Multiple Outputs\n\n```yaml\n- name: Usage Statistics Tracker\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    npm-packages: 'lodash,axios,react'\n    github-repositories: 'microsoft/vscode,facebook/react'\n    pypi-packages: 'requests,numpy'\n    homebrew-formulas: 'git,node'\n    powershell-modules: 'PowerShellGet,PSReadLine'\n    postman-collections: '12345,67890'\n    go-modules: 'github.com/gin-gonic/gin,github.com/go-chi/chi'\n    json-output-path: 'data/stats.json'\n    csv-output-path: 'data/stats.csv'\n    report-output-path: 'docs/usage-report.md'\n    update-readme: 'true'\n    readme-path: 'README.md'\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}\n    commit-message: 'feat: update usage statistics with detailed report'\n```\n\n### Preview Mode for Testing\n\n```yaml\n- name: Test Usage Statistics\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    preview-mode: 'true'\n    json-output-path: 'test-stats.json'\n    csv-output-path: 'test-stats.csv'\n    report-output-path: 'test-report.md'\n    update-readme: 'false'\n```\n\n### Using Outputs in Subsequent Steps\n\n```yaml\n- name: Usage Statistics Tracker\n  id: stats\n  uses: LukeHagar/usage-statistics@v1\n  with:\n    npm-packages: 'lodash,axios'\n    github-repositories: 'microsoft/vscode,facebook/react'\n    powershell-modules: 'PowerShellGet'\n    postman-collections: '12345'\n    go-modules: 'github.com/gin-gonic/gin'\n    json-output-path: 'stats.json'\n\n- name: Use Statistics Data\n  run: |\n    echo \"Total downloads: ${{ steps.stats.outputs.total-downloads }}\"\n    echo \"Unique packages: ${{ steps.stats.outputs.unique-packages }}\"\n    echo \"Platforms: ${{ steps.stats.outputs.platforms-tracked }}\"\n    echo \"JSON file: ${{ steps.stats.outputs.json-output }}\"\n```\n\n## 📊 README Integration\n\nTo enable automatic README updates, add these markers to your README.md:\n\n```markdown\n\u003c!-- USAGE_STATS_START --\u003e\n## 📊 Usage Statistics\n\nLast updated: 2025-07-29T18:53:52.619Z\n\n### Summary\n- **Total Downloads**: 414,533\n- **Unique Packages**: 8\n- **Platforms Tracked**: npm, pypi, homebrew, go\n\n### Platform Totals\n- **HOMEBREW**: 380,163 downloads (2 packages)\n- **NPM**: 34,311 downloads (2 packages)\n- **GO**: 33 downloads (2 packages)\n\n### Top Packages\n1. **node** (homebrew) - 226,882 downloads\n2. **git** (homebrew) - 153,281 downloads\n3. **axios** (npm) - 18,397 downloads\n4. **lodash** (npm) - 15,914 downloads\n5. **github.com/go-chi/chi** (go) - 33 downloads\n\u003c!-- USAGE_STATS_END --\u003e\n```\n\n## 🔧 Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) (version 1.0.0 or higher)\n\n### Local Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun dev\n\n# Run tests\nbun test\n\n# Build the action\nbun run action:build\n\n# Test the action locally\nbun run action:test\n```\n\n### Project Structure\n\n```\nusage-statistics/\n├── src/\n│   ├── index.ts          # Main library entry point\n│   ├── action.ts         # GitHub Action entry point\n│   ├── aggregator.ts     # Statistics aggregation\n│   ├── types/            # TypeScript type definitions\n│   ├── trackers/         # Platform-specific trackers\n│   └── utils/            # Utility functions\n├── .github/\n│   └── workflows/        # GitHub Actions workflows\n├── action.yml            # Action metadata\n├── package.json          # Project configuration\n└── README.md            # This file\n```\n\n## 🚀 Publishing to GitHub Marketplace\n\n### 1. Prepare Your Repository\n\n1. **Create a release tag**:\n   ```bash\n   git tag v1.0.0\n   git push origin v1.0.0\n   ```\n\n2. **Build the action**:\n   ```bash\n   bun run action:build\n   ```\n\n3. **Commit the built files**:\n   ```bash\n   git add dist/\n   git commit -m \"build: add action distribution files\"\n   git push\n   ```\n\n### 2. Publish to Marketplace\n\n1. Go to your repository on GitHub\n2. Click on the **Actions** tab\n3. Click **Publish this Action to the GitHub Marketplace**\n4. Fill in the required information:\n   - **Action name**: `usage-statistics-tracker`\n   - **Description**: `Track download statistics across multiple platforms`\n   - **Category**: `Data` or `Utilities`\n   - **Icon**: Upload an appropriate icon\n   - **Color**: Choose a brand color\n   - **README**: Use the content from this README\n\n### 3. Version Management\n\nFor each new version:\n\n```bash\n# Update version in package.json\n# Build the action\nbun run action:build\n\n# Create and push a new tag\ngit tag v1.1.0\ngit push origin v1.1.0\n```\n\n## 📈 Supported Platforms\n\n- **NPM**: Package download statistics\n- **GitHub**: Release download statistics\n- **PyPI**: Python package downloads\n- **Homebrew**: Formula installation statistics\n- **PowerShell**: Module download statistics\n- **Postman**: Collection fork/download statistics\n- **Go**: Module proxy statistics\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Bun](https://bun.sh/) for fast TypeScript execution\n- Uses [Octokit](https://github.com/octokit/octokit.js) for GitHub API integration\n- Inspired by the need for comprehensive usage analytics across multiple platforms","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukehagar%2Fusage-statistics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukehagar%2Fusage-statistics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukehagar%2Fusage-statistics/lists"}