ghpj

This is a simple API client for GitHub Projects. The library is built with GitHub Projects API.

Install

# with npm
npm install --save-dev ghpj

# with yarn
yarn add -D ghpj

Usage

You can make up to 5,000 requests per hour when these requests are authorized with GitHub's personal access token. For unauthorized requests, the rate limit allows for up to 60 requests per hour. (Rate limiting - GitHub Developer)

How to authorize with GitHub Personal Access Token

1. Create a personal access token (Creating a personal access token for the command line - GitHub Help).

2. Use motdotla/dotenv to load your personal access token.

3. Make .env file in the root directory of your project and set the token. For example:

   PERSONAL_ACCESS_TOKEN=<personal_access_token>
   

4. You can access the environment variable with process.env.PERSONAL_ACCESS_TOKEN.

   import { QueryBuilder } from "ghpj";
   import * as dotenv from "dotenv";
   dotenv.config();
   
   const gh = new QueryBuilder({ token: process.env.PERSONAL_ACCESS_TOKEN! });

5. Don't forget to add .env to your .gitignore file.

Examples

import { QueryBuilder } from "ghpj";
import * as dotenv from "dotenv";
dotenv.config();

async function demo() {
  // skip 10 projects and fetch up to 2 projects with columns and cards.
  const gh = new QueryBuilder({ token: process.env.PERSONAL_ACCESS_TOKEN! });
  const data = await gh
    .select({ owner: "jane-doe" })
    .skip(10)
    .limit(2)
    .eagerLoad("columns", "cards")
    .fetch();
}

demo();

Methods

import { QueryBuilder } from "ghpj";
import * as dotenv from "dotenv";
dotenv.config();

// initialize
const gh = new QueryBuilder({ token: process.env.PERSONAL_ACCESS_TOKEN! });

select

• select({ owner: string }): this
• select({ owner: string, repo: string }): this
• select({ projectId: string | number }): this
• select({ columnId: string | number }): this

Specity results.

// fetch user projects
const userProjects = await gh.select({ owner: "jane-doe" }).fetch();

// fetch repository projects
const repoProjects = await gh
  .select({ owner: "jane-doe", repo: "hello-world" })
  .fetch();

// fetch columns.
const columns = await gh.select({ projectId: repoProjects[0].id }).fetch();

// fetch cards.
const cards = await gh.select({ columnId: columns[0].id }).fetch();

limit

• limit(n: number): this

Limit number of results.

// fetch only 7 projects
const projects = await gh.select({ owner: "jane-done" }).limit(7).fetch();

skip

• skip(n: number): this

Skip results.

// fetch the next 7 projects
const projects = await gh.select({ owner: "jane-done" }).skip(7).fetch();

eagerLoad

• eagerLoad(arg: 'columns'): this
• eagerLoad(arg: 'cards'): this
• eagerLoad(arg1: 'columns', arg2: 'cards'): this

Specify relationships to be eager loaded in the result set.

Projects have many columns. Columns have many cards. Therefore, columns are projects' children and cards are projects' grandchildren. As well, cards are columns' children.

const projects = await gh
  .select({ owner: "jane-doe" })
  .eagerLoad("columns", "cards")
  .fetch();

projects is array of projects which include columns and cards.

fetch

• fetch(): Promise<Project[] | Column[] | Card[]>

Ends the chain sequence and collects data.

fetchRateLimit

• fetchRateLimit(): Promise<RateLimitResponse>

Get rate limit status.

const rateLimitStatus = await gh.fetchRateLimit();

A response example:

{
  resources: {
    core: { limit: 5000, used: 111, remaining: 4889, reset: 1599749076 },
    search: { limit: 30, used: 0, remaining: 30, reset: 1599746130 },
    graphql: { limit: 5000, used: 17, remaining: 4983, reset: 1599749604 },
    integration_manifest: { limit: 5000, used: 0, remaining: 5000, reset: 1599749670 },
    source_import: { limit: 100, used: 0, remaining: 100, reset: 1599746130 },
    code_scanning_upload: { limit: 500, used: 0, remaining: 500, reset: 1599749670 }
  },
  rate: { limit: 5000, used: 111, remaining: 4889, reset: 1599749076 }
}

create

• create(requestData: { name: string, body?: string }): Promise<Project>
• create(param: { owner: string, repo: string }, requestData: { name: string, body?: string }): Promise<Project>
• create(param: { projectId: string | number }, requestData: { name: string }): Promise<Column>
• create(param: { columnId: string | number }, requestData: { note: string }): Promise<Card>
• create(param: { columnId: string | number }, requestData: { content_id: string | number, content_type: 'Issue' | 'PullRequest' }): Promise<Card>

Create a project, column or card.

get

• get(param: { projectId: string | number }): Promise<Project>
• get(param: { columnId: string | number }): Promise<Column>
• get(param: { cardId: string | number }): Promise<Card>

Get a project, column or card.

update

• update(param: { projectId: string | number }, requestData: { name?: string, body?: string, state?: 'open' | 'closed', organization_permission?: 'read' | 'write' | 'admin' | 'none', private?: boolean }): Promise<Project>
• update(param: { columnId: string | number }, requestData: { name?: string }): Promise<Column>
• update(param: { cardId: string | number }, requestData: { note?: string, archived?: boolean }): Promise<Card>

Update a project, column or card.

delete

• delete(param: { projectId: string | number }): Promise<any>
• delete(param: { columnId: string | number }): Promise<any>
• delete(param: { cardId: string | number }): Promise<any>

Delete a project, column or card.