feat: initial version

src/EndpointDefaults.ts

@@ -0,0 +1,22 @@
+import { RequestHeaders } from "./RequestHeaders";
+import { RequestMethod } from "./RequestMethod";
+import { RequestParameters } from "./RequestParameters";
+import { Url } from "./Url";
+
+/**
+ * The `.endpoint()` method is guaranteed to set all keys defined by RequestParameters
+ * as well as the method property.
+ */
+export type EndpointDefaults = RequestParameters & {
+  baseUrl: Url;
+  method: RequestMethod;
+  url?: Url;
+  headers: RequestHeaders & {
+    accept: string;
+    "user-agent": string;
+  };
+  mediaType: {
+    format: string;
+    previews: string[];
+  };
+};

src/EndpointInterface.ts

@@ -0,0 +1,74 @@
+import { EndpointDefaults } from "./EndpointDefaults";
+import { EndpointOptions } from "./EndpointOptions";
+import { RequestOptions } from "./RequestOptions";
+import { RequestParameters } from "./RequestParameters";
+import { Route } from "./Route";
+
+import { Endpoints } from "./generated/Endpoints";
+
+export interface EndpointInterface {
+  /**
+   * Transforms a GitHub REST API endpoint into generic request options
+   *
+   * @param {object} endpoint Must set `method` and `url`. Plus URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  (options: EndpointOptions): RequestOptions;
+
+  /**
+   * Transforms a GitHub REST API endpoint into generic request options
+   *
+   * @param {string} route Request method + URL. Example: `'GET /orgs/:org'`
+   * @param {object} [parameters] URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  <R extends Route>(
+    route: keyof Endpoints | R,
+    options?: R extends keyof Endpoints
+      ? Endpoints[R][0] & RequestParameters
+      : RequestParameters
+  ): R extends keyof Endpoints ? Endpoints[R][1] : RequestOptions;
+
+  /**
+   * Object with current default route and parameters
+   */
+  DEFAULTS: EndpointDefaults;
+
+  /**
+   * Returns a new `endpoint` with updated route and parameters
+   */
+  defaults: (newDefaults: RequestParameters) => EndpointInterface;
+
+  merge: {
+    /**
+     * Merges current endpoint defaults with passed route and parameters,
+     * without transforming them into request options.
+     *
+     * @param {string} route Request method + URL. Example: `'GET /orgs/:org'`
+     * @param {object} [parameters] URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+     *
+     */
+    (route: Route, parameters?: RequestParameters): EndpointDefaults;
+
+    /**
+     * Merges current endpoint defaults with passed route and parameters,
+     * without transforming them into request options.
+     *
+     * @param {object} endpoint Must set `method` and `url`. Plus URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+     */
+    (options: RequestParameters): EndpointDefaults;
+
+    /**
+     * Returns current default options.
+     *
+     * @deprecated use endpoint.DEFAULTS instead
+     */
+    (): EndpointDefaults;
+  };
+
+  /**
+   * Stateless method to turn endpoint options into request options.
+   * Calling `endpoint(options)` is the same as calling `endpoint.parse(endpoint.merge(options))`.
+   *
+   * @param {object} options `method`, `url`. Plus URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  parse: (options: EndpointDefaults) => RequestOptions;
+}

src/EndpointOptions.ts

@@ -0,0 +1,8 @@
+import { RequestMethod } from "./RequestMethod";
+import { Url } from "./Url";
+import { RequestParameters } from "./RequestParameters";
+
+export type EndpointOptions = RequestParameters & {
+  method: RequestMethod;
+  url: Url;
+};

src/Fetch.ts

@@ -0,0 +1,4 @@
+/**
+ * Browser's fetch method (or compatible such as fetch-mock)
+ */
+export type Fetch = any;

src/OctokitResponse.ts

@@ -0,0 +1,18 @@
+import { ResponseHeaders } from "./ResponseHeaders";
+import { Url } from "./Url";
+
+export type OctokitResponse<T> = {
+  headers: ResponseHeaders;
+  /**
+   * http response code
+   */
+  status: number;
+  /**
+   * URL of response after all redirects
+   */
+  url: Url;
+  /**
+   *  This is the data you would see in https://developer.Octokit.com/v3/
+   */
+  data: T;
+};

src/RequestHeaders.ts

@@ -0,0 +1,15 @@
+export type RequestHeaders = {
+  /**
+   * Avoid setting `headers.accept`, use `mediaType.{format|previews}` option instead.
+   */
+  accept?: string;
+  /**
+   * Use `authorization` to send authenticated request, remember `token ` / `bearer ` prefixes. Example: `token 1234567890abcdef1234567890abcdef12345678`
+   */
+  authorization?: string;
+  /**
+   * `user-agent` is set do a default and can be overwritten as needed.
+   */
+  "user-agent"?: string;
+  [header: string]: string | number | undefined;
+};

src/RequestInterface.ts

@@ -0,0 +1,51 @@
+import { EndpointInterface } from "./EndpointInterface";
+import { EndpointOptions } from "./EndpointOptions";
+import { RequestParameters } from "./RequestParameters";
+import { ResponseHeaders } from "./ResponseHeaders";
+import { Route } from "./Route";
+import { Url } from "./Url";
+
+export interface RequestInterface {
+  /**
+   * Sends a request based on endpoint options
+   *
+   * @param {object} endpoint Must set `method` and `url`. Plus URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  <T = any>(options: EndpointOptions): Promise<OctokitResponse<T>>;
+
+  /**
+   * Sends a request based on endpoint options
+   *
+   * @param {string} route Request method + URL. Example: `'GET /orgs/:org'`
+   * @param {object} [parameters] URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  <T = any>(route: Route, parameters?: RequestParameters): Promise<
+    OctokitResponse<T>
+  >;
+
+  /**
+   * Returns a new `endpoint` with updated route and parameters
+   */
+  defaults: (newDefaults: RequestParameters) => RequestInterface;
+
+  /**
+   * Octokit endpoint API, see {@link https://github.com/octokit/endpoint.js|@octokit/endpoint}
+   */
+  endpoint: EndpointInterface;
+}
+
+export type OctokitResponse<T> = {
+  headers: ResponseHeaders;
+  /**
+   * http response code
+   */
+  status: number;
+  /**
+   * URL of response after all redirects
+   */
+  url: Url;
+  /**
+   *  This is the data you would see in https://developer.Octokit.com/v3/
+   */
+  data: T;
+};

src/RequestMethod.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP Verb supported by GitHub's REST API
+ */
+export type RequestMethod =
+  | "DELETE"
+  | "GET"
+  | "HEAD"
+  | "PATCH"
+  | "POST"
+  | "PUT";

src/RequestOptions.ts

@@ -0,0 +1,15 @@
+import { RequestHeaders } from "./RequestHeaders";
+import { RequestMethod } from "./RequestMethod";
+import { RequestRequestOptions } from "./RequestRequestOptions";
+import { Url } from "./Url";
+
+/**
+ * Generic request options as they are returned by the `endpoint()` method
+ */
+export type RequestOptions = {
+  method: RequestMethod;
+  url: Url;
+  headers: RequestHeaders;
+  body?: any;
+  request?: RequestRequestOptions;
+};

src/RequestParameters.ts

@@ -0,0 +1,46 @@
+import { RequestRequestOptions } from "./RequestRequestOptions";
+import { RequestHeaders } from "./RequestHeaders";
+import { Url } from "./Url";
+
+/**
+ * Parameters that can be passed into `request(route, parameters)` or `endpoint(route, parameters)` methods
+ */
+export type RequestParameters = {
+  /**
+   * Base URL to be used when a relative URL is passed, such as `/orgs/:org`.
+   * If `baseUrl` is `https://enterprise.acme-inc.com/api/v3`, then the request
+   * will be sent to `https://enterprise.acme-inc.com/api/v3/orgs/:org`.
+   */
+  baseUrl?: Url;
+  /**
+   * HTTP headers. Use lowercase keys.
+   */
+  headers?: RequestHeaders;
+  /**
+   * Media type options, see {@link https://developer.github.com/v3/media/|GitHub Developer Guide}
+   */
+  mediaType?: {
+    /**
+     * `json` by default. Can be `raw`, `text`, `html`, `full`, `diff`, `patch`, `sha`, `base64`. Depending on endpoint
+     */
+    format?: string;
+    /**
+     * Custom media type names of {@link https://developer.github.com/v3/media/|API Previews} without the `-preview` suffix.
+     * Example for single preview: `['squirrel-girl']`.
+     * Example for multiple previews: `['squirrel-girl', 'mister-fantastic']`.
+     */
+    previews?: string[];
+  };
+  /**
+   * Pass custom meta information for the request. The `request` object will be returned as is.
+   */
+  request?: RequestRequestOptions;
+  /**
+   * Any additional parameter will be passed as follows
+   * 1. URL parameter if `':parameter'` or `{parameter}` is part of `url`
+   * 2. Query parameter if `method` is `'GET'` or `'HEAD'`
+   * 3. Request body if `parameter` is `'data'`
+   * 4. JSON in the request body in the form of `body[parameter]` unless `parameter` key is `'data'`
+   */
+  [parameter: string]: any;
+};

src/RequestRequestOptions.ts

@@ -0,0 +1,27 @@
+import { Agent } from "http";
+import { Fetch } from "./Fetch";
+import { Signal } from "./Signal";
+
+/**
+ * Octokit-specific request options which are ignored for the actual request, but can be used by Octokit or plugins to manipulate how the request is sent or how a response is handled
+ */
+export type RequestRequestOptions = {
+  /**
+   * Node only. Useful for custom proxy, certificate, or dns lookup.
+   */
+  agent?: Agent;
+  /**
+   * Custom replacement for built-in fetch method. Useful for testing or request hooks.
+   */
+  fetch?: Fetch;
+  /**
+   * Use an `AbortController` instance to cancel a request. In node you can only cancel streamed requests.
+   */
+  signal?: Signal;
+  /**
+   * Node only. Request/response timeout in ms, it resets on redirect. 0 to disable (OS limit applies). `options.request.signal` is recommended instead.
+   */
+  timeout?: number;
+
+  [option: string]: any;
+};

src/ResponseHeaders.ts

@@ -0,0 +1,21 @@
+export type ResponseHeaders = {
+  "cache-control"?: string;
+  "content-length"?: number;
+  "content-type"?: string;
+  date?: string;
+  etag?: string;
+  "last-modified"?: string;
+  link?: string;
+  location?: string;
+  server?: string;
+  status?: string;
+  vary?: string;
+  "x-github-mediatype"?: string;
+  "x-github-request-id"?: string;
+  "x-oauth-scopes"?: string;
+  "x-ratelimit-limit"?: string;
+  "x-ratelimit-remaining"?: string;
+  "x-ratelimit-reset"?: string;
+
+  [header: string]: string | number | undefined;
+};

src/Route.ts

@@ -0,0 +1,4 @@
+/**
+ * String consisting of an optional HTTP method and relative path or absolute URL. Examples: `'/orgs/:org'`, `'PUT /orgs/:org'`, `GET https://example.com/foo/bar`
+ */
+export type Route = string;

src/Signal.ts

@@ -0,0 +1,6 @@
+/**
+ * Abort signal
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+ */
+export type Signal = any;

src/Url.ts

@@ -0,0 +1,4 @@
+/**
+ * Relative or absolute URL. Examples: `'/orgs/:org'`, `https://example.com/foo/bar`
+ */
+export type Url = string;

src/VERSION.ts

@@ -0,0 +1 @@
+export const VERSION = "0.0.0-development";