oas 36.0.3 → 37.0.0

package/dist/index.js

@@ -1,10 +1,637 @@
 import {
-  Oas
-} from "./chunk-4WJUHXQH.js";
-import "./chunk-RQZ2BPMU.js";
-import "./chunk-6MDVLJ3A.js";
-import "./chunk-S27IGTVG.js";
-import "./chunk-XG4HGNCN.js";
+  Operation,
+  Webhook,
+  defaultVariablesFromServers,
+  filterPathMethods,
+  findTargetPath,
+  generatePathMatches,
+  getUserVariable,
+  normalizedURLFromServers,
+  splitUrlFromServers,
+  stripTrailingSlash,
+  transformURLIntoRegex,
+  variablesFromServers
+} from "./chunk-WIVQX3DA.js";
+import {
+  SERVER_VARIABLE_REGEX,
+  dereferenceRef,
+  supportedMethods
+} from "./chunk-IEN4GZPF.js";
+import {
+  CODE_SAMPLES,
+  HEADERS,
+  OAUTH_OPTIONS,
+  PARAMETER_ORDERING,
+  SAMPLES_LANGUAGES,
+  extensionDefaults,
+  getExtension,
+  hasRootExtension,
+  validateParameterOrdering
+} from "./chunk-S27IGTVG.js";
+import {
+  isOpenAPI31,
+  isRef
+} from "./chunk-XG4HGNCN.js";
+
+// src/lib/get-auth.ts
+function getPrimitiveDefaultAuth(scheme) {
+  return typeof scheme["x-default"] === "number" || typeof scheme["x-default"] === "string" ? scheme["x-default"] : null;
+}
+function getKey(user, scheme) {
+  switch (scheme.type) {
+    case "oauth2":
+      return user[scheme._key] || user.apiKey || getPrimitiveDefaultAuth(scheme) || null;
+    case "apiKey":
+      return user[scheme._key] || user.apiKey || scheme["x-default"] || null;
+    case "http":
+      if (scheme.scheme === "basic") {
+        return user[scheme._key] || (user.user || user.pass ? { user: user.user || null, pass: user.pass || null } : scheme["x-default"]) || {
+          user: null,
+          pass: null
+        };
+      }
+      if (scheme.scheme === "bearer") {
+        return user[scheme._key] || user.apiKey || scheme["x-default"] || null;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+function getByScheme(user, scheme = {}, selectedApp) {
+  if (user?.keys?.length) {
+    if (selectedApp) {
+      const userKey = user.keys.find((k) => k.name === selectedApp);
+      if (!userKey) {
+        return null;
+      }
+      return getKey(userKey, scheme);
+    }
+    return getKey(user.keys[0], scheme);
+  }
+  return getKey(user, scheme);
+}
+function getAuth(api, user, selectedApp) {
+  return Object.keys(api?.components?.securitySchemes || {}).map((scheme) => {
+    const securityScheme = dereferenceRef(api.components?.securitySchemes?.[scheme], api);
+    if (!securityScheme || isRef(securityScheme)) {
+      return false;
+    }
+    return {
+      [scheme]: getByScheme(
+        user,
+        {
+          ...securityScheme,
+          _key: scheme
+        },
+        selectedApp
+      )
+    };
+  }).filter((item) => item !== void 0).reduce((prev, next) => Object.assign(prev, next), {});
+}
+
+// src/index.ts
+var Oas = class _Oas {
+  /**
+   * The current OpenAPI definition.
+   */
+  api;
+  /**
+   * The current user that we should use when pulling auth tokens from security schemes.
+   */
+  user;
+  /**
+   * @param oas An OpenAPI definition.
+   * @param user The information about a user that we should use when pulling auth tokens from
+   *    security schemes.
+   */
+  constructor(oas, user) {
+    if (typeof oas === "string") {
+      this.api = JSON.parse(oas) || {};
+    } else {
+      this.api = oas || {};
+    }
+    this.user = user || {};
+  }
+  /**
+   * This will initialize a new instance of the `Oas` class. This method is useful if you're using
+   * Typescript and are attempting to supply an untyped JSON object into `Oas` as it will force-type
+   * that object to an `OASDocument` for you.
+   *
+   * @param oas An OpenAPI definition.
+   * @param user The information about a user that we should use when pulling auth tokens from
+   *    security schemes.
+   */
+  static init(oas, user) {
+    return new _Oas(oas, user);
+  }
+  /**
+   * Retrieve the OpenAPI version that this API definition is targeted for.
+   */
+  getVersion() {
+    if (this.api.openapi) {
+      return this.api.openapi;
+    }
+    throw new Error("Unable to recognize what specification version this API definition conforms to.");
+  }
+  /**
+   * Retrieve the current OpenAPI API Definition.
+   *
+   */
+  getDefinition() {
+    return this.api;
+  }
+  url(selected = 0, variables) {
+    const url = normalizedURLFromServers(this.api.servers, selected);
+    return this.replaceUrl(url, variables || this.defaultVariables(selected)).trim();
+  }
+  variables(selected = 0) {
+    return variablesFromServers(this.api.servers, selected);
+  }
+  defaultVariables(selected = 0) {
+    return defaultVariablesFromServers(this.api.servers, selected, this.user);
+  }
+  splitUrl(selected = 0) {
+    return splitUrlFromServers(this.api.servers, selected);
+  }
+  /**
+   * With a fully composed server URL, run through our list of known OAS servers and return back
+   * which server URL was selected along with any contained server variables split out.
+   *
+   * For example, if you have an OAS server URL of `https://{name}.example.com:{port}/{basePath}`,
+   * and pass in `https://buster.example.com:3000/pet` to this function, you'll get back the
+   * following:
+   *
+   *    { selected: 0, variables: { name: 'buster', port: 3000, basePath: 'pet' } }
+   *
+   * Re-supplying this data to `oas.url()` should return the same URL you passed into this method.
+   *
+   * @param baseUrl A given URL to extract server variables out of.
+   */
+  splitVariables(baseUrl) {
+    const matchedServer = (this.api.servers || []).map((server, i) => {
+      const rgx = transformURLIntoRegex(server.url);
+      const found = new RegExp(rgx).exec(baseUrl);
+      if (!found) {
+        return false;
+      }
+      const variables = {};
+      Array.from(server.url.matchAll(SERVER_VARIABLE_REGEX)).forEach((variable, y) => {
+        variables[variable[1]] = found[y + 1];
+      });
+      return {
+        selected: i,
+        variables
+      };
+    }).filter((item) => item !== false);
+    return matchedServer.length ? matchedServer[0] : false;
+  }
+  /**
+   * Replace templated variables with supplied data in a given URL.
+   *
+   * There are a couple ways that this will utilize variable data:
+   *
+   *  - Supplying a `variables` object. If this is supplied, this data will always take priority.
+   *    This incoming `variables` object can be two formats:
+   *    `{ variableName: { default: 'value' } }` and `{ variableName: 'value' }`. If the former is
+   *    present, that will take precedence over the latter.
+   *  - If the supplied `variables` object is empty or does not match the current template name,
+   *    we fallback to the data stored in `this.user` and attempt to match against that.
+   *    See `getUserVariable` for some more information on how this data is pulled from `this.user`.
+   *
+   * If no variables supplied match up with the template name, the template name will instead be
+   * used as the variable data.
+   *
+   * @param url A URL to swap variables into.
+   * @param variables An object containing variables to swap into the URL.
+   */
+  replaceUrl(url, variables = {}) {
+    return stripTrailingSlash(
+      url.replace(SERVER_VARIABLE_REGEX, (original, key) => {
+        if (key in variables) {
+          const data = variables[key];
+          if (typeof data === "object") {
+            if (!Array.isArray(data) && data !== null && "default" in data) {
+              return String(data.default);
+            }
+          } else {
+            return String(data);
+          }
+        }
+        const userVariable = getUserVariable(this.user, key);
+        if (userVariable) {
+          return String(userVariable);
+        }
+        return original;
+      })
+    );
+  }
+  /**
+   * Retrieve an Operation of Webhook class instance for a given path and method.
+   *
+   * @param path Path to lookup and retrieve.
+   * @param method HTTP Method to retrieve on the path.
+   */
+  operation(path, method, opts = {}) {
+    let operation = {
+      parameters: []
+    };
+    if (opts.isWebhook) {
+      if (isOpenAPI31(this.api)) {
+        const webhookPath = dereferenceRef(this.api?.webhooks?.[path], this.api);
+        if (webhookPath && !isRef(webhookPath)) {
+          if (webhookPath?.[method]) {
+            operation = webhookPath[method];
+            return new Webhook(this, path, method, operation);
+          }
+        }
+      }
+    }
+    if (this?.api?.paths?.[path]) {
+      const pathItem = dereferenceRef(this.api.paths[path], this.api);
+      if (pathItem?.[method]) {
+        operation = dereferenceRef(pathItem[method], this.api);
+      }
+    }
+    return new Operation(this, path, method, operation);
+  }
+  findOperationMatches(url) {
+    const { origin, hostname } = new URL(url);
+    const originRegExp = new RegExp(origin, "i");
+    const { servers, paths } = this.api;
+    let pathName;
+    let targetServer;
+    let matchedServer;
+    if (!servers || !servers.length) {
+      matchedServer = {
+        url: "https://example.com"
+      };
+    } else {
+      matchedServer = servers.find((s) => originRegExp.exec(this.replaceUrl(s.url, s.variables || {})));
+      if (!matchedServer) {
+        const hostnameRegExp = new RegExp(hostname);
+        matchedServer = servers.find((s) => hostnameRegExp.exec(this.replaceUrl(s.url, s.variables || {})));
+      }
+    }
+    if (matchedServer) {
+      targetServer = {
+        ...matchedServer,
+        url: this.replaceUrl(matchedServer.url, matchedServer.variables || {})
+      };
+      [, pathName] = url.split(new RegExp(targetServer.url, "i"));
+    }
+    if (!matchedServer || !pathName) {
+      const matchedServerAndPath = (servers || []).map((server) => {
+        const rgx = transformURLIntoRegex(server.url);
+        const found = new RegExp(rgx).exec(url);
+        if (!found) {
+          return;
+        }
+        return {
+          matchedServer: server,
+          pathName: url.split(new RegExp(rgx)).slice(-1).pop()
+        };
+      }).filter((item) => item !== void 0);
+      if (!matchedServerAndPath.length) {
+        return void 0;
+      }
+      pathName = matchedServerAndPath[0].pathName;
+      targetServer = {
+        ...matchedServerAndPath[0].matchedServer
+      };
+    }
+    if (pathName === void 0) return void 0;
+    if (pathName === "") pathName = "/";
+    if (!paths || !targetServer) return void 0;
+    const annotatedPaths = generatePathMatches(paths, pathName, targetServer.url);
+    if (!annotatedPaths.length) return void 0;
+    return annotatedPaths;
+  }
+  /**
+   * Discover an operation in an OAS from a fully-formed URL and HTTP method. Will return an object
+   * containing a `url` object and another one for `operation`. This differs from `getOperation()`
+   * in that it does not return an instance of the `Operation` class.
+   *
+   * @param url A full URL to look up.
+   * @param method The cooresponding HTTP method to look up.
+   */
+  findOperation(url, method) {
+    const annotatedPaths = this.findOperationMatches(url);
+    if (!annotatedPaths) {
+      return void 0;
+    }
+    const matches = filterPathMethods(annotatedPaths, method);
+    if (!matches.length) return void 0;
+    return findTargetPath(matches);
+  }
+  /**
+   * Discover an operation in an OAS from a fully-formed URL without an HTTP method. Will return an
+   * object containing a `url` object and another one for `operation`.
+   *
+   * @param url A full URL to look up.
+   */
+  findOperationWithoutMethod(url) {
+    const annotatedPaths = this.findOperationMatches(url);
+    if (!annotatedPaths) {
+      return void 0;
+    }
+    return findTargetPath(annotatedPaths);
+  }
+  /**
+   * Retrieve an operation in an OAS from a fully-formed URL and HTTP method. Differs from
+   * `findOperation` in that while this method will return an `Operation` instance,
+   * `findOperation()` does not.
+   *
+   * @param url A full URL to look up.
+   * @param method The cooresponding HTTP method to look up.
+   */
+  getOperation(url, method) {
+    const op = this.findOperation(url, method);
+    if (op === void 0) {
+      return void 0;
+    }
+    return this.operation(op.url.nonNormalizedPath, method);
+  }
+  /**
+   * Retrieve an operation in an OAS by an `operationId`.
+   *
+   * If an operation does not have an `operationId` one will be generated in place, using the
+   * default behavior of `Operation.getOperationId()`, and then asserted against your query.
+   *
+   * Note that because `operationId`s are unique that uniqueness does include casing so the ID
+   * you are looking for will be asserted as an exact match.
+   *
+   * @see {Operation.getOperationId()}
+   * @param id The `operationId` to look up.
+   */
+  getOperationById(id) {
+    let found;
+    Object.values(this.getPaths()).forEach((operations) => {
+      if (found) return;
+      found = Object.values(operations).find((operation) => operation.getOperationId() === id);
+    });
+    if (found) {
+      return found;
+    }
+    Object.entries(this.getWebhooks()).forEach(([, webhooks]) => {
+      if (found) return;
+      found = Object.values(webhooks).find((webhook) => webhook.getOperationId() === id);
+    });
+    return found;
+  }
+  /**
+   * With an object of user information, retrieve the appropriate API auth keys from the current
+   * OAS definition.
+   *
+   * @see {@link https://docs.readme.com/docs/passing-data-to-jwt}
+   * @param user User
+   * @param selectedApp The user app to retrieve an auth key for.
+   */
+  getAuth(user, selectedApp) {
+    if (!this.api?.components?.securitySchemes) {
+      return {};
+    }
+    return getAuth(this.api, user, selectedApp);
+  }
+  /**
+   * Determine if a security scheme exists within the API definition.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#security-scheme-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object}
+   * @param name The name of the security scheme to check for.
+   */
+  hasSecurityScheme(name) {
+    return Boolean(this.api?.components?.securitySchemes?.[name]);
+  }
+  /**
+   * Retrieve a security scheme from the API definition.
+   *
+   * If the found security scheme is a `$ref` pointer it will be lazily dereferenced; if the scheme
+   * cannot be resolved after that process (eg. it's circular or is an invalid `$ref`) then
+   * `undefined` will be returned.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#security-scheme-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object}
+   * @param name The name of the security scheme to retrieve.
+   */
+  getSecurityScheme(name) {
+    if (!this.hasSecurityScheme(name)) {
+      return void 0;
+    }
+    let scheme = this.api?.components?.securitySchemes?.[name];
+    if (!scheme) return void 0;
+    if (isRef(scheme)) {
+      scheme = dereferenceRef(scheme, this.api);
+      if (!scheme || isRef(scheme)) return void 0;
+    }
+    return scheme;
+  }
+  /**
+   * Returns the `paths` object that exists in this API definition but with every `method` mapped
+   * to an instance of the `Operation` class.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+   */
+  getPaths() {
+    const paths = {};
+    if (!this.api.paths) {
+      return paths;
+    }
+    Object.keys(this.api.paths).forEach((path) => {
+      if (path.startsWith("x-")) {
+        return;
+      }
+      paths[path] = {};
+      let pathItem = this.api.paths[path];
+      if (!pathItem) {
+        return;
+      } else if (isRef(pathItem)) {
+        this.api.paths[path] = dereferenceRef(pathItem, this.api);
+        pathItem = this.api.paths[path];
+        if (!pathItem || isRef(pathItem)) {
+          return;
+        }
+      }
+      Object.keys(pathItem).forEach((method) => {
+        if (!supportedMethods.includes(method)) {
+          return;
+        }
+        paths[path][method] = this.operation(path, method);
+      });
+    });
+    return paths;
+  }
+  /**
+   * Returns the `webhooks` object that exists in this API definition but with every `method`
+   * mapped to an instance of the `Webhook` class.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+   */
+  getWebhooks() {
+    const webhooks = {};
+    if (!isOpenAPI31(this.api) || !this.api.webhooks) {
+      return webhooks;
+    }
+    Object.keys(this.api.webhooks).forEach((id) => {
+      webhooks[id] = {};
+      const webhookPath = dereferenceRef(this.api.webhooks?.[id], this.api);
+      if (webhookPath) {
+        Object.keys(webhookPath).forEach((method) => {
+          if (!supportedMethods.includes(method)) {
+            return;
+          }
+          webhooks[id][method] = this.operation(id, method, {
+            isWebhook: true
+          });
+        });
+      }
+    });
+    return webhooks;
+  }
+  /**
+   * Return an array of all tag names that exist on this API definition.
+   *
+   * If the API definition uses the `x-disable-tag-sorting` extension then tags will be returned in
+   * the order they're defined.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+   * @param setIfMissing If a tag is not present on an operation that operations path will be added
+   *    into the list of tags returned.
+   */
+  getTags(setIfMissing = false) {
+    const allTags = /* @__PURE__ */ new Set();
+    const oasTags = this.api.tags?.map((tag) => tag.name) || [];
+    const disableTagSorting = getExtension("disable-tag-sorting", this.api);
+    Object.entries(this.getPaths()).forEach(([path, operations]) => {
+      Object.values(operations).forEach((operation) => {
+        const tags = operation.getTags();
+        if (setIfMissing && !tags.length) {
+          allTags.add(path);
+          return;
+        }
+        tags.forEach((tag) => {
+          allTags.add(tag.name);
+        });
+      });
+    });
+    Object.entries(this.getWebhooks()).forEach(([path, webhooks]) => {
+      Object.values(webhooks).forEach((webhook) => {
+        const tags = webhook.getTags();
+        if (setIfMissing && !tags.length) {
+          allTags.add(path);
+          return;
+        }
+        tags.forEach((tag) => {
+          allTags.add(tag.name);
+        });
+      });
+    });
+    const endpointTags = [];
+    const tagsArray = [];
+    if (disableTagSorting) {
+      return Array.from(allTags);
+    }
+    Array.from(allTags).forEach((tag) => {
+      if (oasTags.includes(tag)) {
+        tagsArray.push(tag);
+      } else {
+        endpointTags.push(tag);
+      }
+    });
+    let sortedTags = tagsArray.toSorted((a, b) => {
+      return oasTags.indexOf(a) - oasTags.indexOf(b);
+    });
+    sortedTags = sortedTags.concat(endpointTags);
+    return sortedTags;
+  }
+  /**
+   * Determine if a given a custom specification extension exists within the API definition.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
+   * @param extension Specification extension to lookup.
+   */
+  hasExtension(extension) {
+    return hasRootExtension(extension, this.api);
+  }
+  /**
+   * Retrieve a custom specification extension off of the API definition.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
+   * @param extension Specification extension to lookup.
+   */
+  getExtension(extension, operation) {
+    return getExtension(extension, this.api, operation);
+  }
+  /**
+   * Determine if a given OpenAPI custom extension is valid or not.
+   *
+   * @see {@link https://docs.readme.com/docs/openapi-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
+   * @param extension Specification extension to validate.
+   * @throws
+   */
+  validateExtension(extension) {
+    if (this.hasExtension("x-readme")) {
+      const data = this.getExtension("x-readme");
+      if (typeof data !== "object" || Array.isArray(data) || data === null) {
+        throw new TypeError('"x-readme" must be of type "Object"');
+      }
+      if (extension in data) {
+        if ([CODE_SAMPLES, HEADERS, PARAMETER_ORDERING, SAMPLES_LANGUAGES].includes(extension)) {
+          if (data[extension] !== void 0) {
+            if (!Array.isArray(data[extension])) {
+              throw new TypeError(`"x-readme.${extension}" must be of type "Array"`);
+            }
+            if (extension === PARAMETER_ORDERING) {
+              validateParameterOrdering(data[extension], `x-readme.${extension}`);
+            }
+          }
+        } else if (extension === OAUTH_OPTIONS) {
+          if (typeof data[extension] !== "object") {
+            throw new TypeError(`"x-readme.${extension}" must be of type "Object"`);
+          }
+        } else if (typeof data[extension] !== "boolean") {
+          throw new TypeError(`"x-readme.${extension}" must be of type "Boolean"`);
+        }
+      }
+    }
+    if (this.hasExtension(`x-${extension}`)) {
+      const data = this.getExtension(`x-${extension}`);
+      if ([CODE_SAMPLES, HEADERS, PARAMETER_ORDERING, SAMPLES_LANGUAGES].includes(extension)) {
+        if (!Array.isArray(data)) {
+          throw new TypeError(`"x-${extension}" must be of type "Array"`);
+        }
+        if (extension === PARAMETER_ORDERING) {
+          validateParameterOrdering(data, `x-${extension}`);
+        }
+      } else if (extension === OAUTH_OPTIONS) {
+        if (typeof data !== "object") {
+          throw new TypeError(`"x-${extension}" must be of type "Object"`);
+        }
+      } else if (typeof data !== "boolean") {
+        throw new TypeError(`"x-${extension}" must be of type "Boolean"`);
+      }
+    }
+  }
+  /**
+   * Validate all of our custom or known OpenAPI extensions, throwing exceptions when necessary.
+   *
+   * @see {@link https://docs.readme.com/docs/openapi-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
+   */
+  validateExtensions() {
+    Object.keys(extensionDefaults).forEach((extension) => {
+      this.validateExtension(extension);
+    });
+  }
+};
 export {
   Oas as default
 };