api 4.5.1 → 5.0.0-beta.2

package/src/index.js

@@ -1,177 +0,0 @@
-const fetch = require('node-fetch');
-const fetchHar = require('fetch-har');
-const Oas = require('oas').default;
-const oasToHar = require('@readme/oas-to-har');
-const pkg = require('../package.json');
-
-const Cache = require('./cache');
-const { parseResponse, prepareAuth, prepareParams, prepareServer } = require('./lib');
-
-global.fetch = fetch;
-global.Request = fetch.Request;
-global.Headers = fetch.Headers;
-global.FormData = require('form-data');
-
-class Sdk {
-  constructor(uri, opts = {}) {
-    this.uri = uri;
-    this.userAgent = `${pkg.name} (node)/${pkg.version}`;
-
-    this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
-  }
-
-  static getOperations(spec) {
-    return Object.keys(spec.api.paths)
-      .map(path => {
-        return Object.keys(spec.api.paths[path]).map(method => {
-          return spec.operation(path, method);
-        });
-      })
-      .reduce((prev, next) => prev.concat(next), []);
-  }
-
-  load() {
-    let authKeys = [];
-    const cache = new Cache(this.uri, this.cacheDir);
-    const self = this;
-    let config = { parseResponse: true };
-    let server = false;
-
-    let isLoaded = false;
-    let isCached = cache.isCached();
-    let sdk = {};
-
-    function fetchOperation(spec, operation, body, metadata) {
-      return new Promise(resolve => {
-        resolve(prepareParams(operation, body, metadata));
-      }).then(params => {
-        const data = { ...params };
-
-        // If `sdk.server()` has been issued data then we need to do some extra work to figure out how to use that
-        // supplied server, and also handle any server variables that were sent alongside it.
-        if (server) {
-          const preparedServer = prepareServer(spec, server.url, server.variables);
-          if (preparedServer) {
-            data.server = preparedServer;
-          }
-        }
-
-        const har = oasToHar(spec, operation, data, prepareAuth(authKeys, operation));
-
-        return fetchHar(har, self.userAgent).then(res => {
-          if (res.status >= 400 && res.status <= 599) {
-            throw res;
-          }
-
-          if (config.parseResponse === false) return res;
-
-          return parseResponse(res);
-        });
-      });
-    }
-
-    function loadMethods(spec) {
-      const supportedVerbs = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
-
-      return supportedVerbs
-        .map(name => {
-          return {
-            [name]: ((method, path, ...args) => {
-              const operation = spec.operation(path, method);
-              return fetchOperation(spec, operation, ...args);
-            }).bind(null, name),
-          };
-        })
-        .reduce((prev, next) => Object.assign(prev, next));
-    }
-
-    function loadOperations(spec) {
-      return Sdk.getOperations(spec)
-        .filter(operation => operation.schema.operationId)
-        .reduce((prev, next) => {
-          return Object.assign(prev, {
-            [next.schema.operationId]: ((operation, ...args) => {
-              return fetchOperation(spec, 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);
-
-      sdk = Object.assign(sdk, {
-        ...loadMethods(spec),
-        ...loadOperations(spec),
-      });
-
-      isLoaded = true;
-    }
-
-    const sdkProxy = {
-      get(target, method) {
-        // 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)) {
-          return function (...args) {
-            return target[method].apply(this, args);
-          };
-        }
-
-        return async function (...args) {
-          if (!(method in target)) {
-            // If this method doesn't exist on the proxy (SDK), 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.`);
-            }
-
-            return sdk[method].apply(this, args);
-          }
-
-          return target[method].apply(this, args);
-        };
-      },
-    };
-
-    sdk = {
-      auth: (...values) => {
-        authKeys = values;
-      },
-      config: opts => {
-        // Downside to having `opts` be merged into the existing `config` is that there isn't a clean way to reset your
-        // current config to the default, so having `opts` assigned directly to the existing config should be okay.
-        config = opts;
-        return new Proxy(sdk, sdkProxy);
-      },
-      server: (url, variables = {}) => {
-        server = {
-          url,
-          variables,
-        };
-      },
-    };
-
-    return new Proxy(sdk, sdkProxy);
-  }
-}
-
-module.exports = (uri, opts = {}) => {
-  return new Sdk(uri, opts).load();
-};

package/src/lib/getSchema.js

@@ -1,34 +0,0 @@
-const {
-  utils: { findSchemaDefinition },
-} = require('oas');
-
-// Gets the schema of the first media type defined in the `content` of the path operation
-// or returns the ref if there's no Request Body Object.
-//
-// If the ref looks like a `requestBodies` reference, then do a lookup for the actual schema
-// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8
-module.exports = function getSchema(pathOperation, api) {
-  try {
-    if (pathOperation.requestBody.content) {
-      const type = Object.keys(pathOperation.requestBody.content)[0];
-
-      return {
-        type,
-        schema: pathOperation.requestBody.content[type],
-      };
-    }
-
-    if (pathOperation.requestBody && pathOperation.requestBody.$ref.match(/^#\/components\/requestBodies\/.*$/)) {
-      return getSchema({
-        requestBody: findSchemaDefinition(pathOperation.requestBody.$ref, api),
-      });
-    }
-
-    return {
-      type: 'application/json',
-      schema: pathOperation.requestBody,
-    };
-  } catch (e) {} // eslint-disable-line no-empty
-
-  return undefined;
-};

package/src/lib/index.js

@@ -1,11 +0,0 @@
-const parseResponse = require('./parseResponse');
-const prepareAuth = require('./prepareAuth');
-const prepareParams = require('./prepareParams');
-const prepareServer = require('./prepareServer');
-
-module.exports = {
-  parseResponse,
-  prepareAuth,
-  prepareParams,
-  prepareServer,
-};

package/src/lib/prepareAuth.js

@@ -1,69 +0,0 @@
-/* eslint-disable no-underscore-dangle */
-/**
- * @todo Needs work for supporting multiple different kinds of auth at the same time. for example if
- *  an operation uses OAuth and HTTP bearer, how can we guarantee that the OAuth bearer is used with
- *  OAuth?
- *
- * @param {Array} authKeys
- * @param {Operation} operation
- */
-module.exports = (authKey, operation) => {
-  if (authKey.length === 0) {
-    return {};
-  }
-
-  const prepared = {};
-  const security = operation.prepareSecurity();
-  const securitySchemes = Object.keys(security);
-
-  if (securitySchemes.length === 0) {
-    // If there's no auth configured on this operation, don't prepare anything (even if it was supplied by the user).
-    return {};
-  }
-
-  const securityType = securitySchemes[0];
-  const schemes = security[securityType];
-  if (schemes.length > 1) {
-    throw new Error("Sorry, this API currently requires multiple forms of authentication which we don't yet support.");
-  }
-
-  const scheme = schemes[0];
-  if (scheme.type === 'http') {
-    if (scheme.scheme === 'basic') {
-      prepared[scheme._key] = {
-        user: authKey[0],
-        pass: authKey.length === 2 ? authKey[1] : '',
-      };
-    } else if (scheme.scheme === 'bearer') {
-      if (authKey.length > 1) {
-        throw new Error(
-          'Multiple auth tokens were supplied for the auth on this endpoint, but only a single token is needed.'
-        );
-      }
-
-      prepared[scheme._key] = authKey[0];
-    }
-  } else if (scheme.type === 'oauth2') {
-    if (authKey.length > 1) {
-      throw new Error(
-        'Multiple auth tokens were supplied for the auth on this endpoint, but only a single token is needed.'
-      );
-    }
-
-    prepared[scheme._key] = authKey[0];
-  } else if (scheme.type === 'apiKey') {
-    if (authKey.length > 1) {
-      throw new Error(
-        'Multiple auth keys were supplied for the auth on this endpoint, but only a single key is needed.'
-      );
-    }
-
-    if (scheme.in === 'query' || scheme.in === 'header') {
-      prepared[scheme._key] = authKey[0];
-    }
-  } else {
-    throw new Error(`Sorry, this API currently supports a scheme, ${scheme.type}, that we don't yet support.`);
-  }
-
-  return prepared;
-};

package/src/lib/prepareParams.js

@@ -1,198 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const stream = require('stream');
-const mimer = require('mimer');
-const getStream = require('get-stream');
-const datauri = require('datauri');
-const getSchema = require('./getSchema');
-
-function digestParameters(parameters) {
-  return parameters.reduce((prev, param) => {
-    if ('$ref' in param || 'allOf' in param || 'anyOf' in param || 'oneOf' in param) {
-      throw new Error(`The OpenAPI document for this operation wasn't dereferenced before processing.`);
-    } else if (param.name in prev) {
-      throw new Error(
-        `The operation you are using has the same parameter, ${param.name}, spread across multiple entry points. We unfortunately can't handle this right now.`
-      );
-    }
-
-    return Object.assign(prev, { [param.name]: param });
-  }, {});
-}
-
-// https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_isempty
-function isEmpty(obj) {
-  return [Object, Array].includes((obj || {}).constructor) && !Object.entries(obj || {}).length;
-}
-
-module.exports = async (operation, body, metadata) => {
-  // If no data was supplied, just return immediately.
-  if (isEmpty(body) && isEmpty(metadata)) {
-    return {};
-  }
-
-  const params = {};
-  let shouldDigestParams = false;
-
-  if (Array.isArray(body)) {
-    // If the body param is an array, then it's absolutely a body and not something we need to do analysis against.
-    params.body = body;
-
-    if (typeof metadata !== 'undefined') {
-      shouldDigestParams = true;
-    }
-  } else if (typeof metadata === 'undefined') {
-    // No metadata was explicitly defined so we need to analyze the body to determine if it should actually be treated
-    // as metadata.
-    shouldDigestParams = true;
-  } else {
-    // Body and metadata were both supplied.
-    params.body = body;
-    shouldDigestParams = true;
-  }
-
-  let digested = {};
-  let hasDigestedParams = false;
-  if (shouldDigestParams) {
-    digested = digestParameters(operation.getParameters());
-    hasDigestedParams = Object.keys(digested).length;
-  }
-
-  // No metadata was explicitly defined so we need to analyze the supplied, and we haven't already set a body then we
-  // need to analyze the supplied body to see if it should actually be metadata. If not, then we can just treat it as a
-  // body and pass it along.
-  if (!('body' in params) && typeof metadata === 'undefined') {
-    if (!hasDigestedParams) {
-      // No parameters were able to be digested, so we just have to assume that what the user supplied was for a body.
-      // This might lead to unwanted false positives if an OAS isn't accurate, but short of throwing an error there
-      // isn't anything we can really do about it.
-      params.body = body;
-    } else {
-      const intersection = Object.keys(body).filter(value => Object.keys(digested).includes(value)).length;
-      if (intersection && intersection / Object.keys(body).length > 0.25) {
-        // If more than 25% of the body intersects with the parameters that we've got on hand, then we should treat it
-        // as a metadata object and organize into parameters.
-        // eslint-disable-next-line no-param-reassign
-        metadata = body;
-      } else {
-        // For all other cases, we should just treat the supplied body as a body.
-        params.body = body;
-      }
-    }
-  }
-
-  // @todo support content types like `image/png` where the request body is the binary
-
-  // If the operation is `multipart/form-data`, or one of our recognized variants, we need to look at the incoming
-  // body payload to see if anything in there is either a file path or a file stream so we can translate those into a
-  // data URL for `@readme/oas-to-har` to make a request.
-  if ('body' in params && operation.isMultipart()) {
-    let requestBody = getSchema(operation.schema, operation.api);
-    if (requestBody) {
-      requestBody = requestBody.schema;
-    } else {
-      requestBody = { schema: {} };
-    }
-
-    const bodyKeys = Object.keys(params.body);
-
-    // Loop through the schema to look for `binary` properties so we know what we need to convert.
-    const conversions = [];
-    Object.keys(requestBody.schema.properties)
-      .filter(key => requestBody.schema.properties[key].format === 'binary')
-      .filter(x => bodyKeys.includes(x))
-      .forEach(async prop => {
-        let file = params.body[prop];
-        if (typeof file === 'string') {
-          // In order to support relative pathed files, we need to attempt to resolve them. Thankfully `path.resolve()`
-          // doesn't munge absolute paths.
-          file = path.resolve(file);
-          if (fs.existsSync(file)) {
-            conversions.push(
-              new Promise(resolve => {
-                resolve(datauri(file));
-              }).then(dataurl => {
-                // Doing this manually for now until when/if https://github.com/data-uri/datauri/pull/29 is accepted.
-                params.body[prop] = dataurl.replace(
-                  ';base64',
-                  `;name=${encodeURIComponent(path.basename(file))};base64`
-                );
-
-                return Promise.resolve(true);
-              })
-            );
-          }
-        } else if (file instanceof stream.Readable) {
-          conversions.push(
-            new Promise(resolve => {
-              resolve(getStream.buffer(file));
-            }).then(buffer => {
-              // This logic was taken from the `datauri` package, and ideally it should be able to accept the content
-              // of a file, or a file stream, but I'll PR that later to that package.
-              // @todo
-              const base64 = buffer.toString('base64');
-              const mimeType = mimer(file.path);
-              const filepath = path.basename(file.path);
-
-              params.body[prop] = `data:${mimeType};name=${encodeURIComponent(filepath)};base64,${base64 || ''}`;
-
-              return Promise.resolve(true);
-            })
-          );
-        }
-      });
-
-    await Promise.all(conversions);
-  }
-
-  // @todo add in a debug mode that would run jsonschema validation against request bodies and parameters and throw back errors if what's supplied isn't up to spec.
-
-  // Only spend time trying to organize metadata into parameters if we were able to digest parameters out of the
-  // operation schema. If we couldn't digest anything, but metadata was supplied then we wouldn't know where to place
-  // the metadata!
-  if (hasDigestedParams) {
-    params.header = {};
-    params.path = {};
-    params.query = {};
-
-    if (typeof metadata === 'object' && !isEmpty(metadata)) {
-      const metadataKeys = Object.keys(metadata);
-      if (metadataKeys.length) {
-        metadataKeys.forEach(param => {
-          if (!(param in digested)) {
-            // This param isn't documented in the OAS, so we can't know where to put it!
-            return;
-          }
-
-          if (digested[param].in === 'path') {
-            params.path[param] = metadata[param];
-          } else if (digested[param].in === 'query') {
-            params.query[param] = metadata[param];
-          } else if (digested[param].in === 'header') {
-            params.header[param] = metadata[param];
-          } else if (digested[param].in === 'cookie') {
-            // @todo add support cookie params here and also in @readme/oas-to-har
-          }
-        });
-      }
-    }
-  }
-
-  // Form data should be placed inside `formData` instead of `body` for it to properly get picked up.
-  if (operation.isFormUrlEncoded()) {
-    params.formData = body;
-    delete params.body;
-  }
-
-  // @todo add required params with defaults if they aren't supplied
-  // @todo in debug mode, if a path param is missing (and required -- they always are), and no defaults are present, we should throw an error
-
-  // Clean up any empty items.
-  ['body', 'formData', 'header', 'path', 'query'].forEach(type => {
-    if (type in params && Object.keys(params[type]).length === 0) {
-      delete params[type];
-    }
-  });
-
-  return params;
-};