git-contribution-stats/README.md

High-performance library to generate GitHub contribution reports with timeout controls, circuit breakers, and selective processing for AWS Lambda and background jobs

# GitHub Activity Report ⚡

A high-performance library to generate activity reports for GitHub App installations. This library collects statistics about commits and pull requests across all repositories accessible by your GitHub App.

## 🚀 Key Features

- **⏱️ Timeout Controls**: Individual and global timeouts to prevent Lambda timeouts
- **🛡️ Circuit Breakers**: Skip large installations that cause performance issues  
- **🎯 Selective Processing**: Target specific installations or exclude problematic ones
- **🔄 Error Recovery**: Continue processing even when individual installations fail
- **📊 Detailed Monitoring**: Progress callbacks and comprehensive error reporting
- **⚡ Performance Optimized**: Limit repositories and branches for faster execution

## Installation

```bash
npm install git-contribution-stats
```

## 🎯 Quick Start

### Basic Usage
```typescript
import { generateGitHubReport } from 'git-contribution-stats'

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 7
});

console.log(report.summary);
console.log(`Success: ${report.success}`);
console.log(`Processed: ${report.processed_installations}/${report.total_installations}`);
```

### Lambda-Optimized (Conservative Mode)
```typescript
const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 3,
  
  // Timeout controls
  timeout_per_installation: 15000,      // 15s per installation
  max_total_timeout: 45000,             // 45s total
  
  // Performance limits
  max_repositories_per_installation: 20,
  max_branches_per_repository: 50,
  
  // Error handling
  continue_on_error: true,
  partial_results_on_timeout: true,
  
  // Skip problematic installations
  exclude_installations: ['large-org'],
  priority_mode: 'smallest_first'
});
```

### Background Jobs (Full Mode)
```typescript
const progressCallback = {
  onInstallationStart: (installation, index, total) => {
    console.log(`Processing ${index}/${total}: ${installation.account.login}`)
  },
  onTimeout: (installation, elapsed) => {
    console.log(`⚠️ ${installation.account.login} timed out after ${elapsed}ms`)
  }
}

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 7,
  timeout_per_installation: 120000,     // 2min per installation
  continue_on_error: true,
  retry_failed_installations: 2
}, progressCallback);
```

## 📋 Configuration Options

```typescript
interface GitHubActivityConfig {
  // Required
  app_id: number
  private_key: string
  
  // Basic options
  days_to_look_back?: number              // Default: 7
  logger?: Logger
  
  // ⏱️ Timeout controls
  timeout_per_installation?: number       // Timeout per installation (ms)
  max_total_timeout?: number             // Global timeout (ms)
  
  // 🛡️ Performance filters
  max_repositories_per_installation?: number
  max_branches_per_repository?: number
  skip_large_installations?: boolean
  installation_size_threshold?: number
  
  // 🎯 Selective processing
  target_installations?: string[]         // Process only these
  exclude_installations?: string[]        // Skip these
  priority_mode?: 'smallest_first' | 'largest_first' | 'sequential'
  
  // 🔄 Error handling
  continue_on_error?: boolean            // Default: false
  retry_failed_installations?: number    // Default: 0
  partial_results_on_timeout?: boolean   // Default: false
}
```

## 📊 Progress Monitoring

```typescript
const progressCallback = {
  onInstallationStart: (installation, index, total) => {
    console.log(`🚀 Starting ${index}/${total}: ${installation.account.login}`)
  },
  onInstallationComplete: (installation, stats) => {
    console.log(`✅ Completed: ${installation.account.login}`)
  },
  onInstallationError: (installation, error) => {
    console.log(`❌ Error: ${installation.account.login} - ${error.message}`)
  },
  onTimeout: (installation, elapsed) => {
    console.log(`⏱️ Timeout: ${installation.account.login} after ${elapsed}ms`)
  }
}
```

## 📈 Report Data Structure

### Enhanced Result Format
```typescript
interface GitHubReportResult {
  success: boolean                    // Overall success
  total_installations: number         // Total installations found
  processed_installations: number     // Successfully processed
  failed_installations: string[]      // Failed installation names
  partial_timeout: boolean           // Whether global timeout occurred
  execution_time: number             // Total execution time (ms)
  summary: string                    // Formatted text report
  detailed_results: (InstallationStats | InstallationError)[]
  errors: Array<{                    // Detailed error log
    installation_id: string
    error: string
    timestamp: number
  }>
}
```

### Example Output
```
📊 Statistics for my-org (Organization) - Last 3 days:

👤 user1 (ID: 12345):
  Total: 15 commits, 3 PRs opened, 2 PRs closed
  Contributions by repository:
    - repo1: 10 commits, 2 PRs opened, 1 PRs closed
    - repo2: 5 commits, 1 PRs opened, 1 PRs closed
```

## � Common Use Cases

### 1. AWS Lambda (60s timeout)
```typescript
const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  days_to_look_back: 1,
  timeout_per_installation: 12000,      // 12s per installation
  max_total_timeout: 50000,             // 50s total (safety margin)
  max_repositories_per_installation: 10,
  exclude_installations: ['huge-org'],
  continue_on_error: true,
  partial_results_on_timeout: true
});
```

### 2. Skip Large Organizations
```typescript
const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  skip_large_installations: true,
  installation_size_threshold: 50,      // Skip if >50 repos
  continue_on_error: true
});
```

### 3. Process Specific Organizations Only
```typescript
const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  target_installations: ['my-org', 'partner-org'],
  priority_mode: 'smallest_first'
});
```

### 4. High Availability Mode
```typescript
const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  continue_on_error: true,
  retry_failed_installations: 2,
  timeout_per_installation: 30000
});
```

## 🔍 Troubleshooting

**Problem**: Lambda timeouts on large installations
**Solution**: Use conservative mode with timeouts and filters

**Problem**: Some installations have too many repositories
**Solution**: Use `max_repositories_per_installation` and `skip_large_installations`

**Problem**: Need to process only specific organizations
**Solution**: Use `target_installations` or `exclude_installations`

**Problem**: Want to continue even if some installations fail
**Solution**: Set `continue_on_error: true` and `partial_results_on_timeout: true`

## 🏃‍♂️ Running Locally

```bash
npx ts-node src/run.ts
```

Create `.env` file:
```
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=./path/to/private-key.pem
```


### Running Locally

run on terminal:

```npx ts-node src/run.ts````

.env: 

```
GITHUB_APP_ID=
GITHUB_PRIVATE_KEY_PATH=
````

## License

MIT