Class GitHubClient

Main entry point for the GitHub REST API client.

Example

const gh = new GitHubClient({ token: 'ghp_myPersonalAccessToken' });

const me       = await gh.currentUser();
const user     = await gh.user('octocat');
const repos    = await gh.user('octocat').repos({ sort: 'updated' });
const org      = await gh.org('github');
const repo     = await gh.repo('octocat', 'Hello-World');
const prs      = await gh.repo('octocat', 'Hello-World').pullRequests({ state: 'open' });
const commits  = await gh.repo('octocat', 'Hello-World').commits({ per_page: 10 });
const results  = await gh.searchRepos({ q: 'language:typescript stars:>1000' });

Constructors

constructor

new GitHubClient(options?: GitHubClientOptions): GitHubClient
Parameters
- options: GitHubClientOptions = {}
  Authentication and connection options
Returns GitHubClient
Throws
If apiUrl is not a valid URL
- Defined in src/GitHubClient.ts:134

Methods

advisories

advisories(
params?: AdvisoriesParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubAdvisory>>
Lists global security advisories from the GitHub Advisory Database.

GET /advisories
Parameters
- Optionalparams: AdvisoriesParams
  Optional filters: ghsa_id, cve_id, ecosystem, severity, cwe_id, is_withdrawn, sort, direction, per_page, page
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubAdvisory>>
A paged response of global advisories
Example
```
const advisories = await gh.advisories({ severity: 'critical', ecosystem: 'npm' });
```
- Defined in src/GitHubClient.ts:701

advisory

advisory(ghsaId: string, signal?: AbortSignal): Promise<GitHubAdvisory>
Fetches a single global security advisory by its GHSA ID.

GET /advisories/{ghsa_id}
Parameters
- ghsaId: string
  The GHSA identifier (e.g., 'GHSA-xxxx-xxxx-xxxx')
- Optionalsignal: AbortSignal
Returns Promise<GitHubAdvisory>
The advisory object
Example
```
const advisory = await gh.advisory('GHSA-1234-5678-9abc');
```
- Defined in src/GitHubClient.ts:718

advisoryByCve

advisoryByCve(
cveId: string,
signal?: AbortSignal,
): Promise<null | GitHubAdvisory>
Fetches a global security advisory by its CVE ID.

GET /advisories?cve_id={cveId}
Parameters
- cveId: string
  The CVE identifier (e.g., 'CVE-2021-44228')
- Optionalsignal: AbortSignal
Returns Promise<null | GitHubAdvisory>
The advisory object, or null if no advisory is found for the given CVE ID
Example
```
const advisory = await gh.advisoryByCve('CVE-2021-44228');
if (advisory) console.log(advisory.summary);
```
- Defined in src/GitHubClient.ts:736

createGist

createGist(data: CreateGistData, signal?: AbortSignal): Promise<GitHubGist>
Creates a new gist.

POST /gists
Parameters
- data: CreateGistData
  Gist files and optional description/visibility
- Optionalsignal: AbortSignal
Returns Promise<GitHubGist>
- Defined in src/GitHubClient.ts:684

currentUser

currentUser(signal?: AbortSignal): Promise<GitHubUser>
Fetches the authenticated user's profile.

GET /user
Parameters
- Optionalsignal: AbortSignal
Returns Promise<GitHubUser>
The authenticated user object
Example
```
const me = await gh.currentUser();
console.log(me.login); // 'octocat'
```
- Defined in src/GitHubClient.ts:502

gist

gist(gistId: string): GistResource
Returns a GistResource for a given gist ID.

The returned resource can be awaited directly to fetch the gist, or chained to access nested resources (comments, forks, star).
Parameters
- gistId: string
  The gist ID
Returns GistResource
A chainable gist resource
Example
```
const gist     = await gh.gist('abc123');
const comments = await gh.gist('abc123').comments();
await gh.gist('abc123').star();
```
- Defined in src/GitHubClient.ts:654

graphql

graphql<T>(
    query: string,
    variables?: Record<string, unknown>,
    signal?: AbortSignal,
): Promise<T>
Executes an arbitrary GitHub GraphQL query.

POST https://api.github.com/graphql
Type Parameters
- T
Parameters
- query: string
  The GraphQL query string
- Optionalvariables: Record<string, unknown>
  Optional query variables
- Optionalsignal: AbortSignal
  Optional AbortSignal
Returns Promise<T>
The data field of the GraphQL response
Throws
If the response contains GraphQL errors

Throws
If the HTTP request fails
Example
```
const result = await gh.graphql<{ viewer: { login: string } }>(`
  query { viewer { login } }
`);
console.log(result.viewer.login);
```
- Defined in src/GitHubClient.ts:485

issues

issues(
params?: IssuesParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubIssue>>
Lists issues assigned to the authenticated user across all repositories.

GET /issues

Note: GitHub returns pull requests as issues in this endpoint. Filter them out by checking for the absence of pull_request on each item.
Parameters
- Optionalparams: IssuesParams
  Optional filters: filter, state, labels, sort, direction, since, per_page, page
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubIssue>>
A paged response of issues
Example
```
// All open issues across all repos the user has access to
const { values } = await gh.issues({ filter: 'all', state: 'open' });
const realIssues = values.filter(i => !i.pull_request);
```
- Defined in src/GitHubClient.ts:841

listGists

listGists(
params?: GistsParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubGist>>
Lists gists for the authenticated user (or publicly if unauthenticated).

GET /gists
Parameters
- Optionalparams: GistsParams
  Optional filters: since, per_page, page
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubGist>>
- Defined in src/GitHubClient.ts:673

markAllNotificationsRead

markAllNotificationsRead(signal?: AbortSignal): Promise<void>
Marks all notifications as read.

PUT /notifications

Returns void — GitHub responds with 205 No Content on success.
Parameters
- Optionalsignal: AbortSignal
Returns Promise<void>
Example
```
await gh.markAllNotificationsRead();
```
- Defined in src/GitHubClient.ts:819

markNotificationRead

markNotificationRead(threadId: string, signal?: AbortSignal): Promise<void>
Marks a single notification thread as read.

PATCH /notifications/threads/{thread_id}

Returns void — GitHub responds with 205 No Content on success.
Parameters
- threadId: string
  The numeric thread ID (from GitHubNotification.id)
- Optionalsignal: AbortSignal
Returns Promise<void>
Example
```
await gh.markNotificationRead('123456789');
```
- Defined in src/GitHubClient.ts:803

notifications

notifications(
params?: NotificationsParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubNotification>>
Lists notifications for the authenticated user.

GET /notifications
Parameters
- Optionalparams: NotificationsParams
  Optional filters: all, participating, since, before, per_page, page
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubNotification>>
A paged response of notification threads
Example
```
// Only unread notifications
const { values } = await gh.notifications();

// All notifications including already-read ones
const { values } = await gh.notifications({ all: true });
```
- Defined in src/GitHubClient.ts:785

on

on<K extends "request">(event: K, callback: GitHubClientEvents[K]): this
Subscribes to a client event.
Type Parameters
- K extends "request"
Parameters
- event: K
- callback: GitHubClientEvents[K]
Returns this
Example
```
gh.on('request', (event) => {
  console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);
  if (event.error) console.error('Request failed:', event.error);
});
```
- Defined in src/GitHubClient.ts:149

org

org(name: string): OrganizationResource
Returns an OrganizationResource for a given GitHub organization, providing access to organization data and its repositories.

The returned resource can be awaited directly to fetch organization info, or chained to access nested resources.
Parameters
- name: string
  The organization's login name (e.g., 'github')
Returns OrganizationResource
A chainable organization resource
Example
```
const org   = await gh.org('github');
const repos = await gh.org('github').repos({ type: 'public' });
const prs   = await gh.org('github').repo('linguist').pullRequests({ state: 'open' });
```
- Defined in src/GitHubClient.ts:554

repo

repo(owner: string, name: string): RepositoryResource
Returns a RepositoryResource for a given owner and repository name.

Shortcut that works for both user repositories and organization repositories.
Parameters
- owner: string
  The owner login (user or organization)
- name: string
  The repository name
Returns RepositoryResource
A chainable repository resource
Example
```
const repo  = await gh.repo('octocat', 'Hello-World');
const prs   = await gh.repo('octocat', 'Hello-World').pullRequests();
```
- Defined in src/GitHubClient.ts:582

searchCode

searchCode(
params: SearchCodeParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubCodeResult>>
Searches for code using GitHub's search syntax.

GET /search/code
Parameters
- params: SearchCodeParams
  Search query and optional sort/order. q is required.
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubCodeResult>>
A paged response of code results with totalCount
Example
```
const results = await gh.searchCode({ q: 'addClass repo:jquery/jquery' });
console.log(`Found ${results.totalCount} files`);
results.values; // GitHubCodeResult[]
```
- Defined in src/GitHubClient.ts:948

searchIssues

searchIssues(
params: SearchIssuesParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubIssue>>
Searches for issues and pull requests using GitHub's search syntax.

GET /search/issues
Parameters
- params: SearchIssuesParams
  Search query and optional sort/order. q is required.
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubIssue>>
A paged response of issues/PRs with totalCount
Example
```
// Open PRs authored by a user
const results = await gh.searchIssues({ q: 'is:pr is:open author:octocat' });
console.log(`Found ${results.totalCount} pull requests`);

// Stale issues not updated in 30+ days
const stale = await gh.searchIssues({ q: 'is:issue is:open updated:<2024-01-01', sort: 'updated' });
```
- Defined in src/GitHubClient.ts:863

searchRepos

searchRepos(
params: SearchReposParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubRepository>>
Searches for repositories using GitHub's search syntax.

GET /search/repositories
Parameters
- params: SearchReposParams
  Search query and optional filters. q is required.
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubRepository>>
A paged response of repositories with totalCount
Example
```
const results = await gh.searchRepos({ q: 'language:typescript stars:>1000', sort: 'stars' });
console.log(`Found ${results.totalCount} repositories`);
```
- Defined in src/GitHubClient.ts:610

searchUsers

searchUsers(
params: SearchUsersParams,
signal?: AbortSignal,
): Promise<GitHubPagedResponse<GitHubUser>>
Searches for users using GitHub's search syntax.

GET /search/users
Parameters
- params: SearchUsersParams
  Search query and optional sort/order. q is required.
- Optionalsignal: AbortSignal
Returns Promise<GitHubPagedResponse<GitHubUser>>
A paged response of users with totalCount
Example
```
const results = await gh.searchUsers({ q: 'location:Berlin language:typescript', sort: 'followers' });
console.log(`Found ${results.totalCount} users`);
```
- Defined in src/GitHubClient.ts:905

user

user(login: string): UserResource
Returns a UserResource for a given GitHub login, providing access to user data and their repositories.

The returned resource can be awaited directly to fetch user info, or chained to access nested resources.
Parameters
- login: string
  The user's login name (e.g., 'octocat')
Returns UserResource
A chainable user resource
Example
```
const user  = await gh.user('octocat');
const repos = await gh.user('octocat').repos({ sort: 'updated' });
const pr    = await gh.user('octocat').repo('Hello-World').pullRequest(1).files();
```
- Defined in src/GitHubClient.ts:523

Class GitHubClient

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns GitHubClient

Throws

Methods

advisories

Parameters

Returns Promise<GitHubPagedResponse<GitHubAdvisory>>

Example

advisory

Parameters

Returns Promise<GitHubAdvisory>

Example

advisoryByCve

Parameters

Returns Promise<null | GitHubAdvisory>

Example

createGist

Parameters

Returns Promise<GitHubGist>

currentUser

Parameters

Returns Promise<GitHubUser>

Example

gist

Parameters

Returns GistResource

Example

graphql

Type Parameters

Parameters

Returns Promise<T>

Throws

Throws

Example

issues

Parameters

Returns Promise<GitHubPagedResponse<GitHubIssue>>

Example

listGists

Parameters

Returns Promise<GitHubPagedResponse<GitHubGist>>

markAllNotificationsRead

Parameters

Returns Promise<void>

Example

markNotificationRead

Parameters

Returns Promise<void>

Example

notifications

Parameters

Returns Promise<GitHubPagedResponse<GitHubNotification>>

Example

on

Type Parameters

Parameters

Returns this

Example

org

Parameters

Returns OrganizationResource

Example

repo

Parameters

Returns RepositoryResource

Example

searchCode

Parameters

Returns Promise<GitHubPagedResponse<GitHubCodeResult>>

Example

searchIssues

Parameters

Returns Promise<GitHubPagedResponse<GitHubIssue>>