api 6.1.1 → 7.0.0-alpha.0

package/src/cache.ts

@@ -1,193 +0,0 @@
-import type { OASDocument } from 'oas/dist/rmoas.types';
-
-import crypto from 'crypto';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import findCacheDir from 'find-cache-dir';
-import 'isomorphic-fetch';
-import makeDir from 'make-dir';
-
-import Fetcher from './fetcher';
-import { PACKAGE_NAME } from './packageInfo';
-
-type CacheStore = Record<
-  string,
-  {
-    hash: string;
-    original: string | OASDocument;
-    /**
-     * @deprecated Deprecated in v4.5.0 in favor of `hash`.
-     */
-    path?: string;
-    title?: string;
-    version?: string;
-  }
->;
-
-export default class Cache {
-  static dir: string;
-
-  static cacheStore: string;
-
-  static specsCache: string;
-
-  uri: string | OASDocument;
-
-  uriHash: string;
-
-  cached: false | CacheStore;
-
-  fetcher: Fetcher;
-
-  constructor(uri: string | OASDocument, cacheDir: string | false = false) {
-    Cache.setCacheDir(cacheDir);
-    Cache.cacheStore = path.join(Cache.dir, 'cache.json');
-    Cache.specsCache = path.join(Cache.dir, 'specs');
-
-    this.fetcher = new Fetcher(uri);
-
-    this.uri = this.fetcher.uri;
-    this.uriHash = Cache.getCacheHash(this.uri);
-
-    // This should default to false so we have awareness if we've looked at the cache yet.
-    this.cached = false;
-  }
-
-  static getCacheHash(file: string | OASDocument) {
-    let data: string;
-    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);
-    } else {
-      data = file;
-    }
-
-    return crypto.createHash('md5').update(data).digest('hex');
-  }
-
-  static setCacheDir(dir?: string | false) {
-    if (dir) {
-      Cache.dir = dir;
-      return;
-    } else if (Cache.dir) {
-      // If we already have a cache dir set and aren't explicitly it to something new then we
-      // shouldn't overwrite what we've already got.
-      return;
-    }
-
-    Cache.dir = findCacheDir({ name: PACKAGE_NAME });
-    if (typeof Cache.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
-      Cache.dir = makeDir.sync(path.join(os.tmpdir(), PACKAGE_NAME));
-    }
-  }
-
-  static async reset() {
-    if (Cache.cacheStore) {
-      await fs.promises.rm(Cache.cacheStore).catch(() => {
-        // no-op
-      });
-    }
-
-    if (Cache.specsCache) {
-      await fs.promises.rm(Cache.specsCache, { recursive: true }).catch(() => {
-        // no-op
-      });
-    }
-  }
-
-  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(Cache.cacheStore)) {
-      this.cached = JSON.parse(fs.readFileSync(Cache.cacheStore, 'utf8')) as CacheStore;
-    }
-
-    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(Cache.specsCache, `${cache[this.uriHash].hash}.json`), 'utf8'));
-  }
-
-  async load() {
-    // If the class was supplied a raw object we should still validate and make sure that it's
-    // dereferenced in order for everything to function, but we shouldn't worry about saving it
-    // into the cache directory architecture.
-    if (typeof this.uri === 'object') {
-      return Fetcher.validate(this.uri);
-    }
-
-    return this.fetcher.load().then(async spec => this.save(spec));
-  }
-
-  save(spec: OASDocument) {
-    if (!fs.existsSync(Cache.dir)) {
-      fs.mkdirSync(Cache.dir, { recursive: true });
-    }
-
-    if (!fs.existsSync(Cache.specsCache)) {
-      fs.mkdirSync(Cache.specsCache, { recursive: true });
-    }
-
-    const cache = this.getCache();
-    if (!(this.uriHash in cache)) {
-      const saved = JSON.stringify(spec, null, 2);
-      const fileHash = crypto.createHash('md5').update(saved).digest('hex');
-
-      cache[this.uriHash] = {
-        hash: fileHash,
-        original: this.uri,
-        title: 'title' in spec.info ? spec.info.title : undefined,
-        version: 'version' in spec.info ? spec.info.version : undefined,
-      };
-
-      fs.writeFileSync(path.join(Cache.specsCache, `${fileHash}.json`), saved);
-      fs.writeFileSync(Cache.cacheStore, JSON.stringify(cache, null, 2));
-
-      this.cached = cache;
-    }
-
-    return spec;
-  }
-}

package/src/core/errors/fetchError.ts

@@ -1,31 +0,0 @@
-class FetchError<Status = number, Data = unknown> extends Error {
-  /** HTTP Status */
-  status: Status;
-
-  /** The content of the response. */
-  data: Data;
-
-  /** The Headers of the response. */
-  headers: Headers;
-
-  /** The raw `Response` object. */
-  res: Response;
-
-  constructor(status: Status, data: Data, headers: Headers, res: Response) {
-    super(res.statusText);
-
-    this.name = 'FetchError';
-    this.status = status;
-    this.data = data;
-    this.headers = headers;
-    this.res = res;
-
-    // We could fix this by updating our target to ES2015 but because we support exporting to CJS
-    // we can't.
-    //
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, FetchError.prototype);
-  }
-}
-
-export default FetchError;

package/src/core/getJSONSchemaDefaults.ts

@@ -1,74 +0,0 @@
-import type { SchemaWrapper } from 'oas/dist/operation/get-parameters-as-json-schema';
-import type { SchemaObject } from 'oas/dist/rmoas.types';
-
-import traverse from 'json-schema-traverse';
-
-/**
- * Run through a JSON Schema object and compose up an object containing default data for any schema
- * property that is required and also has a defined default.
- *
- * Code partially adapted from the `json-schema-default` package but modified to only return
- * defaults of required properties.
- *
- * @todo This is a good candidate to be moved into a core `oas` library method.
- * @see {@link https://github.com/mdornseif/json-schema-default}
- */
-export default function getJSONSchemaDefaults(jsonSchemas: SchemaWrapper[]) {
-  return jsonSchemas
-    .map(({ type: payloadType, schema: jsonSchema }) => {
-      const defaults: Record<string, unknown> = {};
-      traverse(
-        jsonSchema,
-        (
-          schema: SchemaObject,
-          pointer: string,
-          rootSchema: SchemaObject,
-          parentPointer: string,
-          parentKeyword: string,
-          parentSchema: SchemaObject,
-          indexProperty: string,
-        ) => {
-          if (!pointer.startsWith('/properties/')) {
-            return;
-          }
-
-          if (Array.isArray(parentSchema?.required) && parentSchema.required.includes(indexProperty)) {
-            if (schema.type === 'object' && indexProperty) {
-              defaults[indexProperty] = {};
-            }
-
-            let destination = defaults;
-            if (parentPointer) {
-              // To map nested objects correct we need to pick apart the parent pointer.
-              parentPointer
-                .replace(/\/properties/g, '')
-                .split('/')
-                .forEach((subSchema: string) => {
-                  if (subSchema === '') {
-                    return;
-                  }
-
-                  destination = (destination?.[subSchema] as Record<string, unknown>) || {};
-                });
-            }
-
-            if (schema.default !== undefined) {
-              if (indexProperty !== undefined) {
-                destination[indexProperty] = schema.default;
-              }
-            }
-          }
-        },
-      );
-
-      if (!Object.keys(defaults).length) {
-        return {};
-      }
-
-      return {
-        // @todo should we filter out empty and undefined objects from here with `remove-undefined-objects`?
-        [payloadType]: defaults,
-      };
-    })
-    .reduce((prev, next) => Object.assign(prev, next));
-}

package/src/core/index.ts

@@ -1,148 +0,0 @@
-import type Oas from 'oas';
-import type { Operation } from 'oas';
-import type { HttpMethods } from 'oas/dist/rmoas.types';
-
-import oasToHar from '@readme/oas-to-har';
-import fetchHar from 'fetch-har';
-import { FormDataEncoder } from 'form-data-encoder';
-import 'isomorphic-fetch';
-// `AbortController` was shipped in Node 15 so when Node 14 is EOL'd we can drop this dependency.
-import { AbortController } from 'node-abort-controller';
-
-import FetchError from './errors/fetchError';
-import getJSONSchemaDefaults from './getJSONSchemaDefaults';
-import parseResponse from './parseResponse';
-import prepareAuth from './prepareAuth';
-import prepareParams from './prepareParams';
-import prepareServer from './prepareServer';
-
-export interface ConfigOptions {
-  /**
-   * Override the default `fetch` request timeout of 30 seconds. This number should be represented
-   * in milliseconds.
-   */
-  timeout?: number;
-}
-
-export interface FetchResponse<status, data> {
-  data: data;
-  headers: Headers;
-  res: Response;
-  status: status;
-}
-
-// https://stackoverflow.com/a/39495173
-type Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N
-  ? Acc[number]
-  : Enumerate<N, [...Acc, Acc['length']]>;
-
-export type HTTPMethodRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
-
-export { getJSONSchemaDefaults, parseResponse, prepareAuth, prepareParams, prepareServer };
-
-export default class APICore {
-  spec: Oas;
-
-  private auth: (number | string)[] = [];
-
-  private server:
-    | false
-    | {
-        url?: string;
-        variables?: Record<string, string | number>;
-      } = false;
-
-  private config: ConfigOptions = {};
-
-  private userAgent: string;
-
-  constructor(spec?: Oas, userAgent?: string) {
-    this.spec = spec;
-    this.userAgent = userAgent;
-  }
-
-  setSpec(spec: Oas) {
-    this.spec = spec;
-  }
-
-  setConfig(config: ConfigOptions) {
-    this.config = config;
-    return this;
-  }
-
-  setUserAgent(userAgent: string) {
-    this.userAgent = userAgent;
-    return this;
-  }
-
-  setAuth(...values: string[] | number[]) {
-    this.auth = values;
-    return this;
-  }
-
-  setServer(url: string, variables: Record<string, string | number> = {}) {
-    this.server = { url, variables };
-    return this;
-  }
-
-  async fetch(path: string, method: HttpMethods, body?: unknown, metadata?: Record<string, unknown>) {
-    const operation = this.spec.operation(path, method);
-
-    return this.fetchOperation(operation, body, metadata);
-  }
-
-  async fetchOperation(operation: Operation, body?: unknown, metadata?: Record<string, unknown>) {
-    return 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 (this.server) {
-        const preparedServer = prepareServer(this.spec, this.server.url, this.server.variables);
-        if (preparedServer) {
-          data.server = preparedServer;
-        }
-      }
-
-      // @ts-expect-error `this.auth` typing is off. FIXME
-      const har = oasToHar(this.spec, operation, data, prepareAuth(this.auth, operation));
-
-      let timeoutSignal: any;
-      const init: RequestInit = {};
-      if (this.config.timeout) {
-        const controller = new AbortController();
-        timeoutSignal = setTimeout(() => controller.abort(), this.config.timeout);
-        // @todo Typing on `AbortController` coming out of `node-abort-controler` isn't right so when
-        // we eventually drop that dependency we can remove the `as any` here.
-        init.signal = controller.signal as any;
-      }
-
-      return fetchHar(har as any, {
-        files: data.files || {},
-        init,
-        multipartEncoder: FormDataEncoder,
-        userAgent: this.userAgent,
-      })
-        .then(async (res: Response) => {
-          const parsed = await parseResponse(res);
-
-          if (res.status >= 400 && res.status <= 599) {
-            throw new FetchError<typeof parsed.status, typeof parsed.data>(
-              parsed.status,
-              parsed.data,
-              parsed.headers,
-              parsed.res,
-            );
-          }
-
-          return parsed;
-        })
-        .finally(() => {
-          if (this.config.timeout) {
-            clearTimeout(timeoutSignal);
-          }
-        });
-    });
-  }
-}

package/src/core/parseResponse.ts

@@ -1,26 +0,0 @@
-import { utils } from 'oas';
-
-const { matchesMimeType } = utils;
-
-export default async function getResponseBody(response: Response) {
-  const contentType = response.headers.get('Content-Type');
-  const isJSON = contentType && (matchesMimeType.json(contentType) || matchesMimeType.wildcard(contentType));
-
-  const responseBody = await response.text();
-
-  let data = responseBody;
-  if (isJSON) {
-    try {
-      data = JSON.parse(responseBody);
-    } catch (e) {
-      // If our JSON parsing failed then we can just return plaintext instead.
-    }
-  }
-
-  return {
-    data,
-    status: response.status,
-    headers: response.headers,
-    res: response,
-  };
-}

package/src/core/prepareAuth.ts

@@ -1,109 +0,0 @@
-/* eslint-disable no-underscore-dangle */
-import type { Operation } from 'oas';
-
-export default function prepareAuth(authKey: (number | string)[], operation: Operation) {
-  if (authKey.length === 0) {
-    return {};
-  }
-
-  const preparedAuth: Record<
-    string,
-    | string
-    | number
-    | {
-        pass: string | number;
-        user: string | number;
-      }
-  > = {};
-
-  const security = operation.getSecurity();
-  if (security.length === 0) {
-    // If there's no auth configured on this operation, don't prepare anything (even if it was
-    // supplied by the user).
-    return {};
-  }
-
-  // Does this operation require multiple forms of auth?
-  if (security.every(s => Object.keys(s).length > 1)) {
-    throw new Error(
-      "Sorry, this operation currently requires multiple forms of authentication which this library doesn't yet support.",
-    );
-  }
-
-  // Since we can only handle single auth security configurations, let's pull those out. This code
-  // is a bit opaque but `security` here may look like `[{ basic: [] }, { oauth2: [], basic: []}]`
-  // and are filtering it down to only single-auth requirements of `[{ basic: [] }]`.
-  const usableSecurity = security
-    .map(s => {
-      return Object.keys(s).length === 1 ? s : false;
-    })
-    .filter(Boolean);
-
-  const usableSecuritySchemes = usableSecurity.map(s => Object.keys(s)).reduce((prev, next) => prev.concat(next), []);
-  const preparedSecurity = operation.prepareSecurity();
-
-  // If we have two auth tokens present let's look for Basic Auth in their configuration.
-  if (authKey.length >= 2) {
-    // If this operation doesn't support HTTP Basic auth but we have two tokens, that's a paddlin.
-    if (!('Basic' in preparedSecurity)) {
-      throw new Error('Multiple auth tokens were supplied for this endpoint but only a single token is needed.');
-    }
-
-    // If we have two auth keys for Basic Auth but Basic isn't a usable security scheme (maybe it's
-    // part of an AND or auth configuration -- which we don't support) then we need to error out.
-    const schemes = preparedSecurity.Basic.filter(s => usableSecuritySchemes.includes(s._key));
-    if (!schemes.length) {
-      throw new Error(
-        'Credentials for Basic Authentication were supplied but this operation requires another form of auth in that case, which this library does not yet support. This operation does, however, allow supplying a single auth token.',
-      );
-    }
-
-    const scheme = schemes.shift();
-    preparedAuth[scheme._key] = {
-      user: authKey[0],
-      pass: authKey.length === 2 ? authKey[1] : '',
-    };
-
-    return preparedAuth;
-  }
-
-  // If we know we don't need to use HTTP Basic auth because we have a username+password then we
-  // can pick the first usable security scheme available and try to use that. This might not always
-  // be the auth scheme that the user wants, but we don't have any other way for the user to tell
-  // us what they want with the current `sdk.auth()` API.
-  const usableScheme = usableSecuritySchemes[0];
-  const schemes = Object.entries(preparedSecurity)
-    .map(([, ps]) => ps.filter(s => usableScheme === s._key))
-    .reduce((prev, next) => prev.concat(next), []);
-
-  const scheme = schemes.shift();
-  switch (scheme.type) {
-    case 'http':
-      if (scheme.scheme === 'basic') {
-        preparedAuth[scheme._key] = {
-          user: authKey[0],
-          pass: authKey.length === 2 ? authKey[1] : '',
-        };
-      } else if (scheme.scheme === 'bearer') {
-        preparedAuth[scheme._key] = authKey[0];
-      }
-      break;
-
-    case 'oauth2':
-      preparedAuth[scheme._key] = authKey[0];
-      break;
-
-    case 'apiKey':
-      if (scheme.in === 'query' || scheme.in === 'header' || scheme.in === 'cookie') {
-        preparedAuth[scheme._key] = authKey[0];
-      }
-      break;
-
-    default:
-      throw new Error(
-        `Sorry, this API currently uses a security scheme, ${scheme.type}, which this library doesn't yet support.`,
-      );
-  }
-
-  return preparedAuth;
-}