core.js

Extendable client for GitHub's REST & GraphQL APIs

Usage
- REST API example
- GraphQL example
Options
Defaults
Authentication
Hooks
Plugins
LICENSE

If you need a minimalistic library to utilize GitHub's REST API and GraphQL API which you can extend with plugins as needed, than @octokit/core is a great starting point.

If you don't need the Plugin API then using @octokit/request or @octokit/graphql directly is a good alternative.

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

// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit({ auth: `personal-access-token123` });

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

See @octokit/request 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 (@octokit/graphql](https://github.com/octokit/graphql.js) for full documentation of the .graphql method.

Options

name	type	description
`options.auth`	`String` or `@octokit/auth` instance	If set to a `String`, then it's expected to be a personal access token or OAuth access token and used accordingly in the `Authorization` header. For all other authentication strategies, set `options.auth` to a `@octokit/auth` instance. See Authentication below for examples.
`options.baseUrl`	`String`	When using with GitHub Enterprise Server, set `options.baseUrl` to the root URL of the API. For example, if your GitHub Enterprise Server's hostname is `github.acme-inc.com`, then set `options.baseUrl` to `https://github.acme-inc.com/api/v3`. Example const octokit = new Octokit({ baseUrl: "https://github.acme-inc.com/api/v3" });
`options.previews`	`Array of Strings`	Some REST API endpoints require preview headers to be set, or enable additional features. Preview headers can be set on a per-request basis, e.g. octokit.request("POST /repos/:owner/:repo/pulls", { mediaType: { previews: ["shadow-cat"] }, owner, repo, title: "My pull request", base: "master", head: "my-feature", draft: true }); You can also set previews globally, by setting the `options.previews` option on the constructor. Example: const octokit = new Octokit({ previews: ["shadow-cat"] });
`options.request`	`Object`	Set a default request timeout (`options.request.timeout`) or an `http(s).Agent` e.g. for proxy usage (Node only, `options.request.agent`). There are more `options.request.*` options, see `@octokit/request` options. `options.request` can also be set on a per-request basis.
`options.userAgent`	`String`	A custom user agent string for your app or library. Example const octokit = new Octokit({ userAgent: "my-app/v1.2.3" });

Defaults

You can create a new Octokit class with customized default options.

const MyOctokit = Octokit.defaults({
  auth: "personal-access-token123",
  baseUrl: "https://github.acme-inc.com/api/v3",
  userAgent: "my-app/v1.2.3"
});
const octokit1 = new MyOctokit();
const octokit2 = new MyOctokit();

Authentication

You can set options.auth to a token, which will be used to correctly set the Authorization header for the requests you do with octokit.request() and octokit.graphql(). Example

import { Octokit } from "@octokit/core";

const octokit = new Octokit({
  auth: "mypersonalaccesstoken123"
});

octokit.request("/user").then(response => console.log(response.data));

All other authentication strategies are supported using @octokit/auth, just pass the auth() method returned by any of the strategies as options.auth. Example

import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";

const octokit = new Octokit({
  auth: createAppAuth({
    id: 123,
    privateKey: process.env.PRIVATE_KEY
  )}
})

octokit.request('/app').then(response => console.log(response.data))

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:

the current instance
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

metttialinezhad / core.js