hubspy/README.md

A package to extract github metadata and total contributions for a github user.

![image](https://github.com/user-attachments/assets/db09ac7b-0b1d-4300-acc1-7b329662af73)

# HUBSPY

An npm package that enables fetching and analyzing GitHub user data, including repositories, contributions, and metadata. The package also provides utility functions for filtering and analyzing the fetched data.

You can see it live on [here](https://wrappedcode.vercel.app/)

## Features

- **Fetch GitHub User Metadata**: Retrieve basic user information such as the number of public repositories.
- **Fetch Repository Data**: Scrape repositories with details like stars, description, programming language, and last updated date.
- **Fetch Yearly Contributions**: Get the user's contributions grouped by year.
- **Filter and Analyze Repositories**: Find the most-starred repositories and analyze repository data based on programming languages and other criteria.
- **Check Valid GitHub Username**: Verify whether a GitHub username exists.

## Installation
npm:
```bash
npm install hubspy
```
yarn:

```bash
yarn add hubspy
```
pnpm:

```bash
pnpm add hubspy
```
## Usage

### Fetch GitHub User Metadata
```javascript
import fetchGithubUserMetadata from 'hubspy';

const username = 'torvalds';
(async () => {
    const userData = await fetchGithubUserMetadata(username);
    console.log(userData);
})();
```

### Fetch Repository Data
```javascript
import GetRepositoriesData from 'hubspy';

const username = 'torvalds';
(async () => {
    const repositories = await GetRepositoriesData(username);
    console.log(repositories);
})();
```

### Fetch Yearly Contributions
```javascript
import GetYearWiseContributions from 'hubspy';

const username = 'torvalds';
(async () => {
    const contributions = await GetYearWiseContributions(username);
    console.log(contributions);
})();
```

### Check Valid GitHub Username
```javascript
import checkValidUsernName from 'hubspy';

const username = 'torvalds';
(async () => {
    const isValid = await checkValidUsernName(username);
    console.log(isValid ? 'Valid username' : 'Invalid username');
})();
```

### Filter and Analyze Repository Data

#### Filter Repository
```javascript
import { filterRepository } from 'hubspy';

const repositories = [/* Array of RepositoryData */];
const year = 2023; // Optional
const mostStarredRepo = filterRepository(repositories, year);
console.log(mostStarredRepo);
```

#### Get Most Starred Repositories
```javascript
import { getMostStarredRepository } from 'hubspy';

const repositories = [/* Array of RepositoryData */];
const year = 2023; // Optional
const mostStarredRepos = getMostStarredRepository(repositories, year);
console.log(mostStarredRepos);
```

#### Get Top Languages
```javascript
import { getTopLanguages } from 'hubspy';

const repositories = [/* Array of RepositoryData */];
const year = 2023; // Optional
const topLanguages = getTopLanguages(repositories, year);
console.log(topLanguages);
```

## Types

The package uses the following TypeScript types for better developer experience:

### UserMetaData
```typescript
interface UserMetaData {
    login: string;
    id: number;
    public_repos: number;
    // other GitHub API fields...
}
```

### RepositoryData
```typescript
interface RepositoryData {
    name: string;
    description: string;
    starred: number;
    last_updated_at: number;
    top_language: string;
    link_href: string;
}
```

### YearContribution
```typescript
interface YearContribution {
    year: number;
    contributions: number;
}
```

### TopLanguageList
```typescript
interface TopLanguageList {
    language: string;
    percentage: string;
}
```

## Error Handling
All async functions throw an error if the request fails. Make sure to wrap calls in a `try-catch` block to handle errors gracefully.

## Contribution
Feel free to fork the repository and submit pull requests. Ensure that your code follows the existing coding style and is thoroughly tested.

## License
[MIT](LICENSE)

## Acknowledgments
- **Cheerio**: Used for HTML parsing.
- **GitHub API**: Used for fetching metadata.
## Prerequisites
| Setting        | Value             |
| -------------- | ----------------- |
| Runtime        | Nodejs>=(18.12.1) |
| Entrypoint     | `src/index.ts`    |
| Build Commands | `npm run start`   |

## Author
[Amit Jimiwal](https://www.github.com/amitjimiwal)
## Disclaimer
This package uses scraping techniques for certain features, which may be subject to changes in GitHub's UI or terms of service. Use responsibly.