github-username-to-emails

Fetches any public emails associated with a GitHub username.
📧

Usage

You can run this as a standalone command, or by its Node.js API.

$3

``shell
npx github-username-to-emails joshuakgoldberg
`

`plaintext
Account email: github@joshuakgoldberg.com
Event Email(s): 12
- git@joshuakgoldberg.com, with names: Josh Goldberg, Josh Goldberg ✨
- ...
`

$3

`shell
npm i github-username-to-emails
`

`ts
import { getGitHubUsernameEmails } from "github-username-to-emails";

await getGitHubUsernameEmails({ username: "joshuakgoldberg" });

/*
{
account: 'github@joshuakgoldberg.com',
events: { 'git@joshuakgoldberg.com': [ 'Josh Goldberg ✨', 'Josh Goldberg' ] }
}
*/
`

Calling getGitHubUsernameEmails will try to find the user's email from two public data points:

- account: /users/${username}: public account information
- events: /users/{username}/events: commits pushed by the user
- This is stored as an object containing, under each email, the commit names associated with that email
- Note that these may be commits originally authored by other users, _not_ the user you're looking for

Note that account might be undefined and events might be {}.
Only publicly visible emails can be retrieved.

$3

auth is retrieved with octokit-from-auth, which defaults to process.env.GH_TOKEN, or failing that, gh auth token.
If neither is available then an auth token must be provided as an option.

| Option | Type | Description | Default |
| -------------- | -------- | ---------------------------------- | -------------------------------------------- |
| auth | string | Auth token for Octokit REST calls. | process.env.GH_TOKEN or $(gh auth token) |
| historyLimit | number | How many public events to look at. | 500 |
| username | string | GitHub user to check emails of. | |

`ts
await getGitHubUsernameEmails({
auth: "gho_abc123",
historyLimit: 9001,
username: "joshuakgoldberg",
});
`

Email Privacy

This package doesn't expose any data users aren't already providing to GitHub.
You can manually check the same data it looks at on:

1. A user's public GitHub profile
2. https://api.github.com/users//events

This package only serves as a convenience to same time searching through that data.

To hide your email from public view, see GitHub's _Setting your commit email address_ docs.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md.
Thanks! 📧

Contributors

Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧

> 💝 This package was templated with create-typescript-app` using the Bingo engine.