feat: plugin API

index.js

@@ -1,28 +1,9 @@
-module.exports = GitHubApi
+const factory = require('./lib/factory')
 
-const endpoint = require('@octokit/request').endpoint
-const Hook = require('before-after-hook')
-
-const parseClientOptions = require('./lib/parse-client-options')
-const requestWithDefaults = require('./lib/request-with-defaults')
-
-const PLUGINS = [
-  require('./lib/plugins/authentication'),
-  require('./lib/plugins/endpoint-methods'),
-  require('./lib/plugins/pagination')
+const CORE_PLUGINS = [
+  require('./plugins/authentication'),
+  require('./plugins/endpoint-methods'),
+  require('./plugins/pagination')
 ]
 
-function GitHubApi (options) {
-  const hook = new Hook()
-  const api = {
-    // NOTE: github.hook and github.plugin are experimental APIs
-    //       at this point and can change at any time
-    hook,
-    plugin: (pluginFunction) => pluginFunction(api),
-    request: requestWithDefaults(hook, endpoint, parseClientOptions(options))
-  }
-
-  PLUGINS.forEach(api.plugin)
-
-  return api
-}
+module.exports = factory(CORE_PLUGINS)

lib/constructor.js

@@ -0,0 +1,19 @@
+module.exports = Octokit
+
+const endpoint = require('@octokit/request').endpoint
+const Hook = require('before-after-hook')
+
+const parseClientOptions = require('./parse-client-options')
+const requestWithDefaults = require('./request-with-defaults')
+
+function Octokit (plugins, options) {
+  const hook = new Hook()
+  const api = {
+    hook,
+    request: requestWithDefaults(hook, endpoint, parseClientOptions(options))
+  }
+
+  plugins.forEach(pluginFunction => pluginFunction(api, options))
+
+  return api
+}

lib/factory.js

@@ -0,0 +1,10 @@
+module.exports = factory
+
+const Octokit = require('./constructor')
+const registerPlugin = require('./register-plugin')
+
+function factory (plugins) {
+  const Api = Octokit.bind(null, plugins)
+  Api.plugin = registerPlugin.bind(null, plugins)
+  return Api
+}

lib/register-plugin.js

@@ -0,0 +1,7 @@
+module.exports = registerPlugin
+
+const factory = require('./factory')
+
+function registerPlugin (plugins, pluginFunction) {
+  return factory(plugins.concat(pluginFunction))
+}

lib/plugins/authentication/before-request.js → plugins/authentication/before-request.js

@@ -3,7 +3,7 @@ module.exports = authenticationBeforeRequest
 const btoa = require('btoa-lite')
 const uniq = require('lodash/uniq')
 
-const deprecate = require('../../deprecate')
+const deprecate = require('../../lib/deprecate')
 
 function authenticationBeforeRequest (state, options) {
   if (!state.auth.type) {

lib/plugins/endpoint-methods/index.js → plugins/endpoint-methods/index.js

@@ -5,7 +5,7 @@ module.exports = apiPlugin
 const set = require('lodash/set')
 
 const validate = require('./validate')
-const ENDPOINT_DEFAULTS = require('../../routes.json')
+const ENDPOINT_DEFAULTS = require('./routes.json')
 
 function apiPlugin (octokit) {
   octokit.hook.before('request', validate)

lib/plugins/endpoint-methods/validate.js → plugins/endpoint-methods/validate.js

@@ -6,7 +6,7 @@ const set = require('lodash/set')
 const get = require('lodash/get')
 const HttpError = require('@octokit/request/lib/http-error')
 
-const deprecate = require('../../deprecate')
+const deprecate = require('../../lib/deprecate')
 
 function validate (options) {
   if (!options.request.endpoint) {

scripts/generate-api-docs.js

@@ -36,7 +36,7 @@ function toSectionComment (namespaceName) {
 function toApiComment (namespaceName, apiName, api) {
   if (!api.method) {
     throw new Error(
-      `No HTTP method specified for ${namespaceName}.${apiName} in routes.json`
+      `No HTTP method specified for ${namespaceName}.${apiName} in plugins/endpoint-methods/routes.json`
     )
   }
 

scripts/generate-routes.js

@@ -11,7 +11,7 @@ function sortRoutesByKeys (routes) {
     Object.keys(routes[scope]).forEach(method => {
       routes[scope][method] = sortByKeys(routes[scope][method])
 
-      // routes-for-api-docs keeps parameters as array, while lib/routes.json uses an object
+      // routes-for-api-docs keeps parameters as array, while plugins/endpoint-methods/routes.json uses an object
       if (Array.isArray(routes[scope][method].params)) {
         return
       }
@@ -101,7 +101,7 @@ NEW_ROUTES['users'].push(...NEW_ROUTES['orgs'].filter(endpoint => ORG_USER_PATHS
 NEW_ROUTES['users'].push(...NEW_ROUTES['repos'].filter(endpoint => REPOS_USER_PATHS.includes(endpoint.path)))
 NEW_ROUTES['users'].push(...NEW_ROUTES['apps'].filter(endpoint => APPS_USER_PATHS.includes(endpoint.path)))
 
-// map scopes from @octokit/routes to what we currently have in lib/routes.json
+// map scopes from @octokit/routes to what we currently have in plugins/endpoint-methods/routes.json
 const mapScopes = {
   activity: 'activity',
   apps: 'apps',
@@ -314,5 +314,5 @@ newRoutes.users.unsuspend = CURRENT_ROUTES.users.unsuspend
 // don’t break the deprecated "integrations" scope
 newRoutes.integrations = CURRENT_ROUTES.integrations
 
-writeFileSync('lib/routes.json', JSON.stringify(sortRoutesByKeys(newRoutes), null, 2) + '\n')
+writeFileSync('plugins/endpoint-methods/routes.json', JSON.stringify(sortRoutesByKeys(newRoutes), null, 2) + '\n')
 writeFileSync('scripts/routes-for-api-docs.json', JSON.stringify(sortRoutesByKeys(newDocRoutes), null, 2))