api 4.5.1 → 5.0.0-beta.2

package/src/fetcher.ts

@@ -0,0 +1,141 @@
+import type { OASDocument } from 'oas/@types/rmoas.types';
+
+import 'isomorphic-fetch';
+import OpenAPIParser from '@readme/openapi-parser';
+import yaml from 'js-yaml';
+import fs from 'fs';
+import path from 'path';
+
+export default class Fetcher {
+  uri: string | OASDocument;
+
+  /**
+   * @example @petstore/v1.0#n6kvf10vakpemvplx
+   * @example @petstore#n6kvf10vakpemvplx
+   */
+  // eslint-disable-next-line unicorn/no-unsafe-regex
+  static registryUUIDRegex = /^@(?<project>[a-zA-Z0-9-_]+)(\/?(?<version>.+))?#(?<uuid>[a-z0-9]+)$/;
+
+  constructor(uri: string | OASDocument) {
+    if (typeof uri === 'string') {
+      if (Fetcher.isAPIRegistryUUID(uri)) {
+        // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+        this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+      } else if (Fetcher.isGitHubBlobURL(uri)) {
+        /**
+         * People may try to use a public repository URL to the source viewer on GitHub not knowing
+         * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+         * version of this page that'll allow us to access the API definition.
+         *
+         * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+         */
+        this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+      } else {
+        this.uri = uri;
+      }
+    } else {
+      this.uri = uri;
+    }
+  }
+
+  static isAPIRegistryUUID(uri: string) {
+    return Fetcher.registryUUIDRegex.test(uri);
+  }
+
+  static isGitHubBlobURL(uri: string) {
+    return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+  }
+
+  static getProjectPrefixFromRegistryUUID(uri: string) {
+    const matches = uri.match(Fetcher.registryUUIDRegex);
+    if (!matches) {
+      return undefined;
+    }
+
+    return matches.groups.project;
+  }
+
+  async load() {
+    if (typeof this.uri !== 'string') {
+      throw new TypeError(
+        "Something disastrous occurred and a non-string URI was supplied to the Fetcher library. This shouldn't have happened!"
+      );
+    }
+
+    return Promise.resolve(this.uri)
+      .then(uri => {
+        let url;
+        try {
+          url = new URL(uri);
+        } catch (err) {
+          // If that try fails for whatever reason than the URI that we have isn't a real URL and
+          // we can safely attempt to look for it on the filesystem.
+          return Fetcher.getFile(uri);
+        }
+
+        return Fetcher.getURL(url.href);
+      })
+      .then(res => Fetcher.validate(res))
+      .then(res => res as OASDocument);
+  }
+
+  static getURL(url: string) {
+    // @todo maybe include our user-agent here to identify our request
+    return fetch(url).then(res => {
+      if (!res.ok) {
+        throw new Error(`Unable to retrieve URL (${url}). Reason: ${res.statusText}`);
+      }
+
+      if (res.headers.get('content-type') === 'application/yaml' || /\.(yaml|yml)/.test(url)) {
+        return res.text().then(text => {
+          return yaml.load(text);
+        });
+      }
+
+      return res.json();
+    });
+  }
+
+  static getFile(uri: string) {
+    // Support relative paths by resolving them against the cwd.
+    const file = path.resolve(process.cwd(), uri);
+
+    if (!fs.existsSync(file)) {
+      throw new Error(
+        `Sorry, we were unable to load an API definition from ${file}. Please either supply a URL or a path on your filesystem.`
+      );
+    }
+
+    return Promise.resolve(fs.readFileSync(file, 'utf8')).then((res: string) => {
+      if (/\.(yaml|yml)/.test(file)) {
+        return yaml.load(res);
+      }
+
+      return JSON.parse(res);
+    });
+  }
+
+  static validate(json: any) {
+    if (json.swagger) {
+      throw new Error('Sorry, this module only supports OpenAPI definitions.');
+    }
+
+    // The `validate` method handles dereferencing for us.
+    return OpenAPIParser.validate(json, {
+      dereference: {
+        /**
+         * If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
+         * This allows us to not only do easy circular reference detection but also stringify and
+         * save dereferenced API definitions back into the cache directory.
+         */
+        circular: 'ignore',
+      },
+    }).catch(err => {
+      if (/is not a valid openapi definition/i.test(err.message)) {
+        throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
+      }
+
+      throw err;
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+import type { Operation } from 'oas';
+import type { HttpMethods, OASDocument } from 'oas/@types/rmoas.types';
+import type { ConfigOptions } from './core';
+
+import Oas from 'oas';
+import APICore from './core';
+
+import Cache from './cache';
+
+import { PACKAGE_NAME, PACKAGE_VERSION } from './packageInfo';
+
+interface SDKOptions {
+  cacheDir?: string;
+}
+
+class Sdk {
+  uri: string | OASDocument;
+
+  userAgent: string;
+
+  cacheDir: string | false;
+
+  constructor(uri: string | OASDocument, opts: SDKOptions = {}) {
+    this.uri = uri;
+    this.userAgent = `${PACKAGE_NAME} (node)/${PACKAGE_VERSION}`;
+
+    this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
+  }
+
+  load() {
+    const cache = new Cache(this.uri, this.cacheDir);
+    const userAgent = this.userAgent;
+
+    const core = new APICore();
+    core.setUserAgent(userAgent);
+
+    let isLoaded = false;
+    let isCached = cache.isCached();
+    let sdk = {};
+
+    /**
+     * Create dynamic accessors for every HTTP method that the OpenAPI specification supports.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-7}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-7}
+     */
+    function loadMethods() {
+      return ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']
+        .map(httpVerb => {
+          return {
+            [httpVerb]: ((method: string, path: string, ...args: unknown[]) => {
+              return core.fetch(path, method as HttpMethods, ...args);
+            }).bind(null, httpVerb),
+          };
+        })
+        .reduce((prev, next) => Object.assign(prev, next));
+    }
+
+    /**
+     * Create dynamic accessors for every operation with a defined operation ID. If an operation
+     * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
+     *
+     * @param spec
+     */
+    function loadOperations(spec: Oas) {
+      return Object.entries(spec.getPaths())
+        .map(([, operations]) => Object.values(operations))
+        .reduce((prev, next) => prev.concat(next), [])
+        .filter(operation => operation.hasOperationId())
+        .reduce((prev, next) => {
+          // `getOperationId()` creates dynamic operation IDs when one isn't available but we need
+          // to know here if we actually have one present or not. The `camelCase` option here also
+          // cleans up any `operationId` that we might have into something that can be used as a
+          // valid JS method.
+          const operationId = next.getOperationId({ camelCase: true });
+
+          return Object.assign(prev, {
+            [operationId]: ((operation: Operation, ...args: unknown[]) => {
+              return core.fetchOperation(operation, ...args);
+            }).bind(null, next),
+          });
+        }, {});
+    }
+
+    async function loadFromCache() {
+      let cachedSpec;
+      if (isCached) {
+        cachedSpec = await cache.get();
+      } else {
+        cachedSpec = await cache.load();
+        isCached = true;
+      }
+
+      const spec = new Oas(cachedSpec);
+
+      core.setSpec(spec);
+
+      sdk = Object.assign(sdk, {
+        ...loadMethods(),
+        ...loadOperations(spec),
+      });
+
+      isLoaded = true;
+    }
+
+    const sdkProxy = {
+      // @give this a better type than any
+      get(target: any, method: string) {
+        // Since auth returns a self-proxy, we **do not** want it to fall through into the async
+        // function below as when that'll happen, instead of returning a self-proxy, it'll end up
+        // returning a Promise. When that happens, chaining `sdk.auth().operationId()` will fail.
+        if (['auth', 'config'].includes(method)) {
+          // @todo split this up so we have better types for `auth` and `config`
+          return function (...args: any) {
+            return target[method].apply(this, args);
+          };
+        }
+
+        return async function (...args: unknown[]) {
+          if (!(method in target)) {
+            // If this method doesn't exist on the proxy, have we loaded the SDK? If we have, then
+            // this method isn't valid.
+            if (isLoaded) {
+              throw new Error(`Sorry, \`${method}\` does not appear to be a valid operation on this API.`);
+            }
+
+            await loadFromCache();
+
+            // If after loading the SDK and this method still doesn't exist, then it's not real!
+            if (!(method in sdk)) {
+              throw new Error(`Sorry, \`${method}\` does not appear to be a valid operation on this API.`);
+            }
+
+            // @todo give sdk a better type
+            return (sdk as any)[method].apply(this, args);
+          }
+
+          return target[method].apply(this, args);
+        };
+      },
+    };
+
+    sdk = {
+      /**
+       * If the API you're using requires authentication you can supply the required credentials
+       * through this method and the library will magically determine how they should be used
+       * within your API request.
+       *
+       * With the exception of OpenID and MutualTLS, it supports all forms of authentication
+       * supported by the OpenAPI specification.
+       *
+       * @example <caption>HTTP Basic auth</caption>
+       * sdk.auth('username', 'password');
+       *
+       * @example <caption>Bearer tokens (HTTP or OAuth 2)</caption>
+       * sdk.auth('myBearerToken');
+       *
+       * @example <caption>API Keys</caption>
+       * sdk.auth('myApiKey');
+       *
+       * @see {@link https://spec.openapis.org/oas/v3.0.3#fixed-fields-22}
+       * @see {@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-22}
+       * @param values Your auth credentials for the API. Can specify up to two strings or numbers.
+       */
+      auth: (...values: string[] | number[]) => {
+        core.setAuth(...values);
+      },
+
+      /**
+       * Optionally configure various options, such as response parsing, that the SDK allows.
+       *
+       * @param config Object of supported SDK options and toggles.
+       * @param config.parseResponse If responses are parsed according to its `Content-Type` header.
+       */
+      config: (config: ConfigOptions) => {
+        core.setConfig(config);
+      },
+
+      /**
+       * If the API you're using offers alternate server URLs, and server variables, you can tell
+       * the SDK which one to use with this method. To use it you can supply either one of the
+       * server URLs that are contained within the OpenAPI definition (along with any server
+       * variables), or you can pass it a fully qualified URL to use (that may or may not exist
+       * within the OpenAPI definition).
+       *
+       * @example <caption>Server URL with server variables</caption>
+       * sdk.server('https://{region}.api.example.com/{basePath}', {
+       *   name: 'eu',
+       *   basePath: 'v14',
+       * });
+       *
+       * @example <caption>Fully qualified server URL</caption>
+       * sdk.server('https://eu.api.example.com/v14');
+       *
+       * @param url Server URL
+       * @param variables An object of variables to replace into the server URL.
+       */
+      server: (url: string, variables = {}) => {
+        core.setServer(url, variables);
+      },
+    };
+
+    return new Proxy(sdk, sdkProxy);
+  }
+}
+
+// Why `export` vs `export default`? If we leave this as `export` then TS will transpile it into
+// a `module.exports` export so that when folks load this they don't need to load it as
+// `require('api').default`.
+export = (uri: string | OASDocument, opts: SDKOptions = {}) => {
+  return new Sdk(uri, opts).load();
+};

package/src/packageInfo.ts

@@ -0,0 +1,3 @@
+// This file is automatically updated by the build script.
+export const PACKAGE_NAME = 'api';
+export const PACKAGE_VERSION = '5.0.0-beta.2';

package/src/typings.d.ts

@@ -0,0 +1,3 @@
+// These libraries don't have any types so we need to let TS know so we can use them.
+declare module 'fetch-har';
+declare module '@readme/oas-to-har';

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "baseUrl": "./src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "lib": ["dom", "es2020"],
+    "noImplicitAny": true,
+    "outDir": "dist/",
+    "paths": {
+      // Because this library uses ES2015+ `#private` syntax that would require us to maket his
+      // library ESM-only we're overloading its types with a `paths` config with this empty file.
+      // This isn't a great solution as we're losing type checks where this library is used, but
+      // it's far too early in the ESM lifecycle for us to make API an ESM-only library.
+      //
+      // And though TS offers an unstable `node12` module resolution that lets us manage this in
+      // another way that module resolution requires TS nightlies to be installed, which no thanks!
+      //
+      // https://github.com/microsoft/TypeScript/issues/17042
+      "form-data-encoder": [".sink.d.ts"]
+    }
+  },
+  "include": ["./src/**/*"]
+}

package/src/cache.js

@@ -1,225 +0,0 @@
-const fetch = require('node-fetch');
-const OpenAPIParser = require('@readme/openapi-parser');
-const yaml = require('js-yaml');
-const crypto = require('crypto');
-const findCacheDir = require('find-cache-dir');
-const pkg = require('../package.json');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const makeDir = require('make-dir');
-
-class Cache {
-  constructor(uri, cacheDir = false) {
-    /**
-     * Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-     *
-     * Examples:
-     *    - @petstore/v1.0#n6kvf10vakpemvplx
-     *    - @petstore#n6kvf10vakpemvplx
-     *
-     * @param {String} u
-     * @returns {String}
-     */
-    const resolveReadMeRegistryAccessor = u =>
-      typeof u === 'string'
-        ? u.replace(/^@[a-zA-Z0-9-_]+\/?(.+)#([a-z0-9]+)$/, 'https://dash.readme.io/api/v1/api-registry/$2')
-        : u;
-
-    this.uri = resolveReadMeRegistryAccessor(uri);
-    this.uriHash = Cache.getCacheHash(this.uri);
-
-    if (cacheDir) {
-      this.dir = cacheDir;
-    } else {
-      this.dir = findCacheDir({ name: pkg.name });
-      if (typeof this.dir === 'undefined') {
-        // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't
-        // writable, or there's no `package.json` in the root-most directory. If this happens, we
-        // can instead adhoc create a cache directory in the users OS temp directory and store our
-        // data there.
-        //
-        // @link https://github.com/avajs/find-cache-dir/issues/29
-        this.dir = makeDir.sync(path.join(os.tmpdir(), pkg.name));
-      }
-    }
-
-    this.cacheStore = path.join(this.dir, 'cache.json');
-    this.specsCache = path.join(this.dir, 'specs');
-
-    // This should default to false so we have awareness if we've looked at the cache yet.
-    this.cached = false;
-  }
-
-  static getCacheHash(file) {
-    let data = file;
-    if (typeof file === 'object') {
-      // Under certain unit testing circumstances, we might be supplying the class with a raw JSON object so we'll need
-      // to convert it to a string in order to hand it off to the crypto module.
-      data = JSON.stringify(file);
-    }
-
-    return crypto.createHash('md5').update(data).digest('hex');
-  }
-
-  isCached() {
-    const cache = this.getCache();
-    return cache && this.uriHash in cache;
-  }
-
-  getCache() {
-    if (typeof this.cached === 'object') {
-      return this.cached;
-    }
-
-    this.cached = {};
-
-    if (fs.existsSync(this.cacheStore)) {
-      this.cached = JSON.parse(fs.readFileSync(this.cacheStore, 'utf8'));
-    }
-
-    return this.cached;
-  }
-
-  get() {
-    // If the class was supplied a raw object, just go ahead and bypass the caching system and return that.
-    if (typeof this.uri === 'object') {
-      return this.uri;
-    }
-
-    if (!this.isCached()) {
-      throw new Error(`${this.uri} has not been cached yet and must do so before being retrieved.`);
-    }
-
-    const cache = this.getCache();
-
-    // Prior to v4.5.0 we were putting a fully resolved path to the API definition in the cache
-    // store but if you had specified a custom caching directory and would generate the cache on
-    // your system, that filepath would obviously not be the same in other environments. For this
-    // reason the `path` was removed from the cache store in favor of storing the `hash` instead.
-    //
-    // If we still have `path` in the config cache for backwards compatibility we should use it.
-    if ('path' in cache[this.uriHash]) {
-      return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
-    }
-
-    return JSON.parse(fs.readFileSync(path.join(this.specsCache, `${cache[this.uriHash].hash}.json`)));
-  }
-
-  async load() {
-    // If the class was supplied a raw object, just go ahead and bypass the caching system and return that.
-    if (typeof this.uri === 'object') {
-      return this.uri;
-    }
-
-    try {
-      const url = new URL(this.uri);
-      this.uri = url.href;
-
-      return this.saveUrl();
-    } catch (err) {
-      // Support relative paths by resolving them against the cwd.
-      this.uri = path.resolve(process.cwd(), this.uri);
-
-      if (!fs.existsSync(this.uri)) {
-        throw new Error(
-          `Sorry, we were unable to load that OpenAPI definition. Please either supply a URL or a path on your filesystem.`
-        );
-      }
-
-      return this.saveFile();
-    }
-  }
-
-  save(json) {
-    const self = this;
-
-    if (json.swagger) {
-      throw new Error('Sorry, this module only supports OpenAPI definitions.');
-    }
-
-    return new Promise(resolve => {
-      resolve(json);
-    })
-      .then(res => {
-        // The `validate` method handles dereferencing for us.
-        return OpenAPIParser.validate(res, {
-          dereference: {
-            // If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`. This allows us to
-            // not only do easy circular reference detection but also stringify and  save dereferenced API definitions
-            // back into the cache directory.
-            circular: 'ignore',
-          },
-        }).catch(err => {
-          if (/is not a valid openapi definition/i.test(err.message)) {
-            throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
-          }
-
-          throw err;
-        });
-      })
-      .then(async spec => {
-        if (!fs.existsSync(self.dir)) {
-          fs.mkdirSync(self.dir, { recursive: true });
-        }
-
-        if (!fs.existsSync(self.specsCache)) {
-          fs.mkdirSync(self.specsCache, { recursive: true });
-        }
-
-        const cache = self.getCache();
-        if (!(self.uriHash in cache)) {
-          const saved = JSON.stringify(spec, null, 2);
-          const fileHash = crypto.createHash('md5').update(saved).digest('hex');
-
-          cache[self.uriHash] = {
-            hash: fileHash,
-            original: self.uri,
-            title: 'title' in spec.info ? spec.info.title : undefined,
-            version: 'version' in spec.info ? spec.info.version : undefined,
-          };
-
-          fs.writeFileSync(path.join(self.specsCache, `${fileHash}.json`), saved);
-          fs.writeFileSync(self.cacheStore, JSON.stringify(cache, null, 2));
-
-          self.cache = cache;
-        }
-
-        return spec;
-      });
-  }
-
-  saveUrl() {
-    return fetch(this.uri)
-      .then(res => {
-        if (!res.ok) {
-          throw new Error(`Unable to retrieve URL. Reason: ${res.statusText}`);
-        }
-
-        if (res.headers.get('content-type') === 'application/yaml' || /\.(yaml|yml)/.test(this.uri)) {
-          return res.text().then(text => {
-            return yaml.load(text);
-          });
-        }
-
-        return res.json();
-      })
-      .then(json => this.save(json));
-  }
-
-  saveFile() {
-    return new Promise(resolve => {
-      resolve(fs.readFileSync(this.uri, 'utf8'));
-    })
-      .then(res => {
-        if (/\.(yaml|yml)/.test(this.uri)) {
-          return yaml.load(res);
-        }
-
-        return JSON.parse(res);
-      })
-      .then(json => this.save(json));
-  }
-}
-
-module.exports = Cache;