core.js

Extendable client for GitHub's REST & GraphQL APIs

• Usage
  • REST API example
  • GraphQL example
• Authentication
• Hooks
• Plugins
• LICENSE

Usage

Browsers	Load @octokit/core directly from cdn.pika.dev <script type="module"> import { Octokit } from "https://cdn.pika.dev/@octokit/core"; </script>
Node	Install with npm install @octokit/core const { Octokit } = require("@octokit/core"); // or: import { Octokit } from "@octokit/core";

REST API example

const octokit = new Octokit({ auth: `secret123` });

const response = await octokit.request("GET /orgs/:org/repos", {
  org: "octokit",
  type: "private"
});

See https://github.com/octokit/request.js for full documentation of the .request method.

GraphQL example

const octokit = new Octokit({ auth: `secret123` });

const response = await octokit.graphql(
  `query ($login: String!) {
    organization(login: $login) {
      repositories(privacy: PRIVATE) {
        totalCount
      }
    }
  }`,
  { login: "octokit" }
);

See https://github.com/octokit/graphql.js for full documentation of the .graphql method.

Authentication

The auth option is a string and can be one of

1. A personal access token
2. An OAuth token
3. A GitHub App installation token
4. A GitHub App JSON Web Token
5. A GitHub Action token (GITHUB_TOKEN environment variable)

More complex authentication strategies will be supported by passing an @octokit/auth instance (🚧 currently work in progress).

Hooks

You can customize Octokit's request lifecycle with hooks.

octokit.hook.before("request", async options => {
  validate(options);
});
octokit.hook.after("request", async (response, options) => {
  console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
  if (error.status === 304) {
    return findInCache(error.headers.etag);
  }

  throw error;
});
octokit.hook.wrap("request", async (request, options) => {
  // add logic before, after, catch errors or replace the request altogether
  return request(options);
});

See before-after-hook for more documentation on hooks.

Plugins

Octokit’s functionality can be extended using plugins. THe Octokit.plugin() method accepts a function or an array of functions and returns a new constructor.

A plugin is a function which gets two arguments:

1. the current instance
2. the Options passed to the constructor.

// index.js
const MyOctokit = require("@octokit/core").plugin([
  require("./lib/my-plugin"),
  require("octokit-plugin-example")
]);

const octokit = new MyOctokit({ greeting: "Moin moin" });
octokit.helloWorld(); // logs "Moin moin, world!"
octokit.request("GET /"); // logs "GET / - 200 in 123ms"

// lib/my-plugin.js
module.exports = (octokit, options = { greeting: "Hello" }) => {
  // add a custom method
  octokit.helloWorld = () => console.log(`${options.greeting}, world!`);

  // hook into the request lifecycle
  octokit.hook.wrap("request", async (request, options) => {
    const time = Date.now();
    const response = await request(options);
    console.log(
      `${options.method} ${options.url} – ${response.status} in ${Date.now() -
        time}ms`
    );
    return response;
  });
};

LICENSE

MIT