{"id":30047347,"url":"https://github.com/usernamap/gh-insight-engine","last_synced_at":"2026-04-18T01:02:53.774Z","repository":{"id":307161059,"uuid":"1027952086","full_name":"usernamap/gh-insight-engine","owner":"usernamap","description":"AI‑powered GitHub analytics: Node.js + TypeScript, OpenAPI, MongoDB – instant, developer‑centric insights.","archived":false,"fork":false,"pushed_at":"2026-03-15T16:54:25.000Z","size":551,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-16T05:17:56.911Z","etag":null,"topics":["github","openai","rest-api","swagger-ui"],"latest_commit_sha":null,"homepage":"https://github.lucas-blanchard.com/docs/","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/usernamap.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-28T19:34:25.000Z","updated_at":"2026-03-15T16:54:28.000Z","dependencies_parsed_at":"2025-07-29T20:47:36.892Z","dependency_job_id":"95e12b98-9c21-4786-aac9-df98e61bfa0d","html_url":"https://github.com/usernamap/gh-insight-engine","commit_stats":null,"previous_names":["usernamap/gh-insight-engine"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/usernamap/gh-insight-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usernamap%2Fgh-insight-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usernamap%2Fgh-insight-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usernamap%2Fgh-insight-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usernamap%2Fgh-insight-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usernamap","download_url":"https://codeload.github.com/usernamap/gh-insight-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usernamap%2Fgh-insight-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31952208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"ssl_error","status_checked_at":"2026-04-18T00:39:20.671Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["github","openai","rest-api","swagger-ui"],"created_at":"2025-08-07T09:39:28.753Z","updated_at":"2026-04-18T01:02:53.768Z","avatar_url":"https://github.com/usernamap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Insight Engine\n\n[![Version](https://img.shields.io/badge/version-0.1.43-blue.svg)](https://github.com/usernamap/gh-insight-engine)\n[![npm](https://img.shields.io/badge/npm-v11.4.2-yellow.svg)](https://www.npmjs.com/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![rest api](https://img.shields.io/badge/Rest_API-green.svg)](https://github.lucas-blanchard.com)\n\n\n\u003e **The most powerful GitHub analytics API ever built** - Fetch, analyze, visualize, and optimize your development journey with comprehensive insights powered by AI.\n\n## 🚀 Features\n\n### Core Analytics\n- **Complete GitHub Profile Analysis** - Deep insights into your development patterns\n- **Repository Analytics** - DevOps maturity, code quality, and community health metrics\n- **AI-Powered Insights** - GPT-4 analysis of code quality, security, and career recommendations\n- **Real-time Data Collection** - Live GitHub API integration with graceful degradation\n\n### Advanced Capabilities\n- **Unified Refresh Endpoint** - Update all user data in one request (`POST /refresh/{username}`)\n- **Automatic Scheduling** - Configurable daily/weekly/monthly data updates\n- **Comprehensive Error Handling** - Partial success support with detailed reporting\n- **JWT Authentication** - Secure API access with GitHub token validation\n\n### Developer Experience\n- **OpenAPI Documentation** - Complete API specification with interactive docs\n- **TypeScript Strict Mode** - Full type safety and modern development practices\n- **Comprehensive Logging** - Detailed audit trail for debugging and monitoring\n- **Rate Limiting** - Respects GitHub API limits with intelligent throttling\n\n## 📋 Quick Start\n\n### Prerequisites\n- Node.js \u003e= 18.14.0\n- MongoDB (local or cloud)\n- [GitHub Classic Token](https://github.com/settings/tokens/new) with required scopes (*repo*, *user:email*, *read:user*, *read:org*, *read:packages*, *admin:repo_hook*\n\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/usernamap/gh-insight-engine.git\ncd gh-insight-engine\n\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your configuration\n\n# Initialize database\nnpm run db:push\n\n# Start development server\nnpm run dev\n```\n\n### Environment Configuration\n\n```env\n# Database\nDATABASE_URL=mongodb://localhost:27017/github_insight_engine\n\n# GitHub API\nGH_TOKEN=your_github_classic_token\nGITHUB_USERNAME=your_username\nGITHUB_FULL_NAME=Your Full Name\n\n# OpenAI (for AI analysis)\nOPENAI_API_KEY=your_openai_api_key\n\n# Server\nPORT=3000\nNODE_ENV=development\n\n# JWT Security\nJWT_SECRET=your_jwt_secret\n\n# Automatic Scheduling (Optional)\nSCHEDULE_ENABLED=false\nSCHEDULE_FREQUENCY=weekly\nSCHEDULE_TIME=02:00\nSCHEDULE_TIMEZONE=Europe/Paris\nSCHEDULE_AUTH_TOKEN=\n```\n\n## 🔧 API Usage\n\n### Authentication\n```bash\n# Login with GitHub token\ncurl -X POST http://localhost:3000/api/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"octocat\",\n    \"fullName\": \"The Octocat\",\n    \"githubToken\": \"ghp_xxxxxxxxxxxxxxxxxxxx\"\n  }'\n```\n\n### Complete Data Refresh\n```bash\n# Refresh all user data in one request\ncurl -X POST http://localhost:3000/api/refresh/octocat \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n```\n\n### Individual Operations\n```bash\n# Collect user profile\ncurl -X POST http://localhost:3000/api/users/octocat \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n\n# Collect repositories\ncurl -X POST http://localhost:3000/api/repositories/octocat \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n\n# Run AI analysis\ncurl -X POST http://localhost:3000/api/ai/octocat \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\"\n```\n\n## 📊 API Endpoints\n\n### Core Operations\n- `POST /api/auth/login` - GitHub token authentication\n- `POST /api/refresh/{username}` - **Complete data refresh** (NEW)\n- `POST /api/users/{username}` - Collect user profile\n- `POST /api/repositories/{username}` - Collect repositories\n- `POST /api/ai/{username}` - Run AI analysis\n\n### Data Retrieval\n- `GET /api/users/{username}` - Get user profile\n- `GET /api/repositories/{username}` - Get repositories with analytics\n- `GET /api/summary/{username}` - Get comprehensive developer summary\n- `GET /api/ai/{username}` - Get AI analysis results\n\n### System\n- `GET /api/health` - Health check\n- `GET /api/ping` - Connectivity test\n- `GET /api/ai/status` - AI service status\n\n## Automatic Scheduling\n\nThe application includes an automatic scheduling system that can update user data at configurable intervals without manual intervention.\n\n### Configuration\n\nEnable automatic scheduling by setting these environment variables:\n\n```env\n# Enable automatic scheduling\nSCHEDULE_ENABLED=true\n\n# Scheduling frequency (daily, weekly, monthly)\nSCHEDULE_FREQUENCY=weekly\n\n# Execution time in 24h format\nSCHEDULE_TIME=02:00\n\n# Timezone for execution\nSCHEDULE_TIMEZONE=Europe/Paris\n\n# Required user information\nGITHUB_USERNAME=your_github_username\nGITHUB_FULL_NAME=Your Full Name\nGH_TOKEN=your_github_classic_token\n```\n\n### How It Works\n\nThe scheduling service automatically:\n\n1. **Retrieves Authentication Tokens**: Calls `POST /auth/login` to get a valid JWT token\n2. **Manages Token Expiration**: Automatically renews tokens when they expire (24h default)\n3. **Executes Scheduled Updates**: Calls `POST /api/refresh/{username}` at the configured intervals\n4. **Handles Errors Gracefully**: Logs failures and continues operation\n\n### Features\n\n- **Automatic Token Management**: No manual token configuration required\n- **Flexible Scheduling**: Daily, weekly, or monthly updates\n- **Timezone Support**: Configurable timezone for execution\n- **Error Handling**: Robust error handling with detailed logging\n- **Status Monitoring**: Check scheduling status via service methods\n\n### Example Usage\n\n```typescript\nimport { SchedulingService } from '@/services/SchedulingService';\n\n// Get scheduling status\nconst status = SchedulingService.getInstance().getStatus();\nconsole.log('Scheduling enabled:', status.enabled);\nconsole.log('Next run:', status.nextRun);\n\n// Test configuration immediately\nconst success = await SchedulingService.getInstance().testConfiguration();\n```\n\n### Security\n\n- Tokens are automatically retrieved and managed\n- No manual token storage required\n- Automatic token renewal prevents expiration issues\n- All operations are logged for audit purposes\n\n## 🏗️ Architecture\n\n```\nGitHub API → Data Collection → MongoDB Storage → AI Analysis → API Response\n     ↓              ↓              ↓              ↓              ↓\n  Rate Limiting  Error Handling  Data Models  OpenAI GPT-4  JWT Auth\n```\n\n### Key Components\n- **GitHubService** - Handles all GitHub API interactions\n- **AIAnalysisService** - OpenAI GPT-4 integration for insights\n- **SchedulingService** - Automatic data refresh management\n- **RefreshController** - Unified endpoint for complete data updates\n\n## 🧪 Development\n\n```bash\n# Run tests\nnpm test\n\n# Type checking\nnpm run typecheck\n\n# Linting\nnpm run lint\n\n# Build for production\nnpm run build\n\n# Start production server\nnpm start\n```\n\n## 📚 Documentation\n\n- **API Documentation**: `http://localhost:3000/` (interactive OpenAPI docs)\n- **OpenAPI Spec**: `openapi.yaml`\n- **Technical Documentation**: [`docs/README.md`](docs/README.md)\n- **Contributing Guide**: [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- **Code of Conduct**: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)\n- **Security Policy**: [`SECURITY.md`](SECURITY.md)\n- **Changelog**: [`CHANGELOG.md`](CHANGELOG.md)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:\n\n- Setting up your development environment\n- Code style and conventions\n- Testing guidelines\n- Pull request process\n- Release procedures\n\nFor quick start:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🆘 Support\n\n- **Issues**: [GitHub Issues](https://github.com/usernamap/gh-insight-engine/issues)\n- **Documentation**: [API Docs](http://localhost:3000/)\n- **Discussions**: [GitHub Discussions](https://github.com/usernamap/gh-insight-engine/discussions)\n\n---\n\n**Built with ❤️ for the developer community**\n\n❤️ [Donation Link](https://lucas-blanchard.com/don) ❤️\n\n## 🏆 Acknowledgements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusernamap%2Fgh-insight-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusernamap%2Fgh-insight-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusernamap%2Fgh-insight-engine/lists"}