copperwall/core.js

Extendable client for GitHub's REST & GraphQL APIs

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:

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